diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 647566ee6895..fc9b6c6d7ac6 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -2130,20 +2130,23 @@ X X =item each ARRAY X -=for Pod::Functions retrieve the next key/value pair from a hash +=for Pod::Functions retrieve the next key/value pair from a hash or index/value from an array 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. +consisting of the key and value for the next element of a hash. +When called in scalar context, returns only the key (not the value). + +When called on an array in list context, in Perl 5.12 and later, it +returns a 2-element list consisting of the index and value for the next +element of the array so that you can iterate over it; older Perls +consider this a syntax error. When called in scalar context, returns +only the index in the 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|/each HASH> or +that the most recent key returned by C or L|/keys HASH> may be deleted without changing the order. So long as a given hash is unmodified you may rely on L|/keys HASH>, L|/values HASH> and @@ -2153,20 +2156,31 @@ 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|/each HASH> has returned all entries from the hash or -array, the next call to L|/each HASH> returns the empty list in +Array entries are returned lowest index first. + + my @colors = (qw(red, green, blue)); + while (my ($index, $value) = each @colors) { + print "[$index] = $value\n"; + } + + [0] = red + [1] = green + [2] = blue + +After C has returned all entries from the hash or +array, the next call to C returns the empty list in list context and L|/undef EXPR> in scalar context; the next call following I one restarts iteration. Each hash or array has -its own internal iterator, accessed by L|/each HASH>, +its own internal iterator, accessed by C, L|/keys HASH>, and L|/values HASH>. The iterator is -implicitly reset when L|/each HASH> has reached the end as just +implicitly reset when C has reached the end as just described; it can be explicitly reset by calling L|/keys HASH> or L|/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|/each HASH>, so the following code works properly: +returned by C, so the following code works properly: while (my ($key, $value) = each %hash) { print $key, "\n"; @@ -2178,7 +2192,7 @@ implementation. The iterator used by C 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 on a single hash or array advance the same +Thus all uses of C on a particular hash or array advance the same iterator location. All uses of C are also subject to having the iterator reset by any use of C or C on the same hash or array, or by the hash (but not array) being referenced in list context. @@ -2226,10 +2240,10 @@ but in a different order: } Starting with Perl 5.14, an experimental feature allowed -L|/each HASH> to take a scalar expression. This experiment has +C 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|/each HASH> in a C +As of Perl 5.18 you can use a bare C in a C loop, which will set L|perlvar/$_> on every iteration. If either an C expression or an explicit assignment of an C expression to a scalar is used as a C/C condition, then @@ -3930,21 +3944,23 @@ X X =item keys ARRAY -=for Pod::Functions retrieve list of indices from a hash +=for Pod::Functions retrieve list of indices from a hash or array Called in list context, returns a list consisting of all the keys of the -named hash, or in Perl 5.12 or later only, the indices of an array. Perl +named hash, or in Perl 5.12 or later, the indices of an array. Perl releases prior to 5.12 will produce a syntax error if you try to use an array argument. In scalar context, returns the number of keys or indices. +Array entries are returned lowest index first. + 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|/each HASH> or -L|/keys HASH> may be deleted without changing the order. So +C may be deleted without changing the order. So long as a given hash is unmodified you may rely on -L|/keys HASH>, L|/values HASH> and L|/each +C, L|/values HASH> and L|/each HASH> to repeatedly return the same order as each other. See L for details on why hash order is randomized. Aside from the guarantees @@ -3953,10 +3969,10 @@ traversal order are subject to change in any release of Perl. Tied hashes may behave differently to Perl's hashes with respect to changes in order on insertion and deletion of items. -As a side effect, calling L|/keys HASH> resets the internal +As a side effect, calling C resets the internal iterator of the HASH or ARRAY (see L|/each HASH>) before yielding the keys. In -particular, calling L|/keys HASH> in void context resets the +particular, calling C in void context resets the iterator with no other overhead. Here is yet another way to print your environment: @@ -3985,7 +4001,7 @@ sort of a hash by its values: printf "%4d %s\n", $hash{$key}, $key; } -Used as an lvalue, L|/keys HASH> allows you to increase the +Used as an lvalue on a hash, C allows you to increase the number of hash buckets allocated for the given hash. This can gain you a measure of efficiency if you know the hash is going to get big. (This is similar to pre-extending @@ -3998,12 +4014,13 @@ in fact, since it rounds up to the next power of two. These buckets will be retained even if you do C<%hash = ()>, use C if you want to free the storage while C<%hash> is still in scope. You can't shrink the number of buckets allocated for the hash using -L|/keys HASH> in this way (but you needn't worry about doing -this by accident, as trying has no effect). C in an lvalue -context is a syntax error. +C in this way (but you needn't worry about doing +this by accident, as trying has no effect). + +C in an lvalue context is a syntax error. Starting with Perl 5.14, an experimental feature allowed -L|/keys HASH> to take a scalar expression. This experiment has +C to take a scalar expression. This experiment has been deemed unsuccessful, and was removed as of Perl 5.24. To avoid confusing would-be users of your code who are running earlier @@ -10494,12 +10511,14 @@ X =item values ARRAY -=for Pod::Functions return a list of the values in a hash +=for Pod::Functions return a list of the values in a hash or array + +Called in list context, returns a list consisting of all the value of the +named hash, or in Perl 5.12 or later, the values of an array. Perl +releases prior to 5.12 will produce a syntax error if you try to use an +array argument. In scalar context, returns the number of keys or indices. -In list context, returns a list consisting of all the values of the named -hash. In Perl 5.12 or later only, will also return a list of the values of -an array; prior to that release, attempting to use an array argument will -produce a syntax error. In scalar context, returns the number of values. +Array entries are returned in the order of lowest index first. 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 @@ -10508,7 +10527,7 @@ into the hash may change the order, as will any deletion, with the exception that the most recent key returned by L|/each HASH> or L|/keys HASH> may be deleted without changing the order. So long as a given hash is unmodified you may rely on -L|/keys HASH>, L|/values HASH> and +L|/keys HASH>, C and L|/each HASH> to repeatedly return the same order as each other. See L for details on why hash order is randomized. Aside from the guarantees @@ -10517,10 +10536,10 @@ traversal order are subject to change in any release of Perl. Tied hashes may behave differently to Perl's hashes with respect to changes in order on insertion and deletion of items. -As a side effect, calling L|/values HASH> resets the HASH or +As a side effect, calling C resets the HASH or ARRAY's internal iterator (see L|/each HASH>) before yielding the values. In particular, -calling L|/values HASH> in void context resets the iterator +calling C in void context resets the iterator with no other overhead. Apart from resetting the iterator, @@ -10536,7 +10555,7 @@ modify the contents of the hash: for (@hash{keys %hash}) { s/foo/bar/g } # same Starting with Perl 5.14, an experimental feature allowed -L|/values HASH> to take a +C to take a scalar expression. This experiment has been deemed unsuccessful, and was removed as of Perl 5.24.