From f975e1c9e51fa9e9161ba1c0208ea9960bdced3d Mon Sep 17 00:00:00 2001 From: Mahmoud Al-Qudsi Date: Wed, 26 Jun 2024 22:30:51 -0500 Subject: [PATCH] Document `string match/replace --max-matches` --- doc_src/cmds/string-match.rst | 4 +++- doc_src/cmds/string-replace.rst | 5 ++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/doc_src/cmds/string-match.rst b/doc_src/cmds/string-match.rst index f48a3c9ca..5ef602fdc 100644 --- a/doc_src/cmds/string-match.rst +++ b/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 diff --git a/doc_src/cmds/string-replace.rst b/doc_src/cmds/string-replace.rst index 059c5c86f..891290c4d 100644 --- a/doc_src/cmds/string-replace.rst +++ b/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