Only for an expression in a :substitute command or substitute() function. Returns the {nr}'th submatch of the matched text. When {nr} is 0 the whole matched text is returned. Note that a NL in the string can stand for a line break of a multi-line match or a NUL character in the text. Also see sub-replace-expression.

If {list} is present and non-zero then submatch() returns a list of strings, similar to getline() with two arguments. NL characters in the text represent NUL characters in the text. Only returns more than one item for :substitute, inside substitute() this list will always contain one or zero items, since there are no real line breaks.

When substitute() is used recursively only the submatches in the current (deepest) call can be obtained.

Returns an empty string or list on error.

Examples:

:s/\d\+/\=submatch(0) + 1/
:echo substitute(text, '\d\+', '\=submatch(0) + 1', '')

This finds the first number in the line and adds one to it. A line break is included as a newline character.

Can also be used as a method:

GetNr()->submatch()