Add example explaining more efficient `string.is_match` usage
| doc m%"
`is_match regex str` checks if `str` matches `regex`.
- Note that this function may perform better by sharing its partial application between multiple calls,
- because in this case the underlying regular expression will only be compiled once.
-
For example:
```nickel
is_match "^\\d+$" "123" =>
is_match "\\d{4}" "123" =>
false
```
+
+ For example, in the following program, the whole call to
+ `string.is_match "[0-9]*\\.?[0-9]+ x"` is re-evaluated at each invocation of
+ `is_number`. The regexp will be recompiled 3 times in total:
+
+ ```nickel
+ let is_number = fun x => string.is_match "[0-9]*\\.?[0-9]+" x in
+ ["0", "42", "0.5"] |> array.all is_number =>
+ true
+ ```
+
+ On the other hand, in the version below, the partial application of
+ `string.is_match "[0-9]*\\.?[0-9]+"` is evaluated once, returning a
+ function capturing the compiled regexp. The regexp will only be compiled
+ once and for all:
+
+ ```nickel
+ let is_number' = string.is_match "[0-9]*\\.?[0-9]+" in
+ ["0", "42", "0.5"] |> array.all is_number' =>
+ true
+ ```
"%m
= fun regex => %str_is_match% regex,
`match regex str` matches `str` given `regex`. Results in the part of `str` that matched, the index of the
first character that was part of the match in `str`, and a arrays of all capture groups if any.
- Note that this function may perform better by sharing its partial application between multiple calls,
- because in this case the underlying regular expression will only be compiled once.
-
For example:
```nickel
match "^(\\d).*(\\d).*(\\d).*$" "5 apples, 6 pears and 0 grapes" =>
match "3" "01234" =>
{ match = "3", index = 3, groups = [ ] }
```
+
+ Note that this function may perform better by sharing its partial application between multiple calls,
+ because in this case the underlying regular expression will only be compiled once (See the documentation
+ of `string.is_match` for more details).
"%m
= fun regex => %str_match% regex,
