assign                 package:base                 R Documentation

_A_s_s_i_g_n _a _V_a_l_u_e _t_o _a _N_a_m_e

_D_e_s_c_r_i_p_t_i_o_n:

     Assign a value to a name in an environment.

_U_s_a_g_e:

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

     x = value

_A_r_g_u_m_e_n_t_s:

       x: a variable name (given as a quoted string in the function
          call).

   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.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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.  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'.

_A_s_s_i_g_n_m_e_n_t _O_p_e_r_a_t_o_r_s:

     There are three different assignment operators. The operators `<-'
     and `=' assign into the environment in which they are evaluated. 
     The `<-' can be used anywhere, but the `=' 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 `<<-' and `->>' 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, `x' can be a name or
     an expression defining a part of an object to be replaced (e.g.,
     `z[[1]]').  The name does not need to be quoted, though it can be.

_S_e_e _A_l_s_o:

     `get', `exists', `environment'.

_E_x_a_m_p_l_e_s:

     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

