vim-patch:9.1.0009: Cannot easily get the list of matches (#27028)

Problem:  Cannot easily get the list of matches
Solution: Add the matchstrlist() and matchbufline() Vim script
          functions (Yegappan Lakshmanan)

closes: vim/vim#13766

Omit CHECK_LIST_MATERIALIZE(): it populates a List with numbers only,
and there is a check for strings below.

f93b1c881a

vim-patch:eb3475df0d92

runtime(doc): Replace non-breaking space with normal space (vim/vim#13868)

eb3475df0d

Co-authored-by: Yegappan Lakshmanan <4298407+yegappan@users.noreply.github.com>

src/nvim/eval.lua

@@ -6615,6 +6615,60 @@ M.funcs = {
     params = { { 'nr', 'integer' } },
     signature = 'matcharg({nr})',
   },
+  matchbufline = {
+    args = { 4, 5 },
+    base = 1,
+    desc = [=[
+      Returns the |List| of matches in lines from {lnum} to {end} in
+      buffer {buf} where {pat} matches.
+
+      {lnum} and {end} can either be a line number or the string "$"
+      to refer to the last line in {buf}.
+
+      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
+          lnum	line number where there is a match
+          text	matched string
+      Note that there can be multiple matches in a single line.
+
+      This function works only for loaded buffers. First call
+      |bufload()| if needed.
+
+      When {buf} is not a valid buffer, the buffer is not loaded or
+      {lnum} or {end} is not valid then an error is given and an
+      empty |List| is returned.
+
+      Examples: >vim
+          " Assuming line 3 in buffer 5 contains "a"
+          :echo matchbufline(5, '\<\k\+\>', 3, 3)
+          [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
+          " Assuming line 4 in buffer 10 contains "tik tok"
+          :echo matchbufline(10, '\<\k\+\>', 1, 4)
+          [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
+      <
+      If {submatch} is present and is v:true, then submatches like
+      "\1", "\2", etc. are also returned.  Example: >vim
+          " Assuming line 2 in buffer 2 contains "acd"
+          :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
+      				\ {'submatches': v:true})
+          [{'lnum': 2, '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.
+    ]=],
+    name = 'matchbufline',
+    params = {
+      { 'buf', 'string|integer' },
+      { 'pat', 'string' },
+      { 'lnum', 'string|integer' },
+      { 'end', 'string|integer' },
+      { 'dict', 'table' },
+    },
+    signature = 'matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])',
+  },
   matchdelete = {
     args = { 1, 2 },
     base = 1,
@@ -6799,6 +6853,43 @@ M.funcs = {
     params = { { 'expr', 'any' }, { 'pat', 'any' }, { 'start', 'any' }, { 'count', 'any' } },
     signature = 'matchstr({expr}, {pat} [, {start} [, {count}]])',
   },
+  matchstrlist = {
+    args = { 2, 3 },
+    base = 1,
+    desc = [=[
+      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}.
+
+      Example: >vim
+          :echo matchstrlist(['tik tok'], '\<\k\+\>')
+          [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
+          :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.
+    ]=],
+    name = 'matchstrlist',
+    params = { { 'list', 'string[]' }, { 'pat', 'string' }, { 'dict', 'table' } },
+    signature = 'matchstrlist({list}, {pat} [, {dict}])',
+  },
   matchstrpos = {
     args = { 2, 4 },
     base = 1,
@@ -6836,7 +6927,7 @@ M.funcs = {
       it returns the maximum of all values in the Dictionary.
       If {expr} is neither a List nor a Dictionary, or one of the
       items in {expr} cannot be used as a Number this results in
-                      an error.  An empty |List| or |Dictionary| results in zero.
+      an error.  An empty |List| or |Dictionary| results in zero.
 
     ]=],
     name = 'max',