Contents

changestr()

Usage:

changestr(Struc,name,x), Struc a structure, name a CHARACTER  scalar, x
  a defined variable
changestr(Struct,n,x), integer n, 1 <= n <= ncomps(Struct) + 1
changestr(Struct,name:x)
changestr(Struc, -n), n a positive integer

Keywords: structures

changestr(Str,Name,x) makes a copy of structure Str except that the
value of component Name is changed to x.  Name must be a quoted string
or CHARACTER scalar of no more than 12 characters.  It is an error if
Name contains a space, '$' or any "control character" (ASCII code <= 31
or 127).  If there is no component with name Name, x will be added as a
new component.  It will have name Name unless x is a keyword phrase

changestr(Str,Name,newname:x) does the same, except the changed or added
component has name 'newname'.

changestr(Str,compname:x) is the same as changestr(Str,"compname", x).
compname must have no more than 10 characters.

If you want to change a named component of a structure, say component
var of structure stats, it is better to use 'stats$var <- x' than
stats <- changestr(stats,"var", x).

changestr(Str,CompNumber,x), where CompNumber is a positive integer,
does the same, except the component to be changed is specified by number
rather than by name.  When CompNumber = ncomps(Str) + 1, a new component
with value x is added.  It is an error if CompNumber > ncomps(Str)+1.

changestr(Str,CompNumber,newname:x) does the same except the changed or
added component will have name 'newname'.

To change a component of a structure by number, it is preferable to us
Str[CompNumber] <- x rather than Str <- changestr(Str,CompNumber,x).

Moreover, you can change more than one component at a time by assigning
to subscripts:
  Cmd> Str[run(2)] <- vector(Pi,PI^2)
changes components and and 2 of Str without changing there names.

changestr(Str,-CompNumber) produces a new structure omitting component
CompNumber.  It is illegal to delete the only component of a structure.

Preferable to this usage is Str[-CompNumber].  Moreover, you can omit
several components by, say, Str[-run(2)].

When Str is a structure with a component Name, Str$Name <- x changes
component Name, without making a temporary copy of Str.

When J is a positive integer <= ncomps(Str), Str[J] <- x changes
component J, without making a temporary component of Str.  You can
change more than component of Str when J is a vector of subscripts.  See
topic 'assignment'.

Examples:  In each of the following groupings, all the commands return
the same structure:
  Cmd> changestr(structure(a:run(10),b:"Hello"),"a",PI)
  Cmd> changestr(structure(a:run(10),b:"Hello"),1,PI)
  Cmd> structure(a:PI,b:"Hello")

  Cmd> changestr(structure(a:run(10),b:"Hello"),"a",pi:PI)
  Cmd> changestr(structure(a:run(10),b:"Hello"),1,pi:PI)
  Cmd> structure(pi:PI,b:"Hello")

  Cmd> changestr(structure(a:run(10),b:"Hello"),3,c:"Dolly")
  Cmd> changestr(structure(a:run(10),b:"Hello"),c:"Dolly")
  Cmd> structure(a:run(10),b:"Hello",c:"Dolly")

  Cmd> changestr(structure(a:run(10),b:"Hello"),-1)
  Cmd> structure(b:"Hello").

See also topics 'structures', 'keywords', structure(), strconcat().