get
Return the Value of a Named Object
Search by name for an object (get
) or zero or more objects
(mget
).
- Keywords
- data
Usage
get(x, pos = -1, envir = as.environment(pos), mode = "any",
inherits = TRUE)mget(x, envir = as.environment(-1), mode = "any", ifnotfound,
inherits = FALSE)
dynGet(x, ifnotfound = , minframe = 1L, inherits = FALSE)
Arguments
- x
For
get
, an object name (given as a character string). Formget
, a character vector of object names.- pos, envir
where to look for the object (see ‘Details’); if omitted search as if the name of the object appeared unquoted in an expression.
- mode
the mode or type of object sought: see the ‘Details’ section.
- inherits
should the enclosing frames of the environment be searched?
- ifnotfound
For
mget
, alist
of values to be used if the item is not found: it will be coerced to a list if necessary. FordynGet
any R object, e.g., a call tostop()
.- minframe
integer specifying the minimal frame number to look into.
Details
The pos
argument can specify the environment in which to look
for the object in any of several ways: as a positive integer (the
position in the search
list); as the character string
name of an element in the search list; or as an
environment
(including using sys.frame
to access the currently active function calls). The default of
-1
indicates the current environment of the call to
get
. The envir
argument is an alternative way to
specify an environment.
These functions look to see if each of the name(s) x
have a
value bound to it in the specified environment. If inherits
is
TRUE
and a value is not found for x
in the specified
environment, the enclosing frames of the environment are searched
until the name x
is encountered. See environment
and the ‘R Language Definition’ manual for details about the
structure of environments and their enclosures.
If mode
is specified then only objects of that type are sought.
mode
here is a mixture of the meanings of typeof
and mode
: "function"
covers primitive functions
and operators, "numeric"
, "integer"
and "double"
all refer to any numeric type, "symbol"
and "name"
are
equivalent but "language"
must be used (and not
"call"
or "("
).
For mget
, the values of mode
and ifnotfound
can
be either the same length as x
or of length 1. The argument
ifnotfound
must be a list containing either the value to use if
the requested item is not found or a function of one argument which
will be called if the item is not found, with argument the name of the
item being requested.
dynGet()
is somewhat experimental and to be used inside
another function. It looks for an object in the callers, i.e.,
the sys.frame()
s of the function. Use with caution.
Value
For get
, the object found. If no object is found an error results.
For mget
, a named list of objects (found or specified via
ifnotfound
).
Note
The reverse (or “inverse”) of a <- get(nam)
is
assign(nam, a)
, assigning a
to name nam
.
inherits = TRUE
is the default for get
in R
but not for S where it had a different meaning.
References
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
See Also
exists
for checking whether an object exists;
get0
for an efficient way of both checking existence and
getting an object.
assign
, the inverse of get()
, see above.
Use getAnywhere
for searching for an object
anywhere, including in other namespaces, and
getFromNamespace
to find an object in a specific
namespace.
Examples
library(base)
# NOT RUN {
get("%o%")
## test mget
e1 <- new.env()
mget(letters, e1, ifnotfound = as.list(LETTERS))
# }
Community examples
`get()` retrieves objects by name. ```{r} x <- 1:5 get("x") ``` You can use it with functions too, but often you want [`match.fun()`](https://www.rdocumentation.org/packages/base/topics/match.fun) for that task. ```{r} get("var") match.fun("var") ``` You can specify where to look for the object. ```{r} get("abs", as.environment("package:base")) ``` If we look in an environment higher up the [`search()`](https://www.rdocumentation.org/packages/base/topics/search) path then get will still find what we asked for. ```{r} get("abs", as.environment("package:stats")) ``` …unless we specify `inherits = FALSE` ```{r} tryCatch( get("abs", as.environment("package:stats"), inherits = FALSE), error = print ) ``` It is a good idea to check to see if the variable [`exists()`](https://www.rdocumentation.org/packages/base/topics/exists) before getting it. ```{r} if(exists("abs", as.environment("package:stats"), inherits = FALSE)) { get("abs", as.environment("package:stats"), inherits = FALSE) } else { message("Could not find abs in the stats package.") } ``` `get0()` provides a more efficient alternative to the previous code pattern. ```{r} abs_fn <- get0("abs", as.environment("package:stats"), inherits = FALSE) if(is.null(abs_fn)) { message("Could not find abs in the stats package.") } ``` `mget()` is useful for retrieving objects satisfying some criterion from an `environment`. For example, you can get all primitive functions from the `methods` package. ```{r} methods_env <- as.environment("package:methods") methods_var_names <- ls(methods_env) methods_vars <- mget(methods_var_names, methods_env) (primitive_fns_in_methods <- Filter(is.primitive, methods_vars)) ``` Another use of `mget()` is for grouping related variables into a `list`. Suppose you have a few variables that you want to calculate the mean of. Working with individual variables can be tiresome. ```{r} x1 <- 1:5 x2 <- (1:5) ^ 2 x3 <- (1:5) ^ 3 x4 <- (1:5) ^ 4 x5 <- (1:5) ^ 5 # The following code involves cutting and pasting, which makes it error-prone. mean(x1) mean(x2) mean(x3) mean(x4) mean(x5) # By using a list, you can use sapply to loop over elements, and save some repeated typing. x_var_names <- ls(globalenv(), pattern = "^x[1-5]$") x_list <- mget(x_var_names, globalenv()) sapply(x_list, mean) ``` `mget()` has an `ifnotfound` argument that saves you having to do if-exists-then-get. ```{r} mget( c("var", "abs"), as.environment("package:stats"), ifnotfound = NA, inherits = FALSE ) ``` `dynGet()` works its way back up the call stack until it finds the variable that you are looking for. ```{r} f <- function(x) { z <- 3 g(x + 1, z - 1) } g <- function(x, y) { message('dynGet("x") = ', dynGet("x")) message('dynGet("y") = ', dynGet("y")) message('dynGet("z") = ', dynGet("z")) message( 'dynGet("<?>") = ', dynGet("<?>", ifnotfound = "did not find <?>") ) } f(0) ```