perldoc improvements for map

[perl5.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 18787fe..d85b3d7 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -125,7 +125,7 @@ C<sin>, C<sqrt>, C<srand>
 =item Functions for real @ARRAYs
 X<array>
 
 =item Functions for real @ARRAYs
 X<array>
 

-C<pop>, C<push>, C<shift>, C<splice>, C<unshift>
+C<each>, C<keys>, C<pop>, C<push>, C<shift>, C<splice>, C<unshift>, C<values>

 
 =item Functions for list data
 X<list>
 
 =item Functions for list data
 X<list>


@@ -681,6 +681,20 @@ might not return information about the call frame you expect it to, for
 C<< N > 1 >>.  In particular, C<@DB::args> might have information from the
 previous time C<caller> was called.
 
 C<< N > 1 >>.  In particular, C<@DB::args> might have information from the
 previous time C<caller> was called.
 

+Also be aware that setting C<@DB::args> is I<best effort>, intended for
+debugging or generating backtraces, and should not be relied upon. In
+particular, as C<@_> contains aliases to the caller's arguments, Perl does
+not take a copy of C<@_>, so C<@DB::args> will contain modifications the
+subroutine makes to C<@_> or its contents, not the original values at call
+time. C<@DB::args>, like C<@_>, does not hold explicit references to its
+elements, so under certain cases its elements may have become freed and
+reallocated for other variables or temporary values. Finally, a side effect
+of the current implementation means that the effects of C<shift @_> can
+I<normally> be undone (but not C<pop @_> or other splicing, and not if a
+reference to C<@_> has been taken, and subject to the caveat about reallocated
+elements), so C<@DB::args> is actually a hybrid of the current state and
+initial state of C<@_>. Buyer beware.
+

 =item chdir EXPR
 X<chdir>
 X<cd>
 =item chdir EXPR
 X<chdir>
 X<cd>


@@ -1249,13 +1263,11 @@ final operation is an element or slice of an aggregate:
 =item die LIST
 X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
 
 =item die LIST
 X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
 

-Outside an C<eval>, prints the value of LIST to C<STDERR> and
-exits with the current value of C<$!> (errno).  If C<$!> is C<0>,
-exits with the value of C<<< ($? >> 8) >>> (backtick `command`
-status).  If C<<< ($? >> 8) >>> is C<0>, exits with C<255>.  Inside
-an C<eval(),> the error message is stuffed into C<$@> and the
-C<eval> is terminated with the undefined value.  This makes
-C<die> the way to raise an exception.
+C<die> raises an exception. Inside an C<eval> the error message is stuffed
+into C<$@> and the C<eval> is terminated with the undefined value.
+If the exception is outside of all enclosing C<eval>s, then the uncaught
+exception prints LIST to C<STDERR> and exits with a non-zero value. If you
+need to exit the process with a specific exit code, see L<exit>.

 
 Equivalent examples:
 
 
 Equivalent examples:
 


@@ -1281,8 +1293,6 @@ produce, respectively
     /etc/games is no good at canasta line 123.
     /etc/games is no good, stopped at canasta line 123.
 
     /etc/games is no good at canasta line 123.
     /etc/games is no good, stopped at canasta line 123.
 

-See also exit(), warn(), and the Carp module.
-

 If the output is empty and C<$@> already contains a value (typically from a
 previous eval) that value is reused after appending C<"\t...propagated">.
 This is useful for propagating exceptions:
 If the output is empty and C<$@> already contains a value (typically from a
 previous eval) that value is reused after appending C<"\t...propagated">.
 This is useful for propagating exceptions:


@@ -1298,6 +1308,19 @@ were called.
 
 If C<$@> is empty then the string C<"Died"> is used.
 
 
 If C<$@> is empty then the string C<"Died"> is used.
 

+If an uncaught exception results in interpreter exit, the exit code is
+determined from the values of C<$!> and C<$?> with this pseudocode:
+
+    exit $! if $!;              # errno
+    exit $? >> 8 if $? >> 8;    # child exit status
+    exit 255;                   # last resort
+
+The intent is to squeeze as much possible information about the likely cause
+into the limited space of the system exit code. However, as C<$!> is the value
+of C's C<errno>, which can be set by any system call, this means that the value
+of the exit code used by C<die> can be non-predictable, so should not be relied
+upon, other than to be non-zero.
+

 You can also call C<die> with a reference argument, and if this is trapped
 within an C<eval>, C<$@> contains that reference.  This permits more
 elaborate exception handling using objects that maintain arbitrary state
 You can also call C<die> with a reference argument, and if this is trapped
 within an C<eval>, C<$@> contains that reference.  This permits more
 elaborate exception handling using objects that maintain arbitrary state


@@ -1341,6 +1364,8 @@ as the first line of the handler (see L<perlvar/$^S>).  Because
 this promotes strange action at a distance, this counterintuitive
 behavior may be fixed in a future release.
 
 this promotes strange action at a distance, this counterintuitive
 behavior may be fixed in a future release.
 

+See also exit(), warn(), and the Carp module.
+

 =item do BLOCK
 X<do> X<block>
 
 =item do BLOCK
 X<do> X<block>
 


@@ -1427,10 +1452,10 @@ convert a core file into an executable. That's why you should now invoke
 it as C<CORE::dump()>, if you don't want to be warned against a possible
 typo.
 
 it as C<CORE::dump()>, if you don't want to be warned against a possible
 typo.
 

-=item each HASH
+=item each HASH (or HASHREF)

 X<each> X<hash, iterator>
 
 X<each> X<hash, iterator>
 

-=item each ARRAY
+=item each ARRAY (or ARRAYREF)

 X<array, iterator>
 
 When called in list context, returns a 2-element list consisting of the key
 X<array, iterator>
 
 When called in list context, returns a 2-element list consisting of the key


@@ -1469,6 +1494,16 @@ but in a different order:
         print "$key=$value\n";
     }
 
         print "$key=$value\n";
     }
 

+When given a reference to a hash or array, the argument will be
+dereferenced automatically.
+
+    while (($key,$value) = each $hashref) { ... }
+
+If the reference is a blessed object that overrides either C<%{}> or
+C<@{}>, the override will be used instead of dereferencing the underlying
+variable type.  If both overrides are provided, C<%{}> will be the default.
+If this is not desired, you must dereference the argument yourself.
+

 See also C<keys>, C<values> and C<sort>.
 
 =item eof FILEHANDLE
 See also C<keys>, C<values> and C<sort>.
 
 =item eof FILEHANDLE


@@ -1570,7 +1605,7 @@ See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>.
 
 Note that, because C<eval> traps otherwise-fatal errors, it is useful for
 determining whether a particular feature (such as C<socket> or C<symlink>)
 
 Note that, because C<eval> traps otherwise-fatal errors, it is useful for
 determining whether a particular feature (such as C<socket> or C<symlink>)

-is implemented.  It is also Perl's exception trapping mechanism, where
+is implemented.  It is also Perl's exception-trapping mechanism, where

 the die operator is used to raise exceptions.
 
 If you want to trap errors when loading an XS module, some problems with
 the die operator is used to raise exceptions.
 
 If you want to trap errors when loading an XS module, some problems with


@@ -1641,8 +1676,8 @@ normally you I<would> like to use double quotes, except that in this
 particular situation, you can just use symbolic references instead, as
 in case 6.
 
 particular situation, you can just use symbolic references instead, as
 in case 6.
 

-The assignment to C<$@> occurs before restoration of localised variables,
-which means a temporary is required if you want to mask some but not all
+Before Perl 5.14, the assignment to C<$@> occured before restoration of localised variables, which means that, if your code is to run on older
+versions, a temporary is required if you want to mask some but not all

 errors:
 
     # alter $@ on nefarious repugnancy only
 errors:
 
     # alter $@ on nefarious repugnancy only


@@ -1651,7 +1686,7 @@ errors:
        {
           local $@; # protect existing $@
           eval { test_repugnancy() };
        {
           local $@; # protect existing $@
           eval { test_repugnancy() };

-          # $@ =~ /nefarious/ and die $@; # DOES NOT WORK
+          # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only

           $@ =~ /nefarious/ and $e = $@;
        }
        die $e if defined $e
           $@ =~ /nefarious/ and $e = $@;
        }
        die $e if defined $e


@@ -1830,7 +1865,8 @@ which can be trapped by an C<eval>.
 The exit() function does not always exit immediately.  It calls any
 defined C<END> routines first, but these C<END> routines may not
 themselves abort the exit.  Likewise any object destructors that need to
 The exit() function does not always exit immediately.  It calls any
 defined C<END> routines first, but these C<END> routines may not
 themselves abort the exit.  Likewise any object destructors that need to

-be called are called before the real exit.  If this is a problem, you
+be called are called before the real exit.  C<END> routines and destructors
+can change the exit status by modifying C<$?>. If this is a problem, you

 can call C<POSIX:_exit($status)> to avoid END and destructor processing.
 See L<perlmod> for details.
 
 can call C<POSIX:_exit($status)> to avoid END and destructor processing.
 See L<perlmod> for details.
 


@@ -2368,7 +2404,7 @@ more detail in L<perlop/"I/O Operators">.
 Note that C<glob> splits its arguments on whitespace and treats
 each segment as separate pattern.  As such, C<glob("*.c *.h")> 
 matches all files with a F<.c> or F<.h> extension.  The expression
 Note that C<glob> splits its arguments on whitespace and treats
 each segment as separate pattern.  As such, C<glob("*.c *.h")> 
 matches all files with a F<.c> or F<.h> extension.  The expression

-C<glob(".* *")> matchs all files in the current working directory.
+C<glob(".* *")> matches all files in the current working directory.

 
 If non-empty braces are the only wildcard characters used in the
 C<glob>, no filenames are matched, but potentially many strings
 
 If non-empty braces are the only wildcard characters used in the
 C<glob>, no filenames are matched, but potentially many strings


@@ -2577,10 +2613,10 @@ separated by the value of EXPR, and returns that new string.  Example:
 Beware that unlike C<split>, C<join> doesn't take a pattern as its
 first argument.  Compare L</split>.
 
 Beware that unlike C<split>, C<join> doesn't take a pattern as its
 first argument.  Compare L</split>.
 

-=item keys HASH
+=item keys HASH (or HASHREF)

 X<keys> X<key>
 
 X<keys> X<key>
 

-=item keys ARRAY
+=item keys ARRAY (or ARRAYREF)

 
 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.)
 
 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.)


@@ -2589,7 +2625,7 @@ 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
 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 5.8.1 the ordering can be different even between different runs of

 Perl for security reasons (see L<perlsec/"Algorithmic Complexity
 Attacks">).
 
 Perl for security reasons (see L<perlsec/"Algorithmic Complexity
 Attacks">).
 


@@ -2637,6 +2673,17 @@ 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.
 
 as trying has no effect). C<keys @array> in an lvalue context is a syntax
 error.
 

+When given a reference to a hash or array, the argument will be
+dereferenced automatically.
+
+    for (keys $hashref) { ... }
+    for (keys $obj->get_arrayref) { ... }
+
+If the reference is a blessed object that overrides either C<%{}> or
+C<@{}>, the override will be used instead of dereferencing the underlying
+variable type.  If both overrides are provided, C<%{}> will be the default.
+If this is not desired, you must dereference the argument yourself.
+

 See also C<each>, C<values> and C<sort>.
 
 =item kill SIGNAL, LIST
 See also C<each>, C<values> and C<sort>.
 
 =item kill SIGNAL, LIST


@@ -2698,12 +2745,61 @@ X<lc> X<lowercase>
 =item lc
 
 Returns a lowercased version of EXPR.  This is the internal function
 =item lc
 
 Returns a lowercased version of EXPR.  This is the internal function

-implementing the C<\L> escape in double-quoted strings.  Respects
-current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
-and L<perlunicode> for more details about locale and Unicode support.
+implementing the C<\L> escape in double-quoted strings.

 
 If EXPR is omitted, uses C<$_>.
 
 
 If EXPR is omitted, uses C<$_>.
 

+What gets returned depends on several factors:
+
+=over
+
+=item If C<use bytes> is in effect:
+
+=over
+
+=item On EBCDIC platforms
+
+The results are what the C language system call C<tolower()> returns.
+
+=item On ASCII platforms
+
+The results follow ASCII semantics.  Only characters C<A-Z> change, to C<a-z>
+respectively.
+
+=back
+
+=item Otherwise, If EXPR has the UTF8 flag set
+
+If the current package has a subroutine named C<ToLower>, it will be used to
+change the case (See L<perlunicode/User-Defined Case Mappings>.)
+Otherwise Unicode semantics are used for the case change.
+
+=item Otherwise, if C<use locale> is in effect
+
+Respects current LC_CTYPE locale.  See L<perllocale>.
+
+=item Otherwise, if C<use feature 'unicode_strings'> is in effect:
+
+Unicode semantics are used for the case change.  Any subroutine named
+C<ToLower> will not be used.
+
+=item Otherwise:
+
+=over
+
+=item On EBCDIC platforms
+
+The results are what the C language system call C<tolower()> returns.
+
+=item On ASCII platforms
+
+ASCII semantics are used for the case change.  The lowercase of any character
+outside the ASCII range is the character itself.
+
+=back
+
+=back
+

 =item lcfirst EXPR
 X<lcfirst> X<lowercase>
 
 =item lcfirst EXPR
 X<lcfirst> X<lowercase>
 


@@ -2711,12 +2807,13 @@ X<lcfirst> X<lowercase>
 
 Returns the value of EXPR with the first character lowercased.  This
 is the internal function implementing the C<\l> escape in
 
 Returns the value of EXPR with the first character lowercased.  This
 is the internal function implementing the C<\l> escape in

-double-quoted strings.  Respects current LC_CTYPE locale if C<use
-locale> in force.  See L<perllocale> and L<perlunicode> for more
-details about locale and Unicode support.
+double-quoted strings.

 
 If EXPR is omitted, uses C<$_>.
 
 
 If EXPR is omitted, uses C<$_>.
 

+This function behaves the same way under various pragma, such as in a locale,
+as L</lc> does.
+

 =item length EXPR
 X<length> X<size>
 
 =item length EXPR
 X<length> X<size>
 


@@ -2850,8 +2947,8 @@ object contained in I<THING> until the lock goes out of scope.
 
 lock() is a "weak keyword" : this means that if you've defined a function
 by this name (before any calls to it), that function will be called
 
 lock() is a "weak keyword" : this means that if you've defined a function
 by this name (before any calls to it), that function will be called

-instead. (However, if you've said C<use threads>, lock() is always a
-keyword.) See L<threads>.
+instead.  If you are not under C<use threads::shared> this does nothing.
+See L<threads::shared>.

 
 =item log EXPR
 X<log> X<logarithm> X<e> X<ln> X<base>
 
 =item log EXPR
 X<log> X<logarithm> X<e> X<ln> X<base>


@@ -2899,9 +2996,26 @@ total number of elements so generated.  Evaluates BLOCK or EXPR in
 list context, so each element of LIST may produce zero, one, or
 more elements in the returned value.
 
 list context, so each element of LIST may produce zero, one, or
 more elements in the returned value.
 

-    @chars = map(chr, @nums);
+    @chars = map(chr, @numbers);
+
+translates a list of numbers to the corresponding characters.
+
+    my @squares = map { $_ * $_ } @numbers;
+
+translates a list of numbers to their squared values.
+
+    my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
+
+shows that number of returned elements can differ from the number of
+input elements. To omit an element, return an empty list ().
+This could also be achieved by writing

 
 

-translates a list of numbers to the corresponding characters.  And
+    my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
+
+which makes the intention more clear.
+
+Map always returns a list which can be assigned to a hash where the elements
+become key/value pairs. See L<perldata> for more details.

 
     %hash = map { get_a_key_for($_) => $_ } @array;
 
 
     %hash = map { get_a_key_for($_) => $_ } @array;
 


@@ -3388,7 +3502,7 @@ piped open when you want to exercise more control over just how the
 pipe command gets executed, such as when running setuid and
 you don't want to have to scan shell commands for metacharacters.
 
 pipe command gets executed, such as when running setuid and
 you don't want to have to scan shell commands for metacharacters.
 

-The following triples are more or less equivalent:
+The following blocks are more or less equivalent:

 
     open(FOO, "|tr '[a-z]' '[A-Z]'");
     open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
 
     open(FOO, "|tr '[a-z]' '[A-Z]'");
     open(FOO, '|-', "tr '[a-z]' '[A-Z]'");


@@ -3400,7 +3514,7 @@ The following triples are more or less equivalent:
     open(FOO, '-|') || exec 'cat', '-n', $file;
     open(FOO, '-|', "cat", '-n', $file);
 
     open(FOO, '-|') || exec 'cat', '-n', $file;
     open(FOO, '-|', "cat", '-n', $file);
 

-The last example in each block shows the pipe as "list form", which is
+The last two examples in each block shows the pipe as "list form", which is

 not yet supported on all platforms.  A good rule of thumb is that if
 your platform has true C<fork()> (in other words, if your platform is
 Unix) you can use the list form.
 not yet supported on all platforms.  A good rule of thumb is that if
 your platform has true C<fork()> (in other words, if your platform is
 Unix) you can use the list form.


@@ -3505,8 +3619,8 @@ X<ord> X<encoding>
 =item ord
 
 Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,
 =item ord
 
 Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,

-or Unicode) value of the first character of EXPR.  If EXPR is omitted,
-uses C<$_>.
+or Unicode) value of the first character of EXPR.  If EXPR is an empty
+string, returns 0.  If EXPR is omitted, uses C<$_>.

 
 For the reverse, see L</chr>.
 See L<perlunicode> for more about Unicode.
 
 For the reverse, see L</chr>.
 See L<perlunicode> for more about Unicode.


@@ -3589,8 +3703,10 @@ Takes a LIST of values and converts it into a string using the rules
 given by the TEMPLATE.  The resulting string is the concatenation of
 the converted values.  Typically, each converted value looks
 like its machine-level representation.  For example, on 32-bit machines
 given by the TEMPLATE.  The resulting string is the concatenation of
 the converted values.  Typically, each converted value looks
 like its machine-level representation.  For example, on 32-bit machines

-an integer may be represented by a sequence of 4 bytes, which will in 
-Perl be presented as a string that's 4 characters long.
+an integer may be represented by a sequence of 4 bytes, which  will in
+Perl be presented as a string that's 4 characters long. 
+
+See L<perlpacktut> for an introduction to this function.

 
 The TEMPLATE is a sequence of characters that give the order and type
 of values, as follows:
 
 The TEMPLATE is a sequence of characters that give the order and type
 of values, as follows:


@@ -3803,7 +3919,7 @@ For each such format, pack() generates 4 bits of the result.
 With non-alphabetical characters, the result is based on the 4 least-significant
 bits of the input character, i.e., on C<ord($char)%16>.  In particular,
 characters C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes
 With non-alphabetical characters, the result is based on the 4 least-significant
 bits of the input character, i.e., on C<ord($char)%16>.  In particular,
 characters C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes

-C<"\0"> and C<"\1">.  For characters C<"a".."f"> and C<"A".."F">, the result
+C<"\000"> and C<"\001">.  For characters C<"a".."f"> and C<"A".."F">, the result

 is compatible with the usual hexadecimal digits, so that C<"a"> and
 C<"A"> both generate the nybble C<0xa==10>.  Do not use any characters
 but these with this format.
 is compatible with the usual hexadecimal digits, so that C<"a"> and
 C<"A"> both generate the nybble C<0xa==10>.  Do not use any characters
 but these with this format.


@@ -3866,7 +3982,7 @@ the I<length-item> is the string length, not the number of strings.  With
 an explicit repeat count for pack, the packed string is adjusted to that
 length.  For example:
 
 an explicit repeat count for pack, the packed string is adjusted to that
 length.  For example:
 

-    unpack("W/a", "\04Gurusamy")            gives ("Guru")
+    unpack("W/a", "\004Gurusamy")           gives ("Guru")

     unpack("a3/A A*", "007 Bond  J ")       gives (" Bond", "J")
     unpack("a3 x2 /A A*", "007: Bond, J.")  gives ("Bond, J", ".")
 
     unpack("a3/A A*", "007 Bond  J ")       gives (" Bond", "J")
     unpack("a3 x2 /A A*", "007: Bond, J.")  gives ("Bond, J", ".")
 


@@ -4127,8 +4243,8 @@ Examples:
     #      $foo = pack("WWWW",193,194,195,196);
 
     $foo = pack("s2",1,2);
     #      $foo = pack("WWWW",193,194,195,196);
 
     $foo = pack("s2",1,2);

-    # "\1\0\2\0" on little-endian
-    # "\0\1\0\2" on big-endian
+    # "\001\000\002\000" on little-endian
+    # "\000\001\000\002" on big-endian

 
     $foo = pack("a4","abcd","x","y","z");
     # "abcd"
 
     $foo = pack("a4","abcd","x","y","z");
     # "abcd"


@@ -4177,10 +4293,19 @@ X<package> X<module> X<namespace> X<version>
 
 =item package NAMESPACE
 
 
 =item package NAMESPACE
 

-Declares the compilation unit as being in the given namespace.  The scope
-of the package declaration is from the declaration itself through the end
-of the enclosing block, file, or eval (the same as the C<my> operator).
-All further unqualified dynamic identifiers will be in this namespace.
+=item package NAMESPACE VERSION BLOCK
+X<package> X<module> X<namespace> X<version>
+
+=item package NAMESPACE BLOCK
+
+Declares the BLOCK, or the rest of the compilation unit, as being in
+the given namespace.  The scope of the package declaration is either the
+supplied code BLOCK or, in the absence of a BLOCK, from the declaration
+itself through the end of the enclosing block, file, or eval (the same
+as the C<my> operator).  All unqualified dynamic identifiers in this
+scope will be in the given namespace, except where overridden by another
+C<package> declaration.
+

 A package statement affects dynamic variables only, including those
 you've used C<local> on, but I<not> lexical variables, which are created
 with C<my> (or C<our> (or C<state>)).  Typically it would be the first 
 A package statement affects dynamic variables only, including those
 you've used C<local> on, but I<not> lexical variables, which are created
 with C<my> (or C<our> (or C<state>)).  Typically it would be the first 


@@ -4220,7 +4345,7 @@ On systems that support a close-on-exec flag on files, that flag is set
 on all newly opened file descriptors whose C<fileno>s are I<higher> than 
 the current value of $^F (by default 2 for C<STDERR>).  See L<perlvar/$^F>.
 
 on all newly opened file descriptors whose C<fileno>s are I<higher> than 
 the current value of $^F (by default 2 for C<STDERR>).  See L<perlvar/$^F>.
 

-=item pop ARRAY
+=item pop ARRAY (or ARRAYREF)

 X<pop> X<stack>
 
 =item pop
 X<pop> X<stack>
 
 =item pop


@@ -4232,20 +4357,29 @@ Returns the undefined value if the array is empty, although this may also
 happen at other times.  If ARRAY is omitted, pops the C<@ARGV> array in the
 main program, but the C<@_> array in subroutines, just like C<shift>.
 
 happen at other times.  If ARRAY is omitted, pops the C<@ARGV> array in the
 main program, but the C<@_> array in subroutines, just like C<shift>.
 

+If given a reference to an array, the argument will be dereferenced
+automatically.
+

 =item pos SCALAR
 X<pos> X<match, position>
 
 =item pos
 
 =item pos SCALAR
 X<pos> X<match, position>
 
 =item pos
 

-Returns the offset of where the last C<m//g> search left off for the variable
-in question (C<$_> is used when the variable is not specified).  Note that
-0 is a valid match offset.  C<undef> indicates that the search position
-is reset (usually due to match failure, but can also be because no match has
-yet been run on the scalar). C<pos> directly accesses the location used
-by the regexp engine to store the offset, so assigning to C<pos> will change
-that offset, and so will also influence the C<\G> zero-width assertion in
-regular expressions. Because a failed C<m//gc> match doesn't reset the offset,
-the return from C<pos> won't change either in this case.  See L<perlre> and
+Returns the offset of where the last C<m//g> search left off for the
+variable in question (C<$_> is used when the variable is not
+specified). Note that 0 is a valid match offset. C<undef> indicates
+that the search position is reset (usually due to match failure, but
+can also be because no match has yet been run on the scalar).
+
+C<pos> directly accesses the location used by the regexp engine to
+store the offset, so assigning to C<pos> will change that offset, and
+so will also influence the C<\G> zero-width assertion in regular
+expressions. Both of these effects take place for the next match, so
+you can't affect the position with C<pos> during the current match,
+such as in C<(?{pos() = 5})> or C<s//pos() = 5/e>.
+
+Because a failed C<m//gc> match doesn't reset the offset, the return
+from C<pos> won't change either in this case.  See L<perlre> and

 L<perlop>.
 
 =item print FILEHANDLE LIST
 L<perlop>.
 
 =item print FILEHANDLE LIST


@@ -4317,7 +4451,7 @@ C<qw//>) or if its arguments cannot be adequately expressed by a prototype
 does not really behave like a Perl function.  Otherwise, the string
 describing the equivalent prototype is returned.
 
 does not really behave like a Perl function.  Otherwise, the string
 describing the equivalent prototype is returned.
 

-=item push ARRAY,LIST
+=item push ARRAY (or ARRAYREF),LIST

 X<push> X<stack>
 
 Treats ARRAY as a stack, and pushes the values of LIST
 X<push> X<stack>
 
 Treats ARRAY as a stack, and pushes the values of LIST


@@ -4331,6 +4465,9 @@ LIST.  Has the same effect as
 but is more efficient.  Returns the number of elements in the array following
 the completed C<push>.
 
 but is more efficient.  Returns the number of elements in the array following
 the completed C<push>.
 

+If given a reference to an array, the argument will be dereferenced
+automatically.
+

 =item q/STRING/
 
 =item qq/STRING/
 =item q/STRING/
 
 =item qq/STRING/


@@ -4359,6 +4496,32 @@ the C<\Q> escape in double-quoted strings.
 
 If EXPR is omitted, uses C<$_>.
 
 
 If EXPR is omitted, uses C<$_>.
 

+quotemeta (and C<\Q> ... C<\E>) are useful when interpolating strings into
+regular expressions, because by default an interpolated variable will be
+considered a mini-regular expression. For example:
+
+    my $sentence = 'The quick brown fox jumped over the lazy dog';
+    my $substring = 'quick.*?fox';
+    $sentence =~ s{$substring}{big bad wolf};
+
+Will cause C<$sentence> to become C<'The big bad wolf jumped over...'>.
+
+On the other hand:
+
+    my $sentence = 'The quick brown fox jumped over the lazy dog';
+    my $substring = 'quick.*?fox';
+    $sentence =~ s{\Q$substring\E}{big bad wolf};
+
+Or:
+
+    my $sentence = 'The quick brown fox jumped over the lazy dog';
+    my $substring = 'quick.*?fox';
+    my $quoted_substring = quotemeta($substring);
+    $sentence =~ s{$quoted_substring}{big bad wolf};
+
+Will both leave the sentence as is. Normally, when accepting string input from
+the user, quotemeta() or C<\Q> must be used.
+

 =item rand EXPR
 X<rand> X<random>
 
 =item rand EXPR
 X<rand> X<random>
 


@@ -4729,8 +4892,8 @@ first look for a similar filename with a "F<.pmc>" extension. If this file
 is found, it will be loaded in place of any file ending in a "F<.pm>"
 extension.
 
 is found, it will be loaded in place of any file ending in a "F<.pm>"
 extension.
 

-You can also insert hooks into the import facility, by putting directly
-Perl code into the @INC array.  There are three forms of hooks: subroutine
+You can also insert hooks into the import facility, by putting Perl code
+directly into the @INC array.  There are three forms of hooks: subroutine

 references, array references and blessed objects.
 
 Subroutine references are the simplest case.  When the inclusion system
 references, array references and blessed objects.
 
 Subroutine references are the simplest case.  When the inclusion system


@@ -5197,7 +5360,7 @@ An example disabling Nagle's algorithm on a socket:
     use Socket qw(IPPROTO_TCP TCP_NODELAY);
     setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
 
     use Socket qw(IPPROTO_TCP TCP_NODELAY);
     setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
 

-=item shift ARRAY
+=item shift ARRAY (or ARRAYREF)

 X<shift>
 
 =item shift
 X<shift>
 
 =item shift


@@ -5210,6 +5373,9 @@ C<@ARGV> array outside a subroutine and also within the lexical scopes
 established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>,
 C<UNITCHECK {}> and C<END {}> constructs.
 
 established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>,
 C<UNITCHECK {}> and C<END {}> constructs.
 

+If given a reference to an array, the argument will be dereferenced
+automatically.
+

 See also C<unshift>, C<push>, and C<pop>.  C<shift> and C<unshift> do the
 same thing to the left end of an array that C<pop> and C<push> do to the
 right end.
 See also C<unshift>, C<push>, and C<pop>.  C<shift> and C<unshift> do the
 same thing to the left end of an array that C<pop> and C<push> do to the
 right end.


@@ -5541,14 +5707,14 @@ eliminate any C<NaN>s from the input list.
 
     @result = sort { $a <=> $b } grep { $_ == $_ } @input;
 
 
     @result = sort { $a <=> $b } grep { $_ == $_ } @input;
 

-=item splice ARRAY,OFFSET,LENGTH,LIST
+=item splice ARRAY (or ARRAYREF),OFFSET,LENGTH,LIST

 X<splice>
 
 X<splice>
 

-=item splice ARRAY,OFFSET,LENGTH
+=item splice ARRAY (or ARRAYREF),OFFSET,LENGTH

 
 

-=item splice ARRAY,OFFSET
+=item splice ARRAY (or ARRAYREF),OFFSET

 
 

-=item splice ARRAY
+=item splice ARRAY (or ARRAYREF)

 
 Removes the elements designated by OFFSET and LENGTH from an array, and
 replaces them with the elements of LIST, if any.  In list context,
 
 Removes the elements designated by OFFSET and LENGTH from an array, and
 replaces them with the elements of LIST, if any.  In list context,


@@ -5563,6 +5729,9 @@ If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
 past the end of the array, Perl issues a warning, and splices at the
 end of the array.
 
 past the end of the array, Perl issues a warning, and splices at the
 end of the array.
 

+If given a reference to an array, the argument will be dereferenced
+automatically.
+

 The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
 
     push(@a,$x,$y)      splice(@a,@a,0,$x,$y)
 The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
 
     push(@a,$x,$y)      splice(@a,@a,0,$x,$y)


@@ -6045,32 +6214,34 @@ X<srand> X<seed> X<randseed>
 
 =item srand
 
 
 =item srand
 

-Sets the random number seed for the C<rand> operator.
+Sets and returns the random number seed for the C<rand> operator.

 
 The point of the function is to "seed" the C<rand> function so that
 C<rand> can produce a different sequence each time you run your
 
 The point of the function is to "seed" the C<rand> function so that
 C<rand> can produce a different sequence each time you run your

-program.
-
-If srand() is not called explicitly, it is called implicitly at the
-first use of the C<rand> operator.  However, this was not true of
-versions of Perl before 5.004, so if your script will run under older
-Perl versions, it should call C<srand>.
-
-Most programs won't even call srand() at all, except those that
-need a cryptographically-strong starting point rather than the
-generally acceptable default, which is based on time of day,
-process ID, and memory allocation, or the F</dev/urandom> device
-if available.
-
-You can call srand($seed) with the same $seed to reproduce the
-I<same> sequence from rand(), but this is usually reserved for
-generating predictable results for testing or debugging.
-Otherwise, don't call srand() more than once in your program.
-
-Do B<not> call srand() (i.e., without an argument) more than once in
-a script.  The internal state of the random number generator should
+program.  When called with a parameter, C<srand> uses that for the seed;
+otherwise it (semi-)randomly chooses a seed.  In either case, starting with
+Perl 5.14, it returns the seed.
+
+If C<srand()> is not called explicitly, it is called implicitly without a
+parameter at the first use of the C<rand> operator.  However, this was not true
+of versions of Perl before 5.004, so if your script will run under older
+Perl versions, it should call C<srand>; otherwise most programs won't call
+C<srand()> at all.
+
+But there are a few situations in recent Perls where programs are likely to
+want to call C<srand>.  One is for generating predictable results generally for
+testing or debugging.  There, you use C<srand($seed)>, with the same C<$seed>
+each time.  Another other case is where you need a cryptographically-strong
+starting point rather than the generally acceptable default, which is based on
+time of day, process ID, and memory allocation, or the F</dev/urandom> device
+if available.  And still another case is that you may want to call C<srand()>
+after a C<fork()> to avoid child processes sharing the same seed value as the
+parent (and consequently each other).
+
+Do B<not> call C<srand()> (i.e., without an argument) more than once per
+process.  The internal state of the random number generator should

 contain more entropy than can be provided by any seed, so calling
 contain more entropy than can be provided by any seed, so calling

-srand() again actually I<loses> randomness.
+C<srand()> again actually I<loses> randomness.

 
 Most implementations of C<srand> take an integer and will silently
 truncate decimal numbers.  This means C<srand(42)> will usually
 
 Most implementations of C<srand> take an integer and will silently
 truncate decimal numbers.  This means C<srand(42)> will usually


@@ -6089,8 +6260,8 @@ example:
 
     srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip -f`);
 
 
     srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip -f`);
 

-If you're particularly concerned with this, see the C<Math::TrulyRandom>
-module in CPAN.
+If you're particularly concerned with this, search the CPAN for
+random number generator modules instead of rolling out your own.

 
 Frequently called programs (like CGI scripts) that simply use
 
 
 Frequently called programs (like CGI scripts) that simply use
 


@@ -6102,6 +6273,11 @@ for a seed can fall prey to the mathematical property that
 
 one-third of the time.  So don't do that.
 
 
 one-third of the time.  So don't do that.
 

+A typical use of the returned seed is for a test program which has too many
+combinations to test comprehensively in the time available to it each run.  It
+can test a random subset each time, and should there be a failure, log the seed
+used for that run so that it can later be used to reproduce the exact results.
+

 =item stat FILEHANDLE
 X<stat> X<file, status> X<ctime>
 
 =item stat FILEHANDLE
 X<stat> X<file, status> X<ctime>
 


@@ -6635,6 +6811,9 @@ When C<system>'s arguments are executed indirectly by the shell,
 results and return codes are subject to its quirks.
 See L<perlop/"`STRING`"> and L</exec> for details.
 
 results and return codes are subject to its quirks.
 See L<perlop/"`STRING`"> and L</exec> for details.
 

+Since C<system> does a C<fork> and C<wait> it may affect a C<SIGCHLD>
+handler. See L<perlipc> for details.
+

 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
 X<syswrite>
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
 X<syswrite>
 


@@ -6855,14 +7034,15 @@ X<uc> X<uppercase> X<toupper>
 =item uc
 
 Returns an uppercased version of EXPR.  This is the internal function
 =item uc
 
 Returns an uppercased version of EXPR.  This is the internal function

-implementing the C<\U> escape in double-quoted strings.  Respects
-current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
-and L<perlunicode> for more details about locale and Unicode support.
+implementing the C<\U> escape in double-quoted strings.

 It does not attempt to do titlecase mapping on initial letters.  See
 It does not attempt to do titlecase mapping on initial letters.  See

-C<ucfirst> for that.
+L</ucfirst> for that.

 
 If EXPR is omitted, uses C<$_>.
 
 
 If EXPR is omitted, uses C<$_>.
 

+This function behaves the same way under various pragma, such as in a locale,
+as L</lc> does.
+

 =item ucfirst EXPR
 X<ucfirst> X<uppercase>
 
 =item ucfirst EXPR
 X<ucfirst> X<uppercase>
 


@@ -6870,12 +7050,13 @@ X<ucfirst> X<uppercase>
 
 Returns the value of EXPR with the first character in uppercase
 (titlecase in Unicode).  This is the internal function implementing
 
 Returns the value of EXPR with the first character in uppercase
 (titlecase in Unicode).  This is the internal function implementing

-the C<\u> escape in double-quoted strings.  Respects current LC_CTYPE
-locale if C<use locale> in force.  See L<perllocale> and L<perlunicode>
-for more details about locale and Unicode support.
+the C<\u> escape in double-quoted strings.

 
 If EXPR is omitted, uses C<$_>.
 
 
 If EXPR is omitted, uses C<$_>.
 

+This function behaves the same way under various pragma, such as in a locale,
+as L</lc> does.
+

 =item umask EXPR
 X<umask>
 
 =item umask EXPR
 X<umask>
 


@@ -6980,6 +7161,7 @@ and expands it out into a list of values.
 (In scalar context, it returns merely the first value produced.)
 
 If EXPR is omitted, unpacks the C<$_> string.
 (In scalar context, it returns merely the first value produced.)
 
 If EXPR is omitted, unpacks the C<$_> string.

+See L<perlpacktut> for an introduction to this function.

 
 The string is broken into chunks described by the TEMPLATE.  Each chunk
 is converted separately to a value.  Typically, either the string is a result
 
 The string is broken into chunks described by the TEMPLATE.  Each chunk
 is converted separately to a value.  Typically, either the string is a result


@@ -7037,7 +7219,7 @@ X<untie>
 Breaks the binding between a variable and a package.  (See C<tie>.)
 Has no effect if the variable is not tied.
 
 Breaks the binding between a variable and a package.  (See C<tie>.)
 Has no effect if the variable is not tied.
 

-=item unshift ARRAY,LIST
+=item unshift ARRAY (or ARRAYREF),LIST

 X<unshift>
 
 Does the opposite of a C<shift>.  Or the opposite of a C<push>,
 X<unshift>
 
 Does the opposite of a C<shift>.  Or the opposite of a C<push>,


@@ -7050,6 +7232,9 @@ Note the LIST is prepended whole, not one element at a time, so the
 prepended elements stay in the same order.  Use C<reverse> to do the
 reverse.
 
 prepended elements stay in the same order.  Use C<reverse> to do the
 reverse.
 

+If given a reference to an array, the argument will be dereferenced
+automatically.
+

 =item use Module VERSION LIST
 X<use> X<module> X<import>
 
 =item use Module VERSION LIST
 X<use> X<module> X<import>
 


@@ -7163,6 +7348,11 @@ or no unimport method being found.
     no strict 'refs';
     no warnings;
 
     no strict 'refs';
     no warnings;
 

+Care should be taken when using the C<no VERSION> form of C<no>.  It is
+I<only> meant to be used to assert that the running perl is of a earlier
+version than its argument and I<not> to undo the feature-enabling side effects
+of C<use VERSION>.
+

 See L<perlmodlib> for a list of standard modules and pragmas.  See L<perlrun>
 for the C<-M> and C<-m> command-line options to Perl that give C<use>
 functionality from the command-line.
 See L<perlmodlib> for a list of standard modules and pragmas.  See L<perlrun>
 for the C<-M> and C<-m> command-line options to Perl that give C<use>
 functionality from the command-line.


@@ -7210,10 +7400,10 @@ files.  On systems that don't support futimes(2), passing filehandles raises
 an exception.  Filehandles must be passed as globs or glob references to be
 recognized; barewords are considered filenames.
 
 an exception.  Filehandles must be passed as globs or glob references to be
 recognized; barewords are considered filenames.
 

-=item values HASH
+=item values HASH (or HASHREF)

 X<values>
 
 X<values>
 

-=item values ARRAY
+=item values ARRAY (or ARRAYREF)

 
 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.)
 
 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.)


@@ -7241,6 +7431,17 @@ 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
 
     for (values %hash)      { s/foo/bar/g }   # modifies %hash values
     for (@hash{keys %hash}) { s/foo/bar/g }   # same
 

+When given a reference to a hash or array, the argument will be
+dereferenced automatically.
+
+    for (values $hashref) { ... }
+    for (values $obj->get_arrayref) { ... }
+
+If the reference is a blessed object that overrides either C<%{}> or
+C<@{}>, the override will be used instead of dereferencing the underlying
+variable type.  If both overrides are provided, C<%{}> will be the default.
+If this is not desired, you must dereference the argument yourself.
+

 See also C<keys>, C<each>, and C<sort>.
 
 =item vec EXPR,OFFSET,BITS
 See also C<keys>, C<each>, and C<sort>.
 
 =item vec EXPR,OFFSET,BITS


@@ -7491,6 +7692,9 @@ and C<${^CHILD_ERROR_NATIVE}>.
 Note that a return value of C<-1> could mean that child processes are
 being automatically reaped, as described in L<perlipc>.
 
 Note that a return value of C<-1> could mean that child processes are
 being automatically reaped, as described in L<perlipc>.
 

+If you use wait in your handler for $SIG{CHLD} it may accidentally for the
+child created by qx() or system(). See L<perlipc> for details.
+

 =item waitpid PID,FLAGS
 X<waitpid>
 
 =item waitpid PID,FLAGS
 X<waitpid>