=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>
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
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
+
+ my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
-translates a list of numbers to the corresponding characters. And
+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.
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", ".")
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/
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 may also want to call srand() after a fork() to
-avoid child processes sharing the same seed value as the parent (and
-consequently each other).
-
-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 per
+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
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>
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 accidently wait for the
+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
https://perl5.git.perl.org / perl5.git / blobdiff