lib: add limit support to split() and replace()

Extend the split() and replace() functions to accept an additional optional
`limit` argument which limits the amount of split operations / substitutions
performed by these functions.

Signed-off-by: Jo-Philipp Wich <jo@mein.io>

1 files changed, 12 insertions, 2 deletions

diff --git a/README.md b/README.md
index fba3177..fc80c9b 100644
--- a/README.md
+++ b/README.md
@@ -934,17 +934,22 @@ If `off` is negative then it starts that far from the end of the array. If
 removes the elements from `off` onward except for `-len` elements at the end of
 the array. If both `off` and `len` are omitted, removes everything.
 
-#### 6.33. `split(str, sep)`
+#### 6.33. `split(str, sep[, limit])`
 
 Split the given string using the separator passed as second argument and return
 an array containing the resulting pieces.
 
+If a limit argument is supplied, the resulting array contains no more than the
+given amount of entries, that means the string is split at most `limit - 1`
+times total.
+
 The separator may either be a plain string or a regular expression.
 
 ```javascript
 split("foo,bar,baz", ",")     // ["foo", "bar", "baz"]
 split("foobar", "")           // ["f", "o", "o", "b", "a", "r"]
 split("foo,bar,baz", /[ao]/)  // ["f", "", ",b", "r,b", "z"]
+split("foo=bar=baz", "=", 2)  // ["foo", "bar=baz"]
 ```
 
 #### 6.34. `sqrt(x)`
@@ -1095,7 +1100,7 @@ match("foobarbaz", /b.(.)/)   // ["bar", "r"]
 match("foobarbaz", /b.(.)/g)  // [["bar", "r"], ["baz", "z"]]
 ```
 
-#### 6.47. `replace(str, /pattern/, replace)`
+#### 6.47. `replace(str, /pattern/, replace[, limit])`
 
 Replace occurences of the specified pattern in the string passed as first
 argument. The pattern value may be either a regular expression or a plain
@@ -1103,6 +1108,9 @@ string. The replace value may be a function which is invoked for each found
 pattern or any other value which is converted into a plain string and used as
 replacement.
 
+When an optional limit is specified, substitutions are performed only that
+many times.
+
 If the pattern is a regular expression and not using the `g` flag, then only the
 first occurence in the string is replaced, if the `g` flag is used or if the
 pattern is not a regular expression, all occurrences are replaced.
@@ -1126,6 +1134,8 @@ replace("barfoobaz", "a", "X")                              // bXrfoobXz
 replace("barfoobaz", /(.)(.)(.)/g, function(m, c1, c2, c3) {
     return c3 + c2 + c1;
 })                                                          // raboofzab
+replace("aaaaa", "a", "x", 3)                               // xxxaa
+replace("foo bar baz", /[ao]/g, "x", 3)                     // fxx bxr baz
 ```
 
 #### 6.48. `json(str)`