R: Return the Value of a Named Object

get {base} | R Documentation

## Return the Value of a Named Object

### Description

Search by name for an object (`get`) or zero or more objects (`mget`).

### 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). For `mget`, 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`, a `list` of values to be used if the item is not found: it will be coerced to a list if necessary. For `dynGet` any R object, e.g., a call to `stop()`.
`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

    get("%o%")

    ## test mget
    e1 <- new.env()
    mget(letters, e1, ifnotfound = as.list(LETTERS))

[Package base version 3.5.1 Index]