\Header{assign}{Assign a Value to a Name}
\alias{->}{assign}
\alias{->{}>}{assign}
\alias{<\Rdash}{assign}
\alias{<{}<\Rdash}{assign}
\alias{=}{assign}
\keyword{data}{assign}
\begin{Description}\relax
Assign a value to a name in an environment.\end{Description}
\begin{Usage}
\begin{verbatim}
assign(x, value, pos = -1, envir = as.environment(pos),
       inherits = FALSE, immediate = TRUE)
x <- value
x <<- value
value -> x
value ->> x

x = value
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a variable name (given as a quoted string in the function call).
\item[\code{value}] a value to be assigned to \code{x}.
\item[\code{pos}] where to do the assignment.  By default, assigns into the
current environment.  See the details for other possibilities.
\item[\code{envir}] the \code{\Link{environment}} to use. See the details section.
\item[\code{inherits}] should the enclosing frames of the environment be
inspected?
\item[\code{immediate}] an ignored compatibility feature.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \code{pos} argument can specify the  environment in which to assign
the object in any of several ways:
as an integer (the position in the \code{\Link{search}} list); as
the character string name of an element in the search list; or as an
\code{\Link{environment}} (including using \code{\Link{sys.frame}} to
access the currently active function calls).
The \code{envir} argument is an alternative way to specify an
environment, but is primarily there for back compatibility.

\code{assign} does not dispatch assignment methods, so it cannot be
used to set elements of vectors, names, attributes, etc.\end{Details}
\begin{Value}
This function is invoked for its side effect, which is assigning
\code{value} to the variable \code{x}.  If no \code{envir} is
specified, then the assignment takes place in the currently active
environment.

If \code{inherits} is \code{TRUE}, enclosing environments of the supplied
environment are searched until the variable \code{x} is encountered.
The value is then assigned in the environment in which the variable is
encountered.  If the symbol is not encountered then assignment takes
place in the user's workspace (the global environment).

If \code{inherits} is \code{FALSE}, assignment takes place in the
initial frame of \code{envir}.\end{Value}
\begin{Section}{Assignment Operators}
There are three different assignment
operators. The operators \code{<-} and \code{=} assign into the
environment in which they are evaluated.  The \code{<-} can be used
anywhere, but the \code{=} is only allowed at the top level (that
is, in the complete expression typed by the user) or as one of the
subexpressions in a braced list of expressions.


The operators \code{<{}<-} and \code{->{}>} cause a search to made
through the environment for an existing
definition of the variable being assigned.  If such a variable is
found then its value is redefined, otherwise assignment takes place
globally. Note that their differs from that in
the S language, but is useful in conjunction with the scoping rules of
R.

In all the assignment operator expressions, \code{x} can be a name
or an expression defining a part of an object to be replaced (e.g.,
\code{z[[1]]}).  The name does not need to be quoted, though it can
be.\end{Section}
\begin{SeeAlso}\relax
\code{\Link{get}},
\code{\Link{exists}},
\code{\Link{environment}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
for(i in 1:6) { #-- Create objects  'r1', 'r2', ... 'r6' --
 nam <- paste("r",i, sep=".")
 assign(nam, 1:i)
}
ls(pat="^r..$")

##-- Global assignment within a function:
myf <- function(x) {
 innerf <- function(x) assign("Global.res", x^2, env = .GlobalEnv)
 innerf(x+1)
}
myf(3)
Global.res # 16

a<-1:4
assign("a[1]",2)
a[1]==2          #FALSE
get("a[1]")==2   #TRUE

\end{ExampleCode}
\end{Examples}

