=head1 NAME
X
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 scalar context to its
argument, while a list operator may provide either scalar or list
contexts for its arguments. If it does both, scalar arguments
come first and list argument follow, and there can only ever
be one such list argument. For instance,
L|/splice ARRAY,OFFSET,LENGTH,LIST> has three scalar arguments
followed by a list, whereas L|/gethostbyname NAME> has
four scalar arguments.
In the syntax descriptions that follow, list operators that expect a
list (and provide list context for 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.
Commas should separate literal elements of the LIST.
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 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. Whitespace
between the function and left parenthesis doesn't count, so sometimes
you need to be careful:
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 L|warnings> pragma, 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.
A few functions take no arguments at all, and therefore work as neither
unary nor list operators. These include such functions as
L|/time> and L|/endpwent>. For example,
C always means C.
For functions that can be used in either a scalar or list context,
nonabortive failure is generally indicated in scalar context by
returning the undefined value, and in list context by returning the
empty 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 would be most
appropriate to return in 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.
X
A 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 concatenation 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
("syscalls") of the same name (like L, L,
L, etc.) return true when they succeed and
L|/undef EXPR> 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 include
L|/wait>, L|/waitpid PID,FLAGS>, and
L|/syscall NUMBER, LIST>. System calls also set the special
L|perlvar/$!> variable on failure. Other functions do not, except
accidentally.
Extension modules can also hook into the Perl parser to define new
kinds of keyword-headed expression. These may look like functions, but
may also look completely different. The syntax following the keyword
is defined entirely by the extension. If you are an implementor, see
L for the mechanism. If you are using such
a module, see the module's documentation for details of the syntax that
it defines.
=head2 Perl Functions by Category
X
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 4
=item Functions for SCALARs or strings
X X X
=for Pod::Functions =String
L|/chomp VARIABLE>, L|/chop VARIABLE>,
L|/chr NUMBER>, L|/crypt PLAINTEXT,SALT>,
L|/fc EXPR>, L|/hex EXPR>,
L|/index STR,SUBSTR,POSITION>, L|/lc EXPR>,
L|/lcfirst EXPR>, L|/length EXPR>,
L|/oct EXPR>, L|/ord EXPR>,
L|/pack TEMPLATE,LIST>,
LE>|/qESTRINGE>,
LE>|/qqESTRINGE>, L|/reverse LIST>,
L|/rindex STR,SUBSTR,POSITION>,
L|/sprintf FORMAT, LIST>,
L|/substr EXPR,OFFSET,LENGTH,REPLACEMENT>,
LEE>|/trEEE>, L|/uc EXPR>,
L|/ucfirst EXPR>,
LEE>|/yEEE>
L|/fc EXPR> is available only if the
L feature|feature/The 'fc' feature> is enabled or if it is
prefixed with C. The
L feature|feature/The 'fc' feature> is enabled automatically
with a C