C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
-=item Keywords related to classes and object-orientedness
+=item Keywords related to classes and object-orientation
X<object> X<class> X<package>
C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
The interpretation of the file permission operators C<-r>, C<-R>,
C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode
of the file and the uids and gids of the user. There may be other
-reasons you can't actually read, write, or execute the file. Such
-reasons may be for example network filesystem access controls, ACLs
-(access control lists), read-only filesystems, and unrecognized
-executable formats.
+reasons you can't actually read, write, or execute the file: for
+example network filesystem access controls, ACLs (access control lists),
+read-only filesystems, and unrecognized executable formats. Note
+that the use of these six specific operators to verify if some operation
+is possible is usually a mistake, because it may be open to race
+conditions.
Also note that, for the superuser on the local filesystems, the C<-r>,
C<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1
access() family of system calls. Also note that the C<-x> and C<-X> may
under this pragma return true even if there are no execute permission
bits set (nor any extra execute permission ACLs). This strangeness is
-due to the underlying system calls' definitions. Read the
-documentation for the C<filetest> pragma for more information.
+due to the underlying system calls' definitions. Note also that, due to
+the implementation of C<use filetest 'access'>, the C<_> special
+filehandle won't cache the results of the file tests when this pragma is
+in effect. Read the documentation for the C<filetest> pragma for more
+information.
Note that C<-s/a/b/> does not do a negated substitution. Saying
C<-exp($foo)> still works as expected, however--only single letters
sub tan { sin($_[0]) / cos($_[0]) }
-Note that atan2(0, 0) is not well-defined.
+The return value for C<atan2(0,0)> is implementation-defined; consult
+your atan2(3) manpage for more information.
=item bind SOCKET,NAME
X<bind>
If LAYER is present it is a single string, but may contain multiple
directives. The directives alter the behaviour of the file handle.
-When LAYER is present using binmode on text file makes sense.
+When LAYER is present using binmode on a text file makes sense.
If LAYER is omitted or specified as C<:raw> the filehandle is made
suitable for passing binary data. This includes turning off possible CRLF
C<$is_require> are set: C<$is_require> is true if the frame is created by a
C<require> or C<use> statement, $evaltext contains the text of the
C<eval EXPR> statement. In particular, for an C<eval BLOCK> statement,
-$filename is C<(eval)>, but $evaltext is undefined. (Note also that
+$subroutine is C<(eval)>, but $evaltext is undefined. (Note also that
each C<use> statement creates a C<require> frame inside an C<eval EXPR>
frame.) $subroutine may also be C<(unknown)> if this particular
subroutine happens to have been deleted from the symbol table.
Creates a digest string exactly like the crypt(3) function in the C
library (assuming that you actually have a version there that has not
-been extirpated as a potential munitions).
+been extirpated as a potential munition).
crypt() is a one-way hash function. The PLAINTEXT and SALT is turned
into a short string, called a digest, which is returned. The same
Traditionally the result is a string of 13 bytes: two first bytes of
the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
-the first eight bytes of the digest string mattered, but alternative
+the first eight bytes of PLAINTEXT mattered. But alternative
hashing schemes (like MD5), higher level security schemes (like C2),
and implementations on non-UNIX platforms may produce different
strings.
=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.1 the ordering is different even between different runs of 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:
determined.
If there is a syntax error or runtime error, or a C<die> statement is
-executed, an undefined value is returned by C<eval>, and C<$@> is set to the
+executed, C<eval> returns an undefined value in scalar context
+or an empty list in list context, and C<$@> is set to the
error message. If there was no error, C<$@> is guaranteed to be a null
string. Beware that using C<eval> neither silences perl from printing
warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
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 binary interface (such as Perl version skew) may be fatal even with
+C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set. See L<perlrun>.
+
If the code to be executed doesn't vary, you may use the eval-BLOCK
form to trap run-time errors without incurring the penalty of
recompiling each time. The error, if any, is still returned in C<$@>.
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
+errors:
+
+ # alter $@ on nefarious repugnancy only
+ {
+ my $e;
+ {
+ local $@; # protect existing $@
+ eval { test_repugnancy() };
+ # $@ =~ /nefarious/ and die $@; # DOES NOT WORK
+ $@ =~ /nefarious/ and $e = $@;
+ }
+ die $e if defined $e
+ }
+
C<eval BLOCK> does I<not> count as a loop, so the loop control statements
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
Given an expression that specifies a hash element or array element,
returns true if the specified element in the hash or array has ever
-been initialized, even if the corresponding value is undefined. The
-element is not autovivified if it doesn't exist.
+been initialized, even if the corresponding value is undefined.
print "Exists\n" if exists $hash{$key};
print "Defined\n" if defined $hash{$key};
Here's a mailbox appender for BSD systems.
- use Fcntl ':flock'; # import LOCK_* constants
+ use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants
sub lock {
- flock(MBOX,LOCK_EX);
- # and, in case someone appended
- # while we were waiting...
- seek(MBOX, 0, 2);
+ my ($fh) = @_;
+ flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
+
+ # and, in case someone appended while we were waiting...
+ seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
}
sub unlock {
- flock(MBOX,LOCK_UN);
+ my ($fh) = @_;
+ flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
}
- open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
+ open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
or die "Can't open mailbox: $!";
- lock();
- print MBOX $msg,"\n\n";
- unlock();
+ lock($mbox);
+ print $mbox $msg,"\n\n";
+ unlock($mbox);
On systems that support a real flock(), locks are inherited across fork()
calls, whereas those that must resort to the more capricious fcntl()
X<getpriority> X<priority> X<nice>
Returns the current priority for a process, a process group, or a user.
-(See L<getpriority(2)>.) Will raise a fatal exception if used on a
+(See C<getpriority(2)>.) Will raise a fatal exception if used on a
machine that doesn't implement getpriority(2).
=item getpwnam NAME
EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is discussed in
more detail in L<perlop/"I/O Operators">.
+Note that C<glob> will split its arguments on whitespace, treating
+each segment as separate pattern. As such, C<glob('*.c *.h')> would
+match all files with a F<.c> or F<.h> extension. The expression
+C<glob('.* *')> would match all files in the current working directory.
+
Beginning with v5.6.0, this operator is implemented using the standard
-C<File::Glob> extension. See L<File::Glob> for details.
+C<File::Glob> extension. See L<File::Glob> for details, including
+C<bsd_glob> which does not treat whitespace as a pattern separator.
=item gmtime EXPR
X<gmtime> X<UTC> X<Greenwich>
=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 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.
%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>.
=item length
Returns the length in I<characters> of the value of EXPR. If EXPR is
-omitted, returns length of C<$_>. Note that this cannot be used on
-an entire array or hash to find out how many elements these have.
-For that, use C<scalar @array> and C<scalar keys %hash> respectively.
+omitted, returns length of C<$_>. If EXPR is undefined, returns C<undef>.
+Note that this cannot be used on an entire array or hash to find out how
+many elements these have. For that, use C<scalar @array> and C<scalar keys
+%hash> respectively.
Note the I<characters>: if the EXPR is in Unicode, you will get the
number of characters, not the number of bytes. To get the length
C<$isdst> is true if the specified time occurs during Daylight Saving
Time, false otherwise.
-If EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>).
+If EXPR is omitted, C<localtime()> uses the current time (as returned
+by time(3)).
In scalar context, C<localtime()> returns the ctime(3) value:
=item m//
-The match operator. See L<perlop>.
+The match operator. See L<perlop/"Regexp Quote-Like Operators">.
=item map BLOCK LIST
X<map>
Opens the file whose filename is given by EXPR, and associates it with
FILEHANDLE.
+Simple examples to open a file for reading:
+
+ open(my $fh, '<', "input.txt") or die $!;
+
+and for writing:
+
+ open(my $fh, '>', "output.txt") or die $!;
+
(The following is a comprehensive reference to open(): for a gentler
introduction you may consider L<perlopentut>.)
that affect how the input and output are processed (see L<open> and
L<PerlIO> for more details). For example
- open(FH, "<:encoding(UTF-8)", "file")
+ open(my $fh, "<:encoding(UTF-8)", "file")
will open the UTF-8 encoded file containing Unicode characters,
see L<perluniintro>. Note that if layers are specified in the
As a special case the 3-arg form with a read/write mode and the third
argument being C<undef>:
- open(TMP, "+>", undef) or die ...
+ open(my $tmp, "+>", undef) or die ...
opens a filehandle to an anonymous temporary file. Also using "+<"
works for symmetry, but you really should consider writing something
open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
# if the open fails, output is discarded
- open(DBASE, '+<', 'dbase.mine') # open for update
+ open(my $dbase, '+<', 'dbase.mine') # open for update
or die "Can't open 'dbase.mine' for update: $!";
- open(DBASE, '+<dbase.mine') # ditto
+ open(my $dbase, '+<dbase.mine') # ditto
or die "Can't open 'dbase.mine' for update: $!";
open(ARTICLE, '-|', "caesar <$article") # decrypt article
You may also, in the Bourne shell tradition, specify an EXPR beginning
with C<< '>&' >>, in which case the rest of the string is interpreted
as the name of a filehandle (or file descriptor, if numeric) to be
-duped (as L<dup(2)>) and opened. You may use C<&> after C<< > >>,
+duped (as C<dup(2)>) and opened. You may use C<&> after C<< > >>,
C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
The mode you specify should match the mode of the original filehandle.
(Duping a filehandle does not take into account any existing contents
If you specify C<< '<&=X' >>, where C<X> is a file descriptor number
or a filehandle, then Perl will do an equivalent of C's C<fdopen> of
-that file descriptor (and not call L<dup(2)>); this is more
+that file descriptor (and not call C<dup(2)>); this is more
parsimonious of file descriptors. For example:
# open for input, reusing the fileno of $fd
will have exactly the opposite restrictions.
-If you want a "real" C C<open> (see L<open(2)> on your system), then you
+If you want a "real" C C<open> (see C<open(2)> on your system), then you
should use the C<sysopen> function, which involves no such magic (but
may use subtly different filemodes than Perl open(), which is mapped
to C fopen()). This is
#...
sub read_myfile_munged {
my $ALL = shift;
- my $handle = new IO::File;
+ my $handle = IO::File->new;
open($handle, "myfile") or die "myfile: $!";
$first = <$handle>
or return (); # Automatically closed here.
reference to a new anonymous dirhandle.
DIRHANDLEs have their own namespace separate from FILEHANDLEs.
+See example at C<readdir>.
+
=item ord EXPR
X<ord> X<encoding>
C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
still seen in older code).
-If NAMESPACE is omitted, then there is no current package, and all
-identifiers must be fully qualified or lexicals. However, you are
-strongly advised not to make use of this feature. Its use can cause
-unexpected behaviour, even crashing some versions of Perl. It is
-deprecated, and will be removed from a future release.
-
See L<perlmod/"Packages"> for more information about packages, modules,
and classes. See L<perlsub> for other scoping issues.
=item qq/STRING/
-=item qr/STRING/
-
=item qx/STRING/
=item qw/STRING/
-Generalized quotes. See L<perlop/"Regexp Quote-Like Operators">.
+Generalized quotes. See L<perlop/"Quote-Like Operators">.
+
+=item qr/STRING/
+
+Regexp-like quote. See L<perlop/"Regexp Quote-Like Operators">.
=item quotemeta EXPR
X<quotemeta> X<metacharacter>
better prepend the directory in question. Otherwise, because we didn't
C<chdir> there, it would have been testing the wrong file.
- opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
- @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
- closedir DIR;
+ opendir(my $dh, $some_dir) || die "can't opendir $some_dir: $!";
+ @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
+ closedir $dh;
=item readline EXPR
for (;;) {
undef $!;
unless (defined( $line = <> )) {
+ last if eof;
die $! if $!;
- last; # reached EOF
}
# ...
}
Note the I<characters>: depending on the status of the socket, either
(8-bit) bytes or characters are received. By default all sockets
operate on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:utf8> I/O layer (see the C<open>
-pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
-characters, not bytes. Similarly for the C<:encoding> pragma:
-in that case pretty much any characters can be read.
+binmode() to operate with the C<:encoding(utf8)> I/O layer (see the
+C<open> pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
+characters, not bytes. Similarly for the C<:encoding> pragma: in that
+case pretty much any characters can be read.
=item redo LABEL
X<redo>
then this subroutine is expected to generate one line of source code per
call, writing the line into C<$_> and returning 1, then returning 0 at
"end of file". If there is a filehandle, then the subroutine will be
-called to act a simple source filter, with the line as read in C<$_>.
+called to act as a simple source filter, with the line as read in C<$_>.
Again, return 1 for each valid line, and 0 after all lines have been
returned.
}
# In the main program
- push @INC, new Foo(...);
+ push @INC, Foo->new(...);
Note that these hooks are also permitted to set the %INC entry
corresponding to the files they have loaded. See L<perlvar/%INC>.
elements of LIST and returns a string value with all characters
in the opposite order.
- print reverse <>; # line tac, last line first
+ print join(", ", reverse "world", "Hello"); # Hello, world
- undef $/; # for efficiency of <>
- print scalar reverse <>; # character tac, last line tsrif
+ print scalar reverse "dlrow ,", "olleH"; # Hello, world
Used without arguments in scalar context, reverse() reverses C<$_>.
+ $_ = "dlrow ,olleH";
+ print reverse; # No output, list context
+ print scalar reverse; # Hello, world
+
This operator is also handy for inverting a hash, although there are some
caveats. If a value is duplicated in the original hash, only one of those
can be represented as a key in the inverted hash. Also, this has to
=item s///
-The substitution operator. See L<perlop>.
+The substitution operator. See L<perlop/"Regexp Quote-Like Operators">.
=item say FILEHANDLE LIST
X<say>
otherwise.
Note the I<in bytes>: even if the filehandle has been set to
-operate on characters (for example by using the C<:utf8> open
+operate on characters (for example by using the C<:encoding(utf8)> open
layer), tell() will return byte offsets, not character offsets
(because implementing that would render seek() and tell() rather slow).
Note the I<characters>: depending on the status of the socket, either
(8-bit) bytes or characters are sent. By default all sockets operate
on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:utf8> I/O layer (see L</open>, or the
-C<open> pragma, L<open>), the I/O will operate on UTF-8 encoded
-Unicode characters, not bytes. Similarly for the C<:encoding> pragma:
-in that case pretty much any characters can be sent.
+binmode() to operate with the C<:encoding(utf8)> I/O layer (see
+L</open>, or the C<open> pragma, L<open>), the I/O will operate on UTF-8
+encoded Unicode characters, not bytes. Similarly for the C<:encoding>
+pragma: in that case pretty much any characters can be sent.
=item setpgrp PID,PGRP
X<setpgrp> X<group>
disables the file descriptor in any forked copies in other
processes.
+Returns C<1> for success. In the case of error, returns C<undef> if
+the first argument is not a valid filehandle, or returns C<0> and sets
+C<$!> for any other failure.
+
=item sin EXPR
X<sin> X<sine> X<asin> X<arcsine>
=item sleep
Causes the script to sleep for EXPR seconds, or forever if no EXPR.
+Returns the number of seconds actually slept.
+
May be interrupted if the process receives a signal such as C<SIGALRM>.
-Returns the number of seconds actually slept. You probably cannot
-mix C<alarm> and C<sleep> calls, because C<sleep> is often implemented
-using C<alarm>.
+
+ eval {
+ local $SIG{ALARM} = sub { die "Alarm!\n" };
+ sleep;
+ };
+ die $@ unless $@ eq "Alarm!\n";
+
+You probably cannot mix C<alarm> and C<sleep> calls, because C<sleep>
+is often implemented using C<alarm>.
On some older systems, it may sleep up to a full second less than what
you requested, depending on how it counts seconds. Most modern systems
limited control of the sort. Its rather blunt control of the
underlying algorithm may not persist into future Perls, but the
ability to characterize the input or output in implementation
-independent ways quite probably will. See L<sort>.
+independent ways quite probably will. See L<the sort pragma|sort>.
Examples:
use sort '_mergesort'; # note discouraging _
@new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
+Warning: syntactical care is required when sorting the list returned from
+a function. If you want to sort the list returned by the function call
+C<find_records(@key)>, you can use:
+
+ @contact = sort { $a cmp $b } find_records @key;
+ @contact = sort +find_records(@key);
+ @contact = sort &find_records(@key);
+ @contact = sort(find_records(@key));
+
+If instead you want to sort the array @key with the comparison routine
+C<find_records()> then you can use:
+
+ @contact = sort { find_records() } @key;
+ @contact = sort find_records(@key);
+ @contact = sort(find_records @key);
+ @contact = sort(find_records (@key));
+
If you're using strict, you I<must not> declare $a
and $b as lexicals. They are package globals. That means
-if you're in the C<main> package and type
+that if you're in the C<main> package and type
@articles = sort {$b <=> $a} @files;
matching a null string) will split the value of EXPR into separate
characters at each point it matches that way. For example:
- print join(':', split(/ */, 'hi there'));
+ print join(':', split(/ */, 'hi there')), "\n";
produces the output 'h:i:t:h:e:r:e'.
of C<//> to mean "the last successful pattern match". So, for C<split>,
the following:
- print join(':', split(//, 'hi there'));
+ print join(':', split(//, 'hi there')), "\n";
produces the output 'h:i: :t:h:e:r:e'.
when LIMIT is given and is not 0), regardless of the length of the match.
For example:
- print join(':', split(//, 'hi there!', -1));
- print join(':', split(/\W/, 'hi there!', -1));
+ print join(':', split(//, 'hi there!', -1)), "\n";
+ print join(':', split(/\W/, 'hi there!', -1)), "\n";
produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively,
both with an empty trailing field.
If you had the entire header of a normal Unix email message in $header,
you could split it up into fields and their values this way:
- $header =~ s/\n\s+/ /g; # fix continuation lines
+ $header =~ s/\n(?=\s)//g; # fix continuation lines
%hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header);
The pattern C</PATTERN/> may be replaced with an expression to specify
Returns a string formatted by the usual C<printf> conventions of the C
library function C<sprintf>. See below for more details
-and see
L<sprintf(3)> or L<printf(3)> on your system for an explanation of
+and see
C<sprintf(3)> or C<printf(3)> on your system for an explanation of
the general principles.
For example:
one or more of:
- space prefix positive number with a space
- + prefix positive number with a plus sign
+ space prefix non-negative number with a space
+ + prefix non-negative number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
# ensure the leading "0" for any octal,
would use C<$a> for the width, C<$b> for the precision and C<$c>
as the value to format, while:
- print '<%*1$.*s>', $a, $b;
+ printf '<%*1$.*s>', $a, $b;
would use C<$a> for the width and the precision, and C<$b> as the
value to format.
negative).
Note the I<in bytes>: even if the filehandle has been set to operate
-on characters (for example by using the C<:utf8> I/O layer), tell()
-will return byte offsets, not character offsets (because implementing
-that would render sysseek() very slow).
+on characters (for example by using the C<:encoding(utf8)> I/O layer),
+tell() will return byte offsets, not character offsets (because
+implementing that would render sysseek() very slow).
sysseek() bypasses normal buffered IO, so mixing this with reads (other
than C<sysread>, for example C<< <> >> or read()) C<print>, C<write>,
last read.
Note the I<in bytes>: even if the filehandle has been set to
-operate on characters (for example by using the C<:utf8> open
-layer), tell() will return byte offsets, not character offsets
-(because that would render seek() and tell() rather slow).
+operate on characters (for example by using the C<:encoding(utf8)> open
+layer), tell() will return byte offsets, not character offsets (because
+that would render seek() and tell() rather slow).
The return value of tell() for the standard streams like the STDIN
depends on the operating system: it may return -1 or something else.
=item tr///
-The transliteration operator. Same as C<y///>. See L<perlop>.
+The transliteration operator. Same as C<y///>. See
+L<perlop/"Quote and Quote-like Operators">.
=item truncate FILEHANDLE,LENGTH
X<truncate>
Specifying VERSION as a literal of the form v5.6.1 should generally be
avoided, because it leads to misleading error messages under earlier
-versions of Perl that do not support this syntax. The equivalent numeric
-version should be used instead.
-
-Alternatively, you can use a numeric version C<use 5.006> followed by a
-v-string version like C<use v5.10.1>, to avoid the unintuitive C<use
-5.010_001>. (older perl versions fail gracefully at the first C<use>,
-later perl versions understand the v-string syntax in the second).
+versions of Perl (that is, prior to 5.6.0) that do not support this
+syntax. The equivalent numeric version should be used instead.
use v5.6.1; # compile time version check
use 5.6.1; # ditto
use 5.006_001; # ditto; preferred for backwards compatibility
- use 5.006; use 5.6.1; # ditto, for compatibility and readability
This is often useful if you need to check the current Perl version before
-C<use>ing library modules that have changed in incompatible ways from
-older versions of Perl. (We try not to do this more than we have to.)
+C<use>ing library modules that won't work with older versions of Perl.
+(We try not to do this more than we have to.)
Also, if the specified perl version is greater than or equal to 5.9.5,
C<use VERSION> will also load the C<feature> pragma and enable all
=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
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:
Behaves like the wait(2) system call on your system: it waits for a child
process to terminate and returns the pid of the deceased process, or
C<-1> if there are no child processes. The status is returned in C<$?>
-and C<{^CHILD_ERROR_NATIVE}>.
+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>.
Waits for a particular child process to terminate and returns the pid of
the deceased process, or C<-1> if there is no such child process. On some
systems, a value of 0 indicates that there are processes still running.
-The status is returned in C<$?> and C<{^CHILD_ERROR_NATIVE}>. If you say
+The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>. If you say
use POSIX ":sys_wait_h";
#...
=item y///
-The transliteration operator. Same as C<tr///>. See L<perlop>.
+The transliteration operator. Same as C<tr///>. See
+L<perlop/"Quote and Quote-like Operators">.
=back
https://perl5.git.perl.org / perl5.git / blobdiff