\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}.

The mode of the simplified answer is chosen to accommodate the modes of
all the values returned by the calls to \code{FUN}: see \code{\LinkA{unlist}{unlist}}.

if \code{X} has length 0, the return value of \code{sapply} is always
a 0-length list.

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{Note}\relax
\code{sapply(*, simplify = FALSE, USE.NAMES = FALSE)} is
equivalent to \code{lapply(*)}.
\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))))
\end{ExampleCode}
\end{Examples}

