Add the optional limit argument to replace() (#1245)

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

Author: gem-neo4j

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

@@ -201,6 +201,16 @@ RETURN count(p) AS count
 
 | Queries no longer require xref:clauses/with.adoc[`WITH`] to transition between reading and writing operations.
 
+a|
+label:functionality[]
+label:updated[]
+[source, cypher, role="noheader"]
+----
+RETURN replace("hello world", "l", "", 1)
+----
+
+| The xref:functions/string.adoc#functions-replace[`replace()`] function now accepts an optional `limit` argument, defining the number of times the search string is replaced.
+
 |===
 
 === New in Cypher 25

modules/ROOT/pages/functions/string.adoc

@@ -323,12 +323,13 @@ RETURN normalize('\uFE64', NFKC) = '\u003C' AS result
 
 .Details
 |===
-| *Syntax* 3+| `replace(original, search, replace)`
+| *Syntax* 3+| `replace(original, search, replace [, limit])`
 | *Description* 3+| Returns a `STRING` in which all occurrences of a specified search `STRING` in the given `STRING` have been replaced by another (specified) replacement `STRING`.
-.4+| *Arguments* | *Name* | *Type* | *Description*
+.5+| *Arguments* | *Name* | *Type* | *Description*
 | `original` | `STRING` | The string to be modified.
 | `search` | `STRING` | The value to replace in the original string.
 | `replace` | `STRING` | The value to be inserted in the original string.
+| `limit` | `STRING` | The maximum amount of times the search value should be replaced in the string, starting from the left. label:new[Introduced in Neo4j 2025.06]
 | *Returns* 3+| `STRING`
 |===
 
@@ -337,6 +338,7 @@ RETURN normalize('\uFE64', NFKC) = '\u003C' AS result
 
 | If any argument is `null`, `null` will be returned.
 | If `search` is not found in `original`, `original` will be returned.
+| If `limit` is not defined, all occurrences of the search will be replaced.
 
 |===
 
@@ -362,6 +364,24 @@ RETURN replace("hello", "l", "w")
 
 |===
 
+.Query with limit
+// tag::functions_string_replace[]
+[source, cypher, indent=0]
+----
+RETURN replace("hello", "l", "w", 1)
+----
+// end::functions_string_replace[]
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+
+| replace("hello", "l", "w", 1)
+| "hewlo"
+1+d|Rows: 1
+
+|===
+
 ======