The basic syntax of a reference to a field within a structure is as follows:


Variable_Name must be a variable that contains a structure. Tag_Name is the name of the field and must exist in the structure. If the field referred to by the tag name is itself a structure, the Tag_Name can optionally be followed by one or more additional tag names, as shown by the following example:


Each tag name, except possibly the last, must refer to a field that contains a structure.

Number of Structure Tags

The function N_TAGS(Structure) returns the number of fields in a structure. To obtain the size, in bytes, of a structure call N_TAGS with the /LENGTH keyword.

Names of Structure Tags

The function TAG_NAMES(Structure) returns a string array containing the names of each tag. To return the name of the structure itself, call TAG_NAMES with the /STRUCTURE_NAME keyword.

Access Fields by Tag Number

A tag can be referenced using its index rather than its tag name. The tag index should be enclosed in parentheses, as follows:

Variable_Name.(Tag_Index)... ... ...

The Tag_Index ranges from zero to the number of fields minus one.

Note: The Tag_Index is an expression, the result of which is taken to be a tag position. In order for the IDL parser to understand that this is the case, you must enclose the Tag_Index in parentheses. This is not an array indexing operation, so using square brackets [ ] is not allowed in this context.

Subscripted Structure References

A subscript specification can be appended to the variable or tag names if the variable is an array of structures or if the field referred to by the tag contains an array. Scalar fields within a structure can also be subscripted, provided the subscript is zero.




Each subscript is applied to the variable or tag name it immediately follows. The syntax and meaning of the subscript specification is similar to simple array subscripting in that it can contain a simple subscript, an array of subscripts, or a subscript range. If a variable or field containing an array is referenced without a subscript specification, all elements of the item are affected. Similarly, when a variable that contains an array of structures is referenced without a subscript but with a tag name, the designated field in all array elements is affected. The complete syntax of references to structures follows. (Optional items are enclosed in braces, {}.)

Structure_reference:= Variable_Name{[Subscripts]}.Tags

Tags:= {Tags.}Tag

Tag:= Tag_Name{[Subscripts]}

For example, all of the following are valid structure references:

A.B[N, M]
A[3:5].B[*, N]
A[12].B.C[X, *]

Storing Into Array Fields

The semantics of storing into structure array fields is slightly different than storing into simple arrays. The main difference is that with structures, a subscript range must be used when storing an array into part of an array field. With normal arrays, when storing an array inside part of another array, use the subscript of the lower-left corner, not a range specification. Other differences occur because the size and type of a field are fixed by the original structure definition, and the normal semantics of dynamic binding are not applicable. The rules for storing into array fields are as follows:

VAR.ARRAY_TAG = Scalar_Expression

All elements of VAR.tag are set to Scalar_Expression. For example:

;Set all 12 elements of A.inten to 100.
A.inten = 100

VAR.TAG = Array_Expression

Each element of Array_Expression is copied into the array VAR.tag. If Array_Expression contains more elements than the destination array does, an error results. If it contains fewer elements than VAR.TAG, the unmatched elements remain unchanged. For example:

;Set A.inten to the 12 numbers 0, 1, 2,..., 11.
A.inten = FINDGEN(12)
;Set A.inten[0] to 1 and A.inten[1] to 2. The other elements 
;remain unchanged.
A.inten = [1, 2]

VAR.TAG[Subscript] = Scalar_Expression

The value of the scalar expression is copied into the designated element of the destination. If Subscript is an array of subscripts, the scalar expression is copied into the designated elements. For example:

;Set the sixth element of A.inten to 100. 
A.inten[5] = 100
;Set elements 2, 4, and 6 to 100.
A.inten[[2, 4, 6]] = 100

VAR.TAG[Subscript] = Array_Expression

Unless VAR.tag is an array of structures, the subscript must be an array. Each element of Array_Expression is copied into the element given by the corresponding element subscript. For example:

;Set elements 2, 4, and 6 to the values 5, 7, and 9 respectively.
A.inten[[2, 4, 6]] = [5, 7, 9]

VAR.TAG[Subscript_Range] = Scalar_Expression

The value of the scalar expression is stored into each element specified by the subscript range. For example:

;Sets elements 8, 9, 10, and 11 to the value 5.
A.inten[8:*] = 5

VAR.TAG[Subscript_Range] = Array_Expression

Each element of the array expression is stored into the element designated by the subscript range. The number of elements in the array expression must agree with the size of the subscript range. For example:

;Sets elements 3, 4, 5, and 6 to the numbers 0, 1, 2, and 3, ;respectively.
A.inten[3:6] = FINDGEN(4)

Examples of Structure References

The name of the star contained in A is referenced as A.NAME. The entire intensity array is referred to as A.INTEN, while the n-th element of A.INTEN is A.INTEN[N]. The following are valid IDL statements using the STAR structure:

;Store a structure of type STAR into variable A. Define the values 
;of all fields.
A = {star, name:'SIRIUS', ra:30., dec:40., inten:INDGEN(12)}
;Set name field. Other fields remain unchanged. = 'BETELGEUSE'
;Print name, right ascension, and declination.
PRINT,, A.ra, A.dec
;Set Q to the value of the sixth element of A.inten. Q will be a 
;floating-point scalar.
Q = A.inten[5]
;Set ra field to 23.21.
A.ra = 23.21
;Zero all 12 elements of intensity field. Because the type and size 
;of A.inten are fixed by the structure definition, the semantics of 
;assignment statements is different than with normal variables.
A.inten = 0
;Store fourth thru seventh elements of inten field in variable B.
B = A.inten[3:6]
;The integer 12 is converted to string and stored in the name field 
;because the field is defined as a string. = 12
;Copy A to B. The entire structure is copied and B contains a STAR 
B = A