Enumeration Datatypes

Name is a scalar string that is unique within the datatype (a given name string can only be associated with a single value)

Value is a scalar integer that is unique within the datatype

Note
Name/value pairs must be assigned to the datatype before it is used to create a dataset. The dataset stores the state of the datatype at the time the dataset is created; additional changes to the datatype will not be reflected in the dataset.

Create the enumeration datatype using the H5T_ENUM_CREATE function. Once you have created an enumeration datatype:

use the H5T_ENUM_INSERT procedure to associate a single name/value pair with the datatype

use the H5T_ENUM_VALUEOF function to retrieve the value associated with a single name

use the H5T_ENUM_NAMEOF function to retrieve the name associated with a single value

These routines replicate the facilities provided by the underlying HDF5 library, which deals only with single name/value pairs. To make it easier to read and write entire enumerated lists, IDL provides two helper routines at package the name/value pairs in arrays of IDL IDL_H5_ENUM structures, which have the following definition:

{IDL_H5_ENUM, NAME:'', VALUE:0}

H5T_ENUM_SET_DATA associates multiple name/value pairs with an enumeration datatype in a single operation. Data can be provided either as a string array of names and an integer array of values or as a single array of IDL_H5_ENUM structures.

H5T_ENUM_GET_DATA retrieves multiple name/value pairs from an enumeration datatype in a single operation. Data are returned in an array of IDL_H5_ENUM structures.

The H5T_ENUM_VALUES_TO_NAMES function is a helper routine that lets you retrieve the names associated with an array of values in a single operation.

The following routines may also be useful when working with enumeration datatypes:

Example

The following example creates an enumeration datatype and saves it to a file. The example then reopens the file and reads the data, printing the names.

; Create a file to hold the data  
file = 'h5_test.h5'  
fid = H5F_CREATE(file)  
  
; Create arrays to serve as name/value pairs  
names = ['dog', 'pony', 'turtle', 'emu', 'wildebeest']  
values = INDGEN(5)+1  
  
; Create the enumeration datatype  
dt = H5T_ENUM_CREATE()  
  
; Associate the name/value pairs with the datatype  
H5T_ENUM_SET_DATA, dt, names, values  
  
; Create a dataspace, then create and write the dataset  
ds = H5S_CREATE_SIMPLE(N_ELEMENTS(values))  
d = H5D_CREATE(fid, 'dataset', dt, ds)  
H5D_WRITE, d, values  
  
; Close the file  
H5F_CLOSE, fid  
  
; Reopen file for reading  
fid = H5F_OPEN(file)  
  
; Read in the data  
d = H5D_OPEN(fid, 'dataset')  
dt = H5D_GET_TYPE(d)  
result = H5D_READ(d)  
  
; Close the file  
H5F_CLOSE, fid  
  
; Print the value associated with the name "pony"  
PRINT, H5T_ENUM_VALUEOF(dt, 'pony')  
  
; Print all the name strings  
PRINT, H5T_ENUM_VALUES_TO_NAMES(dt, result)

IDL Online Help (March 06, 2007)