Skip to content

perlfunc: Improve each, keys, values pod #23260

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 4, 2025
Merged

perlfunc: Improve each, keys, values pod #23260

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dfaf198
perlfunc: Update =for Pod::Functions lines
khwilliamson May 4, 2025
cd68e69
perlfunc: Remove self-referential links
khwilliamson May 4, 2025
4e021f8
perlfunc: Improve each, keys, values pod
khwilliamson May 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 54 additions & 35 deletions pod/perlfunc.pod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2130,20 +2130,23 @@ X<each> X<hash, iterator>
=item each ARRAY
X<array, iterator>

=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<C<each>|/each HASH> or
that the most recent key returned by C<each> 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
Expand All @@ -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<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
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<each> has returned all entries from the hash or
array, the next call to C<each> 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>,
its own internal iterator, accessed by C<each>,
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
implicitly reset when C<each> 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:
returned by C<each>, so the following code works properly:

while (my ($key, $value) = each %hash) {
print $key, "\n";
Expand All @@ -2178,7 +2192,7 @@ 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
Thus all uses of C<each> on a particular 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.
Expand Down Expand Up @@ -2226,10 +2240,10 @@ but in a different order:
}

Starting with Perl 5.14, an experimental feature allowed
L<C<each>|/each HASH> to take a scalar expression. This experiment has
C<each> 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>
As of Perl 5.18 you can use a bare C<each> 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
Expand Down Expand Up @@ -3930,21 +3944,23 @@ X<keys> X<key>

=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<C<each>|/each HASH> or
L<C<keys>|/keys HASH> may be deleted without changing the order. So
C<keys> 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
C<keys>, 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
Expand All @@ -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<C<keys>|/keys HASH> resets the internal
As a side effect, calling C<keys> resets the internal
iterator of the HASH or ARRAY (see L<C<each>|/each HASH>) before
yielding the keys. In
particular, calling L<C<keys>|/keys HASH> in void context resets the
particular, calling C<keys> in void context resets the
iterator with no other overhead.

Here is yet another way to print your environment:
Expand Down Expand Up @@ -3985,7 +4001,7 @@ sort of a hash by its values:
printf "%4d %s\n", $hash{$key}, $key;
}

Used as an lvalue, L<C<keys>|/keys HASH> allows you to increase the
Used as an lvalue on a hash, C<keys> 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
Expand All @@ -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<undef
%hash> 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<C<keys>|/keys HASH> in this way (but you needn't worry about doing
this by accident, as trying has no effect). C<keys @array> in an lvalue
context is a syntax error.
C<keys> in this way (but you needn't worry about doing
this by accident, as trying has no effect).

C<keys @array> in an lvalue context is a syntax error.

Starting with Perl 5.14, an experimental feature allowed
L<C<keys>|/keys HASH> to take a scalar expression. This experiment has
C<keys> 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
Expand Down Expand Up @@ -10494,12 +10511,14 @@ X<values>

=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
Expand All @@ -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<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<keys>|/keys HASH>, C<values> 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
Expand All @@ -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<C<values>|/values HASH> resets the HASH or
As a side effect, calling C<values> resets the HASH or
ARRAY's internal iterator (see L<C<each>|/each HASH>) before yielding the
values. In particular,
calling L<C<values>|/values HASH> in void context resets the iterator
calling C<values> in void context resets the iterator
with no other overhead.

Apart from resetting the iterator,
Expand All @@ -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<C<values>|/values HASH> to take a
C<values> to take a
scalar expression. This experiment has been deemed unsuccessful, and was
removed as of Perl 5.24.

Expand Down
Loading