added EReg.replace specification

std/EReg.hx

@@ -158,9 +158,19 @@ class EReg {
 	}
 
 	/**
-		Replaces a pattern by another string. The [by] format can
-		contains [$1] to [$9] that will correspond to groups matched
-		while replacing. [$$] means the [$] character.
+		Replaces the first substring of [s] which [this] EReg matches with [by].
+		
+		If [this] EReg does not match any substring, the result is [s].
+		
+		By default, this method replaces only the first matched substring. If
+		the global g modifier is in place, all matched substrings are replaced.
+		
+		If [by] contains [$1] to [$9], the digit corresponds to number of a
+		matched sub-group and its value is used instead. If no such sub-group
+		exists, the [$1] to [$9] string is used as is. The string [$$] becomes
+		[$].
+		
+		If [s] or [by] are null, the result is unspecified.
 	**/
 	public function replace( s : String, by : String ) : String {
 		return null;

tests/unit/unitstd/EReg.unit.hx

@@ -65,4 +65,35 @@ pos.len == 2;
 ~/a/g.split("aba") == ["","b",""];
 ~/a/g.split("bab") == ["b","b"];
 ~/a/g.split("baba") == ["b","b",""];
+
+// replace
+~/a/.replace("", "z") == "";
+~/a/.replace("a", "z") == "z";
+~/a/.replace("aa", "z") == "za";
+~/a/.replace("b", "z") == "b";
+~/a/.replace("ab", "z") == "zb";
+~/a/.replace("ba", "z") == "bz";
+~/a/.replace("aba", "z") == "zba";
+~/a/.replace("bab", "z") == "bzb";
+~/a/.replace("baba", "z") == "bzba";
+
+// replace + g
+~/a/g.replace("", "z") == "";
+~/a/g.replace("a", "z") == "z";
+~/a/g.replace("aa", "z") == "zz";
+~/a/g.replace("b", "z") == "b";
+~/a/g.replace("ab", "z") == "zb";
+~/a/g.replace("ba", "z") == "bz";
+~/a/g.replace("aba", "z") == "zbz";
+~/a/g.replace("bab", "z") == "bzb";
+~/a/g.replace("baba", "z") == "bzbz";
+
+// replace + $
+~/href="(.*?)"/.replace('lead href="foo" trail',"$1") == "lead foo trail";
+~/href="(.*?)"/.replace('lead href="foo" trail',"$2") == "lead $2 trail";
+~/href="(.*?)"/.replace('href="foo"',"$1") == "foo";
+~/href="(.*?)"/.replace('href="foo"',"$2") == "$2";
+~/href="(.*?)"/g.replace('lead href="foo" href="bar" trail',"$1") == "lead foo bar trail";
+~/href="(.*?)"/g.replace('lead href="foo" href="bar" trail',"$$$1$$") == "lead $foo$ $bar$ trail";
+~/href="(.*?)"/g.replace('lead href="foo" href="bar" trail',"$$$2$$") == "lead $$2$ $$2$ trail";
 #end