Merge topic 'foreach-ZIP_LISTS'

d30468a2f6 foreach: Allow multiple iteration variables for `ZIP_LIST` mode
f3e51a2b1d foreach: Introduce `IN ZIP_LISTS` mode

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4021

2 files changed, 48 insertions, 0 deletions

diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst
index ecbfed3..a01a104 100644
--- a/Help/command/foreach.rst
+++ b/Help/command/foreach.rst
@@ -82,3 +82,46 @@ yields
   -- X=6
   -- X=7
   -- X=8
+
+
+.. code-block:: cmake
+
+  foreach(<loop_var>... IN ZIP_LISTS <lists>)
+
+In this variant, ``<lists>`` is a whitespace or semicolon
+separated list of list-valued variables. The ``foreach``
+command iterates over each list simultaneously setting the
+iteration variables as follows:
+
+- if the only ``loop_var`` given, then it sets a series of
+  ``loop_var_N`` variables to the current item from the
+  corresponding list;
+- if multiple variable names passed, their count should match
+  the lists variables count;
+- if any of the lists are shorter, the corresponding iteration
+  variable is not defined for the current iteration.
+
+.. code-block:: cmake
+
+  list(APPEND English one two three four)
+  list(APPEND Bahasa satu dua tiga)
+
+  foreach(num IN ZIP_LISTS English Bahasa)
+      message(STATUS "num_0=${num_0}, num_1=${num_1}")
+  endforeach()
+
+  foreach(en ba IN ZIP_LISTS English Bahasa)
+      message(STATUS "en=${en}, ba=${ba}")
+  endforeach()
+
+yields
+::
+
+  -- num_0=one, num_1=satu
+  -- num_0=two, num_1=dua
+  -- num_0=three, num_1=tiga
+  -- num_0=four, num_1=
+  -- en=one, ba=satu
+  -- en=two, ba=dua
+  -- en=three, ba=tiga
+  -- en=four, ba=
diff --git a/Help/release/dev/foreach-ZIP_LISTS.rst b/Help/release/dev/foreach-ZIP_LISTS.rst
new file mode 100644
index 0000000..d45d9b9
--- /dev/null
+++ b/Help/release/dev/foreach-ZIP_LISTS.rst
@@ -0,0 +1,5 @@
+foreach-ZIP_LISTS
+-----------------
+
+* The :command:`foreach` learned a new option ``ZIP_LISTS`` to iterate
+  over multiple lists simultaneously.