diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 70c90057de..fc2512d5d8 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -650,6 +650,7 @@ String manipulation: *string-functions* win_execute() like execute() but in a specified window trim() trim characters from a string gettext() lookup message translation + items() get List of String index-character pairs List manipulation: *list-functions* get() get an item without error for wrong index diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 8cb9722cd6..74c1594e5e 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -5424,22 +5424,27 @@ isnan({expr}) *isnan()* Return: ~ (`0|1`) -items({dict}) *items()* - Return a |List| with all the key-value pairs of {dict}. Each - |List| item is a list with two items: the key of a {dict} - entry and the value of this entry. The |List| is in arbitrary - order. Also see |keys()| and |values()|. +items({expr}) *items()* + Return a |List| with all key/index and value pairs of {expr}. + Each |List| item is a list with two items: + - for a |Dict|: the key and the value + - for a |List| or |String|: the index and the value + The returned |List| is in arbitrary order for a |Dict|, + otherwise it's in ascending order of the index. + + Also see |keys()| and |values()|. + Example: >vim + let mydict = #{a: 'red', b: 'blue'} for [key, value] in items(mydict) - echo key .. ': ' .. value + echo $"{key} = {value}" endfor + echo items([1, 2, 3]) + echo items("foobar") < - A List or a String argument is also supported. In these - cases, items() returns a List with the index and the value at - the index. Parameters: ~ - • {dict} (`table`) + • {expr} (`table|string`) Return: ~ (`any`) diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index c1ac7c3fab..af8e4b786c 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -4908,22 +4908,27 @@ function vim.fn.islocked(expr) end --- @return 0|1 function vim.fn.isnan(expr) end ---- Return a |List| with all the key-value pairs of {dict}. Each ---- |List| item is a list with two items: the key of a {dict} ---- entry and the value of this entry. The |List| is in arbitrary ---- order. Also see |keys()| and |values()|. ---- Example: >vim ---- for [key, value] in items(mydict) ---- echo key .. ': ' .. value ---- endfor ---- < ---- A List or a String argument is also supported. In these ---- cases, items() returns a List with the index and the value at ---- the index. +--- Return a |List| with all key/index and value pairs of {expr}. +--- Each |List| item is a list with two items: +--- - for a |Dict|: the key and the value +--- - for a |List| or |String|: the index and the value +--- The returned |List| is in arbitrary order for a |Dict|, +--- otherwise it's in ascending order of the index. --- ---- @param dict table +--- Also see |keys()| and |values()|. +--- +--- Example: >vim +--- let mydict = #{a: 'red', b: 'blue'} +--- for [key, value] in items(mydict) +--- echo $"{key} = {value}" +--- endfor +--- echo items([1, 2, 3]) +--- echo items("foobar") +--- < +--- +--- @param expr table|string --- @return any -function vim.fn.items(dict) end +function vim.fn.items(expr) end --- @deprecated --- Obsolete name for |chanclose()| diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index 87fd8beb22..e7f5ba18ad 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -6057,22 +6057,27 @@ M.funcs = { args = 1, base = 1, desc = [=[ - Return a |List| with all the key-value pairs of {dict}. Each - |List| item is a list with two items: the key of a {dict} - entry and the value of this entry. The |List| is in arbitrary - order. Also see |keys()| and |values()|. + Return a |List| with all key/index and value pairs of {expr}. + Each |List| item is a list with two items: + - for a |Dict|: the key and the value + - for a |List| or |String|: the index and the value + The returned |List| is in arbitrary order for a |Dict|, + otherwise it's in ascending order of the index. + + Also see |keys()| and |values()|. + Example: >vim + let mydict = #{a: 'red', b: 'blue'} for [key, value] in items(mydict) - echo key .. ': ' .. value + echo $"{key} = {value}" endfor + echo items([1, 2, 3]) + echo items("foobar") < - A List or a String argument is also supported. In these - cases, items() returns a List with the index and the value at - the index. ]=], name = 'items', - params = { { 'dict', 'table' } }, - signature = 'items({dict})', + params = { { 'expr', 'table|string' } }, + signature = 'items({expr})', }, jobclose = { args = { 1, 2 },