TAGSIZE Name
TAGSIZE
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Compute SIZE descriptors for each tag in a structure
Calling Sequence
SIZES = TAGSIZE(STRUCT, N_TAGS=ntags, TAG_NAMES=tagnames,
STRUCTURE_NAME=structname, STATUS=status, LENGTH=length)
Description
The TAGSIZE function determines the types and sizes of each tag in
a structure. This is not as easy as it may seem, because IDL
makes it very, *very* difficult to find out the true dimensions of
a structure element.
Here is a brief explanation. It is known that IDL drops trailing
dimensions of size 1 in many situations. Also, for structures
only, arrays of any dimensionality which have only one element are
RETURNED AS SCALARS. Thus, if you are doing any heavy duty work
with structures, copying and querying individual elements between
structures, etc., you will find that you will lose some crucial
dimensions which you can't normally regain.
TAGSIZE attempts to work around all of these limitations to
present the true dimensions of all elements in a structure.
It returns an 11xNTAGS array, which contains a SIZE-style vector
for each element in the structure. Eleven elements is the largest
array size needed to describe any IDL data type using SIZE. Thus,
to extract information about the second tag in structure X
(element number 1 starting from zero), you would use the following
code:
SIZES = TAGSIZE(X) ;; Extract type information from structure X
SIZE_1 = SIZES(*,1) ;; Extract type information about the 2nd element
SIZE_1 = SIZE_1(0:SIZE_1(0)+2) ;; Trim the array if desired
The last command is optional, but trims the resulting array to be
a true SIZE-style result.
TAGSIZE also has several convenience keywords to extract other
relevant information about a structure.
Inputs
STRUCTURE - any structure to examine. If the value is not a
structure then an error is reported.
Keywords
N_TAGS - upon return, the number of tags in the structure is
stored in this keyword.
TAG_NAMES - upon return, the names of each tag are stored in this
keyword, as an array of strings.
STRUCTURE_NAME - upon return, the name of the structure is stored
in this keyword. If the structure is anonymous
then the empty string ('') is returned.
LENGTH - upon return, the size in bytes of each tag element in the
structure is stored in this keyword, as an array of
integers.
STATUS - upon return, the status is stored in this keyword. A
value of 1 indicates success, 0 indicates failure.
Returns
A two dimensional array, with dimensions LONARR(11,NTAGS),
containing the size information of all tag elements in the
structure. SIZES(*,i) is the SIZE-style vector for tag element i.
Example
Compute the sizes of the elements in X, defined here.
IDL> x = {a: [1], b: intarr(2,2), c: reform(strarr(2,1),2,1)}
IDL> help, /struct, x
** Structure <818c8b4>, 3 tags, length=28, refs=1:
A INT Array[1]
B INT Array[2, 2]
C STRING Array[2, 1]
IDL> print, byte(tagsize(x))
1 [1] 2 1 0 0 0 0 0 0 0
2 [2 2] 2 4 0 0 0 0 0 0
2 [2 1] 7 2 0 0 0 0 0 0
[ Array dimensions are emphasized with brackets ]
Compare this to the type information returned by HELP, which is
incorrect for tags A and C.
IDL> help, x.a, x.b, x.c
<Expression> INT = 1
<Expression> INT = Array[2, 2]
<Expression> STRING = Array[2]
See Also
TAG_NAMES, N_TAGS, SIZE, HELP, INPUTFORM, HELPFORM
Modification History
Written, CM, 13 May 2000
Documented, 05 Jul 2000
Small documentation changes, CM, 31 Aug 2000
Signficant cleanup of HELP parsing, CM, 04 Dec 2000
Added case for array of structures with new parsing, CM 12 Jan
2001