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 |

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.

Gary Oehlert 2003-01-15