From 5ee090278eb1451159be0069ff0ad8b16a235bf8 Mon Sep 17 00:00:00 2001
From: "Sean T. Allen" <sean@seantallen.com>
Date: Sat, 29 Aug 2026 13:35:49 -0500
Subject: [PATCH] Document multi-iterator for loops

ponyc#5896 adds sugar for iterating multiple collections in a single
for loop. This covers the destructured binding form, shortest-iterator
semantics, and the desugared while-loop equivalent.
---
 ...tures-loops-for-multi-while-comparison.pony | 12 ++++++++++++
 .../control-structures-loops-for-multi.pony    |  7 +++++++
 docs/expressions/control-structures.md         | 18 ++++++++++++++++++
 3 files changed, 37 insertions(+)
 create mode 100644 code-samples/control-structures-loops-for-multi-while-comparison.pony
 create mode 100644 code-samples/control-structures-loops-for-multi.pony

diff --git a/code-samples/control-structures-loops-for-multi-while-comparison.pony b/code-samples/control-structures-loops-for-multi-while-comparison.pony
new file mode 100644
index 00000000..adf6c779
--- /dev/null
+++ b/code-samples/control-structures-loops-for-multi-while-comparison.pony
@@ -0,0 +1,12 @@
+actor Main
+  new create(env: Env) =>
+    let names = ["Alice"; "Bob"; "Carol"]
+    let scores = [as U32: 95; 87; 91]
+    try
+      let iter1 = names.values()
+      let iter2 = scores.values()
+      while iter1.has_next() and iter2.has_next() do
+        (let name, let score) = (iter1.next()?, iter2.next()?)
+        env.out.print(name + ": " + score.string())
+      end
+    end
diff --git a/code-samples/control-structures-loops-for-multi.pony b/code-samples/control-structures-loops-for-multi.pony
new file mode 100644
index 00000000..9e92f696
--- /dev/null
+++ b/code-samples/control-structures-loops-for-multi.pony
@@ -0,0 +1,7 @@
+actor Main
+  new create(env: Env) =>
+    let names = ["Alice"; "Bob"; "Carol"]
+    let scores = [as U32: 95; 87; 91]
+    for (name, score) in (names.values(), scores.values()) do
+      env.out.print(name + ": " + score.string())
+    end
diff --git a/docs/expressions/control-structures.md b/docs/expressions/control-structures.md
index 58cad63b..79cac1ae 100644
--- a/docs/expressions/control-structures.md
+++ b/docs/expressions/control-structures.md
@@ -173,6 +173,24 @@ Note that the variable __name__ is declared _let_, so you cannot assign to the c
 
 __Can I use break and continue with for loops?__ Yes, `for` loops can have `else` expressions attached and can use `break` and `continue` just as for `while`.
 
+#### Multiple iterators
+
+A `for` loop can iterate over multiple collections at once. Place a tuple of iterators after `in` and a matching tuple of names after `for`:
+
+```pony
+--8<-- "control-structures-loops-for-multi.pony:3:7"
+```
+
+The names after `for` are bound to the values from each iterator in order. The loop stops when any iterator is exhausted, so the shortest one determines the number of iterations.
+
+You can think of the multi-iterator form as equivalent to one iterator variable per position and an AND-chained condition:
+
+```pony
+--8<-- "control-structures-loops-for-multi-while-comparison.pony:6:11"
+```
+
+`break`, `continue`, and `else` work the same as with a single iterator.
+
 ### Repeat
 
 The final loop construct that Pony provides is `repeat` `until`. Here we evaluate the expression in the loop and then evaluate a condition expression to see if we're done or we should go round again.