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:

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

See Also

IDL_VALIDNAME, N_TAGS, TAG_NAMES