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( [Tag₁, Values₁, ..., Tag_n, Values_n] [, Structures_n] [, NAME=string])

Result = CREATE_STRUCT( [Tags, Values₁, ..., Values_n][, Structures_n] [, NAME=string])

Return Value

Returns a structure composed of given pairs of tag names and values.

Arguments

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