H5T_IDL_CREATE

The H5T_IDL_CREATE function creates a datatype object based on the IDL type of the supplied data.

Example

See the example under H5F_CREATE.

Syntax

Result = H5T_IDL_CREATE(Data [,MEMBER_NAMES=vector] [, /OPAQUE])

Return Value

Returns a long integer containing the identifier of the new datatype.

Note: Datatype identifiers created by this function should be released with H5T_CLOSE.

Arguments

Data

An IDL variable containing the type of data that will be used by the resulting datatype. If a structure is passed in a compound datatype will be created based on the fields of the structure. The following table shows how IDL data types are converted to HDF5 datatypes. Pointers, complex numbers, and object references cannot be written to HDF5 datatypes.

Type Name	HDF5 Datatype
BYTE	H5T_NATIVE_UINT8
INT	H5T_NATIVE_INT16
UINT	H5T_NATIVE_UINT16
LONG	H5T_NATIVE_INT32
ULONG	H5T_NATIVE_UINT32
LONG64	H5T_NATIVE_INT64
ULONG64	H5T_NATIVE_UINT64
FLOAT	H5T_NATIVE_FLOAT
DOUBLE	H5T_NATIVE_DOUBLE
STRING	H5T_C_S1
Structure name or ANONYMOUS	(Member datatypes)

Note: If the data is an array, the datatype is constructed from the first element in the array. If an HDF5 array datatype is desired, then the datatype returned in this routine should be passed into H5T_ARRAY_CREATE. Using the first element could affect the size of a string datatype. All elements of a string datatype will have the same length, or number of characters. Strings smaller than the datatype length will be stored appropriately, but strings longer than the datatype length will be truncated. The size of the returned datatype will include a null termination character and thus will be one more than the number of characters in the string. For example:

datatype_id = H5T_IDL_CREATE('dog')

This produces a datatype with a size of 4. A dataset created with this datatype will only store up to 4 characters per element of the data being written. The following:

datatype_id = H5T_IDL_CREATE(['dog', 'dragon'])

will still produce a datatype with a size of 4 because the first element of the array is used when creating the datatype. When creating a string datatype the longest string needed should be used. Note that an excessively long string could result in a bloated file.

Keywords

MEMBER_NAMES

A string vector giving the name of each member of the compound datatype. This keyword is ignored if Data is not an IDL structure. If Data is an IDL structure and this keyword is not provided, the member names will be constructed from the field names in the structure, converting all letters to uppercase and all non-alphanumeric characters to underscores. If the number of elements in MEMBER_NAMES is less than the number of elements in the structure, field names will be used for member names where needed. If the number of elements in MEMBER_NAMES is greater than the number of elements in the structure, the extra string values will be ignored.

Elements of MEMBER_NAMES are assigned to fields in a depth-first, left-to-right traversal of the structure. For example, if Data contains a structure that looks like:

{ a:0l, b:{d:0l, e:0l}, c:0l }

and MEMBER_NAMES contains:

['cat', 'dog', 'dragon', 'emu']

then the resulting compound datatype uses the name 'cat' to refer to the datatype created from field a, 'dog' to refer to field b, 'dragon' to refer to field d, and 'emu' to refer to field e. Since only four names are provided, the compound datatype uses the name 'C' to refer to field c.

OPAQUE

Set this keyword to create an opaque datatype. The size of the datatype will be determined by the size of the Data argument.

Note: Opaque datatypes store data as a simple string of bytes, regardless of the form the data is in when written to the datatype. An opaque datatype is always a single element, regardless of the number of bytes.

Version History

6.2	Introduced
6.3	Added support for opaque datatypes and OPAQUE keyword