When called in list context, returns a 2-element list consisting of the key and value for the next element of a hash, or the index and value for the next element of an array, so that you can iterate over it. When called in scalar context, returns only the key (not the value) in a hash, or the index in an array.
Hash entries are returned in an apparently random order. The actual random order is subject to change in future versions of Perl, but it is guaranteed to be in the same order as either thekeys orvalues function would produce on the same (unmodified) hash. Since Perl 5.8.2 the ordering can be different even between different runs of Perl for security reasons (see"Algorithmic Complexity Attacks" in perlsec).
Aftereach has returned all entries from the hash or array, the next call toeach returns the empty list in list context andundef in scalar context. The next call following that one restarts iteration. Each hash or array has its own internal iterator, accessed byeach,keys, andvalues. The iterator is implicitly reset wheneach has reached the end as just described; it can be explicitly reset by callingkeys orvalues on the hash or array. If you add or delete a hash's elements while iterating over it, entries may be skipped or duplicated--so don't do that. Exception: It is always safe to delete the item most recently returned byeach(), so the following code works properly:
while (($key, $value) = each %hash) { print $key, "\n"; delete $hash{$key}; # This is safe}This prints out your environment like the printenv(1) program, but in a different order:
while (($key,$value) = each %ENV) { print "$key=$value\n";}See alsokeys,values andsort.
Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via theGitHub issue tracker oremail regarding any issues with the site itself, search, or rendering of documentation.
The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via thePerl issue tracker, themailing list, orIRC to report any issues with the contents or format of the documentation.