X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/ad93219c1d44c131908e99c36e47d141daa709b7..c75669973a178847398e42141fd44f535cfe37e5:/pod/perlfunc.pod diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index e35bec6..650ad0e 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -884,7 +884,7 @@ $INPUT_RECORD_SEPARATOR in the C module). It returns the total number of characters removed from all its arguments. It's often used to remove the newline from the end of an input record when you're worried that the final record may be missing its newline. When in paragraph -mode (C<$/ = "">), it removes all trailing newlines from the string. +mode (C<$/ = ''>), it removes all trailing newlines from the string. When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is a reference to an integer or the like; see L) chomp() won't remove anything. @@ -1701,7 +1701,7 @@ but in a different order: print "$key=$value\n"; } -Starting with Perl 5.14, C can take a scalar EXPR, which must hold +Starting with Perl 5.14, C can take a scalar EXPR, which must hold a reference to an unblessed hash or array. The argument will be dereferenced automatically. This aspect of C is considered highly experimental. The exact behaviour may change in a future version of Perl. @@ -2297,6 +2297,12 @@ same underlying descriptor: "not have a real file descriptor\n"; } +The behavior of C on a directory handle depends on the operating +system. On a system with dirfd(3) or similar, C on a directory +handle returns the underlying file descriptor associated with the +handle; on systems with no such support, it returns the undefined value, +and sets C<$!> (errno). + =item flock FILEHANDLE,OPERATION X X X @@ -2716,7 +2722,8 @@ various get routines are as follows: $comment, $gcos, $dir, $shell, $expire ) = getpw* # 5 6 7 8 9 -(If the entry doesn't exist you get an empty list.) +(If the entry doesn't exist, the return value is a single meaningless true +value.) The exact meaning of the $gcos field varies but it usually contains the real name of the user (as opposed to the login name) and other @@ -3362,7 +3369,7 @@ Respects current C locale for code points < 256; and uses Unicode rules for the remaining code points (this last can only happen if the UTF8 flag is also set). See L. -Starting in v5.20, Perl wil use full Unicode rules if the locale is +Starting in v5.20, Perl uses full Unicode rules if the locale is UTF-8. Otherwise, there is a deficiency in this scheme, which is that case changes that cross the 255/256 boundary are not well-defined. For example, the lower case of LATIN CAPITAL @@ -3372,8 +3379,10 @@ locale), the lower case of U+1E9E is itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the current locale, and Perl has no way of knowing if that character even exists in the locale, much less what code point it is. Perl returns -the input character unchanged, for all instances (and there aren't -many) where the 255/256 boundary would otherwise be crossed. +a result that is above 255 (almost always the input character unchanged, +for all instances (and there aren't many) where the 255/256 boundary +would otherwise be crossed; and starting in v5.22, it raises a +L warning. =item Otherwise, If EXPR has the UTF8 flag set: @@ -4367,7 +4376,9 @@ existing variable: a package variable of the same name. This means that when C is in effect, C lets you use a package variable without qualifying it with the package name, but only within -the lexical scope of the C declaration. +the lexical scope of the C +declaration. This applies immediately--even +within the same statement. package Foo; use strict; @@ -4393,6 +4404,16 @@ package variables spring into existence when first used. print $Foo::foo; # prints 23 +Because the variable becomes legal immediately under C, so +long as there is no variable with that name is already in scope, you can then +reference the package variable again even within the same statement. + + package Foo; + use strict; + + my $foo = $foo; # error, undeclared $foo on right-hand side + our $foo = $foo; # no errors + If more than one variable is listed, the list must be placed in parentheses. @@ -4952,7 +4973,7 @@ will not in general equal $foo. =item * Pack and unpack can operate in two modes: character mode (C mode) where -the packed string is processed per character, and UTF-8 mode (C mode) +the packed string is processed per character, and UTF-8 byte mode (C mode) where the packed string is processed in its UTF-8-encoded Unicode form on a byte-by-byte basis. Character mode is the default unless the format string starts with C. You @@ -5331,11 +5352,14 @@ error prone. =item prototype FUNCTION X +=item prototype + =for Pod::Functions +5.002 get the prototype (if any) of a subroutine Returns the prototype of a function as a string (or C if the function has no prototype). FUNCTION is a reference to, or the name of, -the function whose prototype you want to retrieve. +the function whose prototype you want to retrieve. If FUNCTION is omitted, +$_ is used. If FUNCTION is a string starting with C, the rest is taken as a name for a Perl builtin. If the builtin's arguments @@ -6800,7 +6824,7 @@ Examples: # same thing, but much more efficiently; # we'll build auxiliary indices instead # for speed - my @nums = @caps = (); + my (@nums, @caps); for (@old) { push @nums, ( /=(\d+)/ ? $1 : undef ); push @caps, fc($_); @@ -6877,14 +6901,22 @@ eliminate any Cs from the input list. @result = sort { $a <=> $b } grep { $_ == $_ } @input; -=item splice ARRAY or EXPR,OFFSET,LENGTH,LIST +=item splice ARRAY,OFFSET,LENGTH,LIST X -=item splice ARRAY or EXPR,OFFSET,LENGTH +=item splice ARRAY,OFFSET,LENGTH + +=item splice ARRAY,OFFSET -=item splice ARRAY or EXPR,OFFSET +=item splice ARRAY -=item splice ARRAY or EXPR +=item splice EXPR,OFFSET,LENGTH,LIST + +=item splice EXPR,OFFSET,LENGTH + +=item splice EXPR,OFFSET + +=item splice EXPR =for Pod::Functions add or remove elements anywhere in an array @@ -6976,7 +7008,8 @@ uses empty string matches as separators to produce the output list of its component characters. As a special case for C, the empty pattern given in -L syntax (C) specifically matches the empty string, which is contrary to its usual +L syntax (C) +specifically matches the empty string, which is contrary to its usual interpretation as the last successful match. If PATTERN is C, then it is treated as if it used the @@ -7680,7 +7713,8 @@ list context is currently not possible this would serve no purpose. C variables are enabled only when the C pragma is in effect, unless the keyword is written as C. -See also L. +See also L. Alternately, include a C or later to the +current scope. =item study SCALAR X @@ -7689,14 +7723,18 @@ X =for Pod::Functions optimize input data for repeated searches -Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of -doing many pattern matches on the string before it is next modified. +May take extra time to study SCALAR (C<$_> if unspecified) in anticipation +of doing many pattern matches on the string before it is next modified. This may or may not save time, depending on the nature and number of patterns you are searching and the distribution of character frequencies in the string to be searched; you probably want to compare run times with and without it to see which is faster. Those loops that scan for many short constant strings (including the constant parts of more complex patterns) will benefit most. + +Note that since Perl version 5.16 this function has been a no-op, but +this might change in a future release. + (The way C works is this: a linked list of every character in the string to be searched is made, so we know, for example, where all the C<'k'> characters are. From each search string, @@ -7919,6 +7957,8 @@ filehandle wanted; an undefined scalar will be suitably autovivified. This function calls the underlying operating system's I(2) function with the parameters FILENAME, MODE, and PERMS. +Returns true on success and C otherwise. + The possible values and flag bits of the MODE parameter are system-dependent; they are available via the standard module C. See the documentation of your operating system's I(2) syscall to see @@ -9084,8 +9124,8 @@ 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. -If you use wait in your handler for $SIG{CHLD} it may accidentally for the -child created by qx() or system(). See L for details. +If you use C in your handler for $SIG{CHLD}, it may accidentally wait +for the child created by qx() or system(). See L for details. Portability issues: L.