Chapter 29. Functions - Perl Cd Bookshelf [Electronic resources] نسخه متنی

Chapter 29. Functions

Contents:

Perl Functions in Alphabetical Order

This chapter describes the built-in Perl functions in alphabetical
order[1] for convenient reference. Each function
description begins with a brief summary of the syntax for that
function. Parameter names like THIS
represent placeholders for actual expressions, and the text following
the syntax summary will describe the semantics of supplying (or
omitting) the actual arguments.

[1] Sometimes tightly related functions are grouped
together in the system manpages, so we respect that grouping here. To
find the description of endpwent, for instance,
you''ll have to look under getpwent.

You can think of functions as terms in an expression, along with
literals and variables. Or you can think of them as prefix operators
that process the arguments after them. We call them operators half the
time anyway.

Some of these operators, er, functions take a LIST as an argument.
Elements of the LIST should be separated by commas (or by =>,
which is just a funny kind of comma). The elements of the LIST are
evaluated in a list context, so each element will return either a
scalar or a list value, depending on its sensitivity to list context.
Each returned value, whether scalar or list, will be interpolated as
part of the overall sequence of scalar values. That is, all the lists
get flattened into one list. From the viewpoint of the function
receiving the arguments, the overall argument LIST is always a
single-dimensional list value. (To interpolate an array as a single
element, you must explicitly create and interpolate a reference to the
array instead.)

Predefined Perl functions may be used either with or without
parentheses around their arguments; the syntax summaries in this
chapter omit the parentheses. If you do use parentheses, the simple
but occasionally surprising rule is this: if it looks like a function,
then it is a function, so precedence doesn''t
matter. Otherwise, it''s a list operator or unary operator, and
precedence does matter. Be careful, because even if you put
whitespace between the keyword and its left parenthesis, that doesn''t
keep it from being a function:

print 1+2*4;       # Prints 9.
print(1+2) * 4;    # Prints 3!
print (1+2)*4;     # Also prints 3!
print +(1+2)*4;    # Prints 12.
print ((1+2)*4);   # Prints 12.

print (...) interpreted as function at - line 2.
Useless use of integer multiplication in void context at - line 2.

chmod 0644, @array;

chmod LIST

unshift @array, 0644;
chmod @array;

In contrast to the simple LIST functions, other functions impose
additional syntactic constraints. For instance, push has a syntax
summary that looks like this:

push ARRAY, LIST

For those operations that are based directly on the C library''s
functions, we do not attempt to duplicate your system''s documentation.
When a function description says to see
function(2), that means that you should
look up the corresponding C version of that function to learn more
about its semantics. The number in parentheses indicates the section
of the system programmer''s manual in which you will find the manpage,
if you have the manpages installed. (And in which you won''t, if you
don''t.)

These manpages may document system-dependent behavior like
shadow password files, access control lists, and so forth. Many
Perl functions that derive from C library functions in Unix are
emulated even on non-Unix platforms. For example, although your
operating system might not support the flock(2) or fork(2)
syscalls, Perl will do its best to emulate them anyway by using
whatever native facilities your platform provides.

Occasionally, you''ll find that the documented C function has more
arguments than the corresponding Perl function. Generally, the missing
arguments are things that Perl knows already, such as the length of the
previous argument, so you needn''t supply them in Perl. Any remaining
disparities are caused by the different ways Perl and C specify
filehandles and success/failure values.

In general, functions in Perl that serve as wrappers for syscalls
of the same name (like chown(2), fork(2), closedir(2), etc.) all
return true when they succeed and undef otherwise, as mentioned
in the descriptions that follow. This is different from the C library''s
interfaces to these operations, which all return -1 on failure.
Exceptions to this rule are wait, waitpid, and syscall.
Syscalls also set the special $! ($OS_ERROR) variable on failure. Other
functions do not, except accidentally.

For functions that can be used in either scalar or list context,
failure is generally indicated in scalar context by returning a
false value (usually undef) and in list context by returning
the null list. Successful execution is generally indicated by
returning a value that will evaluate to true (in context).

Remember the following rule: there is no rule that relates the
behavior of a function in list context to its behavior in scalar
context, or vice versa. It might do two totally different things.

Each function knows the context in which it was called. The same
function that returns a list when called in list context will,
when called in scalar context, return whichever kind of value would be most appropriate. Some functions return the
length of the list that would have been returned in list context.
Some operators return the first value in the list. Some functions
return the last value in the list. Some functions return the "other"
value, when something can be looked up either by number or by name.
Some functions return a count of successful operations. In general,
Perl functions do exactly what you want, unless you want consistency.

One final note: we''ve tried to be very consistent in our use of the
terms "byte" and "character". Historically, these terms have been
confused with each other (and with themselves). But when we say "byte"
we always mean an octet, 8 bits. When we say "character", we mean an
abstract character, usually a Unicode character, which may be
represented by one or more bytes within your strings.

But notice that we said "usually". Perl purposefully confuses bytes
with characters in the scope of a use bytes declaration, so whenever
we say "character", you should take it to mean a byte in a use bytes
context, and a Unicode character otherwise. In other words, use bytes just warps the definition of character back to what it was in
older versions of Perl. So, for instance, when we say that a scalar
reverse reverses a string character by character, don''t ask us
whether that really means characters or bytes, because the answer is,
"Yes, it does."

29.1. Perl Functions by Category

Here are Perl''s functions and function-like keywords, arranged by
category. Some functions appear under more than one heading.

Scalar manipulation

chomp, chop, chr, crypt, hex,
index, lc, lcfirst, length, oct, ord, pack, q//, qq//, reverse, rindex,
sprintf, substr, tr///,
uc, ucfirst, y///

Regular expressions and pattern matching

m//, pos,
qr//, quotemeta, s///, split, study

Numeric functions

abs, atan2, cos, exp, hex, int, log, oct,
rand, sin, sqrt, srand

Array processing

pop, push, shift, splice, unshift

List processing

grep, join, map, qw//, reverse, sort, unpack

Hash processing

delete, each, exists, keys, values

Input and output

binmode, close, closedir, dbmclose, dbmopen, die,
eof, fileno, flock, format, getc, print, printf,
read, readdir, readpipe, rewinddir, seek, seekdir,
select (ready file descriptors), syscall, sysread, sysseek,
syswrite, tell, telldir, truncate, warn, write

Fixed-length data and records

pack, read, syscall, sysread, sysseek, syswrite,
unpack, vec

Filehandles, files, and directories

chdir, chmod, chown, chroot, fcntl, glob, ioctl,
link, lstat, mkdir, open, opendir, readlink,
rename, rmdir, select (ready file descriptors), select
(output filehandle), stat, symlink, sysopen, umask,
unlink, utime

Flow of program control

caller, continue, die, do, dump, eval, exit,
goto, last, next, redo, return, sub, wantarray

Scoping

caller, import, local, my, no, our, package, use

Miscellaneous

defined, dump, eval, formline, lock,
prototype, reset, scalar, undef, wantarray

Processes and process groups

alarm, exec, fork, getpgrp, getppid, getpriority,
kill, pipe, qx//,
setpgrp, setpriority, sleep, system, times, wait,
waitpid

Library modules

do, import, no, package, require, use

Classes and objects

bless, dbmclose, dbmopen, package, ref, tie, tied,
untie, use

Low-level socket access

accept, bind, connect, getpeername, getsockname,
getsockopt, listen, recv, send, setsockopt, shutdown,
socket, socketpair

System V interprocess communication

msgctl, msgget, msgrcv, msgsnd, semctl, semget,
semop, shmctl, shmget, shmread, shmwrite

Fetching user and group information

endgrent, endhostent, endnetent, endpwent, getgrent,
getgrgid, getgrnam, getlogin, getpwent, getpwnam,
getpwuid, setgrent, setpwent

Fetching network information

endprotoent, endservent, gethostbyaddr, gethostbyname,
gethostent, getnetbyaddr, getnetbyname, getnetent,
getprotobyname, getprotobynumber, getprotoent,
getservbyname, getservbyport, getservent, sethostent,
setnetent, setprotoent, setservent

Time

gmtime, localtime, time, times