RENAME directive

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 lets you 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 lets you 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
Updated on March 5, 2019

Was this article helpful?