Assigns new identifiers to data structures.
No options
Parameters
OLDIDENTIFIER = identifiers |
Specifies the data structures to rename |
|---|---|
NEWIDENTIFIER =identifiers |
Specifies a new identifier for each data structure |
Description
RENAME allows you to assign a different identifier to a data structure. For example, if you put
RENAME OLDIDENTIFIER=A; NEWIDENTIFIER=B
the data structure previously known as A would be renamed to have the identifier B, and the data structure previously known as B would lose its identifier and become unnamed. The identifier A would then no longer belong to anyone (and could if required be reused).
In the simplest situations, the first appearance of the new identifier will be in the RENAME command. So there will be no consequences from the fact that the “orphan” data structure that it previously identified becomes unnamed.
If the identifier has already been used, the orphan data structure will be deleted, unless it is found to belong to another (named) data structure. So, for example, if the full program was
SCALAR B; VALUE=1
POINTER [VALUES=B] Q
RENAME OLDIDENTIFIER=A; NEWIDENTIFIER=B
the scalar 1 would survive as the first element of the pointer Q. So it could still be referred to as Q[1], although of course no longer as B. You would get the same effect be specifying
RENAME OLDIDENTIFIER=A; NEWIDENTIFIER=Q[1]
as RENAME looks only for the (named) identifier of the data structure specified by NEWIDENTIFIER. So, in this case, A takes over the identifier B of Q[1]. If Q[1] did not have a separate identifier of its own, A would become unnamed. (So this provides a way of removing the identifier of a pointer element.)
You can also specify a pointer element for the setting of OLDIDENTIFIER and, again, RENAME will operate only on its identifier (if it has one). For example, in the program
SCALAR C; VALUE=7
POINTER [NVALUES=2] P
RENAME OLDIDENTIFIER=P[1]; NEWIDENTIFIER=C
the pointer element P[1] gains the identifier C, and so can be referred to as C in future (as well as P[1]).
So, to summarize, for the data structures specified by both the OLDIDENTIFIER and NEWIDENTIFIER parameters, RENAME ignores any memberships that they may have of pointers, or e.g. as classifying factors of a table, or as levels or labels vectors of factors. It operates only on their own identifiers, reassigning the one (if any) belonging to the NEWIDENTIFIER data structure to become the identifier of the data structure specified by the OLDIDENTIFIER parameter.
Finally note that, if either OLDIDENTIFIER or NEWIDENTIFIER is set to a dummy, RENAME will operate on the data structure to which it points, not on the dummy itself (i.e. dummies are always substituted). So, this allows you to rename data structures in your main program from inside a procedure.
Options: none.
Parameters: OLDIDENTIFIER, NEWIDENTIFIER.
See also
Directives: DUMMY, POINTER, PROCEDURE.
Commands for: Calculations and manipulation, Data structures.
Example
" RENAME example " SPLOAD [PRINT=*] '%GENDIR%/Data/Canola.gsh' " form N x S table of mean yields (to show what happens when N and S are renamed) " TABULATE [CLASSIFICATION=N,S] yield; MEAN=MeanYield PRINT MeanYield " print to show the original values of N and S " PRINT N,S " rename N to Nitrogen, and S to Sulphur " RENAME N,S; NEWIDENTIFIER=Nitrogen,Sulphur " print to show that N has become Nitrogen, and S has become Sulphur " PRINT Nitrogen,Sulphur " notice the renaming carries over to the classification of MeanYield " PRINT MeanYield