The IDLHydrate function transforms its IDL primitive input argument into the desired type. The return value of the IDLDehydrate function can be passed into this function and a clone of the original input will be returned.

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

IDLHydrate returns the following based on input:

  • Scalar and array IDL primitive input return the same value, assuming TYPE is compatible with the primitive type.
  • Nested Lists of scalar IDL primitive values will be converted into an array of primitive values, provided all Lists at the same nesting level agree on the number of elements in that dimension.
  • List input for non-primitive types must contain only Hashes describing objects, or other Lists thereof.
  • Hash input which is the expected dehydrated form of the class specified by the TYPE keyword. The class must implement a static Hydrate function that accepts the hash and returns an object.

Examples

Hydrate a scalar number

PRINT, IDLHydrate(!DPI, TYPE='DOUBLE'), /IMPLIED

IDL Prints:

3.1415926535897931

Hydrate a hash describing a scalar complex number

value = HASH('real', 1.0, $
             'imaginary', 2.0)
PRINT, IDLHydrate(value, TYPE='COMPLEX'), /IMPLIED

IDL Prints:

(       1.0000000,       2.0000000)

Hydrate a hash describing a list

value = HASH('elements', LIST(HASH('type', 'STRING', $
                                   'dehydratedForm', 'one'), $
                              HASH('type', 'FLOAT', $
                                   'dehydratedForm', 2.0), $
                              HASH('type', 'INT', $
                                   'dehydratedForm', 3), $
                              HASH('type', 'LONG', $
                                   'dehydratedForm', 4), $
                              HASH('type', 'COMPLEX', $
                                   'dehydratedForm',HASH('real', 5.0, $
                                                         'imaginary', 6.0))))
PRINT, IDLHydrate(value, TYPE='LIST'), /IMPLIED

IDL Prints:

[
  "one",
  2.0000000,
  3,
  4,
  (       5.0000000,       6.0000000)
]

Syntax

Result = IDLHydrate(dehydratedForm, TYPE=type [, ERROR=error])

Return Value

Returns a scalar or array of values that conform to the TYPE keyword.

Arguments

DehydratedForm

The dehydratedForm argument can be a scalar IDL primitive value, an array or List of IDL primitive values, a hash describing all the properties of an object in IDL primitive form, or a list of these hashes. All hash input must contain a "factory" key that references the function to invoke to create the object being described. You can use IDLDehydrate to see the expected DehydratedForm.

 

To restore a LIST, the input is a hash with these keys:

Key Description
elements Required. A list containing a separate hash that describes each element of the original list.
type Required in each hash under elements. A string value indicating the type of the current list element.
dehydratedForm Required in each hash under elements. The result of calling IDLDehydrate on the current list element.

To restore a HASH, the input is a hash with these keys:

Key Description
fold_case A Boolean value that is passed into the FOLD_CASE keyword when constructing the output hash object.
elements Required. A hash of key/value pairs containing a separate hash that describes each element of the original hash, using the same key.
type Required in each hash under elements. A string value indicating the type of the current hash element.
dehydratedForm Required in each hash under elements. The result of calling IDLDehydrate on the current hash element.

To restore a COMPLEX scalar or array, the input is a hash with these keys:

Key Description
real Required. A scalar or array of FLOATs that are the real component of the output COMPLEX value.
imaginary A scalar or array of FLOATs that are the imaginary component of the output COMPLEX value. If this is omitted then every COMPLEX output has a 0 imaginary component. This value must have the same dimensions as the real value.

To restore a DCOMPLEX scalar or array, the input is a hash with these keys:

Key Description
real Required. A scalar or array of DOUBLEs that are the real component of the output DCOMPLEX value.
imaginary A scalar or array of DOUBLEs that are the imaginary component of the output DCOMPLEX value. If this is omitted then every DCOMPLEX output has a 0 imaginary component. This value must have the same dimensions as the real value.

Keywords

TYPE

A scalar string indicating what type of return value the user expects. The TYPE keyword must be a scalar string that references a valid IDL type or must be the class name of the object to create.

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

IDLDehydrate