.BG
.FN assign
.TL
Assign Object to Directory or Frame
.CS
assign(x, value, frame, where)
.AG x
character string giving the name of the object to be assigned.
.AG value
any S object; the value to be assigned to the name in `x'.
.AG frame
number specifying in which of the frames
of the current evaluation the object is to be assigned.
`frame=0' assigns to the session frame; i.e.,
objects that will continue to be available throughout the current S session,
but will disappear at the end of the session.
Avoid creating many session objects\(emthe space they occupy
is not reclaimed in the present implementation.
`frame=1' means that the object is assigned to
the expression frame.
It will be available (from any frame) throughout the evaluation of
the current expression, but will
disappear when evaluation is complete.
This is a useful way to create objects that are to be shared by several
functions during the expression.
.AG where
directory in which the object is to be assigned.
If `where' is supplied, it can either be a number or a character string.
A number implies the corresponding element of the
search list (`.Search.list'), so
`where=2', for example, assigns an object in the second directory.
If `where' is a character string, this is taken as the path name for a
directory in the file system.
In this case, the directory must be an S data directory,
but need not be on the search list.
.SE
`assign' is executed entirely for its side effect of assignment.
Unlike the assignment operators, such as `<-', `assign' does not
return a value.
Assignments are committed when S finishes evaluating an entire
expression.  If an error occurs during evaluation of an expression,
no assignments executed during that expression are committed.
.PP
If both `where' and `frame' are omitted,
the `assign' function works exactly the same way as the operator `<-'; that
is, it assigns (permanently) to the working data when used at top level
(typed by the user, for example), and to the local frame of a function
call when used from inside a function.
.EX
assign("abc", 1:3) # assign "abc"
assign(".Options", options, frame=0) # session dataset
assign(".Counts", counts, w=1) # to working data (even in a function)
# make up variable names in a loop
for(i in 1:10) assign(paste("sample",i,sep="."),runif(10))
# save each column of matrix x under a different name
for(i in seq(ncol(x)))
     assign(colname[i], x[,i])
# save under a weird name !!
assign("a$b",1)
.PP
In the last example, note that this is distinctly not the way to create
the component `b' of object `a', as `a$b \(<- 1' would do.
.SA
`Assignment', `remove', `get', `exists', `attach', `detach', `search',
`synchronize'.
.KW data
.KW programming
.WR
