From bbc162f9794e3b63442d525890569f24b3356c3f Mon Sep 17 00:00:00 2001
From: Torben Wilson <torben@php.net>
Date: Sat, 11 Dec 1999 00:43:25 +0000
Subject: [PATCH] Put foreach() into its own section and clarified some stuff.
 Also copied it into the German tree.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@17020 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/control-structures.xml | 151 ++++++++++++++++++++++----------
 1 file changed, 105 insertions(+), 46 deletions(-)

diff --git a/language/control-structures.xml b/language/control-structures.xml
index 495e5b1be4..53ed8d48b9 100644
--- a/language/control-structures.xml
+++ b/language/control-structures.xml
@@ -333,7 +333,8 @@
       <programlisting>
 for (expr1; expr2; expr3) statement
       </programlisting>
-     </informalexample></para>
+     </informalexample>
+   </para>
  
     <simpara>
      The first expression (<replaceable>expr1</replaceable>) is evaluated
@@ -412,36 +413,96 @@ for (expr1; expr2; expr3) statement
       </programlisting>
      </informalexample></para>
  
-    <para>
-     Other languages have a foreach statement to traverse an array or
-     hash. PHP uses the while statement and the <function>list</function>
-     and <function>each</function> functions for this. See the
-     documentation for these functions for an example.</para>
+   <para>
+    Other languages have a <literal>foreach</literal> statement to
+    traverse an array or hash. PHP3 has no such construct; PHP4 does
+    (see <link
+    linkend="control-structures.foreach">foreach</link>). In PHP3, you
+    can combine <link linkend="control-structures.while">while</link>
+    with the <function>list</function> and <function>each</function>
+    functions to achieve the same effect. See the documentation for
+    these functions for an example.
+   </para>
 
-     <para>
-     A foreach statement has been added to PHP4. There are two supported
-     syteaxes:</para>
+  </sect1>
+
+  <sect1 id="control-structures.foreach">
+   <title><literal>foreach</literal></title>
+
+   <para>
+    PHP4 (not PHP3) includes a <literal>foreach</literal> construct,
+    much like perl and some other languages. This simply gives an easy 
+    way to iterate over arrays. There are two syntaxes; the second is
+    a minor but useful extension of the first:
+    <informalexample>
+     <programlisting>
+foreach(array_expression as $value) statement
+foreach(array_expression as $key => $value) statement
+     </programlisting>
+    </informalexample>
+   </para>
      
-     <para>
-     foreach(array_expression as $v): This will loop through array_expression
-     assigning the value of the array at the current position to $v, and then 
-     advances the postion by one. See examples 1 and 2 below.</para>
+   <simpara>
+    The first form loops over the array given by
+    <literal>array_expression</literal>. On each loop, the value of
+    the current element is assigned to <literal>$value</literal> and
+    the internal array pointer is advanced by one (so on the next
+    loop, you'll be looking at the next element).
+   </simpara>
 
-     <para>
-     foreach(array_expression as $k => $v): This will loop through
-     array_expression assigning the key of the array at the current position
-     to $k and the value of the array at the current position to $v, and then
-     advances the postion by one. See example 3 below.</para>
+   <simpara>
+    The second form does the same thing, except that the current
+    element's key will be assigned to the variable
+    <literal>$key</literal> on each loop.
+   </simpara>
 
-     <informalexample>
-      <programlisting>
+   <simpara>
+    When <literal>foreach</literal> first starts executing, the
+    internal array pointer is automatically reset to the first element 
+    of the array. This means that you do not need to call
+    <function>reset</function> before a <literal>foreach</literal>
+    loop.
+   </simpara>
 
+   <para>
+    You may have noticed that the following are functionally
+    identical:
+    <informalexample>
+     <programlisting>
+reset( $arr );
+while( list( , $value ) = each( $arr ) ) {
+   echo "Value: $value&lt;br&gt;\n";
+}
+
+foreach( $arr as $value ) {
+   echo "Value: $value&lt;br&gt;\n";
+}
+     </programlisting>
+    </informalexample>
+    The following are also functionally identical:
+    <informalexample>
+     <programlisting>
+reset( $arr );
+while( list( $key, $value ) = each( $arr ) ) {
+   echo "Key: $key; Value: $value&lt;br&gt;\n";
+}
+
+foreach( $arr as $key => $value ) {
+   echo "Key: $key; Value: $value&lt;br&gt;\n";
+}
+     </programlisting>
+    </informalexample>
+   </para>
+
+   <para>
+    Some more examples to demonstrate usages:
+    <informalexample>
+     <programlisting>
 /* foreach example 1: value only */
 $a = array(1, 2, 3, 17);
 
-foreach($a as $v)
-{
-print "Current value of \$a: $v.\n";
+foreach($a as $v) {
+   print "Current value of \$a: $v.\n";
 }
 
 /* foreach example 2: value (with key printed for illustration) */
@@ -449,29 +510,27 @@ $a = array(1, 2, 3, 17);
 
 $i = 0; /* for illustrative purposes only */
 
-foreach($a as $v)
-{
-print "\$a[$i] => $k.\n";
+foreach($a as $v) {
+   print "\$a[$i] => $k.\n";
 }
 
-
 /* foreach example 3: key and value */
+$a = array(
+   "one" => 1,
+   "two" => 2,
+   "three" => 3,
+   "seventeen" => 17
+);
 
-$a = array("one" => 1,
-           "two" => 2,
-	   "three" => 3,
-	   "seventeen" => 17);
-
-foreach($a as $k => $v)
-{
-print "\$a[$k] => $v.\n";
+foreach($a as $k => $v) {
+   print "\$a[$k] => $v.\n";
 }
+     </programlisting>
+    </informalexample>
 
+   </para>
 
-      </programlisting>
-     </informalexample>
-
-     </sect1>
+  </sect1>
  
  
    <sect1 id="control-structures.break">
@@ -482,13 +541,13 @@ print "\$a[$k] => $v.\n";
  
      <informalexample>
       <programlisting>
- $i = 0;
- while ($i < 10) {
-     if ($arr[$i] == "stop") {
-         break;
-     }
-     $i++;
- }
+$i = 0;
+while ($i < 10) {
+   if ($arr[$i] == "stop") {
+      break;
+   }
+   $i++;
+}
       </programlisting>
      </informalexample></para></sect1>