Document string match/replace --max-matches

doc_src/cmds/string-match.rst

@@ -10,7 +10,7 @@ Synopsis
 
     string match [-a | --all] [-e | --entire] [-i | --ignore-case]
                  [-g | --groups-only] [-r | --regex] [-n | --index]
-                 [-q | --quiet] [-v | --invert]
+                 [-q | --quiet] [-v | --invert] [[-m | --max-matches] MAX]
                  PATTERN [STRING ...]
 
 .. END SYNOPSIS
@@ -36,6 +36,8 @@ When matching via regular expressions, ``string match`` automatically sets varia
 
 If **--invert** or **-v** is used the selected lines will be only those which do not match the given glob pattern or regular expression.
 
+If **--max-matches MAX** or **-m MAX** is used, ``string`` will stop checking for matches after MAX lines of input have matched. This can be used as an "early exit" optimization when processing long inputs but expecting a limited and fixed number of outputs that might be found considerably before the input stream has been exhausted. If combined with **--invert** or **-v**, considers only inverted matches.
+
 Exit status: 0 if at least one match was found, or 1 otherwise.
 
 .. END DESCRIPTION

doc_src/cmds/string-replace.rst

@@ -9,7 +9,8 @@ Synopsis
 .. synopsis::
 
     string replace [-a | --all] [-f | --filter] [-i | --ignore-case]
-                   [-r | --regex] [-q | --quiet] PATTERN REPLACEMENT [STRING ...]
+                   [-r | --regex] [[-m | --max-matches] MAX] [-q | --quiet] 
+                   PATTERN REPLACEMENT [STRING ...]
 
 .. END SYNOPSIS
 
@@ -24,6 +25,8 @@ If **-r** or **--regex** is given, *PATTERN* is interpreted as a Perl-compatible
 
 If you specify the **-f** or **--filter** flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: ``a_cmd | string match pattern | string replace pattern new_pattern``. You can instead just write ``a_cmd | string replace --filter pattern new_pattern``.
 
+If **--max-matches MAX** or **-m MAX** is used, ``string replace`` will stop all processing after MAX lines of input have matched the specified pattern. In the event of ``--filter`` or ``-f``, this means the output will be MAX lines in length. This can be used as an "early exit" optimization when processing long inputs but expecting a limited and fixed number of outputs that might be found considerably before the input stream has been exhausted.
+
 Exit status: 0 if at least one replacement was performed, or 1 otherwise.
 
 .. END DESCRIPTION