\HeaderA{lapply}{Apply a Function over a List or Vector}{lapply}
\aliasA{replicate}{lapply}{replicate}
\aliasA{sapply}{lapply}{sapply}
\keyword{iteration}{lapply}
\keyword{list}{lapply}
\begin{Description}\relax
\code{lapply} returns a list of the same length as \code{X}, each
element of which is the result of applying \code{FUN} to the
corresponding element of \code{X}.

\code{sapply} is a user-friendly version of \code{lapply}
by default returning a vector or matrix if appropriate.

\code{replicate} is a wrapper for the common use of \code{sapply} for
repeated evaluation of an expression (which will usually involve
random number generation).
\end{Description}
\begin{Usage}
\begin{verbatim}
lapply(X, FUN, ...)

sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)

replicate(n, expr, simplify = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{X}] a vector (atomic or list) or an expressions vector.  Other
objects (including classed objects) will be coerced by
\code{\LinkA{as.list}{as.list}}.
\item[\code{FUN}] the function to be applied to each element of \code{X}:
see \sQuote{Details}.  In the case of functions like
\code{+}, \code{\%*\%}, etc.,
the function name must be backquoted or quoted.
\item[\code{...}] optional arguments to \code{FUN}.
\item[\code{simplify}] logical; should the result be simplified to a vector
or matrix if possible?
\item[\code{USE.NAMES}] logical; if \code{TRUE} and if \code{X} is character,
use \code{X} as \code{\LinkA{names}{names}} for the result unless it had names
already.
\item[\code{n}] number of replications.
\item[\code{expr}] expression (language object, usually a call)
to evaluate repeatedly.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{FUN} is found by a call to \code{\LinkA{match.fun}{match.fun}} and typically
is specified as a function or a symbol (e.g. a backquoted name) or a
character string specifying a function to be searched for from the
environment of the call to \code{lapply}.

Function \code{FUN} must be able to accept as input any of the
elements of \code{X}.  If the latter is an atomic vector, \code{FUN}
will always be passed a length-one vector of the same type as \code{X}.

Simplification in \code{sapply} is only attempted if \code{X} has
length greater than zero and if the return values from all elements
of \code{X} are all of the same (positive) length.  If the common
length is one the result is a vector, and if greater than one is a
matrix with a column corresponding to each element of \code{X}.

Users of S4 classes should pass a list to \code{lapply}: the internal
coercion is done by the system \code{as.list} in the base namespace
and not one defined by a user (e.g. by setting S4 methods on the
system function).
\end{Details}
\begin{Value}
For \code{lapply} and \code{sapply(simplify=FALSE)}, a list.

For \code{sapply(simplify=TRUE)} and \code{replicate}: if \code{X} has
length zero or \code{n = 0}, an empty list.  Otherwise an atomic
vector or matrix or list of the same length as \code{X} (of length
\code{n} for \code{replicate}).  If simplification occurs, the output
type is determined from the highest type of the return values in the
hierarchy NULL < raw < logical < integer < real < complex < character
< list < expression, after coercion of pairlists tolists.
\end{Value}
\begin{Note}\relax
\code{sapply(*, simplify = FALSE, USE.NAMES = FALSE)} is
equivalent to \code{lapply(*)}.

For historical reasons, the calls created by \code{lapply} are
unevaluated, and code has been written (e.g. \code{bquote}) that
relies on this.  This means that the recorded call is always of the
form \code{FUN(X[[0L]], ...)}, with \code{0L} replaced by the current
integer index.  This not normally a problem, but it can be if
\code{FUN} uses \code{\LinkA{sys.call}{sys.call}} or \code{\LinkA{match.call}{match.call}} or
if it is a primitive function that makes use of the call.  This means
that it is often safer to call primitive functions with a wrapper, so
that e.g. \code{lapply(ll, function(x) is.numeric(x))} is required in
\R{} 2.7.1 to ensure that method dispatch for \code{is.numeric} occurs
correctly.

If \code{expr} is a function call, be aware of assumptions about where
it is evaluated, and in particular what \code{...} might refer to.
You can pass additional named arguments to a function call as
additional named arguments to \code{replicate}: see \sQuote{Examples}.
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{apply}{apply}}, \code{\LinkA{tapply}{tapply}},
\code{\LinkA{mapply}{mapply}} for applying a function to \bold{m}ultiple
arguments, and \code{\LinkA{rapply}{rapply}} for a \bold{r}ecursive version of
\code{lapply()}, \code{\LinkA{eapply}{eapply}} for applying a function to each
entry in an \code{\LinkA{environment}{environment}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(stats); require(graphics)

x <- list(a = 1:10, beta = exp(-3:3), logic = c(TRUE,FALSE,FALSE,TRUE))
# compute the list mean for each list element
lapply(x,mean)
# median and quartiles for each list element
lapply(x, quantile, probs = 1:3/4)
sapply(x, quantile)
i39 <- sapply(3:9, seq) # list of vectors
sapply(i39, fivenum)

hist(replicate(100, mean(rexp(10))))

## use of replicate() with parameters:
foo <- function(x=1, y=2) c(x,y)
# does not work: bar <- function(n, ...) replicate(n, foo(...))
bar <- function(n, x) replicate(n, foo(x=x))
bar(5, x=3)
\end{ExampleCode}
\end{Examples}

