environment.Rd 5.96 KB
 Radford Neal committed May 18, 2013 1 2 % File src/library/base/man/environment.Rd % Part of the R package, http://www.R-project.org  Radford Neal committed Aug 26, 2016 3 % Copyright 1995-2012 R Core Team  Radford Neal committed May 18, 2013 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 % Distributed under GPL 2 or later \name{environment} \alias{environment} \alias{environment<-} \alias{.GlobalEnv} \alias{globalenv} \alias{emptyenv} \alias{baseenv} \alias{is.environment} \alias{new.env} \alias{parent.env} \alias{parent.env<-} \alias{.BaseNamespaceEnv} \alias{environmentName} \alias{env.profile}  Radford Neal committed May 18, 2013 20 21 \alias{enclosure}  Radford Neal committed May 18, 2013 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 \title{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()  Radford Neal committed Jun 08, 2017 39 new.env(hash = TRUE, parent = parent.frame(), size = NA)  Radford Neal committed May 18, 2013 40 41 42 43 44 45 46 47 48 49 50 51 52  parent.env(env) parent.env(env) <- value environmentName(env) env.profile(env) } \arguments{ \item{fun}{a \code{\link{function}}, a \code{\link{formula}}, or \code{NULL}, which is the default.} \item{value}{an environment to associate with the function} \item{x}{an arbitrary \R object.}  Radford Neal committed May 18, 2013 53  \item{hash}{a logical, if \code{TRUE} the environment will use a hash table.}  Radford Neal committed May 18, 2013 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73  \item{parent}{an environment to be used as the enclosure of the environment created.} \item{env}{an environment} \item{size}{an integer specifying the initial size for a hashed environment. An internal default value will be used if \code{size} is \code{NA} or zero. This argument is ignored if \code{hash} is \code{FALSE}.} } \value{ If \code{fun} is a function or a formula then \code{environment(fun)} returns the environment associated with that function or formula. If \code{fun} is \code{NULL} then the current evaluation environment is returned. The replacement form sets the environment of the function or formula \code{fun} to the \code{value} given. \code{is.environment(obj)} returns \code{TRUE} if and only if \code{obj} is an \code{environment}.  Radford Neal committed May 18, 2013 74 75  \code{new.env} returns a new (empty) environment with (by default) enclosure the parent frame.  Radford Neal committed May 18, 2013 76   Radford Neal committed May 18, 2013 77  \code{parent.env} returns the enclosing environment of its argument.  Radford Neal committed May 18, 2013 78 79 80 81 82 83 84 85 86  \code{parent.env<-} sets the enclosing environment of its first argument. \code{environmentName} returns a character string, that given when the environment is printed or \code{""} if it is not a named environment. \code{env.profile} returns a list with the following components: \code{size} the number of chains that can be stored in the hash table,  Radford Neal committed May 18, 2013 87 88 89 90 91  \code{nchains} the number of non-empty chains in the table (as reported by \code{HASHPRI}), and \code{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 \code{env} is a non-hashed environment, \code{NULL} is returned.  Radford Neal committed May 18, 2013 92 93 94 95 96 } \details{ Environments consist of a \emph{frame}, or collection of named objects, and a pointer to an \emph{enclosing environment}. The most  Radford Neal committed May 18, 2013 97 98 99 100 101 102  common example is the frame of variables local to a function call; its \emph{enclosure} is the environment where the function was defined (unless changed subsequently). The enclosing environment is distinguished from the \emph{parent frame}: the latter (returned by \code{\link{parent.frame}}) refers to the environment of the caller of a function. Since confusion is so easy, it is best never to use  Radford Neal committed May 18, 2013 103 104  \sQuote{parent} in connection with an environment (despite the presence of the function \code{parent.env}).  Radford Neal committed May 18, 2013 105 106 107 108 109 110 111 112 113 114  When \code{\link{get}} or \code{\link{exists}} search an environment with the default \code{inherits = TRUE}, they look for the variable in the frame, then in the enclosing frame, and so on. The global environment \code{.GlobalEnv}, more often known as the user's workspace, is the first item on the search path. It can also be accessed by \code{globalenv()}. On the search path, each item's enclosure is the next item.  Radford Neal committed May 18, 2013 115  The object \code{.BaseNamespaceEnv} is the namespace environment for  Radford Neal committed May 18, 2013 116  the base package. The environment of the base package itself is  Radford Neal committed May 18, 2013 117 118 119 120 121  available as \code{baseenv()}. If one follows the chain of enclosures found by repeatedly calling \code{parent.env} from any environment, eventually one reaches the empty environment \code{emptyenv()}, into which nothing may  Radford Neal committed May 18, 2013 122 123 124 125 126 127 128 129 130 131  be assigned. The replacement function \code{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 \code{environment}, \code{is.environment}, \code{baseenv}, \code{emptyenv} and \code{globalenv} are \link{primitive} functions.  Radford Neal committed May 18, 2013 132 133  System environments, such as the base, global and empty environments,  Radford Neal committed May 18, 2013 134  have names as do the package and namespace environments and those  Radford Neal committed May 18, 2013 135 136 137  generated by \code{attach()}. Other environments can be named by giving a \code{"name"} attribute, but this needs to be done with care as environments have unusual copying semantics.  Radford Neal committed May 18, 2013 138 139 } \seealso{  Radford Neal committed May 18, 2013 140 141 142  For the performance implications of hashing or not, see \url{http://en.wikipedia.org/wiki/Hash_table}.  Radford Neal committed May 18, 2013 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176  The \code{envir} argument of \code{\link{eval}}, \code{\link{get}}, and \code{\link{exists}}. \code{\link{ls}} may be used to view the objects in an environment, and hence \code{\link{ls.str}} may be useful for an overview. \code{\link{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))) } \keyword{data} \keyword{programming}