From 049de6f11925131364d2820ed53327b1c32af012 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Thu, 21 Aug 2025 08:32:46 +0800 Subject: [PATCH 1/3] vim-patch:partial:308a313: runtime(doc): Update help for the items() function closes: vim/vim#18021 https://github.com/vim/vim/commit/308a3130be89148cdaf83bfaf00e3e7c69ed2133 Co-authored-by: Yegappan Lakshmanan --- runtime/doc/vimfn.txt | 24 ++++++++++++++---------- runtime/lua/vim/_meta/vimfn.lua | 32 ++++++++++++++++++-------------- src/nvim/eval.lua | 24 ++++++++++++++---------- 3 files changed, 46 insertions(+), 34 deletions(-) diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 8cb9722cd6..bbe707c57b 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -5424,22 +5424,26 @@ 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 the 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 |List| is in arbitrary order. + + 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..5312167c44 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -4908,22 +4908,26 @@ 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 the 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 |List| is in arbitrary order. --- ---- @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..ca868edac4 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -6057,22 +6057,26 @@ 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 the 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 |List| is in arbitrary order. + + 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 }, From 1fdacbb3e4e118c7bc3cd03ea16b21a68c7c9631 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Thu, 21 Aug 2025 08:34:20 +0800 Subject: [PATCH 2/3] vim-patch:44c8072: runtime(doc): fix style and clarify items() function for String type related: vim/vim#18021 https://github.com/vim/vim/commit/44c8072ef64a7a218eb8cf4b72866921762633e4 Co-authored-by: Christian Brabandt --- runtime/doc/usr_41.txt | 1 + runtime/doc/vimfn.txt | 2 +- runtime/lua/vim/_meta/vimfn.lua | 2 +- src/nvim/eval.lua | 2 +- 4 files changed, 4 insertions(+), 3 deletions(-) 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 bbe707c57b..17cc3f94c5 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -5425,7 +5425,7 @@ isnan({expr}) *isnan()* (`0|1`) items({expr}) *items()* - Return a |List| with all the key/index and value pairs of {expr}. + 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 diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 5312167c44..3d96bf7255 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -4908,7 +4908,7 @@ function vim.fn.islocked(expr) end --- @return 0|1 function vim.fn.isnan(expr) end ---- Return a |List| with all the key/index and value pairs of {expr}. +--- 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 diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index ca868edac4..e661c7ee8f 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -6057,7 +6057,7 @@ M.funcs = { args = 1, base = 1, desc = [=[ - Return a |List| with all the key/index and value pairs of {expr}. + 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 From 7d53982b7f7991e27ebffd5159de012d900a244c Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Thu, 21 Aug 2025 08:35:30 +0800 Subject: [PATCH 3/3] vim-patch:84a343a: runtime(doc): correct another problem in :h items() The returned value is only in arbitrary order for a Dict. closes: vim/vim#18050 https://github.com/vim/vim/commit/84a343a6ed34995adc67c062b64533c1b0bf7fb1 --- runtime/doc/vimfn.txt | 3 ++- runtime/lua/vim/_meta/vimfn.lua | 3 ++- src/nvim/eval.lua | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 17cc3f94c5..74c1594e5e 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -5429,7 +5429,8 @@ items({expr}) *items()* 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 |List| is in arbitrary order. + The returned |List| is in arbitrary order for a |Dict|, + otherwise it's in ascending order of the index. Also see |keys()| and |values()|. diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 3d96bf7255..af8e4b786c 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -4912,7 +4912,8 @@ function vim.fn.isnan(expr) end --- 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 |List| is in arbitrary order. +--- The returned |List| is in arbitrary order for a |Dict|, +--- otherwise it's in ascending order of the index. --- --- Also see |keys()| and |values()|. --- diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index e661c7ee8f..e7f5ba18ad 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -6061,7 +6061,8 @@ M.funcs = { 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 |List| is in arbitrary order. + The returned |List| is in arbitrary order for a |Dict|, + otherwise it's in ascending order of the index. Also see |keys()| and |values()|.