| % File src/library/base/man/rapply.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{rapply} |
| \alias{rapply} |
| \title{Recursively Apply a Function to a List} |
| \description{ |
| \code{rapply} is a recursive version of \code{\link{lapply}} with |
| flexibility in \emph{how} the result is structured (\code{how = ".."}). |
| } |
| \usage{ |
| rapply(object, f, classes = "ANY", deflt = NULL, |
| how = c("unlist", "replace", "list"), ...) |
| } |
| \arguments{ |
| \item{object}{a \code{\link{list}} or \code{\link{expression}}, i.e., \dQuote{list-like}.} |
| \item{f}{a \code{\link{function}} of one \dQuote{principal} argument, |
| passing further arguments via \code{\dots}.} |
| \item{classes}{character vector of \code{\link{class}} names, or |
| \code{"ANY"} to match any class.} |
| \item{deflt}{The default result (not used if \code{how = "replace"}).} |
| \item{how}{character string partially matching the three possibilities given: |
| see \sQuote{Details}.} |
| \item{\dots}{additional arguments passed to the call to \code{f}.} |
| } |
| \details{ |
| This function has two basic modes. If \code{how = "replace"}, each |
| element of \code{object} which is not itself list-like and has a class |
| included in \code{classes} is replaced by the result of applying |
| \code{f} to the element. |
| |
| Otherwise, with mode \code{how = "list"} or \code{how = "unlist"}, |
| conceptually \code{object} |
| 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{\link{lapply}}: in |
| particular the arguments are evaluated before calling the C code. |
| |
| In \R 3.5.x and earlier, \code{object} was required to be a list, |
| which was \emph{not} the case for its list-like components. |
| } |
| \value{ |
| If \code{how = "unlist"}, a vector, otherwise \dQuote{list-like} |
| of similar structure as \code{object}. |
| } |
| \seealso{ |
| \code{\link{lapply}}, \code{\link{dendrapply}}. |
| } |
| \references{ |
| Chambers, J. A. (1998) |
| \emph{Programming with Data}. |
| Springer.\cr |
| (\code{rapply} is only described briefly there.) |
| } |
| \examples{ |
| X <- list(list(a = pi, b = list(c = 1L)), d = "a test") |
| # the "identity operation": |
| rapply(X, function(x) x, how = "replace") -> X.; stopifnot(identical(X, X.)) |
| rapply(X, sqrt, classes = "numeric", how = "replace") |
| rapply(X, deparse, control = "all") # passing extras. argument of deparse() |
| rapply(X, nchar, classes = "character", deflt = NA_integer_, how = "list") |
| rapply(X, nchar, classes = "character", deflt = NA_integer_, how = "unlist") |
| rapply(X, nchar, classes = "character", how = "unlist") |
| rapply(X, log, classes = "numeric", how = "replace", base = 2) |
| |
| ## with expression() / list(): |
| E <- expression(list(a = pi, b = expression(c = C1 * C2)), d = "a test") |
| LE <- list(expression(a = pi, b = expression(c = C1 * C2)), d = "a test") |
| rapply(E, nchar, how="replace") # "expression(c = C1 * C2)" are 23 chars |
| rapply(E, nchar, classes = "character", deflt = NA_integer_, how = "unlist") |
| rapply(LE, as.character) # a "pi" | b1 "expression" | b2 "C1 * C2" .. |
| rapply(LE, nchar) # (see above) |
| stopifnot(exprs = { |
| identical(E , rapply(E , identity, how = "replace")) |
| identical(LE, rapply(LE, identity, how = "replace")) |
| }) |
| } |
| \keyword{iteration} |
| \keyword{list} |