X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=f87471b069bc65b3b559958122951ee384c16b38;hb=0ade19845bc827615a636e5c073d498c2244ec07;hp=b3cf4e4205021e03b34191f189b5ecd8567afede;hpb=93dc8474cb0353bd11e64192d213ed864602986f;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index b3cf4e4..f87471b 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -35,11 +35,11 @@ operator or unary operator, and precedence does matter. And whitespace between the function and left parenthesis doesn't count--so you need to be careful sometimes: - print 1+2+3; # Prints 6. - print(1+2) + 3; # Prints 3. - print (1+2)+3; # Also prints 3! - print +(1+2)+3; # Prints 6. - print ((1+2)+3); # Prints 6. + print 1+2+4; # Prints 7. + print(1+2) + 4; # Prints 3. + print (1+2)+4; # Also prints 3! + print +(1+2)+4; # Prints 7. + print ((1+2)+4); # Prints 7. If you run Perl with the B<-w> switch it can warn you about this. For example, the third line above produces: @@ -48,30 +48,40 @@ example, the third line above produces: Useless use of integer addition in void context at - line 1. For functions that can be used in either a scalar or list context, -non-abortive failure is generally indicated in a scalar context by +nonabortive failure is generally indicated in a scalar context by returning the undefined value, and in a list context by returning the null list. -Remember the following rule: - -=over 8 - -=item I - -=back - +Remember the following important rule: There is B that relates +the behavior of an expression in list context to its behavior in scalar +context, or vice versa. It might do two totally different things. Each operator and function decides which sort of value it would be most appropriate to return in a scalar context. Some operators return the -length of the list that would have been returned in a list context. Some +length of the list that would have been returned in list context. Some operators return the first value in the list. Some operators return the last value in the list. Some operators return a count of successful operations. In general, they do what you want, unless you want consistency. +An named array in scalar context is quite different from what would at +first glance appear to be a list in scalar context. You can't get a list +like C<(1,2,3)> into being in scalar context, because the compiler knows +the context at compile time. It would generate the scalar comma operator +there, not the list construction version of the comma. That means it +was never a list to start with. + +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 -1 on failure. Exceptions to this rule are wait(), +waitpid(), and syscall(). System calls also set the special C<$!> +variable on failure. Other functions do not, except accidentally. + =head2 Perl Functions by Category Here are Perl's functions (including things that look like -functions, like some of the keywords and named operators) +functions, like some keywords and named operators) arranged by category. Some functions appear in more than one place. @@ -79,117 +89,120 @@ than one place. =item Functions for SCALARs or strings -chomp, chop, chr, crypt, hex, index, lc, lcfirst, length, -oct, ord, pack, q/STRING/, qq/STRING/, reverse, rindex, -sprintf, substr, tr///, uc, ucfirst, y/// +C, C, C, C, C, C, C, C, +C, C, C, C, C/STRING/, C/STRING/, C, +C, C, C, C, C, C, C/// =item Regular expressions and pattern matching -m//, pos, quotemeta, s///, split, study +C//, C, C, C///, C, C =item Numeric functions -abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt, -srand +C, C, C, C, C, C, C, C, C, +C, C, C =item Functions for real @ARRAYs -pop, push, shift, splice, unshift +C, C, C, C, C =item Functions for list data -grep, join, map, qw/STRING/, reverse, sort, unpack +C, C, C, C/STRING/, C, C, C =item Functions for real %HASHes -delete, each, exists, keys, values +C, C, C, C, C =item Input and output functions -binmode, close, closedir, dbmclose, dbmopen, die, eof, -fileno, flock, format, getc, print, printf, read, readdir, -rewinddir, seek, seekdir, select, syscall, sysread, -syswrite, tell, telldir, truncate, warn, write +C, C, C, C, C, C, C, +C, C, C, C, C, C, C, +C, C, C, C, C). If LIST is also omitted, prints $_ to -STDOUT. To set the default output channel to something other than +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 a list context, and any +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 a list context. Also be careful not to follow the print +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 + or put parentheses around all the arguments. @@ -2219,13 +2557,14 @@ you will have to use a block returning its value instead: =item printf FORMAT, LIST -Equivalent to C. The first argument +Equivalent to C, except that $\ +(the output record separator) is not appended. The first argument of the list will be interpreted as the printf 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 printf() when a simple -print() would do. The print() is more efficient, and less +print() would do. The print() is more efficient and less error prone. =item prototype FUNCTION @@ -2234,6 +2573,13 @@ 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. +If FUNCTION is a string starting with C, the rest is taken as +a name for Perl builtin. If builtin is not I (such as +C) or its arguments cannot be expressed by a prototype (such as +C) - in other words, the builtin does not behave like a Perl +function - returns C. Otherwise, the string describing the +equivalent prototype is returned. + =item push ARRAY,LIST Treats ARRAY as a stack, and pushes the values of LIST @@ -2258,9 +2604,9 @@ Generalized quotes. See L. =item quotemeta EXPR -=item quotemeta +=item quotemeta -Returns the value of EXPR with with all non-alphanumeric +Returns the value of EXPR with all non-alphanumeric characters backslashed. (That is, all characters not matching C will be preceded by a backslash in the returned string, regardless of any locale settings.) @@ -2273,36 +2619,33 @@ If EXPR is omitted, uses $_. =item rand -Returns a random fractional number between 0 and the value of EXPR. -(EXPR should be positive.) If EXPR is omitted, returns a value between -0 and 1. Automatically calls srand() unless srand() has already been -called. See also srand(). +Returns a random fractional number greater than or equal to 0 and less +than the value of EXPR. (EXPR should be positive.) If EXPR is +omitted, the value 1 is used. Automatically calls srand() unless +srand() has already been called. See also srand(). -(Note: if your rand function consistently returns numbers that are too +(Note: If your rand function consistently returns numbers that are too large or too small, then your version of Perl was probably compiled -with the wrong number of RANDBITS. As a workaround, you can usually -multiply EXPR by the correct power of 2 to get the range you want. -This will make your script unportable, however. It's better to recompile -if you can.) +with the wrong number of RANDBITS.) =item read FILEHANDLE,SCALAR,LENGTH,OFFSET =item read FILEHANDLE,SCALAR,LENGTH Attempts to read LENGTH bytes of data into variable SCALAR from the -specified FILEHANDLE. Returns the number of bytes actually read, 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 call. To get a true -read system call, see sysread(). +specified FILEHANDLE. Returns the number of bytes actually read, +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 sysread(). =item readdir DIRHANDLE Returns the next directory entry for a directory opened by opendir(). -If used in a list context, returns all the rest of the entries in the +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 -a scalar context or a null list in a list context. +scalar context or a null list in list context. If you're planning to filetest the return values out of a readdir(), you'd better prepend the directory in question. Otherwise, because we didn't @@ -2312,23 +2655,47 @@ chdir() there, it would have been testing the wrong file. @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR); closedir DIR; +=item readline EXPR + +Reads from the filehandle whose typeglob is contained in EXPR. In scalar context, a single line +is read and returned. In list context, reads until end-of-file is +reached and returns a list of lines (however you've defined lines +with $/ or $INPUT_RECORD_SEPARATOR). +This is the internal function implementing the CEXPRE> +operator, but you can use it directly. The CEXPRE> +operator is discussed in more detail in L. + + $line = ; + $line = readline(*STDIN); # same thing + =item readlink EXPR -=item readlink +=item readlink Returns the value of a symbolic link, if symbolic links are implemented. If not, gives a fatal error. If there is some system error, returns the undefined value and sets C<$!> (errno). If EXPR is omitted, uses $_. +=item readpipe EXPR + +EXPR is executed as a system command. +The collected standard output of the command is returned. +In scalar context, it comes back as a single (potentially +multi-line) string. In list context, returns a list of lines +(however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR). +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. + =item recv SOCKET,SCALAR,LEN,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 recvfrom(), so that it can returns the address of the +Actually does a C recvfrom(), 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. +as the system call of the same name. See L for examples. =item redo LABEL @@ -2350,7 +2717,7 @@ themselves about what was just input: $front = $_; while () { if (/}/) { # end of comment? - s|^|$front{|; + s|^|$front\{|; redo LINE; } } @@ -2358,12 +2725,15 @@ themselves about what was just input: print; } +See also L for an illustration of how C, C, and +C work. + =item ref EXPR -=item ref +=item ref -Returns a TRUE value if EXPR is a reference, FALSE otherwise. If EXPR -is not specified, $_ will be used. The value returned depends on the +Returns a TRUE value if EXPR is a reference, FALSE otherwise. If EXPR +is not specified, $_ will be used. The value returned depends on the type of thing the reference is a reference to. Builtin types include: @@ -2374,15 +2744,15 @@ Builtin types include: CODE GLOB -If the referenced object has been blessed into a package, then that package +If the referenced object has been blessed into a package, then that package name is returned instead. You can think of ref() as a typeof() operator. if (ref($r) eq "HASH") { print "r is a reference to a hash.\n"; - } - if (!ref ($r) { + } + if (!ref($r)) { print "r is not a reference at all.\n"; - } + } See also L. @@ -2405,9 +2775,9 @@ essentially just a variety of eval(). Has semantics similar to the following subroutine: sub require { - local($filename) = @_; + my($filename) = @_; return 1 if $INC{$filename}; - local($realfilename,$result); + my($realfilename,$result); ITER: { foreach $prefix (@INC) { $realfilename = "$prefix/$filename"; @@ -2421,7 +2791,7 @@ subroutine: die $@ if $@; die "$filename did not return true value" unless $result; $INC{$filename} = $realfilename; - $result; + return $result; } Note that the file will not be included twice under the same specified @@ -2431,13 +2801,31 @@ end such a file with "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 bare word, the require assumes a "F<.pm>" extension and +If EXPR is a bareword, the require assumes a "F<.pm>" extension and replaces "F<::>" with "F" in the filename for you, -to make it easy to load standard modules. This form of loading of +to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace. -For a yet-more-powerful import facility, see L and -L. +In other words, if you try this: + + require Foo::Bar; # a splendid bareword + +The require function will actually look for the "Foo/Bar.pm" file in the +directories specified in the @INC array. + +But if you try this: + + $class = 'Foo::Bar'; + require $class; # $class is not a bareword + #or + require "Foo::Bar"; # not a bareword because of the "" + +The require function will look for the "Foo::Bar" file in the @INC array and +will complain about not finding "Foo::Bar" there. In this case you can do: + + eval "require $class"; + +For a yet-more-powerful import facility, see L and L. =item reset EXPR @@ -2461,23 +2849,39 @@ ARGV and ENV arrays. Resets only package variables--lexical variables are unaffected, but they clean themselves up on scope exit anyway, so you'll probably want to use them instead. See L. -=item return LIST +=item return EXPR + +=item return + +Returns from a subroutine, eval(), 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 wantarray()). If no EXPR +is given, returns an empty list in list context, an undefined value in +scalar context, or nothing in a void context. -Returns from a subroutine or eval with the value specified. (Note that -in the absence of a return a subroutine or eval() will automatically -return the value of the last expression evaluated.) +(Note that in the absence of a return, a subroutine, eval, or do FILE +will automatically return the value of the last expression evaluated.) =item reverse LIST -In a list context, returns a list value consisting of the elements -of LIST in the opposite order. In a scalar context, returns a string -value consisting of the bytes of the first element of LIST in the -opposite order. +In list context, returns a list value consisting of the elements +of LIST in the opposite order. In scalar context, concatenates the +elements of LIST, and returns a string value consisting of those bytes, +but in the opposite order. - print reverse <>; # line tac + print reverse <>; # line tac, last line first - undef $/; - print scalar reverse scalar <>; # byte tac + undef $/; # for efficiency of <> + print scalar reverse <>; # byte tac, last line tsrif + +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 +unwind one hash and build a whole new one, which may take some time +on a large hash. + + %by_name = reverse %by_address; # Invert the hash =item rewinddir DIRHANDLE @@ -2494,10 +2898,10 @@ last occurrence at or before that position. =item rmdir FILENAME -=item rmdir +=item rmdir -Deletes the directory specified by FILENAME if it is empty. If it -succeeds it returns 1, otherwise it returns 0 and sets C<$!> (errno). If +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 FILENAME is omitted, uses $_. =item s/// @@ -2506,39 +2910,43 @@ The substitution operator. See L. =item scalar EXPR -Forces EXPR to be interpreted in a scalar context and returns the value -of EXPR. +Forces EXPR to be interpreted in scalar context and returns the value +of EXPR. @counts = ( scalar @a, scalar @b, scalar @c ); -There is no equivalent operator to force an expression to -be interpolated in a list context because it's in practice never +There is no equivalent operator to force an expression to +be interpolated in list context because it's in practice never 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. =item seek FILEHANDLE,POSITION,WHENCE -Randomly positions the file pointer for FILEHANDLE, just like the fseek() -call of stdio. FILEHANDLE may be an expression whose value gives the name -of the filehandle. The values for WHENCE are 0 to set the file pointer to -POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF -plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for -this from POSIX module. Returns 1 upon success, 0 otherwise. +Sets FILEHANDLE's position, just like the fseek() call of stdio. +FILEHANDLE may be an expression whose value gives the name of the +filehandle. The values for WHENCE are 0 to set the new position to +POSITION, 1 to set it to the current position plus POSITION, and 2 to +set it to EOF plus POSITION (typically negative). For WHENCE you may +use the constants SEEK_SET, SEEK_CUR, and SEEK_END from either the +IO::Seekable or the POSIX module. Returns 1 upon success, 0 otherwise. + +If you want to position file for sysread() or syswrite(), don't use +seek() -- buffering makes its effect on the file's system position +unpredictable and non-portable. Use sysseek() instead. On some systems you have to do a seek whenever you switch between reading and writing. Amongst other things, this may have the effect of calling -stdio's clearerr(3). A "whence" of 1 (SEEK_CUR) is useful for not moving -the file pointer: +stdio's clearerr(3). A WHENCE of 1 (SEEK_CUR) is useful for not moving +the file position: seek(TEST,0,1); 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. First the simple trick listed above to clear the -filepointer. The seek() 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. +seek() to reset things. The seek() 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. If that doesn't work (some stdios are particularly cantankerous), then you may need something more like this: @@ -2600,8 +3008,8 @@ If you want to select on many filehandles you might wish to write a subroutine: sub fhbits { - local(@fhlist) = split(' ',$_[0]); - local($bits); + my(@fhlist) = split(' ',$_[0]); + my($bits); for (@fhlist) { vec($bits,fileno($_),1) = 1; } @@ -2614,12 +3022,12 @@ The usual idiom is: ($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout); -or to block until something becomes ready just do this +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 $timeleft, so -calling select() in a scalar context just returns $nfound. +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 @@ -2630,21 +3038,27 @@ You can effect a sleep of 250 milliseconds this way: select(undef, undef, undef, 0.25); -B: Do not attempt to mix buffered I/O (like read() or EFHE) -with select(). You have to use sysread() instead. +B: One should not attempt to mix buffered I/O (like read() +or EFHE) with select(), except as permitted by POSIX, and even +then only on POSIX systems. You have to use sysread() instead. =item semctl ID,SEMNUM,CMD,ARG -Calls the System V IPC function semctl. If CMD is &IPC_STAT or -&GETALL, then ARG must be a variable which will hold the returned +Calls the System V IPC function semctl. You'll probably have to say + + use IPC::SysV; + +first to get the correct constant definitions. If CMD is IPC_STAT or +GETALL, then ARG must be a variable which will hold the returned semid_ds structure or semaphore value array. Returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return -value otherwise. +value otherwise. See also IPC::SysV and IPC::Semaphore documentation. =item semget KEY,NSEMS,FLAGS Calls the System V IPC function semget. Returns the semaphore id, or -the undefined value if there is an error. +the undefined value if there is an error. See also IPC::SysV and +IPC::SysV::Semaphore documentation. =item semop KEY,OPSTRING @@ -2659,7 +3073,8 @@ following code waits on semaphore $semnum of semaphore id $semid: $semop = pack("sss", $semnum, -1, 0); die "Semaphore trouble: $!\n" unless semop($semid, $semop); -To signal the semaphore, replace "-1" with "1". +To signal the semaphore, replace "-1" with "1". See also IPC::SysV +and IPC::SysV::Semaphore documentation. =item send SOCKET,MSG,FLAGS,TO @@ -2699,22 +3114,30 @@ argument. Shifts the first value of the array off and returns it, shortening the array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the -@ARGV array in the main program, and the @_ array in subroutines. -(This is determined lexically.) See also unshift(), push(), and pop(). -Shift() and unshift() do the same thing to the left end of an array -that push() and pop() do to the right end. +@_ array within the lexical scope of subroutines and formats, and the +@ARGV array at file scopes or within the lexical scopes established by +the C, C, C, and C constructs. +See also unshift(), push(), and pop(). Shift() and unshift() do the +same thing to the left end of an array that pop() and push() do to the +right end. =item shmctl ID,CMD,ARG -Calls the System V IPC function shmctl. If CMD is &IPC_STAT, then ARG -must be a variable which will hold the returned shmid_ds structure. -Returns like ioctl: the undefined value for error, "0 but true" for -zero, or the actual return value otherwise. +Calls the System V IPC function shmctl. You'll probably have to say + + use IPC::SysV; + +first to get the correct constant definitions. If CMD is IPC_STAT, +then ARG must be a variable which will hold the returned shmid_ds +structure. Returns like ioctl: the undefined value for error, "0 but +true" for zero, or the actual return value otherwise. +See also IPC::SysV documentation. =item shmget KEY,SIZE,FLAGS Calls the System V IPC function shmget. Returns the shared memory segment id, or the undefined value if there is an error. +See also IPC::SysV documentation. =item shmread ID,VAR,POS,SIZE @@ -2722,24 +3145,35 @@ segment id, or the undefined value if there is an error. Reads or writes the System V shared memory segment ID starting at position POS for size SIZE by attaching to it, copying in/out, and -detaching from it. When reading, VAR must be a variable which will +detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return TRUE if successful, or FALSE if there is an error. +See also IPC::SysV documentation. =item shutdown SOCKET,HOW Shuts down a socket connection in the manner indicated by HOW, which has the same interpretation as in the system call of the same name. + shutdown(SOCKET, 0); # I/we have stopped reading data + shutdown(SOCKET, 1); # I/we have stopped writing data + shutdown(SOCKET, 2); # I/we have stopped using this socket + +This is useful with sockets when you want to tell the other +side you're done writing but not done reading, or vice versa. +It's also a more insistent form of close because it also +disables the filedescriptor in any forked copies in other +processes. + =item sin EXPR -=item sin +=item sin Returns the sine of EXPR (expressed in radians). If EXPR is omitted, returns sine of $_. -For the inverse sine operation, you may use the POSIX::sin() +For the inverse sine operation, you may use the POSIX::asin() function, or use this relation: sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) } @@ -2749,17 +3183,20 @@ function, or use this relation: =item sleep Causes the script to sleep for EXPR seconds, or forever if no EXPR. -May be interrupted by sending the process a SIGALRM. Returns the -number of seconds actually slept. You probably cannot mix alarm() and -sleep() calls, because sleep() is often implemented using alarm(). +May be interrupted if the process receives a signal such as SIGALRM. +Returns the number of seconds actually slept. You probably cannot +mix alarm() and sleep() calls, because sleep() is often implemented +using 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 -always sleep the full amount. +always sleep the full amount. They may appear to sleep longer than that, +however, because your process might not be scheduled right away in a +busy multitasking system. For delays of finer granularity than one second, you may use Perl's -syscall() interface to access setitimer(2) if your system supports it, -or else see L below. +syscall() interface to access setitimer(2) if your system supports it, +or else see L above. See also the POSIX module's sigpause() function. @@ -2777,21 +3214,31 @@ 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. +Some systems defined pipe() in terms of socketpair, in which a call +to C is essentially: + + use Socket; + socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC); + shutdown(Rdr, 1); # no more writing for reader + shutdown(Wtr, 0); # no more reading for writer + +See L for an example of socketpair use. + =item sort SUBNAME LIST =item sort BLOCK LIST =item sort LIST -Sorts the LIST and returns the sorted list value. Nonexistent values -of arrays are stripped out. If SUBNAME or BLOCK is omitted, sorts -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 0, depending on how the elements of the array are -to be ordered. (The E=E and cmp operators are extremely useful in such -routines.) SUBNAME may be a scalar variable name, in which case the -value provides the name of the subroutine to use. In place of a -SUBNAME, you can provide a BLOCK as an anonymous, in-line sort +Sorts the LIST and returns the sorted list value. If SUBNAME or BLOCK +is omitted, sorts 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 0, depending on how the elements +of the array are to be ordered. (The C=E> 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 @@ -2816,7 +3263,7 @@ Examples: @articles = sort {$a cmp $b} @files; # now case-insensitively - @articles = sort { uc($a) cmp uc($b)} @files; + @articles = sort {uc($a) cmp uc($b)} @files; # same thing in reversed order @articles = sort {$b cmp $a} @files; @@ -2829,7 +3276,7 @@ Examples: # sort using explicit subroutine name sub byage { - $age{$a} <=> $age{$b}; # presuming integers + $age{$a} <=> $age{$b}; # presuming numeric } @sortedclass = sort byage @class; @@ -2847,8 +3294,8 @@ Examples: print sort @george, 'to', @harry; # prints AbelAxedCainPunishedcatchaseddoggonetoxyz - # inefficiently sort by descending numeric compare using - # the first integer after the first = sign, or the + # inefficiently sort by descending numeric compare using + # the first integer after the first = sign, or the # whole record case-insensitively otherwise @new = sort { @@ -2861,10 +3308,10 @@ Examples: # we'll build auxiliary indices instead # for speed @nums = @caps = (); - for (@old) { + for (@old) { push @nums, /=(\d+)/; push @caps, uc($_); - } + } @new = @old[ sort { $nums[$b] <=> $nums[$a] @@ -2908,22 +3355,26 @@ sanity checks in the interest of speed. =item splice ARRAY,OFFSET Removes the elements designated by OFFSET and LENGTH from an array, and -replaces them with the elements of LIST, if any. Returns the elements -removed from the array. The array grows or shrinks as necessary. If -LENGTH is omitted, removes everything from OFFSET onward. The -following equivalences hold (assuming C<$[ == 0>): - - push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y) +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 LENGTH is omitted, removes everything from OFFSET onward. +If LENGTH is negative, leave that many elements off the end of the array. +The following equivalences hold (assuming C<$[ == 0>): + + push(@a,$x,$y) splice(@a,@a,0,$x,$y) pop(@a) splice(@a,-1) shift(@a) splice(@a,0,1) unshift(@a,$x,$y) splice(@a,0,0,$x,$y) - $a[$x] = $y splice(@a,$x,1,$y); + $a[$x] = $y splice(@a,$x,1,$y) Example, assuming array lengths are passed before arrays: sub aeq { # compare two list values - local(@a) = splice(@_,0,shift); - local(@b) = splice(@_,0,shift); + my(@a) = splice(@_,0,shift); + my(@b) = splice(@_,0,shift); return 0 unless @a == @b; # same len? while (@a) { return 0 if pop(@a) ne pop(@b); @@ -2940,22 +3391,25 @@ Example, assuming array lengths are passed before arrays: =item split -Splits a string into an array of strings, and returns it. +Splits a string into an array of strings, and returns it. By default, +empty leading fields are preserved, and empty trailing ones are deleted. -If not in a list context, returns the number of fields found and splits into -the @_ array. (In a list context, you can force the split into @_ by -using C as the pattern delimiters, but it still returns the array -value.) The use of implicit split to @_ is deprecated, however. +If not in list context, returns the number of fields found and splits into +the @_ array. (In list context, you can force the split into @_ by +using C as the pattern delimiters, but it still returns the list +value.) The use of implicit split to @_ is deprecated, however, because +it clobbers your subroutine arguments. If EXPR is omitted, splits the $_ string. If PATTERN is also omitted, splits on whitespace (after skipping any leading whitespace). Anything matching PATTERN is taken to be a delimiter separating the fields. (Note -that the delimiter may be longer than one character.) If LIMIT is -specified and is not negative, splits into no more than that many fields -(though it may split into fewer). If LIMIT is unspecified, trailing null -fields are stripped (which potential users of pop() would do well to -remember). If LIMIT is negative, it is treated as if an arbitrarily large -LIMIT had been specified. +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 pop() 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 a null pattern C, which is just one member of the set of patterns @@ -2985,11 +3439,11 @@ produces the list value (1, '-', 10, ',', 20) -If you had the entire header of a normal Unix email message in $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 - %hdrs = (UNIX_FROM => split /^(.*?):\s*/m, $header); + %hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header); The pattern C may be replaced with an expression to specify patterns that vary at runtime. (To do runtime compilation only once, @@ -3005,31 +3459,89 @@ really does a C internally. Example: - open(passwd, '/etc/passwd'); - while () { - ($login, $passwd, $uid, $gid, $gcos, - $home, $shell) = split(/:/); - ... + open(PASSWD, '/etc/passwd'); + while () { + ($login, $passwd, $uid, $gid, $gcos,$home, $shell) = split(/:/); + #... } -(Note that $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 printf conventions of the C -language. See L or L on your system for details. -(The * character for an indirectly specified length is not -supported, but you can get the same effect by interpolating a variable -into the pattern.) 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. -Some C libraries' implementations of sprintf() can -dump core when fed ludicrous arguments. +Returns a string formatted by the usual printf conventions of the +C library function sprintf(). See L or L +on your system for an explanation of the general principles. + +Perl does its own sprintf() formatting -- it emulates the C +function sprintf(), 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 sprintf() are not +available from Perl. + +Perl's sprintf() permits the following universally-known conversions: + + %% a percent sign + %c a character with the given number + %s a string + %d a signed integer, in decimal + %u an unsigned integer, in decimal + %o an unsigned integer, in octal + %x an unsigned integer, in hexadecimal + %e a floating-point number, in scientific notation + %f a floating-point number, in fixed decimal notation + %g a floating-point number, in %e or %f notation + +In addition, Perl permits the following widely-supported conversions: + + %X like %x, but using upper-case letters + %E like %e, but using an upper-case "E" + %G like %g, but with an upper-case "E" (if applicable) + %p a pointer (outputs the Perl value's address in hexadecimal) + %n special: *stores* the number of characters output so far + into the next variable in the parameter list + +Finally, for backward (and we do mean "backward") compatibility, Perl +permits these unnecessary but widely-supported conversions: + + %i a synonym for %d + %D a synonym for %ld + %U a synonym for %lu + %O a synonym for %lo + %F a synonym for %f + +Perl permits the following universally-known flags between the C<%> +and the conversion letter: + + space prefix positive number with a space + + prefix positive number with a plus sign + - left-justify within the field + 0 use zeros, not spaces, to right-justify + # prefix non-zero octal with "0", non-zero hex with "0x" + number minimum field width + .number "precision": digits after decimal point for floating-point, + max length for string, minimum length for integer + l interpret integer as C type "long" or "unsigned long" + h interpret integer as C type "short" or "unsigned short" + +There is also one Perl-specific flag: + + V interpret integer as Perl's standard integer type + +Where a number would appear in the flags, an asterisk ("*") 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 "*" is negative, it has the same +effect as the '-' flag: left-justification. + +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. =item sqrt EXPR -=item sqrt +=item sqrt Return the square root of EXPR. If EXPR is omitted, returns square root of $_. @@ -3043,16 +3555,18 @@ omitted, uses a semi-random value 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 time(). This isn't a particularly good seed, so many old programs supply their own seed value (often C