EVOLUTION-MANAGER
Edit File: environment.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Environment Access</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for environment {base}"><tr><td>environment {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Environment Access</h2> <h3>Description</h3> <p>Get, set, test for and create environments. </p> <h3>Usage</h3> <pre> 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) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>fun</code></td> <td> <p>a <code><a href="function.html">function</a></code>, a <code><a href="../../stats/html/formula.html">formula</a></code>, or <code>NULL</code>, which is the default.</p> </td></tr> <tr valign="top"><td><code>value</code></td> <td> <p>an environment to associate with the function</p> </td></tr> <tr valign="top"><td><code>x</code></td> <td> <p>an arbitrary <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> object.</p> </td></tr> <tr valign="top"><td><code>hash</code></td> <td> <p>a logical, if <code>TRUE</code> the environment will use a hash table.</p> </td></tr> <tr valign="top"><td><code>parent</code></td> <td> <p>an environment to be used as the enclosure of the environment created.</p> </td></tr> <tr valign="top"><td><code>env</code></td> <td> <p>an environment</p> </td></tr> <tr valign="top"><td><code>size</code></td> <td> <p>an integer specifying the initial size for a hashed environment. An internal default value will be used if <code>size</code> is <code>NA</code> or zero. This argument is ignored if <code>hash</code> is <code>FALSE</code>.</p> </td></tr> </table> <h3>Details</h3> <p>Environments consist of a <em>frame</em>, or collection of named objects, and a pointer to an <em>enclosing environment</em>. The most common example is the frame of variables local to a function call; its <em>enclosure</em> is the environment where the function was defined (unless changed subsequently). The enclosing environment is distinguished from the <em>parent frame</em>: the latter (returned by <code><a href="sys.parent.html">parent.frame</a></code>) 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 <code>parent.env</code>). </p> <p>When <code><a href="get.html">get</a></code> or <code><a href="exists.html">exists</a></code> search an environment with the default <code>inherits = TRUE</code>, they look for the variable in the frame, then in the enclosing frame, and so on. </p> <p>The global environment <code>.GlobalEnv</code>, more often known as the user's workspace, is the first item on the search path. It can also be accessed by <code>globalenv()</code>. On the search path, each item's enclosure is the next item. </p> <p>The object <code>.BaseNamespaceEnv</code> is the namespace environment for the base package. The environment of the base package itself is available as <code>baseenv()</code>. </p> <p>If one follows the chain of enclosures found by repeatedly calling <code>parent.env</code> from any environment, eventually one reaches the empty environment <code>emptyenv()</code>, into which nothing may be assigned. </p> <p>The replacement function <code>parent.env<-</code> 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. </p> <p>The replacement form of <code>environment</code>, <code>is.environment</code>, <code>baseenv</code>, <code>emptyenv</code> and <code>globalenv</code> are <a href="Primitive.html">primitive</a> functions. </p> <p>System environments, such as the base, global and empty environments, have names as do the package and namespace environments and those generated by <code>attach()</code>. Other environments can be named by giving a <code>"name"</code> attribute, but this needs to be done with care as environments have unusual copying semantics. </p> <h3>Value</h3> <p>If <code>fun</code> is a function or a formula then <code>environment(fun)</code> returns the environment associated with that function or formula. If <code>fun</code> is <code>NULL</code> then the current evaluation environment is returned. </p> <p>The replacement form sets the environment of the function or formula <code>fun</code> to the <code>value</code> given. </p> <p><code>is.environment(obj)</code> returns <code>TRUE</code> if and only if <code>obj</code> is an <code>environment</code>. </p> <p><code>new.env</code> returns a new (empty) environment with (by default) enclosure the parent frame. </p> <p><code>parent.env</code> returns the enclosing environment of its argument. </p> <p><code>parent.env<-</code> sets the enclosing environment of its first argument. </p> <p><code>environmentName</code> returns a character string, that given when the environment is printed or <code>""</code> if it is not a named environment. </p> <p><code>env.profile</code> returns a list with the following components: <code>size</code> the number of chains that can be stored in the hash table, <code>nchains</code> the number of non-empty chains in the table (as reported by <code>HASHPRI</code>), and <code>counts</code> 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 <code>env</code> is a non-hashed environment, <code>NULL</code> is returned. </p> <h3>See Also</h3> <p>For the performance implications of hashing or not, see <a href="https://en.wikipedia.org/wiki/Hash_table">https://en.wikipedia.org/wiki/Hash_table</a>. </p> <p>The <code>envir</code> argument of <code><a href="eval.html">eval</a></code>, <code><a href="get.html">get</a></code>, and <code><a href="exists.html">exists</a></code>. </p> <p><code><a href="ls.html">ls</a></code> may be used to view the objects in an environment, and hence <code><a href="../../utils/html/ls_str.html">ls.str</a></code> may be useful for an overview. </p> <p><code><a href="sys.source.html">sys.source</a></code> can be used to populate an environment. </p> <h3>Examples</h3> <pre> 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))) </pre> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>