Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Enumeration Datatypes
Datatypes (H5T) » Compound and Enumeration Datatypes

## Detailed Description

## Functions
hid_t | H5Tenum_create (hid_t base_id)
| Creates a new enumeration datatype.
herr_t | H5Tenum_insert (hid_t type, const char *name, const void *value)
| Inserts a new enumeration datatype member.
herr_t | H5Tenum_nameof (hid_t type, const void *value, char *name, size_t size)
| Returns the symbol name corresponding to a specified member of an enumeration datatype.
herr_t | H5Tenum_valueof (hid_t type, const char *name, void *value)
| Returns the value corresponding to a specified member of an enumeration datatype.
herr_t | H5Tget_member_value (hid_t type_id, unsigned membno, void *value)
| Returns the value of an enumeration datatype member.

## Function Documentation

## ◆ H5Tenum_create()

hid_t H5Tenum_create | ( | hid_t | base_id | ) |

Creates a new enumeration datatype.

Parameters

  [in] | base_id | Datatype identifier for the base datatype. Must be an integer datatype

Returns
  Returns a enumeration datatype identifier if successful; otherwise returns H5I_INVALID_HID.

H5Tenum_create() creates a new enumeration datatype based on the specified base datatype, dtype_id, which must be an integer datatype.

If a particular architecture datatype is required, a little endian or big endian datatype for example, use a native datatype as the base datatype and use H5Tconvert() on values as they are read from or written to a dataset.

Since
  1.2.0

## ◆ H5Tenum_insert()

herr_t H5Tenum_insert | ( | hid_t | type,
|  | const char * | name,
|  | const void * | value )

Inserts a new enumeration datatype member.

Parameters

  [in] | type | Datatype identifier
  [in] | name | Name of the new member
  [in] | value | Pointer to the value of the new member

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tenum_insert() inserts a new enumeration datatype member into an enumeration datatype.

`type_id` is the datatype identifier for the enumeration datatype, `name` is the name of the new member, and `value` points to the value of the new member.

`name` and `value` must both be unique within `dtype_id`.

`value` points to data which must be of the integer base datatype used when the enumeration datatype was created. If a particular architecture datatype is required, a little endian or big endian datatype for example, use a native datatype as the base datatype and use H5Tconvert() on values as they are read from or written to a dataset.

Since
  1.2.0

## ◆ H5Tenum_nameof()

herr_t H5Tenum_nameof | ( | hid_t | type,
|  | const void * | value,
|  | char * | name,
|  | size_t | size )

Returns the symbol name corresponding to a specified member of an enumeration datatype.

Parameters

  [in] | type | Datatype identifier
  [in] | value | Value of the enumeration datatype
  [out] | name | Buffer for output of the symbol name
  [in] | size | Anticipated size of the symbol name, in bytes

Returns
  Returns a non-negative value if successful. Otherwise returns a negative value

H5Tenum_nameof() finds the symbol name that corresponds to the specified `value` of the enumeration datatype `type`.

At most `size` characters of the symbol `name` are copied into the `name` buffer. If the entire symbol name and null terminator do not fit in the name buffer, then as many characters as possible are copied (not null terminated) and the function fails.

Since
  1.2.0

## ◆ H5Tenum_valueof()

herr_t H5Tenum_valueof | ( | hid_t | type,
|  | const char * | name,
|  | void * | value )

Returns the value corresponding to a specified member of an enumeration datatype.

Parameters

  [in] | type | Datatype identifier
  [in] | name | Symbol name of the enumeration datatype
  [out] | value | Buffer for the value of the enumeration datatype

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tenum_valueof() finds the value that corresponds to the specified name of the enumeration datatype `dtype_id`.

Values returned in `value` will be of the enumerated type's base type, that is, the datatype used by H5Tenum_create() when the enumerated type was created.

The `value` buffer must be at least large enough to hold a value of that base type. If the size is unknown, you can determine it with H5Tget_size().

Since
  1.2.0

## ◆ H5Tget_member_value()

herr_t H5Tget_member_value | ( | hid_t | type_id,
|  | unsigned | membno,
|  | void * | value )

Returns the value of an enumeration datatype member.

Parameters

  [in] | type_id | Datatype identifier
  [in] | membno | Number of the enumeration datatype member
  [out] | value | Buffer for the value of the enumeration datatype member

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tget_member_value() returns the value of the enumeration datatype member `member_no`.

The member value is returned in a user-supplied buffer pointed to by `value`. Values returned in `value` will be of the enumerated type's base type, that is, the datatype used by H5Tenum_create() when the enumerated type was created.

The value buffer must be at least large enough to hold a value of that base type. If the size is unknown, you can determine it with H5Tget_size().

Since
  1.0.0