=over

=item values HASH
X<values>

=item values ARRAY

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.

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
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 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
provided here the exact details of Perl's hash algorithm and the hash
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
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
with no other overhead.

Apart from resetting the iterator,
C<values @array> in list context is the same as plain C<@array>.
(We recommend that you use void context C<keys @array> for this, but
reasoned that taking C<values @array> out would require more
documentation than leaving it in.)

Note that the values are not copied, which means modifying them will
modify the contents of the hash:

    for (values %hash)      { s/foo/bar/g }  # modifies %hash values
    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
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
versions of Perl with mysterious syntax errors, put this sort of thing at
the top of your file to signal that your code will work I<only> on Perls of
a recent vintage:

    use 5.012;	# so keys/values/each work on arrays

See also L<C<keys>|/keys HASH>, L<C<each>|/each HASH>, and
L<C<sort>|/sort SUBNAME LIST>.

=back