R: Is an Object Defined?

exists {base} | R Documentation

## Is an Object Defined?

### Description

Look for an R object of the given name and possibly return it

### Usage

    exists(x, where = -1, envir = , frame, mode = "any",
           inherits = TRUE)

    get0(x, envir = pos.to.env(-1L), mode = "any", inherits = TRUE,
         ifnotfound = NULL)

### Arguments

`x` | a variable name (given as a character string).
`where` | 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, but it is usually simpler to just use the `where` argument.
`frame` | a frame in the calling list. Equivalent to giving `where` as `sys.frame(frame)`.
`mode` | the mode or type of object sought: see the ‘Details’ section.
`inherits` | should the enclosing frames of the environment be searched?
`ifnotfound` | the return value of `get0(x, *)` when `x` does not exist.

### Details

The `where` 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. (This is true even if a member of a collection is specified, so for example `mode = "special"` will seek any type of function.)

### Value

`exists():` Logical, true if and only if an object of the correct name and mode is found.

`get0():` The object—as from `get(x, *)`— if `exists(x, *)` is true, otherwise `ifnotfound`.

### Note

With `get0()`, instead of the easy to read but somewhat inefficient

        if (exists(myVarName, envir = myEnvir)) {
          r <- get(myVarName, envir = myEnvir)
          ## ... deal with r ...
        }

you now can use the more efficient (and slightly harder to read)

        if (!is.null(r <- get0(myVarName, envir = myEnvir))) {
          ## ... deal with r ...
        }

### References

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

### See Also

`get` and `hasName`. For quite a different kind of “existence” checking, namely if function arguments were specified, `missing`; and for yet a different kind, namely if a file exists, `file.exists`.

### Examples

    ##  Define a substitute function if necessary:
    if(!exists("some.fun", mode = "function"))
      some.fun <- function(x) { cat("some.fun(x)\n"); x }
    search()
    exists("ls", 2) # true even though ls is in pos = 3
    exists("ls", 2, inherits = FALSE) # false

    ## These are true (in most circumstances):
    identical(ls,   get0("ls"))
    identical(NULL, get0(".foo.bar.")) # default ifnotfound = NULL (!)

[Package base version 4.0.5 Index]