Assign a Name to an Object

DESCRIPTION:

Operators that assign a value to a name.

USAGE:

expression <- value
expression _ value
expression = value
value -> expression
expression <<- value

REQUIRED ARGUMENTS:

value
the value to be assigned to the output from expression. The value argument itself can be a S-PLUS expression.
expression
a S-PLUS expression. If expression is a name or character string, the assignment operator in any of its forms causes value to be saved under that name. The arrow in the assignment operator always points toward the name. The expression argument can also specify a subset, element, or attribute of an object, or any combination of such expressions. Expressions of this form are called replacements to distinguish them from simple assignments. Examples include:

x[-1] <- 0,

length(mystuff) <- n

z$b <- 3

attr(obj,"myattr")[[1]] <- new.value

VALUE:

the value of the assignment is the right side of the operation (i.e., the value argument). This is true for replacements as well; the value of a replacement is the substituted values, not the whole object in which the replacement occurs.

SIDE EFFECTS:

The expression object is given the value of the value object.

WARNINGS:

Because the underscore _ is a S-PLUS assignment operator, it is extremely important to remember it cannot be used in function and object names, unlike in many other languages. It is also deprecated as an assignment operator, so it may not be supported in future releases of S-PLUS.

In addition to object assignments, the equals sign = is used for argument assignments within a function definition. Because of this, there are some ambiguities you must be aware of when using the equals sign as an assignment operator. For example, the command print(x <- myfunc(y)) assigns the value from myfunc(y) to the object x and then prints x . Conversely, the command print(x = myfunc(y)) simply prints the value of myfunc(y) and does not perform an assignment. This is because the print function has an argument named x and argument assignment takes precedence over object assignment with the equals sign. Because of these ambiguities, TIBCO discourages the use of the equals sign for left assignment.

DETAILS:

The left-arrow assignment operator is made up of the two characters < and -. An underscore _ or an equal sign = can also be used as an assignment operator. The right arrow is the two characters - and >. All four of these are equivalent semantically.

Location of Assignments. Assignments made with <- appear in the frame of the function call in which they occur, or in the working directory if they occur in frame 1. If an object is not in your working directory, it must be reassigned before replacements can take place in frame 1. For example, if there is no object named iris in the working directory but iris exists elsewhere in the search list, the expression dim(iris) <- c(50,12) does not work unless you first copy the object to your working directory; use the command iris <- iris to do this.

The <<- operator does assignments on the working data directory from any frame. The command name <<- value is similar to assign(where=1, "name", value) . The <<- operator cannot be used for replacements.

Once an assignment is made, the data can be retrieved in the same frame by typing the name used in the assignment.

Commitment. Assignments made to a data directory or to frame 0 are committed when S-PLUS finishes evaluating an entire expression. If an error occurs during the evaluation of an expression, no assignments executed during that expression are committed.

Legal Names. A name can be any combination of alphanumeric characters and periods that does not begin with a number, though there are a few reserved names. Names can be any length, but on a few machines they are unique to only a certain length. For example, only 14 characters are unique on a few UNIX machines and 11 characters are unique under DOS. To avoid confusion, it is best to create names that are not built-in function names. The most common function names users choose accidentally are c and t . See the masked help file for more details.

The names of operators, including user-written operators, are "% something %". See the examples below for an illustration of a user-defined operator.

At times, you may find occasion to try something like paste("xxx", i, sep="") <- tmp . However, this does not work. Instead, use assign(paste("xxx", i, sep=""), tmp) .

There is an object in the working directory called .Last.value containing the last object which was not assigned. If you would like to keep the results of a command you just executed, you can use .Last.value to do this.

SEE ALSO:

, , , , , , , , , , .

EXAMPLES:

# 100 uniforms saved as x.
# The square root of the sample saved as y
y <- sqrt(x<-runif(100))

# y is local to the function, but foo.foo is assigned to
# the working directory. If an error occurs in the function,
# foo.foo is not assigned.
function(x)
{
        y <- x + 3
        foo.foo <<- c(x, y)
}

# Create an operator named "gauss".
"%gauss%" <- function(x, y) exp(-x^2/y)

# Save results using .Last.value.
lsfit(my.x, my.y)
my.xyreg <- .Last.value