=over

=item each HASH
X<each> X<hash, iterator>

=item each ARRAY
X<array, iterator>

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 L<C<each>|/each HASH> or
L<C<keys>|/keys HASH> may be deleted without changing the order.  So
long as a given hash is unmodified you may rely on
L<C<keys>|/keys HASH>, L<C<values>|/values HASH> and
L<C<each>|/each HASH> to repeatedly return the same order
as each other.  See L<perlsec/"Algorithmic Complexity Attacks"> 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 L<C<each>|/each HASH> has returned all entries from the hash or
array, the next call to L<C<each>|/each HASH> returns the empty list in
list context and L<C<undef>|/undef EXPR> in scalar context; the next
call following I<that> one restarts iteration.  Each hash or array has
its own internal iterator, accessed by L<C<each>|/each HASH>,
L<C<keys>|/keys HASH>, and L<C<values>|/values HASH>.  The iterator is
implicitly reset when L<C<each>|/each HASH> has reached the end as just
described; it can be explicitly reset by calling L<C<keys>|/keys HASH>
or L<C<values>|/values HASH> 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 L<C<each>|/each HASH>, so the following code works properly:

    while (my ($key, $value) = each %hash) {
        print $key, "\n";
        delete $hash{$key};   # This is safe
    }

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

The iterator used by C<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 C<each> on a single hash or array advance the same
iterator location.  All uses of C<each> are also subject to having the
iterator reset by any use of C<keys> or C<values> on the same hash or
array, or by the hash (but not array) being referenced in list context.
This makes C<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.

This extends to using C<each> on the result of an anonymous hash or
array constructor.  A new underlying array or hash is created each
time so each will always start iterating from scratch, eg:

  # loops forever
  while (my ($key, $value) = each %{ +{ a => 1 } }) {
      print "$key=$value\n";
  }

To avoid these problems resulting from the hash-embedded iterator, use a
L<C<foreach>|perlsyn/"Foreach Loops"> loop rather than C<while>-C<each>.
As of Perl 5.36, you can iterate over both keys and values directly with
a multiple-value C<foreach> loop.

  # retrieves the keys one time for iteration
  # iteration is unaffected by any operations on %hash within
  foreach my $key (keys %hash) {
      my $value = $hash{$key};
      $hash{$key} = {keys => scalar keys %hash, outer => [%hash]};
      some_function_that_may_mess_with(\%hash, $key, $value);
      $hash{"new$key"} = delete $hash{$key};
  }

  # Perl 5.36+
  foreach my ($key, $value) (%{ +{ a => 1 } }) {
      print "$key=$value\n";
  }

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

    while (my ($key,$value) = each %ENV) {
        print "$key=$value\n";
    }

Starting with Perl 5.14, an experimental feature allowed
L<C<each>|/each HASH> 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 L<C<each>|/each HASH> in a C<while>
loop, which will set L<C<$_>|perlvar/$_> on every iteration.
If either an C<each> expression or an explicit assignment of an C<each>
expression to a scalar is used as a C<while>/C<for> condition, then
the condition actually tests for definedness of the expression's value,
not for its regular truth value.

    while (each %ENV) {
	print "$_=$ENV{$_}\n";
    }

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 I<only> on Perls of
a recent vintage:

    use v5.12;	# so keys/values/each work on arrays
    use v5.18;	# so each assigns to $_ in a lone while test

See also L<C<keys>|/keys HASH>, L<C<values>|/values HASH>, and
L<C<sort>|/sort SUBNAME LIST>.

=back