NAME

each - retrieve the next key/value pair from a hash

SYNOPSIS

each HASH

DESCRIPTION

When called in a list context, returns a 2-element array consisting of the key and value for the next element of a hash, so that you can iterate over it. When called in a scalar context, returns the key for only the next element in the hash. (Note: Keys may be ``0'' or ``'', which are logically false; you may wish to avoid constructs like while {} for this reason.)

Entries are returned in an apparently random order. When the hash is entirely read, a null array is returned in list context (which when assigned produces a FALSE (0) value), and undef is returned in a scalar context. The next call to each after that will start iterating again. There is a single iterator for each hash, shared by all each, keys, and values function calls in the program; it can be reset by reading all the elements from the hash, or by evaluating keys HASH or values HASH. If you add or delete elements of a hash while you're iterating over it, you may get entries skipped or duplicated, so don't.

The following prints out your environment like the printenv program, only in a different order:

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