\HeaderA{rapply}{Recursively Apply a Function to a List}{rapply}
\keyword{iteration}{rapply}
\keyword{list}{rapply}
\begin{Description}\relax
\code{rapply} is a recursive version of \code{\LinkA{lapply}{lapply}}.
\end{Description}
\begin{Usage}
\begin{verbatim}
rapply(object, f, classes = "ANY", deflt = NULL,
       how = c("unlist", "replace", "list"), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] A list.
\item[\code{f}] A function of a single argument.
\item[\code{classes}] A character vector of \code{\LinkA{class}{class}} names, or
\code{"ANY"} to match any class.
\item[\code{deflt}] The default result (not used if \code{how = "replace"}).
\item[\code{how}] A character string matching the three possibilities given:
see \sQuote{Details}.
\item[\code{...}] additional arguments passed to the call to \code{f}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This function has two basic modes.  If \code{how = "replace"}, each
element of the list which is not itself a list and has a class
included in \code{classes} is replaced by the result of applying
\code{f} to the element.

If the mode is \code{how = "list"} or \code{how = "unlist"}, the list
is copied, all non-list elements which have a class included in
\code{classes} are replaced by the result of applying \code{f} to the
element and all others are replaced by \code{deflt}.  Finally, if
\code{how = "unlist"}, \code{unlist(recursive = TRUE)} is called on
the result.

The semantics differ in detail from \code{\LinkA{lapply}{lapply}}: in
particular the arguments are evaluated before calling the C code.
\end{Details}
\begin{Value}
If \code{how = "unlist"}, a vector, otherwise a list of similar
structure to \code{object}.
\end{Value}
\begin{References}\relax
Chambers, J. A. (1998)
\emph{Programming with Data}.
Springer.\\
(\code{rapply} is only described briefly there.)
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{lapply}{lapply}}, \code{\LinkA{dendrapply}{dendrapply}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
X <- list(list(a=pi, b=list(c=1:1)), d="a test")
rapply(X, function(x) x, how="replace")
rapply(X, sqrt, classes="numeric", how="replace")
rapply(X, nchar, classes="character",
       deflt = as.integer(NA), how="list")
rapply(X, nchar, classes="character",
       deflt = as.integer(NA), how="unlist")
rapply(X, nchar, classes="character", how="unlist")
rapply(X, log, classes="numeric", how="replace", base=2)
\end{ExampleCode}
\end{Examples}

