STRUCTURE directive

Defines a compound data structure.

 

Options

NAME = text Single-valued text defining a name for the type of structure, which must not clash with the name of any existing type of structure
STRUCTURELIST = string token Whether or not the structure consists of a list (of any length) of structures of the same type or types (yes, no); default no

 

Parameters

LABEL = texts Single-valued texts defining the labels of the elements of the structure
SUFFIX = scalars Suffix numbers for the elements; default assumes the numbers 1, 2 …
TYPE = texts Texts defining the allowed types for each element
COMPATIBLE = texts Defines aspects to check for compatibility with the first element

 

Description

The STRUCTURE directive allows you to define customized compound data structures for use, for example, in procedures. The NAME option supplies a single-valued text to define the name to be used for the new “type” of data structure. This can then be used as a setting for the TYPE parameter in either the OPTION or PARAMETER directives within a procedure, to indicate that the option or parameter concerned must be supplied with this type of structure. The case of the letters in the name is not significant. So they can be specified in capitals, or in lower case, or in any mixture.

The parameters of the directive define the contents of the structure. The LABEL parameter lists the labels to be used with each element of the structure, and the SUFFIX parameter lists the corresponding suffix numbers (by default the numbers 1, 2, etc.). The TYPE parameter allows you to define the types of structure that are allowed in each element (which may be any of the standard Genstat data structures, or other customized types), and the COMPATIBLE parameter allows you to define aspects that must be compatible with the first element of the structure similarly to the COMPATIBLE parameter of the OPTION and PARAMETER directives. These are checked when the structure is declared, and when it is used as an option or parameter setting of a procedure that requests that type.

For example, we could define a complex matrix structure by

STRUCTURE [NAME='complex_matrix'] 'real','imaginary';\

  TYPE='matrix'; COMPATIBLE=!t(rows,columns)A particular complex matrix, Cmat say, could then be declared using the DECLARE directive:

DECLARE [TYPE='complex_matrix'] Cmat   The elements of the compound structure can be referred to like those of an ordinary pointer declared using the POINTER directive with options CASE=ignored, ABBREVIATE=yes and FIXNVALUES=yes. So, the labels can be given in either upper or lower case or in any mixture, and each can be abbreviated to the minimum number of characters required to distinguish it from the previous labels. So the imaginary part of the complex matrix above could, for example, be referred to as Cmat['imaginary'] or Cmat['IMAGINARY'] or simply Cmat['i'].

Options: NAME, STRUCTURELIST.

Parameters: LABEL, SUFFIX, TYPE, COMPATIBLE.

 

See also

Directives: DECLARE, POINTER, LRV, SSPM, TSM.

Commands for: Data structures.

Updated on January 17, 2018

Was this article helpful?