idlastro / IDL Structure procedures: COPY_STRUCT

[Source code]

NAME
COPY_STRUCT
PURPOSE
Copy all fields with matching tag names from one structure to another
EXPLANATION
COPY_STRUCT is similar to the intrinsic STRUCT_ASSIGN procedure but 
has optional keywords to exclude or specify specific tags.
 Fields with matching tag names are copied from one structure array to 
 another structure array of different type.
 This allows copying of tag values when equating the structures of
 different types is not allowed, or when not all tags are to be copied.
 Can also recursively copy from/to structures nested within structures.
 Note that the number of elements in the output structure array
 is automatically adjusted to equal the length of input structure array.
 If this not desired then use pro copy_struct_inx which allows
 specifying via subscripts which elements are copied where in the arrays.
CALLING SEQUENCE
copy_struct, struct_From, struct_To, NT_copied
copy_struct, struct_From, struct_To, EXCEPT=["image","misc"]
copy_struct, struct_From, struct_To, /RECUR_TANDEM
INPUTS
struct_From = structure array to copy from.
struct_To = structure array to copy values to.
KEYWORDS
EXCEPT_TAGS = string array of tag names to ignore (to NOT copy).
        Used at all levels of recursion.
SELECT_TAGS = tag names to copy (takes priority over EXCEPT).
        This keyword is not passed to recursive calls in order
        to avoid the confusion of not copying tags in sub-structures.
/RECUR_FROM = search for sub-structures in struct_From, and then
        call copy_struct recursively for those nested structures.
/RECUR_TO = search for sub-structures of struct_To, and then
        call copy_struct recursively for those nested structures.
/RECUR_TANDEM = call copy_struct recursively for the sub-structures
        with matching Tag names in struct_From and struct_To
        (for use when Tag names match but sub-structure types differ).
OUTPUTS
struct_To = structure array to which new tag values are copied.
NT_copied = incremented by total # of tags copied (optional)
INTERNAL
Recur_Level = # of times copy_struct calls itself.
        This argument is for internal recursive execution only.
        The user call is 1, subsequent recursive calls increment it,
        and the counter is decremented before returning.
        The counter is used just to find out if argument checking
        should be performed, and to set NT_copied = 0 first call.
EXTERNAL CALLS
pro match       (when keyword SELECT_TAGS is specified)
PROCEDURE
Match Tag names and then use corresponding Tag numbers.
HISTORY
written 1989 Frank Varosi STX @ NASA/GSFC
mod Jul.90 by F.V. added option to copy sub-structures RECURSIVELY.
mod Aug.90 by F.V. adjust # elements in TO (output) to equal
                # elements in FROM (input) & count # of fields copied.
mod Jan.91 by F.V. added Recur_Level as internal argument so that
                argument checking done just once, to avoid confusion.
                Checked against Except_Tags in RECUR_FROM option.
mod Oct.91 by F.V. added option SELECT_TAGS= selected field names.
mod Aug.95 by W. Landsman to fix match of a single selected tag.
mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion.
Converted to IDL V5.0   W. Landsman   September 1997
od May 01 by D. Schlegel use long integers