Home • Explore • Blog • CI
☰



neovim
82th chunk of `runtime/doc/vimfn.txt`
67d62793cab7220c7f928eba0868243457a4ea70d31cce010000000100000fb9
             Return: ~
                  (`any`)

matchlist({expr}, {pat} [, {start} [, {count}]])                   *matchlist()*
		Same as |match()|, but return a |List|.  The first item in the
		list is the matched string, same as what matchstr() would
		return.  Following items are submatches, like "\1", "\2", etc.
		in |:substitute|.  When an optional submatch didn't match an
		empty string is used.  Example: >vim
			echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
<		Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
		When there is no match an empty list is returned.

		You can pass in a List, but that is not very useful.

                Parameters: ~
                  • {expr} (`any`)
                  • {pat} (`string`)
                  • {start} (`integer?`)
                  • {count} (`integer?`)

                Return: ~
                  (`any`)

matchstr({expr}, {pat} [, {start} [, {count}]])                     *matchstr()*
		Same as |match()|, but return the matched string.  Example: >vim
			echo matchstr("testing", "ing")
<		results in "ing".
		When there is no match "" is returned.
		The {start}, if given, has the same meaning as for |match()|. >vim
			echo matchstr("testing", "ing", 2)
<		results in "ing". >vim
			echo matchstr("testing", "ing", 5)
<		result is "".
		When {expr} is a |List| then the matching item is returned.
		The type isn't changed, it's not necessarily a String.

                Parameters: ~
                  • {expr} (`any`)
                  • {pat} (`string`)
                  • {start} (`integer?`)
                  • {count} (`integer?`)

                Return: ~
                  (`any`)

matchstrlist({list}, {pat} [, {dict}])                          *matchstrlist()*
		Returns the |List| of matches in {list} where {pat} matches.
		{list} is a |List| of strings.  {pat} is matched against each
		string in {list}.

		The {dict} argument supports following items:
		    submatches	include submatch information (|/\(|)

		For each match, a |Dict| with the following items is returned:
		    byteidx	starting byte index of the match.
		    idx		index in {list} of the match.
		    text	matched string
		    submatches	a List of submatches.  Present only if
				"submatches" is set to v:true in {dict}.

		See |match-pattern| for information about the effect of some
		option settings on the pattern.

		Example: >vim
		    echo matchstrlist(['tik tok'], '\<\k\+\>')
<		    `[{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]` >vim
		    echo matchstrlist(['a', 'b'], '\<\k\+\>')
<		    `[{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]`

		If "submatches" is present and is v:true, then submatches like
		"\1", "\2", etc. are also returned.  Example: >vim
		    echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
						\ #{submatches: v:true})
<		    `[{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]`
		The "submatches" List always contains 9 items.  If a submatch
		is not found, then an empty string is returned for that
		submatch.

                Parameters: ~
                  • {list} (`string[]`)
                  • {pat} (`string`)
                  • {dict} (`table?`)

                Return: ~
                  (`any`)

matchstrpos({expr}, {pat} [, {start} [, {count}]])               *matchstrpos()*
		Same as |matchstr()|, but return the matched string, the start
		position and the end position of the match.  Example: >vim
			echo matchstrpos("testing", "ing")
<		results in ["ing", 4, 7].
		When there is no match ["", -1, -1] is returned.
		The {start}, if given, has the same meaning as for |match()|. >vim
			echo matchstrpos("testing", "ing", 2)
<		results in ["ing", 4, 7]. >vim
			echo matchstrpos("testing", "ing", 5)
<		result is ["", -1, -1].
		When {expr} is a |List| then the matching item, the index
		of first item where {pat} matches, the start position and the
Title: Vim Function Documentation: matchstr(), matchstrlist(), and matchstrpos()
Summary
This section documents the `matchstr()` function, which returns the matched string, and explains how it behaves with strings and lists, along with the use of the {start} parameter. It then describes `matchstrlist()`, which returns a list of matches in a list of strings, with options for including submatch information. Finally, it documents `matchstrpos()`, which returns the matched string, start position, and end position of the match.