Declares one or more pointer data structures.
Options
NVALUES = scalar or text |
Number of values, or labels for values; default * |
|---|---|
VALUES = identifiers |
Values for all the pointers; default * |
SUFFIXES = variate or scalar |
Defines an integer number for each of the suffixes; default * indicates that the numbers 1,2,… are to be used |
CASE = string token |
Whether to distinguish upper and lower case in the labels of the pointers (significant, ignored); default sign |
ABBREVIATE = string token |
Whether or not to allow the labels to be abbreviated (yes, no); default no |
FIXNVALUES = string token |
Whether or not to prohibit automatic extension of the pointers (yes, no); default no |
RENAME = string token |
Whether to reset the default names of elements of the pointer if they do not have their own identifiers (yes, no); default no |
MODIFY = string token |
Whether to modify (instead of redefining) existing structures (yes, no); default no |
IPRINT = string tokens |
Information to be used by default to identify the pointers in output (identifier, extra); if this is not set, they will be identified in the standard way for each type of output |
EXTEND = string token |
Whether to extend (instead of redefining) an existing pointer (yes, no); default no |
Parameters
IDENTIFIER = identifiers |
Identifiers of the pointers |
|---|---|
VALUES = pointers |
Values for each pointer |
EXTRA = texts |
Extra text associated with each identifier |
Description
Lists of data structures can be stored in a Genstat pointer structure to save having to type the list in full every time it is used. For example
POINTER [VALUES=Rain,Temp,Windspeed] Vars
VARIATE #Vars
READ [CHANNEL=2] #Vars
PRINT #Vars; DECIMALS=2,1,2
defines Rain, Temp and Windspeed to be variates, and then reads and prints their values. When none of the structures in the list is itself a pointer, the substitution symbol (#) simply replaces the pointer by its values. If, however, there are pointers in the list, they too are substituted, as are any pointers to which they point. An example is given below.
The individual elements of a pointer can also be referred to by the use of suffixes. We can refer to Rain above either using its own identifier, or as the first element of Vars by using the suffix [1]: so
Vars[1] |
is Rain |
|---|---|
Vars[2] |
is Temp |
Vars[3] |
is Windspeed |
Furthermore, we can put a list within the brackets:
Vars[3,1] |
is Windspeed,Rain. |
|---|
Also, you can put a null list to mean all the available suffixes of the pointer:
Vars[] |
is Rain,Temp,Windspeed. |
|---|
Identifiers like Vars[1], Vars[2] and Vars[3] are called suffixed identifiers and, in fact, you can use these even without defining the identifier of the pointer explicitly. Whenever a suffixed identifier is used, Genstat automatically sets up a pointer for the unsuffixed part of the identifier if it does not already exist. Furthermore the pointer will automatically be extended (whether it has been set up by you or by Genstat) if you later use a new suffix, like Vars[93] for example. Notice that the suffixes do not need to be a contiguous list, nor need they run from one upwards, although they must be integers; if you give a decimal number it will be rounded to the nearest integer (for example, -27.2 becomes -27).
The SUFFIXES option of the POINTER directive allows you to specify the required suffixes for pointers that are defined explicitly. For example
VARIATE [VALUES=1990,1991,1992,1993] Suffs
POINTER [NVALUES=4; SUFFIXES=Suffs] Profit
defines Profit to be a pointer of length four, with suffixes 1990 to 1993. If you are setting the suffixes explicitly, you might want to forbid Genstat to extend the pointer if another suffix is encountered later in the program; this can be done by setting option FIXNVALUES=yes.
We could actually omit the NVALUES option in the definition of the pointer Profit above, as Genstat can determine the length of the pointer by counting the number of values. However, by supplying a text instead of a scalar for NVALUES you can define labels for the suffixes of the pointer. The length of the text defines the number of values of the pointer, and its values give the labels. For example
TEXT [VALUES=name,salary,grade] Labs
POINTER [NVALUES=Labs] Employee
would allow you to refer to Employee['name'], Employee['salary'], and so on.
Usually, when the pointer is later used, Genstat requires the labels to be given exactly as in the definition. However, you can set option CASE=ignored to indicate that case is unimportant, so they can be specified in capitals, or lower case, or in any mixture. You can also set option ABBREVIATE=yes to allow each one to be abbreviated to the minimum number of characters required to distinguish it from the labels of earlier elements of the pointer.
The identifiers in a suffix list can be of scalars, variates or texts; this of course includes numbers and strings as unnamed scalars and texts respectively. If one of these structures contains several values, it defines a sub-pointer: for example Vars[!(3,2)] is a pointer with two elements, Windspeed and Temp. You must thus be careful not to confuse a sub-pointer with a list of some of the elements of a pointer: for example Vars[!(3,2)] is a single pointer with two elements, whereas Vars[3,2] is a list of the two structures Windspeed and Temp.
As mentioned above, a pointer can be extended automatically to include a new suffix, if that suffix is used with the pointer in your program. However, it is not possible to extend the pointer automatically to include a new label, as Genstat would not know which suffix to give it and an automatic choice could lead to errors or confusion. So, the POINTER directive has an option EXTEND which can be set to yes to do this explicitly. The pointer elements that are defined are then added to the existing elements of the pointer. So, we could add additional labels to the pointer Employee, above, by the statements
TEXT [VALUES=department,room] Newlabs
VARIATE [VALUES=4,5] Newsuffs
POINTER [NVALUES=Newlabs; SUFFIXES=Newsuffs; EXTEND=yes] Employee
adds Employee['department'] as suffix 4, and Employee['room'] as suffix 5. If you do not specify a label, the new suffix is still added (but unlabelled). If you do not specify a suffix, the new label is given a suffix of one plus the largest suffix already in the pointer. When EXTEND=yes, the EXTRA parameter and the CASE, ABBREVIATE, FIXNVALUES, MODIFY and IPRINT options are ignored.
Elements of pointers can themselves be pointers, allowing you to construct trees of structures. For example
VARIATE A,B,C,D,E
POINTER R; VALUES=!P(D,E)
& S; VALUES=!P(B,C)
& Q; VALUES=!P(A,S)
& P; VALUES=!P(Q,R)
You can refer to elements within the tree by giving several levels of suffixes: for example P[2][1] is R[1] which is D; P[2,1][1,2] is (R,Q)[1,2] or D,E,A,S. The special symbol # allows you to list all the structures at the ends of the branches of the tree: #P replaces P by the identifiers of the structures to which it points (Q and R); then, if any of these is a pointer, it replaces it by its own values, and so on. Thus #P is the list A,B,C,D,E.
As you have seen, structures need not have an identifiers of their own, but may simply be identifiable as a member of a pointer using the suffix notation. Where a structure like this is a member of more than one pointer, Genstat will refer to it in output using the pointer with which it was first associated. So, for example, in
POINTER [NVALUES=2] P
& [VALUES=P[1,2],C] Q
VARIATE [VALUES=1,2,3,4] Q[]
PRINT Q[]the output will be labelled as P[1], P[2] and C. However, we can set option RENAME=yes when Q is defined
POINTER [VALUES=P[1,2],C; RENAME=yes]to request that the pointer Q takes precedence over earlier definitions, so the labels become Q[1], Q[2] and C.
Options: NVALUES, VALUES, SUFFIXES, CASE, ABBREVIATE, FIXNVALUES, RENAME, MODIFY, IPRINT, EXTEND.
Parameters: IDENTIFIER, VALUES, EXTRA.
See also
Directives: ASSIGN, STRUCTURE, DECLARE, DUMMY, LRV, SSPM, TSM, TREE.
Procedure: PDUPLICATE.
Functions: VSUMS, VTOTALS, VMEANS, VMEDIANS, VMINIMA, VMAXIMA, VRANGE, VCOVARIANCE, VCORRELATION, VSD, VSEMEANS, VSKEWNESS, VKURTOSIS, VVARIANCES, VNOBSERVATIONS, VNVALUES, VNMV, VPOSITIONS.
Commands for: Data structures.
Example
" Example POIN-1: Declaring a pointer" VARIATE [NVALUES=2] Yield,Costs,Profit READ Yield,Costs,Profit 5.6 1200 455 6.1 1530 620 : POINTER [VALUES=Yield,Costs,Profit] Info PRINT Info[1]