Contents

assignment

Usage:

a <- x assigns value of x to a.
a[J1] <- x, a[J1,J2] <- x, ..., where the J's are valid subscripts,
  replaces the designated elements to corresponding elements of x.
a[J] <- x, when a is a structure, replaces the designated components
  of a by x, J a valid subscript
a <-+ x assigns a + x to a and similarly for a <-- x, a <-* x, a <-/ x,
  a <-%% x and a <-^ x.
When Str is a structure"
  Str$a <- x, Str$a$b <- x, ..., Str[[i]] <- x, Str[[i]][[j]] <- x, ...
  replaces the indicated component of Str by x

Keywords: syntax

This topic describes the use of the assignment operator '<-' and
arithmetic assignment operators '<-+', '<--', '<-*', '<-/' and '<-%%'.
It has sections on ordinary assignment, assignment to subscripts,
assignment to structure components and arithmetic assignment operators.

                          Ordinary assignment
You can assign values to a variable using the left pointing arrow '<-'
made up of the two characters "less than" and "minus".  For example,
'foo <- 5' assigns the value 5 to the variable foo.  When foo does not
already exist, it is created; otherwise, its previous value is discarded
and foo is re-defined.

An expression of the form 'y <-3', say, is always interpreted as 'y <-
3' rather than as 'y < -3'.  When you want the latter, be sure to put a
space before '-3'.

The value of such an assignment is the value of the variable after the
assignment.  For example, 'y <- exp(x <- 4)' sets variables x and y to 4
and exp(4), respectively, and 'y <- x <- 4' assigns 4 to both x and y.

This value is normally not printed unless the assignment is the last
command in a compound command {command_1;...;command_k}.

For example, '{y <- 3}' not only assigns the value 3 to y put also
prints the number 3, although 'y <- 3' by itself prints nothing.  For
this reason, it is a often a good idea to terminate compound commands
with ';;', as in '{y <- 3;;}'.  Of course, this is a bad idea if you
want the final value to be printed or if you are assigning the value of
the entire compound statement to a variable.

Some "special" variables such as CLIPBOARD can be assigned to.  What
actually happens depends on the particular variable.  You cannot assign
to special structure variable GRAPHWINDOWS although you can assign to
its components.  See topics 'CLIPBOARD', 'GRAPHWINDOWS' and
'graph_assign'.

                        Assignment to subscripts
You can modify parts of an existing vector, matrix or array y by
y[J1] <- x, y[J1,J2] <- x, y[J1,J2,J3] <- x, ... as long as the
subscripts are appropriate.  You can use positive, negative and LOGICAL
vector subscripts or a single matrix subscript, but not an array
subscript with more than two dimensions.

x must be the same type variable as y, REAL, CHARACTER or LOGICAL.  When
x is a scalar (number, T or F or quoted string), it replaces all the
elements of y selected by the subscripts.  When x is not a scalar, then
length(x) must match the number of elements of y selected, but x can be
of any shape and is treated as if it were vector(x).

The value of an assignment to subscripts is a vector, matrix or array
containing the new elements and having the same shape as the elements of
y that were replaced.

It is legal for the subscripts to select the same element of x more than
once (for instance, y[vector(1,1,2)] <- vector(3,5,7)).  In this case
the eventual value for an element selected more than once is the last
element in x assigned to that element (in the example, y[1] is set to
5).

See below for using subscripts to change components of an existing
structure.

y[J1] <- NULL, y[J1,J2] <- NULL, ... are legal provided at least one of
the subscripts is NULL or is non-selecting (is all False or is a
complete set of negative subscripts).  y is not changed and the value of
the assignment is NULL.  For example, even if all the elements of u are
positive, y[u < 0] <- x[u < 0] is legal and does not change y.

Similarly, when x is a scalar of the appropriate type , y[J1] <- x,
y[J1,J2] <- x, ... is legal even one or more subscripts are NULL or
non-selecting. y is not changed and the value of the assignment is NULL.
For example, y[vector(y) > 10] <- 10 is legal even when there are no
elements of y greater than 10.

It is an error to assign a non-NULL non-scalar variable to subscripts
when there is a NULL or non-selecting subscript.

Suppose y is a matrix or array and J is a vector such that vector(y)[J]
is legal, and x is a scalar or a vector with the same length as
vector(y)[J].  Then y[J] <- x is legal and assigns the elements of x to
the positions that would be specified by J if y were a vector.  The
dimensions of y are retained.  For example,
  Cmd> y[vector(abs(y)) > 3] <- ?
replaces all elements of y that exceed 3 in absolute value by MISSING,
without disturbing the dimensioning of y.

Similarly, when x is a scalar or is a vector, matrix or array with
length(x) = length(y), y[] <- x replaces all the values of y by values
from x without changing the dimensions of y.

When y is not a structure, y[[J]] <- x is illegal except when J = 1 in
which case it is equivalent to y <- x.

See below (assignment:"assignment_to_structure_components") for
assignment to components of a structure.

Examples assuming x is a vector of length 5 and y is a 3 by 2 matrix.

  Cmd> y <- x[-run(2)] <- 17
sets all the elements of except x[1] and x[2] to 17 and sets y to
vector(17,17,17).

  Cmd> y <- x[vector(1,4)] <- vector(17,19)
sets x[1] and x[4] to 17 and 19 and y to vector(17,19)

  Cmd> y <- x[vector(1,3,1)] <- vector(17,19,21)
sets x[1] and x[3] to 21 and 19 and y to vector(17,19,21).

  Cmd> y[vector(1,4)] <- run(3)
is illegal because there are 3 elements in run(3), but only 2 elements
are selected in y.

  Cmd> y <- x[-1,] <- run(4) # change all but row 1 of x
changes x[2,1], x[3,1], x[2,2] and x[3,2] to 1, 2, 3 and 4,
respectively, and sets y to the 2 by 2 matrix matrix(run(4),2).

  Cmd> y <- x[hconcat(run(2),run(2))] <- 4 #matrix subscript
sets x[1,1] and x[2,2] to 4 and y to vector(4,4).

  Cmd> y <- x[x>max(x)] <- 3
doesn't change x and sets y to NULL because x > max(x) has value
vector(F,F,F,F,F).

                   Assignment to structure components
You can assign to structure components by name or by number.  In the
following Str is assumed to be an existing structure variable, not the
result of an operation like describe(x).

When a component of Str has name Name, Str$Name <- x replaces that
component by the value of x without changing it's name.  The value of
the assignment expression is x.  If more than one component is named
Name, assignment is to the first such component.  It is an error if Str
has no such component.

Str$Name1$Name2 <- x, Str$Name1$Name2$Name3 <- x, ... are also legal,
provided the indicated component exists.

Str[J] <- x and Str[[J]] <- x are identical and work similarly to a[J]
<- x, when a is a vector, matrix or array, except that entire components
are replaced.  The names of components in Str are never changed.

There are four cases depending on x and K = number of components
selected in Str by J, counting any duplicated subscripts more than once.

1.  When K = 1, the selected component is always replaced by a copy of
x, whether x is a structure or a non-structure.

2.  When K > 1 and x is a structure with ncomps(x) = K, the selected
components in Str are replaced by copies of the corresponding components
of x and the value is identical to x.  When a component of Str is
selected more than once, its new value is the highest numbered component
of the x that was assigned to it.  The value of the assignment is a copy
of x.

3.  When K > 1 and x is not a structure or is a structure with ncomps(x)
!= K, each selected component of Str is replaced by a copy of x.  The
value is structure(x,x,...,x), where there are K copies of x.

4.  When K == 0, that is, no component of Str is selected as in
Str[rep(F,3)], x is ignored, Str is not changed and the value is NULL.

In addition, you can specify by number components of components to be
changed.  For example, Str[[3]][[2]] <- x replaces component 2 of the
third compoent of Str by x and Str[[3]][[-1]] <- x replaces all but the
first component of the third component of Str by x.  If x is a structure
with the right number of components, each component of Str[[3]][[-1]] is
replaced by the correspoding component of x.  Otherwise, each component
of Str[[3]][[-1]] is replaced by x.

You can nest component specificiation, mixing names and [[...]]
subscripts up to 31 deep.  All subscripts except possibly the final one
must be integer scalars.  With nested components, no [...] subscripts
are allowed, that is, Str[[1]][3] <- x is illegal; use Str[[1]][[3]] <-
x.

                    Arithmetic assignment operators
There are several arithmetic assignment operators: <-+, <--, <-*, <-/,
<-%% and <-^.  For example, a <-* b is equivalent to a <- a*b and a <-^
b is equivalent to a <- a^b.  '<--' and '<-+' require a following space.

The variable being modified cannot be subscripted or be a structure
component.  For example, x[3] <-+ 1 and Str$x <-- 1 are illegal.  See
topic 'arithmetic' for more information.