<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Return the current key and value pair from an array and advance the array cursor</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.current.html">current</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.end.html">end</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.each" class="refentry">
<div class="refnamediv">
<h1 class="refname">each</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">each</span> — <span class="dc-title">Return the current key and value pair from an array and advance the array cursor</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.each-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">array</span> <span class="methodname"><strong>each</strong></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$array</code></span>
)</div>
<p class="para rdfs-comment">
Return the current key and value pair from an array and advance the array
cursor.
</p>
<p class="para">
After <span class="function"><strong>each()</strong></span> has executed, the array cursor
will be left on the next element of the array, or past the last
element if it hits the end of the array. You have to use
<span class="function"><a href="function.reset.html" class="function">reset()</a></span> if you want to traverse the array
again using each.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.each-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">array</code></em></span>
<dd>
<p class="para">
The input array.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.each-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns the current key and value pair from the array
<em><code class="parameter">array</code></em>. This pair is returned in a four-element
array, with the keys <em>0</em>, <em>1</em>,
<em>key</em>, and <em>value</em>. Elements
<em>0</em> and <em>key</em> contain the key name of
the array element, and <em>1</em> and <em>value</em>
contain the data.
</p>
<p class="para">
If the internal pointer for the array points past the end of the
array contents, <span class="function"><strong>each()</strong></span> returns
<strong><code>FALSE</code></strong>.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.each-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-5009">
<p><strong>Example #1 <span class="function"><strong>each()</strong></span> examples</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$foo </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"bob"</span><span style="color: #007700">, </span><span style="color: #DD0000">"fred"</span><span style="color: #007700">, </span><span style="color: #DD0000">"jussi"</span><span style="color: #007700">, </span><span style="color: #DD0000">"jouni"</span><span style="color: #007700">, </span><span style="color: #DD0000">"egon"</span><span style="color: #007700">, </span><span style="color: #DD0000">"marliese"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$bar </span><span style="color: #007700">= </span><span style="color: #0000BB">each</span><span style="color: #007700">(</span><span style="color: #0000BB">$foo</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$bar</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
<var class="varname"><var class="varname">$bar</var></var> now contains the following key/value
pairs:
</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Array
(
[1] => bob
[value] => bob
[0] => 0
[key] => 0
)
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$foo </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"Robert" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Bob"</span><span style="color: #007700">, </span><span style="color: #DD0000">"Seppo" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Sepi"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$bar </span><span style="color: #007700">= </span><span style="color: #0000BB">each</span><span style="color: #007700">(</span><span style="color: #0000BB">$foo</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$bar</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<p class="para">
<var class="varname"><var class="varname">$bar</var></var> now contains the following key/value
pairs:
</p>
<div class="example-contents screen">
<div class="cdata"><pre>
Array
(
[1] => Bob
[value] => Bob
[0] => Robert
[key] => Robert
)
</pre></div>
</div>
</div>
</p>
<p class="para">
<span class="function"><strong>each()</strong></span> is typically used in conjunction with
<span class="function"><a href="function.list.html" class="function">list()</a></span> to traverse an array, here's an
example:
<div class="example" id="example-5010">
<p><strong>Example #2 Traversing an array with <span class="function"><strong>each()</strong></span></strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$fruit </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'a' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'apple'</span><span style="color: #007700">, </span><span style="color: #DD0000">'b' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'banana'</span><span style="color: #007700">, </span><span style="color: #DD0000">'c' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'cranberry'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">reset</span><span style="color: #007700">(</span><span style="color: #0000BB">$fruit</span><span style="color: #007700">);<br />while (list(</span><span style="color: #0000BB">$key</span><span style="color: #007700">, </span><span style="color: #0000BB">$val</span><span style="color: #007700">) = </span><span style="color: #0000BB">each</span><span style="color: #007700">(</span><span style="color: #0000BB">$fruit</span><span style="color: #007700">)) {<br /> echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$key</span><span style="color: #DD0000"> => </span><span style="color: #0000BB">$val</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
a => apple
b => banana
c => cranberry
</pre></div>
</div>
</div>
</p>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
Because assigning an array to another variable resets the original
arrays pointer, our example above would cause an endless loop had we
assigned <var class="varname"><var class="varname">$fruit</var></var> to another variable inside the
loop.
</p>
</div>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
<span class="function"><strong>each()</strong></span> will also accept objects, but may return unexpected
results. Its therefore not recommended to iterate though object properties
with <span class="function"><strong>each()</strong></span>.
</p>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-function.each-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.key.html" class="function" rel="rdfs-seeAlso">key()</a> - Fetch a key from an array</span></li>
<li class="member"> <span class="function"><a href="function.list.html" class="function" rel="rdfs-seeAlso">list()</a> - Assign variables as if they were an array</span></li>
<li class="member"> <span class="function"><a href="function.current.html" class="function" rel="rdfs-seeAlso">current()</a> - Return the current element in an array</span></li>
<li class="member"> <span class="function"><a href="function.reset.html" class="function" rel="rdfs-seeAlso">reset()</a> - Set the internal pointer of an array to its first element</span></li>
<li class="member"> <span class="function"><a href="function.next.html" class="function" rel="rdfs-seeAlso">next()</a> - Advance the internal array pointer of an array</span></li>
<li class="member"> <span class="function"><a href="function.prev.html" class="function" rel="rdfs-seeAlso">prev()</a> - Rewind the internal array pointer</span></li>
<li class="member"><a href="control-structures.foreach.html" class="link">foreach</a></li>
<li class="member"><a href="language.oop5.iterations.html" class="link">Object Iteration</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.current.html">current</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.end.html">end</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
