exists {base}

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 or a symbol).

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 (!)