X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/22dc801b01be340f8de52cbeaf93644d57682f7c..cc6b73957505a73b130c87add7bf3d534f129041:/pod/perlfunc.pod diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index fe661aa..0570c8f 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -1,3 +1,4 @@ + =head1 NAME perlfunc - Perl builtin functions @@ -14,8 +15,8 @@ a unary operator, but merely separates the arguments of a list operator. A unary operator generally provides a scalar context to its argument, while a list operator may provide either scalar and list contexts for its arguments. If it does both, the scalar arguments will -be first, and the list argument will follow. (Note that there can only -ever be one list argument.) For instance, splice() has three scalar +be first, and the list argument will follow. (Note that there can ever +be only one list argument.) For instance, splice() has three scalar arguments followed by a list. In the syntax descriptions that follow, list operators that expect a @@ -28,18 +29,18 @@ 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 -parens.) If you use the parens, the simple (but occasionally +parentheses.) If you use the parentheses, the simple (but occasionally 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 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,7 +49,7 @@ 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. @@ -56,9 +57,7 @@ Remember the following rule: =over 8 -=item - -I +=item I =back @@ -81,117 +80,132 @@ 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 STDOUT use the select operation. Note that, because print takes a LIST, anything in the LIST is evaluated in a list context, and any @@ -1946,20 +2347,39 @@ 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 keyword with a left parenthesis unless you want the corresponding right parenthesis to terminate the arguments to the print--interpose a + or -put parens around all the arguments. +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 +you will have to use a block returning its value instead: print { $files[$i] } "stuff\n"; print { $OK ? STDOUT : STDERR } "stuff\n"; -=item printf FILEHANDLE LIST +=item printf FILEHANDLE FORMAT, LIST + +=item printf FORMAT, LIST + +Equivalent to C. 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. -=item printf LIST +Don't fall into the trap of using a printf() when a simple +print() would do. The print() is more efficient, and less +error prone. -Equivalent to a "print FILEHANDLE sprintf(LIST)". The first argument -of the list will be interpreted as the printf format. +=item prototype FUNCTION + +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 @@ -1985,25 +2405,29 @@ Generalized quotes. See L. =item quotemeta EXPR -Returns the value of EXPR with with all regular expression -metacharacters backslashed. This is the internal function implementing +=item quotemeta + +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.) +This is the internal function implementing the \Q escape in double-quoted strings. +If EXPR is omitted, uses $_. + =item rand EXPR =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. This function produces repeatable sequences unless srand() -is invoked. 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 @@ -2025,20 +2449,43 @@ directory. If there are no more entries, returns an undefined value in a scalar context or a null list in a list context. If you're planning to filetest the return values out of a readdir(), you'd -better prepend the directory in question. Otherwise, since we didn't +better prepend the directory in question. Otherwise, because we didn't chdir() there, it would have been testing the wrong file. opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!"; @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR); closedir DIR; +=item readline EXPR + +Reads from the file handle 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. + =item readlink EXPR +=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 $! (errno). If EXPR is +error, returns the undefined value and sets C<$!> (errno). If EXPR is omitted, uses $_. +=item readpipe EXPR + +EXPR is interpolated and then 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 @@ -2046,7 +2493,7 @@ data into variable SCALAR from the specified SOCKET filehandle. Actually does a C recvfrom(), so that it can returns 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 @@ -2078,8 +2525,11 @@ themselves about what was just input: =item ref EXPR -Returns a TRUE value if EXPR is a reference, FALSE otherwise. The value -returned depends on the type of thing the reference is a reference to. +=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 +type of thing the reference is a reference to. Builtin types include: REF @@ -2089,22 +2539,22 @@ 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 an associative array.\n"; - } + print "r is a reference to a hash.\n"; + } if (!ref ($r) { print "r is not a reference at all.\n"; - } + } See also L. =item rename OLDNAME,NEWNAME Changes the name of a file. Returns 1 for success, 0 otherwise. Will -not work across filesystem boundaries. +not work across file system boundaries. =item require EXPR @@ -2112,7 +2562,7 @@ not work across filesystem boundaries. Demands some semantics specified by EXPR, or by $_ if EXPR is not supplied. If EXPR is numeric, demands that the current version of Perl -($] or $PERL_VERSION) be equal or greater than EXPR. +(C<$]> or $PERL_VERSION) be equal or greater than EXPR. 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 @@ -2146,11 +2596,12 @@ 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 for you, -to make it easy to load standard modules. This form of loading of +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 modules does not risk altering your namespace. -For a yet-more-powerful import facility, see the L and +For a yet-more-powerful import facility, see L and L. =item reset EXPR @@ -2162,36 +2613,52 @@ variables and reset ?? searches so that they work again. The expression is interpreted as a list of single characters (hyphens allowed for ranges). All variables and arrays beginning with one of those letters are reset to their pristine state. If the expression is -omitted, one-match searches (?pattern?) are reset to match again. Only -resets variables or searches in the current package. Always returns +omitted, one-match searches (?pattern?) are reset to match again. Resets +only variables or searches in the current package. Always returns 1. Examples: reset 'X'; # reset all X variables reset 'a-z'; # reset lower case variables reset; # just reset ?? searches -Resetting "A-Z" is not recommended since you'll wipe out your -ARGV and ENV arrays. Only resets package variables--lexical variables +Resetting "A-Z" is not recommended because you'll wipe out your +ARGV and ENV arrays. Resets only package variables--lexical variables are unaffected, but they clean themselves up on scope exit anyway, -so anymore you probably want to use them instead. See L. +so you'll probably want to use them instead. See L. + +=item return EXPR + +=item return -=item return LIST +Returns from a subroutine, eval(), or do FILE with the value of the +given EXPR. Evaluation of EXPR may be in a 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 a list context, an undefined value in +a 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. +of LIST in the opposite order. In a 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 @@ -2208,8 +2675,10 @@ last occurrence at or before that position. =item rmdir FILENAME +=item rmdir + Deletes the directory specified by FILENAME if it is empty. If it -succeeds it returns 1, otherwise it returns 0 and sets $! (errno). If +succeeds it returns 1, otherwise it returns 0 and sets C<$!> (errno). If FILENAME is omitted, uses $_. =item s/// @@ -2219,11 +2688,11 @@ The substitution operator. See L. =item scalar EXPR Forces EXPR to be interpreted in a scalar context and returns the value -of EXPR. +of EXPR. @counts = ( scalar @a, scalar @b, scalar @c ); -There is no equivalent operator to force an expression to +There is no equivalent operator to force an expression to be interpolated in a 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 @@ -2231,26 +2700,30 @@ 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 -CFILE> makes Perl try again to read something. Hopefully. +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: @@ -2295,12 +2768,12 @@ actual filehandle. Thus: Some programmers may prefer to think of filehandles as objects with methods, preferring to write the last example as: - use FileHandle; + use IO::Handle; STDERR->autoflush(1); =item select RBITS,WBITS,EBITS,TIMEOUT -This calls the select(2) system call with the bitmasks specified, which +This calls the select(2) system call with the bit masks specified, which can be constructed using fileno() and vec(), along these lines: $rin = $win = $ein = ''; @@ -2326,20 +2799,23 @@ The usual idiom is: ($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout); -or to block until something becomes ready: +or to block until something becomes ready just do this $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); -Any of the bitmasks can also be undef. The timeout, if specified, is +Most systems do not bother to return anything useful in $timeleft, so +calling select() in a 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 the $timeleft. If not, they always return $timeleft equal to the supplied $timeout. -You can effect a 250-microsecond sleep this way: +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 ) +B: Do not attempt to mix buffered I/O (like read() or EFHE) with select(). You have to use sysread() instead. =item semctl ID,SEMNUM,CMD,ARG @@ -2385,7 +2861,9 @@ See L for examples. Sets the current process group for the specified PID, 0 for the current process. Will produce a fatal error if used on a machine that doesn't -implement setpgrp(2). +implement setpgrp(2). If the arguments are omitted, it defaults to +0,0. Note that the POSIX version of setpgrp() does not accept any +arguments, so only setpgrp 0,0 is portable. =item setpriority WHICH,WHO,PRIORITY @@ -2406,10 +2884,12 @@ 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 @@ -2441,9 +2921,16 @@ has the same interpretation as in the system call of the same name. =item sin EXPR +=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::asin() +function, or use this relation: + + sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) } + =item sleep EXPR =item sleep @@ -2451,27 +2938,29 @@ returns sine of $_. 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, since sleep() is often implemented using alarm(). +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. 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 below. + +See also the POSIX module's sigpause() 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 +SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for the system call of the same name. You should "use Socket;" first to get the proper definitions imported. See the example in 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 +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. @@ -2481,16 +2970,15 @@ error. Returns TRUE if successful. =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 <=> 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 -subroutine. +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, 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 subroutine. In the interests of efficiency the normal calling code for subroutines is bypassed, with the following effects: the subroutine may not be a @@ -2499,6 +2987,12 @@ the subroutine not via @_ but as the package global variables $a and $b (see example below). They are passed by reference, so don't modify $a and $b. And don't try to declare them as lexicals either. +You also cannot exit out of the sort block or subroutine using any of the +loop control operators described in L or with goto(). + +When C is in effect, C sorts LIST according to the +current collation locale. See L. + Examples: # sort lexically @@ -2508,7 +3002,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; @@ -2521,10 +3015,14 @@ Examples: # sort using explicit subroutine name sub byage { - $age{$a} <=> $age{$b}; # presuming integers + $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'); @@ -2535,8 +3033,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 { @@ -2549,10 +3047,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] @@ -2568,7 +3066,7 @@ Examples: $a->[2] cmp $b->[2] } map { [$_, /=(\d+)/, uc($_)] } @old; -If you're and using strict, you I declare $a +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, it's @@ -2582,6 +3080,13 @@ but if you're in the C package, it's @articles = sort {$FooPack::b <=> $FooPack::a} @files; +The comparison function is required to behave. If it returns +inconsistent results (sometimes saying $x[1] is less than $x[2] and +sometimes saying the opposite, for example) the Perl interpreter will +probably crash and dump core. This is entirely due to and dependent +upon your system's qsort(3) library routine; this routine often avoids +sanity checks in the interest of speed. + =item splice ARRAY,OFFSET,LENGTH,LIST =item splice ARRAY,OFFSET,LENGTH @@ -2592,7 +3097,7 @@ 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 equivalencies hold (assuming $[ == 0): +following equivalences hold (assuming C<$[ == 0>): push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y) pop(@a) splice(@a,-1) @@ -2631,12 +3136,13 @@ value.) The use of implicit split to @_ is deprecated, however. 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 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. 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 @@ -2647,7 +3153,7 @@ characters at each point it matches that way. For example: produces the output 'h:i:t:h:e:r:e'. -The LIMIT parameter can be used to partially split a line +The LIMIT parameter can be used to split a line partially ($login, $passwd, $remainder) = split(/:/, $_, 3); @@ -2660,17 +3166,17 @@ into more fields than you really need. If the PATTERN contains parentheses, additional array elements are created from each matching substring in the delimiter. - split(/([,-])/, "1-10,20"); + split(/([,-])/, "1-10,20", 3); 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, @@ -2688,50 +3194,170 @@ Example: open(passwd, '/etc/passwd'); while () { - ($login, $passwd, $uid, $gid, $gcos, + ($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.) Some C libraries' implementations of sprintf() can -dump core when fed ludicrous arguments. +=item sprintf FORMAT, LIST + +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 all of 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 octal with "0", 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 + Return the square root of EXPR. If EXPR is omitted, returns square root of $_. =item srand EXPR -Sets the random number seed for the C operator. If EXPR is omitted, -does C. Many folks use an explicit C -instead. Of course, you'd need something much more random than that for -cryptographic purposes, since it's easy to guess the current time. -Checksumming the compressed output of rapidly changing operating system -status programs is the usual method. Examples are posted regularly to -the comp.security.unix newsgroup. +=item srand + +Sets the random number seed for the C operator. If EXPR is +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