assign                 package:base                 R Documentation

Assign a Value to a Name

Description:

     Assign a value to a name in an environment.

Usage:

     assign(x, value, pos = -1, envir = as.environment(pos),
            inherits = FALSE, immediate = TRUE)

Arguments:

       x: a variable name, given as a character string.  No coercion is
          done, and the first element of a character vector of length
          greater than one will be used, with a warning.

   value: a value to be assigned to 'x'.

     pos: where to do the assignment.  By default, assigns into the
          current environment.  See the details for other
          possibilities.

   envir: the 'environment' to use. See the details section.

inherits: should the enclosing frames of the environment be inspected?

immediate: an ignored compatibility feature.

Details:

     There are no restrictions on 'name': it can be a non-syntactic
     name (see 'make.names').

     The 'pos' argument can specify the  environment in which to assign
     the object in any of several ways: as an integer (the position in
     the 'search' list); as the character string name of an element in
     the search list; or as an 'environment' (including using
     'sys.frame' to access the currently active function calls). The
     'envir' argument is an alternative way to specify an environment,
     but is primarily there for back compatibility.

     'assign' does not dispatch assignment methods, so it cannot be
     used to set elements of vectors, names, attributes, etc.

     Note that assignment to an attached list or data frame changes the
     attached copy and not the original object: see 'attach' and
     'with'.

Value:

     This function is invoked for its side effect, which is assigning
     'value' to the variable 'x'.  If no 'envir' is specified, then the
     assignment takes place in the currently active environment.

     If 'inherits' is 'TRUE', enclosing environments of the supplied
     environment are searched until the variable 'x' is encountered.
     The value is then assigned in the environment in which the
     variable is encountered (provided that the binding is not locked:
     see 'lockBinding': if it is, an error is signaled).  If the symbol
     is not encountered then assignment takes place in the user's
     workspace (the global environment).

     If 'inherits' is 'FALSE', assignment takes place in the initial
     frame of 'envir', unless an existing binding is locked or there is
     no existing binding and the environment is locked.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     '<-', 'get', 'exists', 'environment'.

Examples:

     for(i in 1:6) { #-- Create objects  'r.1', 'r.2', ... 'r.6' --
      nam <- paste("r",i, sep=".")
      assign(nam, 1:i)
     }
     ls(pattern = "^r..$")

     ##-- Global assignment within a function:
     myf <- function(x) {
      innerf <- function(x) assign("Global.res", x^2, envir = .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

