environment.Rd 5.96 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/environment.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2012 R Core Team
Radford Neal's avatar
Radford Neal committed
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's avatar
Radford Neal committed
20 21
\alias{enclosure}

Radford Neal's avatar
Radford Neal committed
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's avatar
Radford Neal committed
39
new.env(hash = TRUE, parent = parent.frame(), size = NA)
Radford Neal's avatar
Radford Neal committed
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's avatar
Radford Neal committed
53
  \item{hash}{a logical, if \code{TRUE} the environment will use a hash table.}
Radford Neal's avatar
Radford Neal committed
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's avatar
Radford Neal committed
74 75
  \code{new.env} returns a new (empty) environment with (by default)
  enclosure the parent frame.
Radford Neal's avatar
Radford Neal committed
76

Radford Neal's avatar
Radford Neal committed
77
  \code{parent.env} returns the enclosing environment of its argument.
Radford Neal's avatar
Radford Neal committed
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's avatar
Radford Neal committed
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's avatar
Radford Neal committed
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's avatar
Radford Neal committed
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's avatar
Radford Neal committed
103 104
  \sQuote{parent} in connection with an environment (despite the
  presence of the function \code{parent.env}).
Radford Neal's avatar
Radford Neal committed
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's avatar
Radford Neal committed
115
  The object \code{.BaseNamespaceEnv} is the namespace environment for
Radford Neal's avatar
Radford Neal committed
116
  the base package.  The environment of the base package itself is
Radford Neal's avatar
Radford Neal committed
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's avatar
Radford Neal committed
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's avatar
Radford Neal committed
132 133
  
  System environments, such as the base, global and empty environments,
Radford Neal's avatar
Radford Neal committed
134
  have names as do the package and namespace environments and those
Radford Neal's avatar
Radford Neal committed
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's avatar
Radford Neal committed
138 139
}
\seealso{
Radford Neal's avatar
Radford Neal committed
140 141 142
  For the performance implications of hashing or not, see
  \url{http://en.wikipedia.org/wiki/Hash_table}.

Radford Neal's avatar
Radford Neal committed
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}