patch 9.1.0027: Vim is missing a foreach() func
Problem: Vim is missing a foreach() func
Solution: Implement foreach({expr1}, {expr2}) function,
which applies {expr2} for each item in {expr1}
without changing it (Ernie Rael)
closes: #12166
Signed-off-by: Ernie Rael <errael@raelity.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 9ac79c6..4bbf506 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt* For Vim version 9.1. Last change: 2024 Jan 05
+*builtin.txt* For Vim version 9.1. Last change: 2024 Jan 13
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -198,6 +198,8 @@
foldlevel({lnum}) Number fold level at {lnum}
foldtext() String line displayed for closed fold
foldtextresult({lnum}) String text for closed fold at {lnum}
+foreach({expr1}, {expr2}) List/Dict/Blob/String
+ for each item in {expr1} call {expr2}
foreground() Number bring the Vim window to the foreground
fullcommand({name} [, {vim9}]) String get full command from {name}
funcref({name} [, {arglist}] [, {dict}])
@@ -2995,6 +2997,45 @@
Can also be used as a |method|: >
GetLnum()->foldtextresult()
+
+foreach({expr1}, {expr2}) *foreach()*
+ {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
+ For each item in {expr1} execute {expr2}. {expr1} is not
+ modified; its values may be, as with |:lockvar| 1. *E741*
+ See |map()| and |filter()| to modify {expr1}.
+
+ {expr2} must be a |string| or |Funcref|.
+
+ If {expr2} is a |string|, inside {expr2} |v:val| has the value
+ of the current item. For a |Dictionary| |v:key| has the key
+ of the current item and for a |List| |v:key| has the index of
+ the current item. For a |Blob| |v:key| has the index of the
+ current byte. For a |String| |v:key| has the index of the
+ current character.
+ Examples: >
+ call foreach(mylist, 'used[v:val] = true')
+< This records the items that are in the {expr1} list.
+
+ Note that {expr2} is the result of expression and is then used
+ as a command. Often it is good to use a |literal-string| to
+ avoid having to double backslashes.
+
+ If {expr2} is a |Funcref| it must take two arguments:
+ 1. the key or the index of the current item.
+ 2. the value of the current item.
+ With a legacy script lambda you don't get an error if it only
+ accepts one argument, but with a Vim9 lambda you get "E1106:
+ One argument too many", the number of arguments must match.
+ If the function returns a value, it is ignored.
+
+ Returns {expr1} in all cases.
+ When an error is encountered while executing {expr2} no
+ further items in {expr1} are processed.
+ When {expr2} is a Funcref errors inside a function are ignored,
+ unless it was defined with the "abort" flag.
+
+ Can also be used as a |method|: >
+ mylist->foreach(expr2)
<
*foreground()*
foreground() Move the Vim window to the foreground. Useful when sent from
diff --git a/runtime/doc/tags b/runtime/doc/tags
index b3691bb..40b90c0 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -5167,6 +5167,7 @@
E739 builtin.txt /*E739*
E74 message.txt /*E74*
E740 userfunc.txt /*E740*
+E741 builtin.txt /*E741*
E741 eval.txt /*E741*
E742 userfunc.txt /*E742*
E743 eval.txt /*E743*
@@ -7148,6 +7149,7 @@
font-sizes gui_x11.txt /*font-sizes*
fontset mbyte.txt /*fontset*
forced-motion motion.txt /*forced-motion*
+foreach() builtin.txt /*foreach()*
foreground() builtin.txt /*foreground()*
fork os_unix.txt /*fork*
form.vim syntax.txt /*form.vim*
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 2286d48..0990a06 100644
--- 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: 2023 May 06
+*usr_41.txt* For Vim version 9.1. Last change: 2024 Jan 13
VIM USER MANUAL - by Bram Moolenaar
@@ -798,6 +798,7 @@
filter() remove selected items from a List
map() change each List item
mapnew() make a new List with changed items
+ foreach() apply function to List items
reduce() reduce a List to a value
slice() take a slice of a List
sort() sort a List
@@ -829,6 +830,7 @@
filter() remove selected entries from a Dictionary
map() change each Dictionary entry
mapnew() make a new Dictionary with changed items
+ foreach() apply function to Dictionary items
keys() get List of Dictionary keys
values() get List of Dictionary values
items() get List of Dictionary key-value pairs