=head1 NAME perlfunc - Perl builtin functions =head1 DESCRIPTION The functions in this section can serve as terms in an expression. They fall into two major categories: list operators and named unary operators. These differ in their precedence relationship with a following comma. (See the precedence table in L.) List operators take more than one argument, while unary operators can never take more than one argument. Thus, a comma terminates the argument of 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 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 list (and provide list context for the elements of the list) are shown with LIST as an argument. Such a list may consist of any combination of scalar arguments or list values; the list values will be included in the list as if each individual element were interpolated at that point in the list, forming a longer single-dimensional list value. 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 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+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: print (...) interpreted as function at - line 1. Useless use of integer addition in void context at - line 1. For functions that can be used in either a scalar or list context, 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 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 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 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 Here are Perl's functions (including things that look like functions, like some keywords and named operators) arranged by category. Some functions appear in more than one place. =over =item Functions for SCALARs or strings C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C =item Regular expressions and pattern matching C, C, C, C, C, C, C =item Numeric functions C, C, C, C, C, C, C, C, C, C, C, C =item Functions for real @ARRAYs C, C, C, C, C =item Functions for list data C, C, C, C, C, C, C =item Functions for real %HASHes C, C, C, C, C =item Input and output functions 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 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. Note that if you're storing FILEHANDLES in an array or other expression, 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 FORMAT, LIST =item printf FORMAT, LIST 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 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 error prone. =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 Treats ARRAY as a stack, and pushes the values of LIST onto the end of ARRAY. The length of ARRAY increases by the length of LIST. Has the same effect as for $value (LIST) { $ARRAY[++$#ARRAY] = $value; } but is more efficient. Returns the new number of elements in the array. =item q/STRING/ =item qq/STRING/ =item qr/STRING/ =item qx/STRING/ =item qw/STRING/ Generalized quotes. See L. =item quotemeta EXPR =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 C<\Q> escape in double-quoted strings. If EXPR is omitted, uses C<$_>. =item rand EXPR =item rand 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. (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.) =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, 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. =item readdir DIRHANDLE 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 better prepend the directory in question. Otherwise, because we didn't 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); 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 C<$/> or C<$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 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 C<$_>. =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 C<$/> or C<$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 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. =item redo LABEL =item redo The C command restarts the loop block without evaluating the conditional again. The C block, if any, is not executed. If the LABEL is omitted, the command refers to the innermost enclosing loop. This command is normally used by programs that want to lie to themselves about what was just input: # a simpleminded Pascal comment stripper # (warning: assumes no { or } in strings) LINE: while () { while (s|({.*}.*){.*}|$1 |) {} s|{.*}| |; if (s|{.*| |) { $front = $_; while () { if (/}/) { # end of comment? s|^|$front\{|; redo LINE; } } } print; } See also L for an illustration of how C, C, and C work. =item ref EXPR =item ref 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 GLOB 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. if (ref($r) eq "HASH") { 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 C<1> for success, C<0> otherwise. Will not work across file system boundaries. =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. 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 subroutine: sub require { my($filename) = @_; return 1 if $INC{$filename}; my($realfilename,$result); ITER: { foreach $prefix (@INC) { $realfilename = "$prefix/$filename"; if (-f $realfilename) { $result = do $realfilename; last ITER; } } die "Can't find $filename in \@INC"; } 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 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 statements. 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. In other words, if you try this: require Foo::Bar; # a splendid bareword The require function will actually look for the "F" file in the directories specified in the C<@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 "F" file in the @INC array and will complain about not finding "F" there. In this case you can do: eval "require $class"; For a yet-more-powerful import facility, see L and L. =item reset EXPR =item reset Generally used in a C block at the end of a loop to clear variables and reset C 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 (C) 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 C<"A-Z"> is not recommended because you'll wipe out your C<@ARGV> and C<@INC> arrays and your C<%ENV> hash. 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 EXPR =item return 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 is given, returns an empty list in list context, an undefined value in scalar context, or nothing in a void context. (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 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, last line first 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 Sets the current position to the beginning of the directory for the C routine on DIRHANDLE. =item rindex STR,SUBSTR,POSITION =item rindex STR,SUBSTR Works just like index except that it returns the position of the LAST occurrence of SUBSTR in STR. If POSITION is specified, returns the last occurrence at or before that position. =item rmdir FILENAME =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 FILENAME is omitted, uses C<$_>. =item s/// The substitution operator. See L. =item scalar 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 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 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. 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. 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 C<1> (C) 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. 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. If that doesn't work (some stdios are particularly cantankerous), then you may need something more like this: for (;;) { for ($curpos = tell(FILE); $_ = ; $curpos = tell(FILE)) { # search for some stuff and put it into files } sleep($for_a_while); seek(FILE, $curpos, 0); } =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 possible directory compaction as the corresponding system library routine. =item select FILEHANDLE =item select 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 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 do the following: select(REPORT1); $^ = 'report1_top'; select(REPORT2); $^ = 'report2_top'; FILEHANDLE may be an expression whose value gives the name of the actual filehandle. Thus: $oldfh = select(STDERR); $| = 1; select($oldfh); Some programmers may prefer to think of filehandles as objects with methods, preferring to write the last example as: use IO::Handle; STDERR->autoflush(1); =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: $rin = $win = $ein = ''; vec($rin,fileno(STDIN),1) = 1; vec($win,fileno(STDOUT),1) = 1; $ein = $rin | $win; If you want to select on many filehandles you might wish to write a subroutine: sub fhbits { my(@fhlist) = split(' ',$_[0]); my($bits); for (@fhlist) { vec($bits,fileno($_),1) = 1; } $bits; } $rin = fhbits('STDIN TTY SOCK'); The usual idiom is: ($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout); 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>. 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>. 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. =item semctl ID,SEMNUM,CMD,ARG Calls the System V IPC function C. 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 C: the undefined value for error, "C<0> but true" for zero, or the actual return value otherwise. See also C and C 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. See also C and C documentation. =item semop KEY,OPSTRING Calls the System V IPC function semop to perform semaphore operations such as signaling and waiting. OPSTRING must be a packed array of semop structures. Each semop structure can be generated with C. The number of semaphore operations is implied by the length of OPSTRING. Returns TRUE if successful, or FALSE if there is an error. As an example, the following code waits on semaphore C<$semnum> of semaphore id C<$semid>: $semop = pack("sss", $semnum, -1, 0); die "Semaphore trouble: $!\n" unless semop($semid, $semop); To signal the semaphore, replace C<-1> with C<1>. See also C and C documentation. =item send SOCKET,MSG,FLAGS,TO =item send SOCKET,MSG,FLAGS Sends a message on a socket. Takes the same flags as the system call of the same name. On unconnected sockets you must specify a destination to send TO, in which case it does a C C. Returns the number of characters sent, or the undefined value if there is an error. See L for examples. =item setpgrp PID,PGRP Sets the current process group for the specified PID, C<0> for the current process. Will produce a fatal error if used on a machine that doesn't implement setpgrp(2). If the arguments are omitted, it defaults to C<0,0>. Note that the POSIX version of C does not accept any arguments, so only setpgrp C<0,0> is portable. =item setpriority WHICH,WHO,PRIORITY Sets the current priority for a process, a process group, or a user. (See setpriority(2).) Will produce a fatal error if used on a machine that doesn't implement setpriority(2). =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL Sets the socket option requested. Returns undefined if there is an error. OPTVAL may be specified as C if you don't want to pass an argument. =item shift ARRAY =item shift 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 C<@_> array within the lexical scope of subroutines and formats, and the C<@ARGV> array at file scopes or within the lexical scopes established by the C, C, C, and C constructs. See also C, C, and C. C and C do the same thing to the left end of an array that C and C do to the right end. =item shmctl ID,CMD,ARG 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 C, then ARG must be a variable which will hold the returned C structure. Returns like ioctl: the undefined value for error, "C<0> but true" for zero, or the actual return value otherwise. See also C 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 C documentation. =item shmread ID,VAR,POS,SIZE =item shmwrite ID,STRING,POS,SIZE 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 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 C 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 Returns the sine of EXPR (expressed in radians). If EXPR is omitted, returns sine of C<$_>. For the inverse sine operation, you may use the C function, or use this relation: sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) } =item sleep EXPR =item sleep Causes the script to sleep for EXPR seconds, or forever if no EXPR. May be interrupted if the process receives a signal such as C. Returns the number of seconds actually slept. You probably cannot mix C and C calls, because C is often implemented using C. 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. 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 C interface to access setitimer(2) if your system supports it, or else see L above. 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 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 for the system call of the same name. If unimplemented, yields a fatal error. Returns TRUE if successful. Some systems defined C in terms of C, 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. If SUBNAME or BLOCK 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 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. You also cannot exit out of the sort block or subroutine using any of the 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. Examples: # sort lexically @articles = sort @files; # same thing, but with explicit sort routine @articles = sort {$a cmp $b} @files; # now case-insensitively @articles = sort {uc($a) cmp uc($b)} @files; # same thing in reversed order @articles = sort {$b cmp $a} @files; # sort numerically ascending @articles = sort {$a <=> $b} @files; # sort numerically descending @articles = sort {$b <=> $a} @files; # 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'); print sort @harry; # prints AbelCaincatdogx print sort backwards @harry; # prints xdogcatCainAbel print sort @george, 'to', @harry; # prints AbelAxedCainPunishedcatchaseddoggonetoxyz # inefficiently sort by descending numeric compare using # the first integer after the first = sign, or the # whole record case-insensitively otherwise @new = sort { ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0] || uc($a) cmp uc($b) } @old; # same thing, but much more efficiently; # we'll build auxiliary indices instead # for speed @nums = @caps = (); for (@old) { push @nums, /=(\d+)/; push @caps, uc($_); } @new = @old[ sort { $nums[$b] <=> $nums[$a] || $caps[$a] cmp $caps[$b] } 0..$#old ]; # same thing using a Schwartzian Transform (no 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 @articles = sort {$FooPack::b <=> $FooPack::a} @files; The comparison function is required to behave. If it returns inconsistent results (sometimes saying C<$x[1]> is less than C<$x[2]> and sometimes saying the opposite, for example) the results are not well-defined. =item splice ARRAY,OFFSET,LENGTH,LIST =item splice ARRAY,OFFSET,LENGTH =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. 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) Example, assuming array lengths are passed before arrays: sub aeq { # compare two list values 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); } return 1; } if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... } =item split /PATTERN/,EXPR,LIMIT =item split /PATTERN/,EXPR =item split /PATTERN/ =item split 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 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. If EXPR is omitted, splits the C<$_> 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 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 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 matching a null string) will split the value of EXPR into separate characters at each point it matches that way. For example: print join(':', split(/ */, 'hi there')); produces the output 'h:i:t:h:e:r:e'. The LIMIT parameter can be used to split a line partially ($login, $passwd, $remainder) = split(/:/, $_, 3); When assigning to a list, if LIMIT is omitted, Perl supplies a LIMIT one larger than the number of variables in the list, to avoid 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 created from each matching substring in the delimiter. 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 C<$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*?):\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, 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 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 really does a C internally. Example: open(PASSWD, '/etc/passwd'); while () { ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/); #... } (Note that C<$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. 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 available from Perl. Perl's C 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 ("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 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 C<$_>. =item srand EXPR =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 C. This isn't a particularly good seed, so many old programs supply their own seed value (often C