=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>
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 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:
/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 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
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>
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>
-=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
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
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
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
{
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
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.
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
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>
-=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.)
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">).
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
=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<$_>.
+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>
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<$_>.
+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>
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>
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;
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, '-|') || 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.
=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.
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:
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.
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", ".")
# $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"
=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
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
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
-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
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
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/
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>
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
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
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.
@result = sort { $a <=> $b } grep { $_ == $_ } @input;
-=item splice ARRAY,OFFSET,LENGTH,LIST
+=item splice ARRAY (or ARRAYREF),OFFSET,LENGTH,LIST
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,
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)
=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
-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
-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
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
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>
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 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
-C<ucfirst> for that.
+L</ucfirst> for that.
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>
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<$_>.
+This function behaves the same way under various pragma, such as in a locale,
+as L</lc> does.
+
=item umask EXPR
X<umask>
(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
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>,
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>
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.
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>
-=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.)
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
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>