The IDLDehydrate function takes its input argument and transforms it into IDL primitives or collections of IDL primitives. This is useful for storage and transmission of object state. It is used by IDL Task Engine to provide output in a serialized form. IDL primitives are the numeric and string types. The return value of this function can be passed into the IDLHydrate function to create a clone of the input.

All IDL Data Types are supported by IDLDehydrate, except for Null, Structure, and Pointer. Any Object that implements a Dehydrate function method is supported as well.

IDLDehydrate returns the following based on input:

  • Scalar or array IDL primitive input return the same value, except for COMPLEX and DCOMPLEX input.
  • COMPLEX and DCOMPLEX input generate a Hash that separates the real and imaginary components into separate arrays.
  • Scalar object input causes the class's Dehydrate static function method, which must return a Hash the represents the object.
  • Object array input generates a List that contains the Hash returned by the object's Dehydrate function method.

Examples

Dehydrate a scalar number

PRINT, IDLDehydrate(!DPI), /IMPLIED

IDL Prints:

3.1415926535897931

Dehydrate a scalar complex number

PRINT, IDLDehydrate(COMPLEX(1, 2)), /IMPLIED

IDL Prints:

{
    "imaginary": 2.0000000,
    "real": 1.0000000
}

Dehydrate a list

value = LIST('one', 2.0, 3, 4L, COMPLEX(7))
PRINT, IDLDehydrate(value), /IMPLIED

IDL Prints:

{
    "elements": [
        {
            "type": "STRING",
            "dehydratedForm": "one"
        },
        {
            "type": "FLOAT",
            "dehydratedForm": 2.0000000
        },
        {
            "type": "INT",
            "dehydratedForm": 3
        },
        {
            "type": "LONG",
            "dehydratedForm": 4
        },
        {
            "type": "COMPLEX",
            "dehydratedForm": {
                "imaginary": 0.00000000,
                "real": 7.0000000
            }
        }
    ]
}

Syntax

Result = IDLDehydrate(value [, ERROR=error])

Return Value

Returns a scalar IDL primitive value, an array of IDL primitive values, a Hash of IDL primitive values, or a List of Hashes of IDL primitive values.

Arguments

Value

The value argument can be of any IDL data type including !NULL. If an object input must implement the Dehydrate function method to be supported by this routine.

Keywords

ERROR

Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').

When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.

Version History

8.5.2

Introduced

See Also

IDLHydrate