From c216ba2dfee66b15e06e5c85fa0a9b9f7c82894b Mon Sep 17 00:00:00 2001
From: Chris Angelico <rosuav@gmail.com>
Date: Thu, 27 Sep 2012 16:56:15 +1000
Subject: [PATCH] Document the three-arg form of foreach

---
 refdoc/chapters/control_structures.xml | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/refdoc/chapters/control_structures.xml b/refdoc/chapters/control_structures.xml
index 4af6274307..c52ea00a49 100644
--- a/refdoc/chapters/control_structures.xml
+++ b/refdoc/chapters/control_structures.xml
@@ -253,7 +253,7 @@ this:</p>
 
 <example>
 foreach ( array_expression, variable )
-  statement ;
+  statement;
 </example>
 
 <p>We have already seen an example of <tt>foreach</tt> in the <tt>find_song</tt>
@@ -273,7 +273,7 @@ function in chapter 2. What foreach does is:</p>
 doing the same thing with a <tt>for</tt> loop, as shown here:</p>
 
 <example>
-array tmp1= array_expression;
+array tmp1 = array_expression;
 for ( tmp2 = 0; tmp2 &lt; sizeof(tmp1); tmp2++ )
 {
   variable = tmp1 [ tmp2 ];
@@ -281,6 +281,27 @@ for ( tmp2 = 0; tmp2 &lt; sizeof(tmp1); tmp2++ )
 }
 </example>
 
+<p><tt>Foreach</tt> can also iterate over a mapping, providing both the key and the
+value at the same time:</p>
+
+<example>
+foreach ( mapping_expression; variable1; variable2 )
+  statement;
+</example>
+
+<p>This is approximately equivalent to:</p>
+
+<example>
+mapping tmp1 = mapping_expression;
+array tmp2 = indices(tmp1);
+for ( tmp3 = 0; tmp3 &lt; sizeof(tmp2); tmp3++ )
+{
+  variable1 = tmp2 [ tmp3 ];
+  variable2 = tmp1 [ variable1 ];
+  statement;
+}
+</example>
+
 </subsection>
 </section>
 
-- 
GitLab