Skip to content

scan("(a)(b)") returning an array is not documented #3086

@emanuele6

Description

@emanuele6

Describe the bug
If the regular expression of scan/1/scan/2 contains a capture group, arrays contains the values of the capture groups are returned instead of strings that are the full match of the regular expression.

I use this feature all the time, and I have just noticed it is not documented!

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 [ expr ], e.g. [ scan(regex) ].

         jq ´scan("c")´
            "abcdefabc"
         => "c", "c"

To Reproduce

$ jq -cn '"foo bar xzbox" | scan(".b.")'
" ba"
"zbo"
$ jq -cn '"foo bar xzbox" | scan("(.)b(.)")'
[" ","a"]
["z","o"]

Expected behavior
The feature should be documented.

Environment (please complete the following information):

  • OS and Version: Arch Linux
  • jq version: 1.7.1

Additional context
This feature has been supported by jq for many years, and it also works in gojq.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions