Assign Object to Database or Frame

DESCRIPTION:

Assigns a value to a name. The location of the assignment can be a specific frame (useful when writing functions), a data directory, or a meta-database for functions or documentation.

USAGE:

assign(x, value, frame=<<see below>>, where=<<see below>>, immediate, meta) 

REQUIRED ARGUMENTS:

x
character string giving the name of the object to be assigned.
value
any S-PLUS object; the value to be assigned the name in x.

OPTIONAL ARGUMENTS:

frame
number specifying in which of the frames of the current evaluation the object is to be assigned. frame=0 assigns to a database of objects (the session database) that will continue to be available throughout the current S-PLUS session, but will disappear at the end of the session. 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.
where
the database to which the object should be assigned. If where is supplied, it can either be a number or an object defining a database. A number implies the corresponding element of the search list, so where=2, for example, assigns an object to the second database. Using where=0 assigns to the session database. Otherwise, where is interpreted as a database, of any type. If the database is not currently attached, S-PLUS attaches it temporarily for the duration of the call. See attach for alternatives, usually more efficient, by which a database can be attached for the duration you need, without interfering with the search path.

Do not give both frame and where; if you do, S-PLUS reports an error.
immediate
a special option, meaningful only if where= is supplied and the database specified is the working data. In this case only, immediate=F causes assign to emulate the effect of an ordinary S-PLUS assignment expression in the top-level frame of the evaluator. That is, the object is assigned to frame 1, and copied at the end of the top-level task to the working data. Any other call to assign that includes where= performs the assignment immediately, regardless of this argument.
meta
if supplied, this specifies the purpose of the database to which the assignment takes place. For example, meta="help" says to assign to the help meta-data associated with the database where. This argument has no effect if frame is specified or where does not specify an attached chapter.

VALUE:

NULL.

SIDE EFFECTS:

assign is executed entirely for its side effect of assignment. Unlike the assignment operators, such as <-, assign does not return a non-NULL value.

The x argument provides the name of the object that will be created. For example, assign("a$b", 1) is distinctly not the way to create the component b of object a; rather it will create an object named a$b. If you created this object, you would need to use the get function to use the object. This allows you to create objects (to correspond with objects in another language, perhaps) whose names are not legal object names in S-PLUS. If you do want to assign the b component of a, then create all of a and assign a.

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 the top level (typed by the user, for example), and to the local frame of a function call when used from inside a function.

SEE ALSO:

, , , , , , , , , .

EXAMPLES:

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])