Document each/keys/values @array

p4raw-id: //depot/perl@32692

pod/perlfunc.pod

@@ -1418,25 +1418,30 @@ typo.
 =item each HASH
 X<each> X<hash, iterator>
 
+=item each ARRAY
+X<array, iterator>
+
 When called in list context, returns a 2-element list consisting of the
-key and value for the next element of a hash, so that you can iterate over
-it.  When called in scalar context, returns only the key for the next
-element in the hash.
+key and value for the next element of a hash, or the index and value for
+the next element of an array, so that you can iterate over it.  When called
+in scalar context, returns only the key for the next element in the hash
+(or the index for an array).
 
-Entries are returned in an apparently random order.  The actual random
+Hash entries are returned in an apparently random order.  The actual random
 order is subject to change in future versions of perl, but it is
 guaranteed to be in the same order as either the C<keys> or C<values>
 function would produce on the same (unmodified) hash.  Since Perl
 5.8.2 the ordering can be different even between different runs of Perl
 for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
 
-When the hash is entirely read, a null array is returned in list context
-(which when assigned produces a false (C<0>) value), and C<undef> in
+When the hash or array is entirely read, a null array is returned in list
+context (which when assigned produces a false (C<0>) value), and C<undef> in
 scalar context.  The next call to C<each> after that will start iterating
-again.  There is a single iterator for each hash, shared by all C<each>,
-C<keys>, and C<values> function calls in the program; it can be reset by
-reading all the elements from the hash, or by evaluating C<keys HASH> or
-C<values HASH>.  If you add or delete elements of a hash while you're
+again.  There is a single iterator for each hash or array, shared by all
+C<each>, C<keys>, and C<values> function calls in the program; it can be
+reset by reading all the elements from the hash or array, or by evaluating
+C<keys HASH>, C<values HASH>, C<keys ARRAY>, or C<values ARRAY>.  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.  Exception: It is always safe to delete the item most recently
 returned by C<each()>, which means that the following code will work:
@@ -2521,18 +2526,20 @@ first argument.  Compare L</split>.
 =item keys HASH
 X<keys> X<key>
 
-Returns a list consisting of all the keys of the named hash.
-(In scalar context, returns the number of keys.)
+=item keys ARRAY
+
+Returns a list consisting of all the keys of the named hash, or the indices
+of an array. (In scalar context, returns the number of keys or indices.)
 
-The keys are returned in an apparently random order.  The actual
+The keys of a hash are returned in an apparently random order.  The actual
 random order is subject to change in future versions of perl, but it
 is guaranteed to be the same order as either the C<values> or C<each>
 function produces (given that the hash has not been modified).  Since
 Perl 5.8.1 the ordering is different even between different runs of
 Perl for security reasons (see L<perlsec/"Algorithmic Complexity
 Attacks">).
 
-As a side effect, calling keys() resets the HASH's internal iterator
+As a side effect, calling keys() resets the HASH or ARRAY's internal iterator
 (see L</each>).  In particular, calling keys() in void context resets
 the iterator with no other overhead.
 
@@ -2573,7 +2580,8 @@ 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
 C<keys> in this way (but you needn't worry about doing this by accident,
-as trying has no effect).
+as trying has no effect). C<keys @array> in an lvalue context is a syntax
+error.
 
 See also C<each>, C<values> and C<sort>.
 
@@ -6980,8 +6988,10 @@ file names.
 =item values HASH
 X<values>
 
-Returns a list consisting of all the values of the named hash.
-(In a scalar context, returns the number of values.)
+=item values ARRAY
+
+Returns a list consisting of all the values of the named hash, or the values
+of an array. (In a scalar context, returns the number of values.)
 
 The values are returned in an apparently random order.  The actual
 random order is subject to change in future versions of perl, but it
@@ -6990,9 +7000,15 @@ function would produce on the same (unmodified) hash.  Since Perl
 5.8.1 the ordering is different even between different runs of Perl
 for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
 
-As a side effect, calling values() resets the HASH's internal iterator,
+As a side effect, calling values() resets the HASH or ARRAY's internal
+iterator,
 see L</each>. (In particular, calling values() in void context resets
-the iterator with no other overhead.)
+the iterator with no other overhead. Apart from resetting the iterator,
+C<values @array> in list context is no different to plain C<@array>.
+We recommend that you use void context C<keys @array> for this, but reasoned
+that it 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: