get                   package:base                   R Documentation

_R_e_t_u_r_n _t_h_e _V_a_l_u_e _o_f _a _N_a_m_e_d _O_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

       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.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

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

_N_o_t_e:

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

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'exists', 'assign'.

_E_x_a_m_p_l_e_s:

     get("%o%")

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