perlfunc
gods
<P>
each - retrieve the next key/value pair from a hash
<P>
<HR>
<P>
each
<FONT SIZE=-1>HASH</FONT>
<P>
<HR>
<P>
When called in list context, returns a 2-element list consisting of the key
and value for the next element of a hash, so that you can iterate over it.
When called in scalar context, returns the key for only the ``next''
element in the hash. (Note: Keys may be <CODE>"0"</CODE> or <CODE>""</CODE>, which are logically false; you may wish to avoid constructs like <CODE>while ($k = each %foo) {}</CODE>
for this reason.)
<P>
Entries are returned in an apparently random order. When the hash is entirely read, a null array is returned in list context (which when assigned produces a
<FONT SIZE=-1>FALSE</FONT> (
<CODE>0</CODE>) value), and [perlfunc:undef|undef] in scalar context. The next call to [perlfunc:each|each()] after that will start iterating again. There is a single iterator for each
hash, shared by all [perlfunc:each|each()],
[perlfunc:keys|keys()], and [perlfunc:values|values()] function calls in the program; it can be reset by reading all the elements
from the hash, or by evaluating <CODE>keys HASH</CODE> or
<CODE>values HASH</CODE>. If you add or delete elements of a hash while you're iterating over it,
you may get entries skipped or duplicated, so don't.
<P>
The following prints out your environment like the
<CODE>printenv(1)</CODE> program, only
in a different order:
<P>
<PRE> while (($key,$value) = each %ENV) {
print "$key=$value\n";
}
</PRE>
<P>
See also [perlfunc:keys|keys()] and [perlfunc:values|values()].
<HR>