Enumeration Datatypes

An enumeration datatype consists of a set of (Name, Value) pairs, where:

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}

The routines are:

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:

H5T_GET_MEMBER_INDEX, H5T_GET_MEMBER_NAME, H5T_GET_MEMBER_VALUE

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)