R: Environment Access

environment {base} | R Documentation

## Environment Access

### 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`, 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 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 if `size` is `NA` or zero. This argument is ignored if `hash` 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`) 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` 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 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 calling `parent.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` are primitive 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 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 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, see http://en.wikipedia.org/wiki/Hash_table.

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.

### 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 3.1.2 Index]