rapply
Apply a Function Recursively
Description
Applies the specified function recursively to all the leaf elements of
the list object, to all leaf elements of nested list elements,
and so on.
Usage
rapply(object, f, classes = "ANY", deflt = NULL,
how = c("unlist", "replace", "list"), ...)
Arguments
| object |
the object to which to apply the function recursively.
|
| f |
the function to apply to leaf elements.
The function must be a function object: it cannot be a character
string giving the name of a function.
|
| classes |
the classes in the object to which to apply the function.
By default, "ANY", which matches objects of any class.
|
| deflt |
a value inserted into the output when a leaf object does not match
the classes argument, instead of inserting the result of
calling f.
This value is not used when how matches "replace",
because the old leaf object is inserted instead.
|
| how |
controls the results. how should match the initial substring of
one of the strings c("unlist", "replace", "list").
By default, it is "unlist".
See the DETAILS section for more information.
|
| ... |
additional arguments passed to the function f.
|
Details
rapply scans through the elements of the list
object,
recursively scans through any list elements, and so on.
It does not recursively scan through all types of recursive objects,
but only ones where
typeof(x)=="list".
Any other object is considered a leaf object.
- If how is "list", rapply scans through the
nested list object and constructs a new nested list with the same
structure and names. When rapply encounters a leaf object, it checks whether the
class of the leaf objects matches the classes argument.
If the class matches, the leaf object is passed to the function
f, along with any additional arguments passed to rapply,
and the function value is inserted in the new nested list.
If the leaf object class does not match the classes argument,
then the value of deflt is inserted in the new nested list.
- If how is "unlist", the same scanning is done
as with "list", but the resulting nested list is passed to
unlist to produce a single vector. unlist removes
NULL list elements from the final result, so if
how="unlist" and deflt=NULL, rapply returns
just the unlisted, concatenated values. You can use this option for
a function that returns a single value or a numeric value.
- If how is "replace", it is similar to
"list", except for leaf objects whose class does not match
the classes argument. If a leaf object class does not match,
the leaf object itself is inserted in the new nested list, instead
of deflt. Thus, the result is similar to the original
object, except that the objects with matching classes are
replaced.
Value
returns a result determined by f and how. See
the DETAILS section for more information.
See Also
Examples
x <- list(x=4, y=list(z=5, w='a'))
f <- function(x, y) x + y
rapply(x, f, classes='numeric', how='list', y=2)
# $x
# [1] 6
#
# $y
# $y$z
# [1] 7
#
# $y$w
# NULL
rapply(x, f, classes='numeric', how='unlist', y=2)
# x y.z
# 6 7
rapply(x, f, classes='numeric', deflt='test', how='list', y=2)
# $x
# [1] 6
#
# $y
# $y$z
# [1] 7
#
# $y$w
# [1] "test"
rapply(x, f, classes='numeric', how='replace', y=2)
# $x
# [1] 6
#
# $y
# $y$z
# [1] 7
#
# $y$w
# [1] "a"