exists                 package:base                 R Documentation

Is an Object Defined?

Description:

     Look for an R object of the given name.

Usage:

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

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?

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:

     Logical, true if and only if an object of the correct name and
     mode is found.

References:

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

See Also:

     'get'.

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

