runtime(doc): Update help for the items() function

closes: #18021

Signed-off-by: Yegappan Lakshmanan <yegappan@yahoo.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 752d0515d842354e07bcd1d003883168f891e534..e011c10888bbdc21b8837ed74e6c420ddcc6bbd1 100644 (file)
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt*  For Vim version 9.1.  Last change: 2025 Aug 12
+*builtin.txt*  For Vim version 9.1.  Last change: 2025 Aug 17
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -344,7 +344,7 @@ isinf({expr})                       Number  determine if {expr} is infinity value
                                        (positive or negative)
 islocked({expr})               Number  |TRUE| if {expr} is locked
 isnan({expr})                  Number  |TRUE| if {expr} is NaN
-items({dict})                  List    key-value pairs in {dict}
+items({expr})                  List    key-value pairs in {expr}
 job_getchannel({job})          Channel get the channel handle for {job}
 job_info([{job}])              Dict    get information about {job}
 job_setoptions({job}, {options}) none  set options for {job}
@@ -6310,20 +6310,24 @@ isnan({expr})                                           *isnan()*
                Return type: |Number|
 
 
-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()|.
-               Example: >
+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|, |Tuple| or |String|: the index and the value
+               The |List| is in arbitrary order.
+
+               Also see |keys()| and |values()|.
+
+               Examples: >
+                       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(('a', 'b', 'c'))
+                       echo items("foobar")
 <
-               A |List|, a |Tuple| or a |String| argument is also supported.
-               In these cases, items() returns a List with the index and the
-               value at the index.
-
                Can also be used as a |method|: >
                        mydict->items()
 <

diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 094fe78e1ea4d4cb7eac5d279d5699cfdf2fbf1e..360f3a862256c8b96be85d3ff04a5f8a28b28b99 100644 (file)
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1,4 +1,4 @@
-*usr_41.txt*   For Vim version 9.1.  Last change: 2025 Aug 10
+*usr_41.txt*   For Vim version 9.1.  Last change: 2025 Aug 17
 
                     VIM USER MANUAL - by Bram Moolenaar
 
@@ -806,6 +806,7 @@ String manipulation:                                        *string-functions*
        ngettext()              lookup single/plural message translation
        str2blob()              convert a list of strings into a blob
        blob2str()              convert a blob into a list of strings
+       items()                 get List of List index-value pairs
 
 List manipulation:                                     *list-functions*
        get()                   get an item without error for wrong index