docs: mention the behavior of scan using regex with capturing groups (#3240)

docs/content/manual/dev/manual.yml

@@ -2699,12 +2699,17 @@ sections:
           that match the regex in accordance with the flags, if any
           have been specified.  If there is no match, the stream is empty.
           To capture all the matches for each input string, use the idiom
-          `[ expr ]`, e.g. `[ scan(regex) ]`.
+          `[ expr ]`, e.g. `[ scan(regex) ]`.  If the regex contains capturing
+          groups, the filter emits a stream of arrays, each of which contains
+          the captured strings.
 
         examples:
           - program: 'scan("c")'
             input: '"abcdefabc"'
             output: ['"c"', '"c"']
+          - program: 'scan("(a+)(b+)")'
+            input: '"abaabbaaabbb"'
+            output: ['["a","b"]', '["aa","bb"]', '["aaa","bbb"]']
 
       - title: "`split(regex; flags)`"
         body: |

docs/content/manual/v1.7/manual.yml

@@ -2646,12 +2646,17 @@ sections:
           that match the regex in accordance with the flags, if any
           have been specified.  If there is no match, the stream is empty.
           To capture all the matches for each input string, use the idiom
-          `[ expr ]`, e.g. `[ scan(regex) ]`.
+          `[ expr ]`, e.g. `[ scan(regex) ]`.  If the regex contains capturing
+          groups, the filter emits a stream of arrays, each of which contains
+          the captured strings.
 
         examples:
           - program: 'scan("c")'
             input: '"abcdefabc"'
             output: ['"c"', '"c"']
+          - program: 'scan("(a+)(b+)")'
+            input: '"abaabbaaabbb"'
+            output: ['["a","b"]', '["aa","bb"]', '["aaa","bbb"]']
 
       - title: "`split(regex; flags)`"
         body: |

jq.1.prebuilt

@@ -2985,7 +2985,7 @@ jq \'capture("(?<a>[a\-z]+)\-(?<n>[0\-9]+)")\'
 .IP "" 0
 .
 .SS "scan(regex), scan(regex; flags)"
-Emit a stream of the non\-overlapping substrings of the input that match the regex in accordance with the flags, if any have been specified\. If there is no match, the stream is empty\. To capture all the matches for each input string, use the idiom \fB[ expr ]\fR, e\.g\. \fB[ scan(regex) ]\fR\.
+Emit a stream of the non\-overlapping substrings of the input that match the regex in accordance with the flags, if any have been specified\. If there is no match, the stream is empty\. To capture all the matches for each input string, use the idiom \fB[ expr ]\fR, e\.g\. \fB[ scan(regex) ]\fR\. If the regex contains capturing groups, the filter emits a stream of arrays, each of which contains the captured strings\.
 .
 .IP "" 4
 .
@@ -2994,6 +2994,10 @@ Emit a stream of the non\-overlapping substrings of the input that match the reg
 jq \'scan("c")\'
    "abcdefabc"
 => "c", "c"
+
+jq \'scan("(a+)(b+)")\'
+   "abaabbaaabbb"
+=> ["a","b"], ["aa","bb"], ["aaa","bbb"]
 .
 .fi
 .

tests/manonig.test

@@ -47,6 +47,12 @@ scan("c")
 "c"
 "c"
 
+scan("(a+)(b+)")
+"abaabbaaabbb"
+["a","b"]
+["aa","bb"]
+["aaa","bbb"]
+
 split(", *"; null)
 "ab,cd, ef"
 ["ab","cd","ef"]