exists
Is an Object Defined?
Look for an R object of the given name and possibly return it
- Keywords
- data
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
assys.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, *)
whenx
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
library(base)
# NOT RUN {
## 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 (!)
# }