CREATE_STRUCT
The CREATE_STRUCT function creates a structure given pairs of tag names and values. CREATE_STRUCT can also be used to concatenate structures.
Examples
To create the anonymous structure { A: 1, B: 'xxx'} in the variable P, enter:
p = CREATE_STRUCT('A', 1, 'B', 'xxx')
To add the fields “FIRST” and “LAST” to the structure, enter the following:
p = CREATE_STRUCT('FIRST', 0, p, 'LAST', 3)
The resulting structure contains { FIRST: 0, A: 1, B: 'xxx', LAST: 3}.
Finally, consider the following statements:
s1 = {Struct1, Tag1:'AAA', Tag2:'BBB'}
s2 = {Struct2, TagA:100, TagB:200}
s3 = CREATE_STRUCT(NAME='Struct3', ['A','B','C'], 1, 2, s1, s2)
Here, the variable s3 contains the following named structure:
{Struct3, A: 1, B: 2, C:{Struct1, Tag1: 'AAA', Tag2: 'BBB'}, TagA: 100, TagB: 200}
Note that the value of s3.C is itself a “Struct1” structure, since the structure variable s1 was interpreted as a Values argument, whereas the structure variable s2 was interpreted as a Structures argument, thus including the tags from the “Struct2” structure directly in the new structure.
Syntax
Result = CREATE_STRUCT( [Tag1, Values1, ..., Tagn, Valuesn] [, Structuresn] [, NAME=string])
or
Result = CREATE_STRUCT( [Tags, Values1, ..., Valuesn][, Structuresn] [, NAME=string])
Return Value
Returns a structure composed of given pairs of tag names and values.
Arguments
Tags
The structure tag names. Tag names may be specified either as scalar strings or a single string array. If scalar strings are specified, values alternate with the tag names. If a string array is provided, values must still be specified individually. Tag names must be enclosed in quotes. Tag names may not be IDL Reserved Words, and must be unique within a given structure, although the same tag name can be used in more than one structure. Tag names follow the rules of IDL identifiers: they must begin with a letter; following characters can be letters, digits, or the underscore or dollar sign characters; and case is ignored.
Note: If a tag name contains spaces, CREATE_STRUCT will replace the spaces with underscores. For example, if you specify a tag name of 'my tag', the tag will be created with the name 'my_tag'.
Values
The values for the structure fields. The number of Values arguments must match the number of Tags arguments (if tags are specified as scalar strings) or the number of elements of the Tags array (if tags are specified as a single array.)
Structures
One or more existing structure variables whose tags and values will be inserted into the new structure. When concatenating structures in this manner, the following rules apply:
- All tag names, whether specified via the Tags argument or in an existing structure variable, must be unique.
- Names of named structures included via the Structures arguments are not used in the newly-created structure.
- Structures arguments can be interspersed with groups of Tags and Values arguments in the call to CREATE_STRUCT. Use caution, however, to ensure that the number of Tags and Values in each group are equal, to avoid inserting a structure variable as the value of a single tag when you mean to include the structure’s data as individual tags and values.
Keywords
NAME
To create a named structure, set this keyword equal to a string specifying the structure name. If this keyword is not present, an anonymous structure is created. Structure names must begin with a letter; following characters can be letters, digits, or the underscore or dollar sign characters; and case is ignored.
If NAME is specified and no plain arguments (tags, values, or structures) are present, then CREATE_STRUCT will return a structure of known type, either from IDL's internal table of already known named structures or by locating the appropriate __define.pro file for that structure in the current IDL search path (!PATH) and executing it. Hence, the following IDL statements are equivalent:
Result = { mystruct }
Result = CREATE_STRUCT(NAME='mystruct')
The CREATE_STRUCT version can be convenient in situations where the name of the structure is computed at runtime, and the EXECUTE function is not available (e.g., code running in the free IDL Virtual Machine environment, in which EXECUTE is disallowed).
Version History
|
Pre 4.0 |
Introduced |
|
6.1 |
Added NAME keyword |