mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00
309 lines
6.7 KiB
XML
309 lines
6.7 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<sect1 xml:id="control-structures.foreach" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>foreach</title>
|
|
<?phpdoc print-version-for="foreach"?>
|
|
<para>
|
|
The <literal>foreach</literal> construct provides an easy way to
|
|
iterate over arrays. <literal>foreach</literal> works only on arrays
|
|
and objects, and will issue an error when you try to use it on a variable
|
|
with a different data type or an uninitialized variable. There are two
|
|
syntaxes:
|
|
<informalexample>
|
|
<programlisting>
|
|
<![CDATA[
|
|
foreach (iterable_expression as $value)
|
|
statement
|
|
foreach (iterable_expression as $key => $value)
|
|
statement
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
The first form traverses the iterable given by
|
|
<literal>iterable_expression</literal>. On each iteration, the value of
|
|
the current element is assigned to <literal>$value</literal>.
|
|
</simpara>
|
|
<simpara>
|
|
The second form will additionally assign the current element's key to
|
|
the <literal>$key</literal> variable on each iteration.
|
|
</simpara>
|
|
<simpara>
|
|
Note that <literal>foreach</literal> does not modify the internal array
|
|
pointer, which is used by functions such as <function>current</function>
|
|
and <function>key</function>.
|
|
</simpara>
|
|
<simpara>
|
|
It is possible to
|
|
<link linkend="language.oop5.iterations">customize object iteration</link>.
|
|
</simpara>
|
|
|
|
<para>
|
|
In order to be able to directly modify array elements within the loop precede
|
|
<literal>$value</literal> with &. In that case the value will be assigned by
|
|
<link linkend="language.references">reference</link>.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$arr = array(1, 2, 3, 4);
|
|
foreach ($arr as &$value) {
|
|
$value = $value * 2;
|
|
}
|
|
// $arr is now array(2, 4, 6, 8)
|
|
unset($value); // break the reference with the last element
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
Reference of a <literal>$value</literal> and the last array element
|
|
remain even after the <literal>foreach</literal> loop. It is recommended
|
|
to destroy it by <function>unset</function>.
|
|
Otherwise you will experience the following behavior:
|
|
</para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$arr = array(1, 2, 3, 4);
|
|
foreach ($arr as &$value) {
|
|
$value = $value * 2;
|
|
}
|
|
// $arr is now array(2, 4, 6, 8)
|
|
|
|
// without an unset($value), $value is still a reference to the last item: $arr[3]
|
|
|
|
foreach ($arr as $key => $value) {
|
|
// $arr[3] will be updated with each value from $arr...
|
|
echo "{$key} => {$value} ";
|
|
print_r($arr);
|
|
}
|
|
// ...until ultimately the second-to-last value is copied onto the last value
|
|
|
|
// output:
|
|
// 0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
|
|
// 1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
|
|
// 2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
|
|
// 3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</warning>
|
|
<para>
|
|
It is possible to iterate a constant array's value by reference:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
foreach (array(1, 2, 3, 4) as &$value) {
|
|
$value = $value * 2;
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
<literal>foreach</literal> does not support the ability to
|
|
suppress error messages using
|
|
<literal linkend="language.operators.errorcontrol">@</literal>.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
Some more examples to demonstrate usage:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/* foreach example 1: value only */
|
|
|
|
$a = array(1, 2, 3, 17);
|
|
|
|
foreach ($a as $v) {
|
|
echo "Current value of \$a: $v.\n";
|
|
}
|
|
|
|
/* foreach example 2: value (with its manual access notation printed for illustration) */
|
|
|
|
$a = array(1, 2, 3, 17);
|
|
|
|
$i = 0; /* for illustrative purposes only */
|
|
|
|
foreach ($a as $v) {
|
|
echo "\$a[$i] => $v.\n";
|
|
$i++;
|
|
}
|
|
|
|
/* foreach example 3: key and value */
|
|
|
|
$a = array(
|
|
"one" => 1,
|
|
"two" => 2,
|
|
"three" => 3,
|
|
"seventeen" => 17
|
|
);
|
|
|
|
foreach ($a as $k => $v) {
|
|
echo "\$a[$k] => $v.\n";
|
|
}
|
|
|
|
/* foreach example 4: multi-dimensional arrays */
|
|
$a = array();
|
|
$a[0][0] = "a";
|
|
$a[0][1] = "b";
|
|
$a[1][0] = "y";
|
|
$a[1][1] = "z";
|
|
|
|
foreach ($a as $v1) {
|
|
foreach ($v1 as $v2) {
|
|
echo "$v2\n";
|
|
}
|
|
}
|
|
|
|
/* foreach example 5: dynamic arrays */
|
|
|
|
foreach (array(1, 2, 3, 4, 5) as $v) {
|
|
echo "$v\n";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<sect2 xml:id="control-structures.foreach.list">
|
|
<title>Unpacking nested arrays with list()</title>
|
|
<?phpdoc print-version-for="foreach.list"?>
|
|
|
|
<para>
|
|
It is possible to iterate over an array of arrays and unpack the
|
|
nested array into loop variables by providing a <function>list</function>
|
|
as the value.
|
|
</para>
|
|
|
|
<para>
|
|
For example:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$array = [
|
|
[1, 2],
|
|
[3, 4],
|
|
];
|
|
|
|
foreach ($array as list($a, $b)) {
|
|
// $a contains the first element of the nested array,
|
|
// and $b contains the second element.
|
|
echo "A: $a; B: $b\n";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
A: 1; B: 2
|
|
A: 3; B: 4
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
You can provide fewer elements in the <function>list</function> than there
|
|
are in the nested array, in which case the leftover array values will be
|
|
ignored:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$array = [
|
|
[1, 2],
|
|
[3, 4],
|
|
];
|
|
|
|
foreach ($array as list($a)) {
|
|
// Note that there is no $b here.
|
|
echo "$a\n";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
1
|
|
3
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
A notice will be generated if there aren't enough array elements to fill
|
|
the <function>list</function>:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$array = [
|
|
[1, 2],
|
|
[3, 4],
|
|
];
|
|
|
|
foreach ($array as list($a, $b, $c)) {
|
|
echo "A: $a; B: $b; C: $c\n";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
|
|
Notice: Undefined offset: 2 in example.php on line 7
|
|
A: 1; B: 2; C:
|
|
|
|
Notice: Undefined offset: 2 in example.php on line 7
|
|
A: 3; B: 4; C:
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|