environment               package:base               R Documentation

_E_n_v_i_r_o_n_m_e_n_t _A_c_c_e_s_s

_D_e_s_c_r_i_p_t_i_o_n:

     Get, set, test for and create environments.

_U_s_a_g_e:

     environment(fun = NULL)
     environment(fun) <- value

     is.environment(x)

     .GlobalEnv
     globalenv()
     .BaseNamespaceEnv

     emptyenv()
     baseenv()

     new.env(hash = FALSE, parent = parent.frame(), size = 29L)

     parent.env(env)
     parent.env(env) <- value

     environmentName(env)

     env.profile(env)

_A_r_g_u_m_e_n_t_s:

     fun: a 'function', a 'formula', or 'NULL', which is the default.

   value: an environment to associate with the function

       x: an arbitrary R object.

    hash: a logical, if 'TRUE' the environment will be hashed

  parent: an environment to be used as the enclosure of the environment
          created.

     env: an environment

    size: an integer specifying the initial size for a hashed
          environment.  An internal default value will be used if
          'size' is 'NA' or zero.  This argument is ignored if 'hash'
          is 'FALSE'.

_D_e_t_a_i_l_s:

     Environments consist of a _frame_, or collection of named objects,
     and a pointer to an _enclosing environment_.  The most common
     example is the frame of variables local to a function call; its
     enclosure is the environment where the function was defined.  The
     enclosing environment is distinguished from the _parent frame_: 
     the latter (returned by 'parent.frame') refers to the environment
     of the caller of a function.

     When 'get' or 'exists' search an environment with the default
     'inherits = TRUE', they look for the variable in the frame, then
     in the enclosing frame, and so on.

     The global environment '.GlobalEnv', more often known as the
     user's workspace, is the first item on the search path.  It can
     also be accessed by 'globalenv()'.  On the search path, each
     item's enclosure is the next item.

     The object '.BaseNamespaceEnv' is the name space environment for
     the base package.  The environment of the base package itself is
     available as 'baseenv()'.  The ultimate enclosure of any
     environment is the empty environment 'emptyenv()', to which
     nothing may be assigned. If one follows the 'parent.env()' chain
     of enclosures back far enough from any environment, eventually one
     reaches the empty environment.

     The replacement function 'parent.env<-' is extremely dangerous as
     it can be used to destructively change environments in ways that
     violate assumptions made by the internal C code.  It may be
     removed in the near future.

     The replacement form of 'environment', 'is.environment',
     'baseenv', 'emptyenv' and 'globalenv' are primitive functions.

_V_a_l_u_e:

     If 'fun' is a function or a formula then 'environment(fun)'
     returns the environment associated with that function or formula.
     If 'fun' is 'NULL' then the current evaluation environment is
     returned.

     The replacement form sets the environment of the function or
     formula 'fun' to the 'value' given.

     'is.environment(obj)' returns 'TRUE' if and only if 'obj' is an
     'environment'.

     'new.env' returns a new (empty) environment enclosed in the
     parent's environment, by default.

     'parent.env' returns the parent environment of its argument.

     'parent.env<-' sets the enclosing environment of its first
     argument.

     'environmentName' returns a character string, that given when the
     environment is printed or '""' if it is not a named environment.

     'env.profile' returns a list with the following components: 'size'
     the number of chains that can be stored in the hash table,
     'nchains' the number of non-empty chains in the table (as reported
     by HASHPRI), and 'counts' an integer vector giving the length of
     each chain (zero for empty chains).  This function is intended to
     assess the performance of hashed environments.  When 'env' is a
     non-hashed environment, 'NULL' is returned.

_S_e_e _A_l_s_o:

     The 'envir' argument of 'eval', 'get', and 'exists'.

     'ls' may be used to view the objects in an environment, and hence
     'ls.str' may be useful for an overview.

     'sys.source' can be used to populate an environment.

_E_x_a_m_p_l_e_s:

     f <- function() "top level function"

     ##-- all three give the same:
     environment()
     environment(f)
     .GlobalEnv

     ls(envir=environment(stats::approxfun(1:2,1:2, method="const")))

     is.environment(.GlobalEnv) # TRUE

     e1 <- new.env(parent = baseenv())  # this one has enclosure package:base.
     e2 <- new.env(parent = e1)
     assign("a", 3, envir=e1)
     ls(e1)
     ls(e2)
     exists("a", envir=e2)   # this succeeds by inheritance
     exists("a", envir=e2, inherits = FALSE)
     exists("+", envir=e2)   # this succeeds by inheritance