X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=a56b4a889b7b585bf73889a6152a515c4e6100b9;hb=7ed149c909e2812f62b12bd7d09f4ccfb79e0041;hp=d409319a09f8ad96e911d7909faabff64c3e2180;hpb=2cdbc966996b991c40c8522dcf668b1e34b5e76b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index d409319..a56b4a8 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -30,7 +30,7 @@ Elements of the LIST should be separated by commas. Any function in the list below may be used either with or without parentheses around its arguments. (The syntax descriptions omit the parentheses.) If you use the parentheses, the simple (but occasionally -surprising) rule is this: It I like a function, therefore it I a +surprising) rule is this: It I like a function, therefore it I a function, and precedence doesn't matter. Otherwise it's a list operator or unary operator, and precedence does matter. And whitespace between the function and left parenthesis doesn't count--so you need to @@ -80,8 +80,8 @@ In general, functions in Perl that serve as wrappers for system calls of the same name (like chown(2), fork(2), closedir(2), etc.) all return true when they succeed and C otherwise, as is usually mentioned in the descriptions below. This is different from the C interfaces, -which return C<-1> on failure. Exceptions to this rule are C, -C, and C. System calls also set the special C<$!> +which return C<-1> on failure. Exceptions to this rule are C, +C, and C. System calls also set the special C<$!> variable on failure. Other functions do not, except accidentally. =head2 Perl Functions by Category @@ -146,11 +146,11 @@ C, C, C, C, C, C, C =item Keywords related to scoping -C, C, C, C, C, C +C, C, C, C, C, C, C =item Miscellaneous functions -C, C, C, C, C, C, C, +C, C, C, C, C, C, C, C, C, C, C =item Functions for processes and process groups @@ -200,8 +200,8 @@ C, C, C, L, L. =item delete EXPR -Deletes the specified key(s) and their associated values from a hash. -For each key, returns the deleted value associated with that key, or -the undefined value if there was no such key. Deleting from C<$ENV{}> -modifies the environment. Deleting from a hash tied to a DBM file -deletes the entry from the DBM file. (But deleting from a Cd hash -doesn't necessarily return anything.) +Given an expression that specifies a hash element, array element, hash slice, +or array slice, deletes the specified element(s) from the hash or array. +In the case of an array, if the array elements happen to be at the end, +the size of the array will shrink to the highest element that tests +true for exists() (or 0 if no such element exists). + +Returns each element so deleted or the undefined value if there was no such +element. Deleting from C<$ENV{}> modifies the environment. Deleting from +a hash tied to a DBM file deletes the entry from the DBM file. Deleting +from a Cd hash or array may not necessarily return anything. + +Deleting an array element effectively returns that position of the array +to its initial, uninitialized state. Subsequently testing for the same +element with exists() will return false. Note that deleting array +elements in the middle of an array will not shift the index of the ones +after them down--use splice() for that. See L. -The following deletes all the values of a hash: +The following (inefficiently) deletes all the values of %HASH and @ARRAY: foreach $key (keys %HASH) { delete $HASH{$key}; } -And so does this: + foreach $index (0 .. $#ARRAY) { + delete $ARRAY[$index]; + } + +And so do these: - delete @HASH{keys %HASH} + delete @HASH{keys %HASH}; + + delete @ARRAY[0 .. $#ARRAY]; But both of these are slower than just assigning the empty list -or undefining it: +or undefining %HASH or @ARRAY: + + %HASH = (); # completely empty %HASH + undef %HASH; # forget %HASH ever existed - %hash = (); # completely empty %hash - undef %hash; # forget %hash every existed + @ARRAY = (); # completely empty @ARRAY + undef @ARRAY; # forget @ARRAY ever existed Note that the EXPR can be arbitrarily complicated as long as the final -operation is a hash element lookup or hash slice: +operation is a hash element, array element, hash slice, or array slice +lookup: delete $ref->[$x][$y]{$key}; delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys}; + delete $ref->[$x][$y][$index]; + delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; + =item die LIST -Outside an C, prints the value of LIST to C and exits with -the current value of C<$!> (errno). If C<$!> is C<0>, exits with the value of -C<($? EE 8)> (backtick `command` status). If C<($? EE 8)> -is C<0>, exits with C<255>. Inside an C the error message is stuffed into -C<$@> and the C is terminated with the undefined value. This makes -C the way to raise an exception. +Outside an C, prints the value of LIST to C 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 the error message is stuffed into C<$@> and the +C is terminated with the undefined value. This makes +C the way to raise an exception. Equivalent examples: @@ -970,7 +1059,7 @@ If C<$@> is empty then the string C<"Died"> is used. die() can also be called with a reference argument. If this happens to be trapped within an eval(), $@ contains the reference. This behavior permits a more elaborate exception handling implementation using objects that -maintain arbitary state about the nature of the exception. Such a scheme +maintain arbitrary state about the nature of the exception. Such a scheme is sometimes preferable to matching particular string values of $@ using regular expressions. Here's an example: @@ -984,25 +1073,26 @@ regular expressions. Here's an example: } } -Since perl will stringify uncaught exception messages before displaying +Because perl will stringify uncaught exception messages before displaying them, you may want to overload stringification operations on such custom exception objects. See L for details about that. -You can arrange for a callback to be run just before the C does -its deed, by setting the C<$SIG{__DIE__}> hook. The associated handler -will be called with the error text and can change the error message, if -it sees fit, by calling C again. See L for details on -setting C<%SIG> entries, and L<"eval BLOCK"> for some examples. - -Note that the C<$SIG{__DIE__}> hook is currently called even inside -eval()ed blocks/strings! If one wants the hook to do nothing in such -situations, put +You can arrange for a callback to be run just before the C +does its deed, by setting the C<$SIG{__DIE__}> hook. The associated +handler will be called with the error text and can change the error +message, if it sees fit, by calling C again. See +L for details on setting C<%SIG> entries, and +L<"eval BLOCK"> for some examples. Although this feature was meant +to be run only right before your program was to exit, this is not +currently the case--the C<$SIG{__DIE__}> hook is currently called +even inside eval()ed blocks/strings! If one wants the hook to do +nothing in such situations, put die @_ if $^S; -as the first line of the handler (see L). Because this -promotes action at a distance, this counterintuitive behavior may be fixed -in a future release. +as the first line of the handler (see L). Because +this promotes strange action at a distance, this counterintuitive +behavior may be fixed in a future release. =item do BLOCK @@ -1046,7 +1136,7 @@ successfully compiled, C returns the value of the last expression evaluated. Note that inclusion of library modules is better done with the -C and C operators, which also do automatic error checking +C and C operators, which also do automatic error checking and raise an exception if there's a problem. You might like to use C to read in a program configuration @@ -1067,60 +1157,49 @@ file. Manual error checking can be done this way: =item dump -This causes an immediate core dump. Primarily this is so that you can -use the B program to turn your core dump into an executable binary -after having initialized all your variables at the beginning of the -program. When the new binary is executed it will begin by executing a -C (with all the restrictions that C suffers). Think of -it as a goto with an intervening core dump and reincarnation. If C for more on how the evaluation context can be determined. -If there is a syntax error or runtime error, or a C statement is -executed, an undefined value is returned by C, and C<$@> is set to the +If there is a syntax error or runtime error, or a C statement is +executed, an undefined value is returned by C, 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 neither silences perl from printing +string. Beware that using C neither silences perl from printing warnings to STDERR, nor does it stuff the text of warning messages into C<$@>. To do either of those, you have to use the C<$SIG{__WARN__}> facility. See L and L. -Note that, because C traps otherwise-fatal errors, it is useful for -determining whether a particular feature (such as C or C) +Note that, because C traps otherwise-fatal errors, it is useful for +determining whether a particular feature (such as C or C) is implemented. It is also Perl's exception trapping mechanism, where the die operator is used to raise exceptions. @@ -1247,7 +1331,7 @@ as shown in this example: warn $@ if $@; This is especially significant, given that C<__DIE__> hooks can call -C again, which has the effect of changing their error messages: +C again, which has the effect of changing their error messages: # __DIE__ hooks may modify error messages { @@ -1257,10 +1341,10 @@ C again, which has the effect of changing their error messages: print $@ if $@; # prints "bar lives here" } -Because this promotes action at a distance, this counterintuive behavior +Because this promotes action at a distance, this counterintuitive behavior may be fixed in a future release. -With an C, you should be especially careful to remember what's +With an C, you should be especially careful to remember what's being looked at when: eval $x; # CASE 1 @@ -1273,13 +1357,13 @@ being looked at when: $$x++; # CASE 6 Cases 1 and 2 above behave identically: they run the code contained in -the variable C<$x>. (Although case 2 has misleading double quotes making +the variable $x. (Although case 2 has misleading double quotes making the reader wonder what else might be happening (nothing is).) Cases 3 and 4 likewise behave in the same way: they run the code C<'$x'>, which -does nothing but return the value of C<$x>. (Case 4 is preferred for +does nothing but return the value of $x. (Case 4 is preferred for purely visual reasons, but it also has the advantage of compiling at compile-time instead of at run-time.) Case 5 is a place where -normally you I like to use double quotes, except that in this +normally you I like to use double quotes, except that in this particular situation, you can just use symbolic references instead, as in case 6. @@ -1290,15 +1374,15 @@ C, C, or C cannot be used to leave or restart the block. =item exec PROGRAM LIST -The C function executes a system command I - -use C instead of C if you want it to return. It fails and -returns FALSE only if the command does not exist I it is executed +The C function executes a system command I-- +use C instead of C if you want it to return. It fails and +returns false only if the command does not exist I it is executed directly instead of via your system's command shell (see below). -Since it's a common mistake to use C instead of C, Perl -warns you if there is a following statement which isn't C, C, -or C (if C<-w> is set - but you always do that). If you -I want to follow an C with some other statement, you +Since it's a common mistake to use C instead of C, Perl +warns you if there is a following statement which isn't C, C, +or C (if C<-w> is set - but you always do that). If you +I want to follow an C with some other statement, you can use one of these styles to avoid the warning: exec ('foo') or print STDERR "couldn't exec foo: $!"; @@ -1311,9 +1395,11 @@ the argument is checked for shell metacharacters, and if there are any, the entire argument is passed to the system's command shell for parsing (this is C on Unix platforms, but varies on other platforms). If there are no shell metacharacters in the argument, it is split into -words and passed directly to C, which is more efficient. +words and passed directly to C, which is more efficient. +Examples: -All files opened for output are flushed before attempting the exec(). + exec '/bin/echo', 'Your arguments are: ', @ARGV; + exec "sort $outfile | uniq"; If you don't really want to execute the first argument, but want to lie to the program you are executing about its own name, you can specify @@ -1333,10 +1419,11 @@ When the arguments get executed via the system shell, results will be subject to its quirks and capabilities. See L for details. -Using an indirect object with C or C is also more secure. -This usage forces interpretation of the arguments as a multivalued list, -even if the list had just one argument. That way you're safe from the -shell expanding wildcards or splitting up words with whitespace in them. +Using an indirect object with C or C is also more +secure. This usage (which also works fine with system()) forces +interpretation of the arguments as a multivalued list, even if the +list had just one argument. That way you're safe from the shell +expanding wildcards or splitting up words with whitespace in them. @args = ( "echo surprise" ); @@ -1349,32 +1436,57 @@ program, passing it C<"surprise"> an argument. The second version didn't--it tried to run a program literally called I<"echo surprise">, didn't find it, and set C<$?> to a non-zero value indicating failure. -Note that C will not call your C blocks, nor will it call +Beginning with v5.6.0, Perl will attempt to flush all files opened for +output before the exec, but this may not be supported on some platforms +(see L). To be safe, you may need to set C<$|> ($AUTOFLUSH +in English) or call the C method of C on any +open handles in order to avoid lost output. + +Note that C will not call your C blocks, nor will it call any C methods in your objects. =item exists EXPR -Returns TRUE if the specified hash key exists in its hash array, even -if the corresponding value is undefined. +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. + + print "Exists\n" if exists $hash{$key}; + print "Defined\n" if defined $hash{$key}; + print "True\n" if $hash{$key}; - print "Exists\n" if exists $array{$key}; - print "Defined\n" if defined $array{$key}; - print "True\n" if $array{$key}; + print "Exists\n" if exists $array[$index]; + print "Defined\n" if defined $array[$index]; + print "True\n" if $array[$index]; -A hash element can be TRUE only if it's defined, and defined if +A hash or array element can be true only if it's defined, and defined if it exists, but the reverse doesn't necessarily hold true. +Given an expression that specifies the name of a subroutine, +returns true if the specified subroutine has ever been declared, even +if it is undefined. Mentioning a subroutine name for exists or defined +does not count as declaring it. + + print "Exists\n" if exists &subroutine; + print "Defined\n" if defined &subroutine; + Note that the EXPR can be arbitrarily complicated as long as the final -operation is a hash key lookup: +operation is a hash or array key lookup or subroutine name: if (exists $ref->{A}->{B}->{$key}) { } if (exists $hash{A}{B}{$key}) { } -Although the last element will not spring into existence just because -its existence was tested, intervening ones will. Thus C<$ref-E{"A"}> -and C<$ref-E{"A"}-E{"B"}> will spring into existence due to the -existence test for a $key element. This happens anywhere the arrow -operator is used, including even + if (exists $ref->{A}->{B}->[$ix]) { } + if (exists $hash{A}{B}[$ix]) { } + + if (exists &{$ref->{A}{B}{$key}}) { } + +Although the deepest nested array or hash will not spring into existence +just because its existence was tested, any intervening ones will. +Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring +into existence due to the existence test for the $key element above. +This happens anywhere the arrow operator is used, including even: undef $ref; if (exists $ref->{"Some key"}) { } @@ -1384,6 +1496,15 @@ This surprising autovivification in what does not at first--or even second--glance appear to be an lvalue context may be fixed in a future release. +See L for specifics +on how exists() acts when used on a pseudo-hash. + +Use of a subroutine call, rather than a subroutine name, as an argument +to exists() is an error. + + exists ⊂ # OK + exists &sub(); # Error + =item exit EXPR Evaluates EXPR and exits immediately with that value. Example: @@ -1391,23 +1512,23 @@ Evaluates EXPR and exits immediately with that value. Example: $ans = ; exit 0 if $ans =~ /^[Xx]/; -See also C. If EXPR is omitted, exits with C<0> status. The only +See also C. If EXPR is omitted, exits with C<0> status. The only universally recognized values for EXPR are C<0> for success and C<1> for error; other values are subject to interpretation depending on the environment in which the Perl program is running. For example, exiting 69 (EX_UNAVAILABLE) from a I incoming-mail filter will cause the mailer to return the item undelivered, but that's not true everywhere. -Don't use C to abort a subroutine if there's any chance that -someone might want to trap whatever error happened. Use C instead, -which can be trapped by an C. +Don't use C to abort a subroutine if there's any chance that +someone might want to trap whatever error happened. Use C instead, +which can be trapped by an C. -The exit() function does not always exit immediately. It calls any +The exit() function does not always exit immediately. It calls any defined C routines first, but these C routines may not -themselves abort the exit. Likewise any object destructors that need to +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 can call C to avoid END and destructor processing. -See L for details. +See L for details. =item exp EXPR @@ -1423,20 +1544,20 @@ Implements the fcntl(2) function. You'll probably have to say use Fcntl; first to get the correct constant definitions. Argument processing and -value return works just like C below. +value return works just like C below. For example: use Fcntl; fcntl($filehandle, F_GETFL, $packed_return_buffer) or die "can't fcntl F_GETFL: $!"; -You don't have to check for C on the return from C. -Like C, it maps a C<0> return from the system call into "C<0> -but true" in Perl. This string is true in boolean context and C<0> +You don't have to check for C on the return from C. +Like C, it maps a C<0> return from the system call into +C<"0 but true"> in Perl. This string is true in boolean context and C<0> in numeric context. It is also exempt from the normal B<-w> warnings on improper numeric conversions. -Note that C will produce a fatal error if used on a machine that +Note that C will produce a fatal error if used on a machine that doesn't implement fcntl(2). See the Fcntl module or your fcntl(2) manpage to learn what functions are available on your system. @@ -1444,7 +1565,7 @@ manpage to learn what functions are available on your system. Returns the file descriptor for a filehandle, or undefined if the filehandle is not open. This is mainly useful for constructing -bitmaps for C and low-level POSIX tty-handling operations. +bitmaps for C). If LIST is also omitted, -prints C<$_> to the currently selected output channel. To set the default -output channel to something other than STDOUT use the select operation. -Note that, because print takes a LIST, anything in the LIST is evaluated -in list context, and any subroutine that you call will have one or -more of its expressions evaluated in list context. Also be careful -not to follow the print keyword with a left parenthesis unless you want -the corresponding right parenthesis to terminate the arguments to the -print--interpose a C<+> or put parentheses around all the arguments. +If FILEHANDLE is omitted, prints by default to standard output (or +to the last selected output channel--see L). If LIST is +also omitted, prints C<$_> to the currently selected output channel. +To set the default output channel to something other than STDOUT +use the select operation. The current value of C<$,> (if any) is +printed between each LIST item. The current value of C<$\> (if +any) is printed after the entire LIST has been printed. Because +print takes a LIST, anything in the LIST is evaluated in list +context, and any subroutine that you call will have one or more of +its expressions evaluated in list context. Also be careful not to +follow the print keyword with a left parenthesis unless you want +the corresponding right parenthesis to terminate the arguments to +the print--interpose a C<+> or put parentheses around all the +arguments. Note that if you're storing FILEHANDLES in an array or other expression, you will have to use a block returning its value instead: @@ -2919,12 +3388,12 @@ you will have to use a block returning its value instead: Equivalent to C, except that C<$\> (the output record separator) is not appended. The first argument -of the list will be interpreted as the C format. If C is +of the list will be interpreted as the C format. If C is in effect, the character used for the decimal point in formatted real numbers is affected by the LC_NUMERIC locale. See L. -Don't fall into the trap of using a C when a simple -C would do. The C is more efficient and less +Don't fall into the trap of using a C when a simple +C would do. The C is more efficient and less error prone. =item prototype FUNCTION @@ -2936,7 +3405,7 @@ the function whose prototype you want to retrieve. If FUNCTION is a string starting with C, the rest is taken as a name for Perl builtin. If the builtin is not I (such as C) or its arguments cannot be expressed by a prototype (such as -C) returns C because the builtin does not really behave +C) returns C because the builtin does not really behave like a Perl function. Otherwise, the string describing the equivalent prototype is returned. @@ -2968,7 +3437,7 @@ Generalized quotes. See L. =item quotemeta -Returns the value of EXPR with all non-alphanumeric +Returns the value of EXPR with all non-"word" characters backslashed. (That is, all characters not matching C will be preceded by a backslash in the returned string, regardless of any locale settings.) @@ -2983,8 +3452,8 @@ If EXPR is omitted, uses C<$_>. Returns a random fractional number greater than or equal to C<0> and less than the value of EXPR. (EXPR should be positive.) If EXPR is -omitted, the value C<1> is used. Automatically calls C unless -C has already been called. See also C. +omitted, the value C<1> is used. Automatically calls C unless +C has already been called. See also C. (Note: If your rand function consistently returns numbers that are too large or too small, then your version of Perl was probably compiled @@ -3000,18 +3469,18 @@ C<0> at end of file, or undef if there was an error. SCALAR will be grown or shrunk to the length actually read. An OFFSET may be specified to place the read data at some other place than the beginning of the string. This call is actually implemented in terms of stdio's fread(3) -call. To get a true read(2) system call, see C. +call. To get a true read(2) system call, see C. =item readdir DIRHANDLE -Returns the next directory entry for a directory opened by C. +Returns the next directory entry for a directory opened by C. If used in list context, returns all the rest of the entries in the directory. If there are no more entries, returns an undefined value in scalar context or a null list in list context. -If you're planning to filetest the return values out of a C, you'd +If you're planning to filetest the return values out of a C, you'd better prepend the directory in question. Otherwise, because we didn't -C there, it would have been testing the wrong file. +C 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); @@ -3030,8 +3499,8 @@ When C<$/> is set to C, when readline() is in scalar context (i.e. file slurp mode), and when an empty file is read, it returns C<''> the first time, followed by C subsequently. -This is the internal function implementing the CEXPRE> -operator, but you can use it directly. The CEXPRE> +This is the internal function implementing the C<< >> +operator, but you can use it directly. The C<< >> operator is discussed in more detail in L. $line = ; @@ -3060,12 +3529,13 @@ operator is discussed in more detail in L. =item recv SOCKET,SCALAR,LENGTH,FLAGS Receives a message on a socket. Attempts to receive LENGTH bytes of -data into variable SCALAR from the specified SOCKET filehandle. -Actually does a C C, so that it can return the address of the -sender. Returns the undefined value if there's an error. SCALAR will -be grown or shrunk to the length actually read. Takes the same flags -as the system call of the same name. -See L for examples. +data into variable SCALAR from the specified SOCKET filehandle. SCALAR +will be grown or shrunk to the length actually read. Takes the same +flags as the system call of the same name. Returns the address of the +sender if SOCKET's protocol supports this; returns an empty string +otherwise. If there's an error, returns the undefined value. This call +is actually implemented in terms of recvfrom(2) system call. See +L for examples. =item redo LABEL @@ -3098,6 +3568,10 @@ C cannot be used to retry a block which returns a value such as C, C or C, and should not be used to exit a grep() or map() operation. +Note that a block by itself is semantically identical to a loop +that executes once. Thus C inside such a block will effectively +turn it into a looping construct. + See also L for an illustration of how C, C, and C work. @@ -3105,20 +3579,21 @@ C work. =item ref -Returns a TRUE value if EXPR is a reference, FALSE otherwise. If EXPR +Returns a true value if EXPR is a reference, false otherwise. If EXPR is not specified, C<$_> will be used. The value returned depends on the type of thing the reference is a reference to. Builtin types include: - REF SCALAR ARRAY HASH CODE + REF GLOB + LVALUE If the referenced object has been blessed into a package, then that package -name is returned instead. You can think of C as a C operator. +name is returned instead. You can think of C as a C operator. if (ref($r) eq "HASH") { print "r is a reference to a hash.\n"; @@ -3134,7 +3609,9 @@ See also L. =item rename OLDNAME,NEWNAME -Changes the name of a file. Returns C<1> for success, C<0> otherwise. +Changes the name of a file; an existing file NEWNAME will be +clobbered. Returns true for success, false otherwise. + Behavior of this function varies wildly depending on your system implementation. For example, it will usually not work across file system boundaries, even though the system I command sometimes compensates @@ -3142,17 +3619,29 @@ for this. Other restrictions include whether it works on directories, open files, or pre-existing files. Check L and either the rename(2) manpage or equivalent system documentation for details. +=item require VERSION + =item require EXPR =item require Demands some semantics specified by EXPR, or by C<$_> if EXPR is not -supplied. If EXPR is numeric, demands that the current version of Perl -(C<$]> or $PERL_VERSION) be equal or greater than EXPR. +supplied. + +If a VERSION is specified as a literal of the form v5.6.1, +demands that the current version of Perl (C<$^V> or $PERL_VERSION) be +at least as recent as that version, at run time. (For compatibility +with older versions of Perl, a numeric argument will also be interpreted +as VERSION.) Compare with L, which can do a similar check at +compile time. + + require v5.6.1; # run time version check + require 5.6.1; # ditto + require 5.005_03; # float version allowed for compatibility Otherwise, demands that a library file be included if it hasn't already been included. The file is included via the do-FILE mechanism, which is -essentially just a variety of C. Has semantics similar to the following +essentially just a variety of C. Has semantics similar to the following subroutine: sub require { @@ -3163,23 +3652,24 @@ subroutine: foreach $prefix (@INC) { $realfilename = "$prefix/$filename"; if (-f $realfilename) { + $INC{$filename} = $realfilename; $result = do $realfilename; last ITER; } } die "Can't find $filename in \@INC"; } + delete $INC{$filename} if $@ || !$result; die $@ if $@; die "$filename did not return true value" unless $result; - $INC{$filename} = $realfilename; return $result; } Note that the file will not be included twice under the same specified -name. The file must return TRUE as the last statement to indicate +name. The file must return true as the last statement to indicate successful execution of any initialization code, so it's customary to -end such a file with "C<1;>" unless you're sure it'll return TRUE -otherwise. But it's better just to put the "C<1;>", in case you add more +end such a file with C<1;> unless you're sure it'll return true +otherwise. But it's better just to put the C<1;>, in case you add more statements. If EXPR is a bareword, the require assumes a "F<.pm>" extension and @@ -3202,7 +3692,7 @@ But if you try this: require "Foo::Bar"; # not a bareword because of the "" The require function will look for the "F" file in the @INC array and -will complain about not finding "F" there. In this case you can do: +will complain about not finding "F" there. In this case you can do: eval "require $class"; @@ -3235,10 +3725,10 @@ See L. =item return -Returns from a subroutine, C, or C with the value +Returns from a subroutine, C, or C with the value given in EXPR. Evaluation of EXPR may be in list, scalar, or void context, depending on how the return value will be used, and the context -may vary from one execution to the next (see C). If no EXPR +may vary from one execution to the next (see C). If no EXPR is given, returns an empty list in list context, the undefined value in scalar context, and (of course) nothing at all in a void context. @@ -3269,7 +3759,7 @@ on a large hash, such as from a DBM file. =item rewinddir DIRHANDLE Sets the current position to the beginning of the directory for the -C routine on DIRHANDLE. +C routine on DIRHANDLE. =item rindex STR,SUBSTR,POSITION @@ -3284,7 +3774,7 @@ last occurrence at or before that position. =item rmdir Deletes the directory specified by FILENAME if that directory is empty. If it -succeeds it returns TRUE, otherwise it returns FALSE and sets C<$!> (errno). If +succeeds it returns true, otherwise it returns false and sets C<$!> (errno). If FILENAME is omitted, uses C<$_>. =item s/// @@ -3304,7 +3794,7 @@ needed. If you really wanted to do so, however, you could use the construction C<@{[ (some expression) ]}>, but usually a simple C<(some expression)> suffices. -Wince C is unary operator, if you accidentally use for EXPR a +Because C is unary operator, if you accidentally use for EXPR a parenthesized list, this behaves as a scalar comma expression, evaluating all but the last element in void context and returning the final element evaluated in scalar context. This is seldom what you want. @@ -3322,17 +3812,18 @@ See L for more details on unary operators and the comma operator. =item seek FILEHANDLE,POSITION,WHENCE -Sets FILEHANDLE's position, just like the C call of C. +Sets FILEHANDLE's position, just like the C call of C. FILEHANDLE may be an expression whose value gives the name of the filehandle. The values for WHENCE are C<0> to set the new position to -POSITION, C<1> to set it to the current position plus POSITION, and C<2> to -set it to EOF plus POSITION (typically negative). For WHENCE you may -use the constants C, C, and C from either the -C or the POSIX module. Returns C<1> upon success, C<0> otherwise. +POSITION, C<1> to set it to the current position plus POSITION, and +C<2> to set it to EOF plus POSITION (typically negative). For WHENCE +you may use the constants C, C, and C +(start of the file, current position, end of the file) from the Fcntl +module. Returns C<1> upon success, C<0> otherwise. -If you want to position file for C or C, don't use -C -- buffering makes its effect on the file's system position -unpredictable and non-portable. Use C instead. +If you want to position file for C or C, don't use +C--buffering makes its effect on the file's system position +unpredictable and non-portable. Use C instead. Due to the rules and rigors of ANSI C, on some systems you have to do a seek whenever you switch between reading and writing. Amongst other @@ -3343,9 +3834,9 @@ A WHENCE of C<1> (C) is useful for not moving the file position: This is also useful for applications emulating C. Once you hit EOF on your read, and then sleep for a while, you might have to stick in a -seek() to reset things. The C doesn't change the current position, +seek() to reset things. The C doesn't change the current position, but it I clear the end-of-file condition on the handle, so that the -next CFILEE> makes Perl try again to read something. We hope. +next C<< >> makes Perl try again to read something. We hope. If that doesn't work (some stdios are particularly cantankerous), then you may need something more like this: @@ -3361,8 +3852,8 @@ you may need something more like this: =item seekdir DIRHANDLE,POS -Sets the current position for the C routine on DIRHANDLE. POS -must be a value returned by C. Has the same caveats about +Sets the current position for the C routine on DIRHANDLE. POS +must be a value returned by C. Has the same caveats about possible directory compaction as the corresponding system library routine. @@ -3372,7 +3863,7 @@ routine. Returns the currently selected filehandle. Sets the current default filehandle for output, if FILEHANDLE is supplied. This has two -effects: first, a C or a C without a filehandle will +effects: first, a C or a C without a filehandle will default to this FILEHANDLE. Second, references to variables related to output will refer to this output channel. For example, if you have to set the top of form format for more than one output channel, you might @@ -3397,7 +3888,7 @@ methods, preferring to write the last example as: =item select RBITS,WBITS,EBITS,TIMEOUT This calls the select(2) system call with the bit masks specified, which -can be constructed using C and C, along these lines: +can be constructed using C and C, along these lines: $rin = $win = $ein = ''; vec($rin,fileno(STDIN),1) = 1; @@ -3426,39 +3917,43 @@ or to block until something becomes ready just do this $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); -Most systems do not bother to return anything useful in C<$timeleft>, so -calling select() in scalar context just returns C<$nfound>. +Most systems do not bother to return anything useful in $timeleft, so +calling select() in scalar context just returns $nfound. Any of the bit masks can also be undef. The timeout, if specified, is in seconds, which may be fractional. Note: not all implementations are -capable of returning theC<$timeleft>. If not, they always return -C<$timeleft> equal to the supplied C<$timeout>. +capable of returning the$timeleft. If not, they always return +$timeleft equal to the supplied $timeout. You can effect a sleep of 250 milliseconds this way: select(undef, undef, undef, 0.25); -B: One should not attempt to mix buffered I/O (like C -or EFHE) with C, except as permitted by POSIX, and even -then only on POSIX systems. You have to use C instead. +B: One should not attempt to mix buffered I/O (like C +or ) with C above. +C interface to access setitimer(2) if your system supports +it, or else see L above. The Time::HiRes module from CPAN +may also help. -See also the POSIX module's C function. +See also the POSIX module's C function. =item socket SOCKET,DOMAIN,TYPE,PROTOCOL Opens a socket of the specified kind and attaches it to filehandle -SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for the -system call of the same name. You should "C" first to get -the proper definitions imported. See the examples in L. +SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for +the system call of the same name. You should C first +to get the proper definitions imported. See the examples in +L. + +On systems that support a close-on-exec flag on files, the flag will +be set for the newly opened file descriptor, as determined by the +value of $^F. See L. =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL Creates an unnamed pair of sockets in the specified domain, of the specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as for the system call of the same name. If unimplemented, yields a fatal -error. Returns TRUE if successful. +error. Returns true if successful. + +On systems that support a close-on-exec flag on files, the flag will +be set for the newly opened file descriptors, as determined by the value +of $^F. See L. -Some systems defined C in terms of C, in which a call +Some systems defined C in terms of C, in which a call to C is essentially: use Socket; @@ -3632,25 +4141,29 @@ See L for an example of socketpair use. =item sort LIST Sorts the LIST and returns the sorted list value. If SUBNAME or BLOCK -is omitted, Cs in standard string comparison order. If SUBNAME is +is omitted, Cs in standard string comparison order. If SUBNAME is specified, it gives the name of a subroutine that returns an integer less than, equal to, or greater than C<0>, depending on how the elements -of the array are to be ordered. (The C=E> and C +of the list are to be ordered. (The C<< <=> >> and C operators are extremely useful in such routines.) SUBNAME may be a scalar variable name (unsubscripted), in which case the value provides the name of (or a reference to) the actual subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine. -In the interests of efficiency the normal calling code for subroutines is -bypassed, with the following effects: the subroutine may not be a -recursive subroutine, and the two elements to be compared are passed into -the subroutine not via C<@_> but as the package global variables C<$a> and -C<$b> (see example below). They are passed by reference, so don't -modify C<$a> and C<$b>. And don't try to declare them as lexicals either. +If the subroutine's prototype is C<($$)>, the elements to be compared +are passed by reference in C<@_>, as for a normal subroutine. This is +slower than unprototyped subroutines, where the elements to be +compared are passed into the subroutine +as the package global variables $a and $b (see example below). Note that +in the latter case, it is usually counter-productive to declare $a and +$b as lexicals. + +In either case, the subroutine may not be recursive. The values to be +compared are always passed by reference, so don't modify them. You also cannot exit out of the sort block or subroutine using any of the -loop control operators described in L or with C. +loop control operators described in L or with C. When C is in effect, C sorts LIST according to the current collation locale. See L. @@ -3675,19 +4188,19 @@ Examples: # sort numerically descending @articles = sort {$b <=> $a} @files; + # this sorts the %age hash by value instead of key + # using an in-line function + @eldest = sort { $age{$b} <=> $age{$a} } keys %age; + # sort using explicit subroutine name sub byage { $age{$a} <=> $age{$b}; # presuming numeric } @sortedclass = sort byage @class; - # this sorts the %age hash by value instead of key - # using an in-line function - @eldest = sort { $age{$b} <=> $age{$a} } keys %age; - - sub backwards { $b cmp $a; } - @harry = ('dog','cat','x','Cain','Abel'); - @george = ('gone','chased','yz','Punished','Axed'); + sub backwards { $b cmp $a } + @harry = qw(dog cat x Cain Abel); + @george = qw(gone chased yz Punished Axed); print sort @harry; # prints AbelCaincatdogx print sort backwards @harry; @@ -3721,24 +4234,29 @@ Examples: } 0..$#old ]; - # same thing using a Schwartzian Transform (no temps) + # same thing, but without any temps @new = map { $_->[0] } - sort { $b->[1] <=> $a->[1] - || - $a->[2] cmp $b->[2] - } map { [$_, /=(\d+)/, uc($_)] } @old; - -If you're using strict, you I declare C<$a> -and C<$b> as lexicals. They are package globals. That means -if you're in the C
package, it's - - @articles = sort {$main::b <=> $main::a} @files; - -or just - - @articles = sort {$::b <=> $::a} @files; - -but if you're in the C package, it's + sort { $b->[1] <=> $a->[1] + || + $a->[2] cmp $b->[2] + } map { [$_, /=(\d+)/, uc($_)] } @old; + + # using a prototype allows you to use any comparison subroutine + # as a sort subroutine (including other package's subroutines) + package other; + sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here + + package main; + @new = sort other::backwards @old; + +If you're using strict, you I declare $a +and $b as lexicals. They are package globals. That means +if you're in the C
package and type + + @articles = sort {$b <=> $a} @files; + +then C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>), +but if you're in the C package, it's the same as typing @articles = sort {$FooPack::b <=> $FooPack::a} @files; @@ -3753,14 +4271,18 @@ well-defined. =item splice ARRAY,OFFSET +=item splice ARRAY + Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. In list context, returns the elements removed from the array. In scalar context, returns the last element removed, or C if no elements are removed. The array grows or shrinks as necessary. -If OFFSET is negative then it start that far from the end of the array. +If OFFSET is negative then it starts that far from the end of the array. If LENGTH is omitted, removes everything from OFFSET onward. -If LENGTH is negative, leave that many elements off the end of the array. +If LENGTH is negative, leaves that many elements off the end of the array. +If both OFFSET and LENGTH are omitted, removes everything. + The following equivalences hold (assuming C<$[ == 0>): push(@a,$x,$y) splice(@a,@a,0,$x,$y) @@ -3790,14 +4312,12 @@ Example, assuming array lengths are passed before arrays: =item split -Splits a string into an array of strings, and returns it. By default, +Splits a string into a list of strings and returns that list. By default, empty leading fields are preserved, and empty trailing ones are deleted. -If not in list context, returns the number of fields found and splits into -the C<@_> array. (In list context, you can force the split into C<@_> by -using C as the pattern delimiters, but it still returns the list -value.) The use of implicit split to C<@_> is deprecated, however, because -it clobbers your subroutine arguments. +In scalar context, returns the number of fields found and splits into +the C<@_> array. Use of split in scalar context is deprecated, however, +because it clobbers your subroutine arguments. If EXPR is omitted, splits the C<$_> string. If PATTERN is also omitted, splits on whitespace (after skipping any leading whitespace). Anything @@ -3807,7 +4327,7 @@ that the delimiter may be longer than one character.) If LIMIT is specified and positive, splits into no more than that many fields (though it may split into fewer). If LIMIT is unspecified or zero, trailing null fields are stripped (which potential users -of C would do well to remember). If LIMIT is negative, it is +of C would do well to remember). If LIMIT is negative, it is treated as if an arbitrarily large LIMIT had been specified. A pattern matching the null string (not to be confused with @@ -3829,7 +4349,7 @@ unnecessary work. For the list above LIMIT would have been 4 by default. In time critical applications it behooves you not to split into more fields than you really need. -If the PATTERN contains parentheses, additional array elements are +If the PATTERN contains parentheses, additional list elements are created from each matching substring in the delimiter. split(/([,-])/, "1-10,20", 3); @@ -3838,7 +4358,7 @@ produces the list value (1, '-', 10, ',', 20) -If you had the entire header of a normal Unix email message in C<$header>, +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 @@ -3849,13 +4369,16 @@ patterns that vary at runtime. (To do runtime compilation only once, use C.) As a special case, specifying a PATTERN of space (C<' '>) will split on -white space just as C with no arguments does. Thus, C can +white space just as C with no arguments does. Thus, C can be used to emulate B's default behavior, whereas C will give you as many null initial fields as there are leading spaces. -A C on C is like a C except that any leading -whitespace produces a null first field. A C with no arguments +A C on C is like a C except that any leading +whitespace produces a null first field. A C with no arguments really does a C internally. +A PATTERN of C is treated as if it were C, since it isn't +much use otherwise. + Example: open(PASSWD, '/etc/passwd'); @@ -3865,22 +4388,31 @@ Example: #... } -(Note that C<$shell> above will still have a newline on it. See L, +(Note that $shell above will still have a newline on it. See L, L, and L.) =item sprintf FORMAT, LIST -Returns a string formatted by the usual C conventions of the -C library function C. See L or L -on your system for an explanation of the general principles. +Returns a string formatted by the usual C conventions of the C +library function C. See below for more details +and see L or L on your system for an explanation of +the general principles. + +For example: + + # Format number with up to 8 leading zeroes + $result = sprintf("%08d", $number); + + # Round number to 3 digits after decimal point + $rounded = sprintf("%.3f", $number); -Perl does its own C formatting -- it emulates the C -function C, but it doesn't use it (except for floating-point +Perl does its own C formatting--it emulates the C +function C, but it doesn't use it (except for floating-point numbers, and even then only the standard modifiers are allowed). As a -result, any non-standard extensions in your local C are not +result, any non-standard extensions in your local C are not available from Perl. -Perl's C permits the following universally-known conversions: +Perl's C permits the following universally-known conversions: %% a percent sign %c a character with the given number @@ -3926,21 +4458,71 @@ and the conversion letter: for integer l interpret integer as C type "long" or "unsigned long" h interpret integer as C type "short" or "unsigned short" + If no flags, interpret integer as C type "int" or "unsigned" -There is also one Perl-specific flag: +There are also two Perl-specific flags: V interpret integer as Perl's standard integer type + v interpret string as a vector of integers, output as + numbers separated either by dots, or by an arbitrary + string received from the argument list when the flag + is preceded by C<*> -Where a number would appear in the flags, an asterisk ("C<*>") may be +Where a number would appear in the flags, an asterisk (C<*>) may be used instead, in which case Perl uses the next item in the parameter list as the given number (that is, as the field width or precision). -If a field width obtained through "C<*>" is negative, it has the same -effect as the "C<->" flag: left-justification. +If a field width obtained through C<*> is negative, it has the same +effect as the C<-> flag: left-justification. + +The C flag is useful for displaying ordinal values of characters +in arbitrary strings: + + printf "version is v%vd\n", $^V; # Perl's version + printf "address is %*vX\n", ":", $addr; # IPv6 address + printf "bits are %*vb\n", " ", $bits; # random bitstring If C is in effect, the character used for the decimal point in formatted real numbers is affected by the LC_NUMERIC locale. See L. +If Perl understands "quads" (64-bit integers) (this requires +either that the platform natively support quads or that Perl +be specifically compiled to support quads), the characters + + d u o x X b i D U O + +print quads, and they may optionally be preceded by + + ll L q + +For example + + %lld %16LX %qo + +You can find out whether your Perl supports quads via L: + + use Config; + ($Config{use64bitint} eq 'define' || $Config{longsize} == 8) && + print "quads\n"; + +If Perl understands "long doubles" (this requires that the platform +support long doubles), the flags + + e f g E F G + +may optionally be preceded by + + ll L + +For example + + %llf %Lg + +You can find out whether your Perl supports long doubles via L: + + use Config; + $Config{d_longdbl} eq 'define' && print "long doubles\n"; + =item sqrt EXPR =item sqrt @@ -3956,19 +4538,19 @@ loaded the standard Math::Complex module. =item srand -Sets the random number seed for the C operator. If EXPR is +Sets the random number seed for the C operator. If EXPR is omitted, uses a semi-random value supplied by the kernel (if it supports the F device) or based on the current time and process ID, among other things. In versions of Perl prior to 5.004 the default -seed was just the current C. This isn't a particularly good seed, +seed was just the current C