R: Return the Value of a Named Object

get {base} | R Documentation

## Return the Value of a Named Object

### Description

Search for an R object with a given name and return it.

### Usage

    get(x, pos = -1, envir = as.environment(pos), mode = "any",
        inherits = TRUE)

    mget(x, envir, mode = "any",
         ifnotfound = list(function(x)
             stop(paste("value for '", x, "' not found", sep = ""),
                  call. = FALSE)),
         inherits = FALSE)

### Arguments

`x` | a variable name (given as a character string).
`pos` | where to look for the object (see the details section); if omitted, the function will search as if the name of the object appeared unquoted in an expression.
`envir` | an alternative way to specify an environment to look in; see the ‘Details’ section.
`mode` | the mode or type of object sought: see the ‘Details’ section.
`inherits` | should the enclosing frames of the environment be searched?
`ifnotfound` | A `list` of values to be used if the item is not found: it will be coerced to list if necessary.

### Details

The `pos` argument can specify the environment in which to look for the object in any of several ways: as an 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 `envir` argument is an alternative way to specify an environment, but is primarily there for back compatibility.

This function looks to see if the name `x` has 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.

Warning: `inherits = TRUE` is the default behaviour for R but not for S.

If `mode` is specified then only objects of that type are sought. The `mode` may specify one of the collections `"numeric"` and `"function"` (see `mode`): any member of the collection will suffice.

Using a `NULL` environment is equivalent to using the current environment.

For `mget` multiple values are returned in a named `list`. This is true even if only one value is requested. The value in `mode` and `ifnotfound` can be either the same length as the number of requested items 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. The default value for `inherits` is `FALSE`, in contrast to the default behavior for `get`.

`mode` here is a mixture of the meanings of `typeof` and `mode`: `"function"` covers primitive functions and operators, `"numeric"`, `"integer"`, `"real"` and `"double"` all refer to any numeric type, `"symbol"` and `"name"` are equivalent but `"language"` must be used.

### Value

The object found. (If no object is found an error results.)

### Note

The reverse of `a <- get(nam)` is `assign(nam, a)`.

### References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

### See Also

`exists`, `assign`.

### Examples

    get("%o%")

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

[Package base version 2.8.1 Index]