---
name: each
signatures:
  - 'each HASH'
  - 'each ARRAY'
since: 5.0
status: documented
categories: ["Arrays", "Hashes"]
---

```{index} single: each; Perl built-in
```

*[Arrays](../perlfunc-by-category) · [Hashes](../perlfunc-by-category)*

# 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`](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

```perl
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`](undef).
- **Bare `each %h` in a `while`/`for` condition**: tests
  *definedness* of the returned key/index, not truth, and assigns the
  key to [`$_`](../perlvar). 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`](keys), and [`values`](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 [`$_`](../perlvar); if you rely on
  [`$_`](../perlvar) elsewhere in the loop body, save it with [`local`](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`](keys) instead.

## Examples

Basic hash iteration:

```perl
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+):

```perl
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`](keys) plus [`sort`](sort) instead:

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

Bare `each` in a `while` condition, which sets [`$_`](../perlvar) to the key every
iteration (Perl 5.18+):

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

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

```perl
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):

```perl
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:

```perl
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`](last), [`return`](return), or [`die`](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`](keys)/[`values`](values) resets the iterator**: any call to
  [`keys`](keys) or [`values`](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.

## See also

- [`keys`](keys) — snapshot of all keys (hash) or indices (array);
  **resets the iterator** `each` uses
- [`values`](values) — snapshot of all values; **resets the
  iterator** `each` uses
- [`delete`](delete) — safe for the entry just returned by `each`,
  unsafe for any other during iteration
- [`exists`](exists) — test key/index membership without perturbing
  the iterator
- `for` / `foreach` — the safer loop when the body might
  touch the container; combine with [`keys`](keys) to snapshot first
- [`sort`](sort) — pair with [`keys`](keys) when you need a defined
  iteration order; `each` never sorts