R: Environment Access (original) (raw)
| environment {base} | R Documentation |
|---|
Description
Get, set, test for and create environments.
Usage
environment(fun = NULL)
environment(fun) <- value
is.environment(x)
.GlobalEnv
globalenv()
.BaseNamespaceEnv
emptyenv()
baseenv()
new.env(hash = TRUE, parent = parent.frame(), size = 29L)
parent.env(env)
parent.env(env) <- value
environmentName(env)
env.profile(env)
Arguments
| fun | a function, a formula, orNULL, 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 use a hash table. |
| 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 ifsize is NA or zero. This argument is ignored ifhash is FALSE. |
Details
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 (unless changed subsequently). The enclosing environment is distinguished from the parent frame: the latter (returned by[parent.frame](../../base/help/parent.frame.html)) refers to the environment of the caller of a function. Since confusion is so easy, it is best never to use ‘parent’ in connection with an environment (despite the presence of the function parent.env).
When [get](../../base/help/get.html) or [exists](../../base/help/exists.html) 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 namespace environment for the base package. The environment of the base package itself is available as baseenv().
If one follows the chain of enclosures found by repeatedly callingparent.env from any environment, eventually one reaches the empty environment emptyenv(), into which nothing may be assigned.
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 areprimitive functions.
System environments, such as the base, global and empty environments, have names as do the package and namespace environments and those generated by attach(). Other environments can be named by giving a "name" attribute, but this needs to be done with care as environments have unusual copying semantics.
Value
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 formulafun to the value given. Note that [primitive](../../base/help/primitive.html) functions fun have no environment and trying to set it to a non-NULL value is deprecated.
is.environment(obj) returns TRUE if and only ifobj is an environment.
new.env returns a new (empty) environment with (by default) enclosure the parent frame.
parent.env returns the enclosing 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.
See Also
For the performance implications of hashing or not, seehttps://en.wikipedia.org/wiki/Hash_table.
The envir argument of [eval](../../base/help/eval.html), [get](../../base/help/get.html), and [exists](../../base/help/exists.html).
[ls](../../base/help/ls.html) may be used to view the objects in an environment, and hence [ls.str](../../utils/html/ls%5Fstr.html) may be useful for an overview.
[sys.source](../../base/help/sys.source.html) can be used to populate an environment.
Examples
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
eh <- new.env(hash = TRUE, size = NA)
with(env.profile(eh), stopifnot(size == length(counts)))
[Package _base_ version 4.6.0 Index]