each

When called on a hash in list context, returns a 2-element list
consisting of the key and value for the next element of a hash. In Perl
5.12 and later only, it will also return the index and value for the next
element of an array so that you can iterate over it; older Perls consider
this a syntax error. 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 specific to a given hash; the exact same series of operations
on two hashes may result in a different order for each hash. Any insertion
into the hash may change the order, as will any deletion, with the exception
that the most recent key returned by each or
keys may be deleted without changing the order. So
long as a given hash is unmodified you may rely on
keys, values and
each to repeatedly return the same order
as each other. See Algorithmic Complexity Attacks in perlsec for
details on why hash order is randomized. Aside from the guarantees
provided here the exact details of Perl's hash algorithm and the hash
traversal order are subject to change in any release of Perl.

After each has returned all entries from the hash or
array, the next call to each returns the empty list in
list context and undef in scalar context; the next
call following that one restarts iteration. Each hash or array has
its own internal iterator, accessed by each,
keys, and values. The iterator is
implicitly reset when each has reached the end as just
described; it can be explicitly reset by calling keys
or values on the hash or array, or by referencing
the hash (but not array) in list context. If you add or delete
a hash's elements while iterating over it, the effect on the iterator is
unspecified; for example, entries may be skipped or duplicated--so don't
do that. Exception: It is always safe to delete the item most recently
returned by each, so the following code works properly:

Tied hashes may have a different ordering behaviour to perl's hash
implementation.

The iterator used by each is attached to the hash or array, and is
shared between all iteration operations applied to the same hash or array.
Thus all uses of each on a single hash or array advance the same
iterator location. All uses of each are also subject to having the
iterator reset by any use of keys or values on the same hash or
array, or by the hash (but not array) being referenced in list context.
This makes each-based loops quite fragile: it is easy to arrive at
such a loop with the iterator already part way through the object, or to
accidentally clobber the iterator state during execution of the loop body.
It's easy enough to explicitly reset the iterator before starting a loop,
but there is no way to insulate the iterator state used by a loop from
the iterator state used by anything else that might execute during the
loop body. To avoid these problems, use a foreach loop rather than
while-each.

This prints out your environment like the printenv(1) program,
but in a different order:

Starting with Perl 5.14, an experimental feature allowed
each to take a scalar expression. This experiment has
been deemed unsuccessful, and was removed as of Perl 5.24.

As of Perl 5.18 you can use a bare each in a while
loop, which will set $_ on every iteration.
If either an each expression or an explicit assignment of an each
expression to a scalar is used as a while/for condition, then
the condition actually tests for definedness of the expression's value,
not for its regular truth value.

To avoid confusing would-be users of your code who are running earlier
versions of Perl with mysterious syntax errors, put this sort of thing at
the top of your file to signal that your code will work only on Perls of
a recent vintage: