+ String.replace

docs/Regex.md

@@ -64,6 +64,18 @@ Also, string indexing is Regex-aware, and works like `Regex.find` (_not findall!
     assert( "cd" == ("abcdef"[ "c.".re ] as RegexMatch).value )
     >>> void
 
+Regex replacement is exposed on `String.replace` and `String.replaceFirst`:
+
+    assertEquals( "v#.#.#", "v1.2.3".replace( "\d+".re, "#" ) )
+    assertEquals( "v[1].[2].[3]", "v1.2.3".replace( "(\d+)".re ) { m -> "[" + m[1] + "]" } )
+    assertEquals( "year-04-08", "2026-04-08".replaceFirst( "\d+".re, "year" ) )
+    >>> void
+
+When `replace` takes a plain `String`, it is treated literally, not as a regex pattern:
+
+    assertEquals( "a-b-c", "a.b.c".replace( ".", "-" ) )
+    >>> void
+
 
 # Regex class reference
 

docs/tutorial.md

@@ -1833,6 +1833,14 @@ Part match:
     assert( "foo" == ($~ as RegexMatch).value )
     >>> void
 
+Replacing text:
+
+    assertEquals("bonono", "banana".replace('a', 'o'))
+    assertEquals("a-b-c", "a.b.c".replace(".", "-"))   // string patterns are literal
+    assertEquals("v#.#.#", "v1.2.3".replace("\d+".re, "#"))
+    assertEquals("v[1].[2].[3]", "v1.2.3".replace("(\d+)".re) { m -> "[" + m[1] + "]" })
+    >>> void
+
 Repeating the fragment:
 
     assertEquals("hellohello", "hello"*2)
@@ -1868,6 +1876,8 @@ A typical set of String functions includes:
 | characters           | create [List] of characters (1)                            |
 | encodeUtf8()         | returns [Buffer] with characters encoded to utf8           |
 | matches(re)          | matches the regular expression (2)                         |
+| replace(old, new)    | replace all literal or regex matches; regex needs [Regex]  |
+| replaceFirst(old,new)| replace the first literal or regex match                   |
 |                      |                                                            |
 
 (1)