each#

Step through a hash or array one entry at a time.

each advances a per-container iterator and hands back the next entry. For a hash that entry is a (key, value) pair; for an array it is an (index, value) pair. When the iterator has walked every entry, the next call returns the empty list (or undef in scalar context) and then rewinds, so a fresh while (each ...) loop starts from the beginning. Hash order is randomised per process and per hash; array order is strictly lowest index first.

Synopsis#

while (my ($k, $v) = each %h) { ... }
while (my ($i, $v) = each @a) { ... }
while (each %h) { ... }             # sets $_ to the key
my $k = each %h;                    # scalar context: key/index only

What you get back#

List context: a two-element list ($key, $value) for a hash, ($index, $value) for an array. On exhaustion, the empty list.
Scalar context: the key (for a hash) or the index (for an array). On exhaustion, undef.
Bare each %h in a while/for condition: tests definedness of the returned key/index, not truth, and assigns the key to $_. This is what makes while (each %h) { print "$_\n" } work even when a key is the empty string or 0.

After exhaustion the iterator is implicitly reset, so the call after the one that returned empty restarts iteration from the top.

Global state it touches#

Every hash and every array carries its own internal iterator. each, keys, and values all advance and share that one iterator — they are three views of the same cursor, not three independent loops. This is the single most important fact about each:

Calling keys %h or values %h (in any context, even as a one-off count like scalar keys %h) resets the hash’s iterator. A while (each %h) loop interrupted by scalar keys %h in the body will restart from the top on the next iteration — or worse, loop forever.
Referencing a hash in list context resets its iterator too (e.g. my @copy = %h, or passing %h to a sub). Array iterators are not reset by list-context reference.
Two loops iterating the same %h share one cursor. Nesting while (each %h) { ... while (each %h) { ... } ... } visits each entry at most once total, not n * m times.
An anonymous hash/array in the condition (each %{ +{ a => 1 } }) builds a new container every iteration, so the iterator is always fresh — the loop never terminates.
The bare-each form assigns to $_; if you rely on $_ elsewhere in the loop body, save it with local.

Every entry to a while (each ...) loop picks up whatever iterator position the container happens to be at. There is no way to isolate a loop’s iterator from other code that touches the same container. If the loop body calls a function that might read the same hash, the safe pattern is a foreach loop over keys instead.

Examples#

Basic hash iteration:

my %colour = (red => "#f00", green => "#0f0", blue => "#00f");
while (my ($name, $hex) = each %colour) {
    print "$name = $hex\n";
}
# order is unspecified

Array iteration (Perl 5.12+):

my @letters = ('a' .. 'e');
while (my ($i, $c) = each @letters) {
    print "[$i] $c\n";
}
# [0] a
# [1] b
# [2] c
# [3] d
# [4] e

Printing a hash in sorted order — each does not sort, so reach for keys plus sort instead:

for my $k (sort keys %colour) {
    print "$k = $colour{$k}\n";
}

Bare each in a while condition, which sets $_ to the key every iteration (Perl 5.18+):

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

Safe deletion during iteration — you may delete the key just returned by each without disturbing the cursor:

while (my ($key, $value) = each %hash) {
    delete $hash{$key} if $value < 0;   # safe
}

Iterating a hash with a foreach loop when anything in the body might touch %hash (the robust pattern — snapshot the keys first):

for my $key (keys %hash) {
    my $value = $hash{$key};
    # body is free to read %hash, call subs that read it, even
    # mutate it cautiously — our iteration list is fixed already.
}

Multi-value foreach over a hash (Perl 5.36+), which makes each unnecessary for most loops and sidesteps the shared-iterator trap:

foreach my ($key, $value) (%hash) {
    print "$key => $value\n";
}

Edge cases#

Iterator not reset between re-entries: a while (each %h) loop that exits early via last, return, or die leaves the iterator mid-walk. The next while (each %h) on the same hash picks up where the first left off, not at the start. Call keys %h in void context — keys %h; — to force a reset before the new loop.
keys/values resets the iterator: any call to keys or values on the same hash — including scalar keys %h inside the loop body — rewinds the cursor.
List-context reference resets a hash’s iterator, not an array’s: my @flat = %h rewinds %h’s cursor; the equivalent my @copy = @a does not touch @a’s iterator.
Delete-during-iteration is unspecified except for the entry most recently returned. Deleting any other key may cause entries to be visited twice or skipped entirely.
Add-during-iteration is unspecified — inserting a new key mid loop may or may not be visited, and may disturb the order of entries not yet seen.
Anonymous container in the condition: each %{ +{ a => 1 } } or each @{ [1,2,3] } constructs a fresh container each time the condition is evaluated, so the iterator is always new and the loop never terminates.
Tied hashes and arrays delegate to FIRSTKEY/NEXTKEY (hashes) or FETCHSIZE/FETCH (arrays), so iteration order is whatever the tied class chooses and none of the guarantees above necessarily hold.
Definedness vs truth in the loop condition: while (each %h) and while (my $k = each %h) both test definedness of the expression, so a key of "0" or "" does not terminate the loop. This is special-cased for each specifically.
Scalar expressions: each $href on a scalar holding a reference was an experimental feature in 5.14 and was removed in 5.24. Dereference explicitly: each %$href, each @$aref.
Shared state across subs: passing %h to a sub that calls each %h, keys %h, or values %h on it perturbs your caller’s iterator. If you publish a hash, assume callers may break your loop; prefer foreach (keys ...) for robustness.

Differences from upstream#

Fully compatible with upstream Perl 5.42.