Datatype (H5T)

Datatype of elements in a dataset

Description

Use the MATLAB^® HDF5 datatype interface, H5T, to create and handle datatypes, and access information about them.

An HDF5 datatype describes the storage format for a single data element, such as the datatype of numeric and character data. In addition to numbers and characters, an HDF5 datatype can describe more abstract classes of types, including enumerations, strings, and references. Users can also define new datatypes within the datatype classes.

General Datatype Operations

H5T.close

Close datatype

H5T.close(typeID) releases the datatype specified by typeID.

H5T.commit

Commit transient datatype

H5T.commit(locID,name,typeID) commits a transient datatype to a file, creating a new named datatype. This syntax corresponds to the H5Tcommit interface in version 1.6 of the HDF5 C library.

H5T.commit(locID,name,typeID,lcplID,tcplID,taplID) commits a transient datatype to a file, creating a new named datatype, and uses link creation, datatype creation, and datatype access property lists. This syntax corresponds to the H5Tcommit interface in version 1.8 of the HDF5 C library.

 Details

Input Arguments

• locID — File or group identifier.

• name — Name of the datatype.

• typeID — Datatype identifier.

• lcplID — Link creation property list.

• tcplID — Datatype creation property list.

• taplID — Datatype access property list.

H5T.committed

Determine if datatype is committed

output = H5T.committed(typeID) returns a positive value if the datatype specified by typeID has been committed, and 0 if it has not.

H5T.copy

Copy datatype

newtypeID = H5T.copy(typeID) copies the existing datatype identifier, a dataset identifier specified by typeID, or a predefined datatype such as "H5T_NATIVE_DOUBLE".

H5T.create

Create new datatype

newtype = H5T.create(classID,typesize) creates a new datatype that belongs to the class specified by classID, with the number of bytes specified by typesize.

H5T.detect_class

Determine if datatype contains datatypes of specific class

output = H5T.detect_class(typeID,classID) returns a positive value if the datatype specified by typeID contains any datatypes of the datatype class classID, and 0 if it does not.

H5T.equal

Determine equality of datatypes

output = H5T.equal(type1ID,type2ID) returns a positive value if the datatype identifiers, type1ID and type2ID, refer to the same datatype, and 0 if they do not.

Specify type1ID and type2ID as string scalars or character vectors containing an HDF5 datatype.

H5T.get_class

Datatype class identifier

classID = H5T.get_class(typeID) returns the datatype class identifier of the datatype specified by typeID.

 Details

Output Arguments

classID — Datatype class identifier, returned as a numeric constant corresponding to one of these values:

• "H5T_INTEGER"

• "H5T_FLOAT"

• "H5T_STRING"

• "H5T_BITFIELD"

• "H5T_OPAQUE"

• "H5T_COMPOUND"

• "H5T_REFERENCE"

• "H5T_ENUM"

• "H5T_VLEN"

• "H5T_ARRAY"

H5T.get_create_plist

Copy of datatype creation property list

plistID = H5T.get_create_plist(typeID) returns a property list identifier for the datatype creation property list associated with the datatype specified by typeID.

H5T.get_native_type

Native datatype of specified datatype

nativetypeID = H5T.get_native_type(typeID,direction) returns the equivalent native datatype for the dataset datatype specified in typeID.

 Details

Specify the value of direction as one of these values:

• "H5T_DIR_ASCEND" — Search library in ascending order.

• "H5T_DIR_DESCEND" — Search library in descending order.

H5T.get_size

Size of datatype in bytes

typeSize = H5T.get_size(typeID) returns the size of the datatype specified by typeID in bytes.

H5T.get_super

Base datatype

superTypeID = H5T.get_super(typeID) returns the base datatype from which the datatype specified by typeID is derived.

H5T.lock

Lock datatype

H5T.lock(typeID) locks the datatype specified by typeID, making it read-only and non-destructible.

H5T.open

Open named datatype

typeID = H5T.open(locID,typename) opens a named datatype typename in the file or group specified by locID and returns a datatype identifier.

This function corresponds to the H5Topen1 function in the HDF5 library C API.

Array Datatype

H5T.array_create

Create array datatype object

arraytypeID = H5T.array_create(baseID,rank,dims,perms) creates a new array datatype object of rank rank and with dimensions dims. This syntax corresponds to the H5Tarray_create interface in version 1.6 of the HDF5 C library. The perms input argument is not used at this time and can be omitted.

arraytypeID = H5T.array_create(baseID,dims) creates a new array datatype object. This syntax corresponds to the H5Tarray_create interface in version 1.8 of the HDF5 C library.

 Details

Input Arguments

• baseID — Identifier of base datatype.

• dims — Dimensions of the new datatype.

• rank — Rank of the new datatype.

Output Arguments

• arraytypeID — Identifier of created array datatype.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The dims parameter assumes C-style ordering. For more information, see Report Data Set Dimensions.

H5T.get_array_dims

Sizes of array dimensions

dims = H5T.get_array_dims(typeID) returns the sizes of the dimensions and the dimension permutations of the array datatype specified by typeID. This syntax corresponds to the H5Tget_array_dims interface in version 1.8 of the HDF5 C library.

[ndims,dimsizes,perm] = H5T.get_array_dims(typeID) corresponds to the interface in version 1.6 of the HDF5 C library. It is strongly deprecated.

 Details

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The dims parameter assumes C-style ordering. For more information, see Report Data Set Dimensions.

H5T.get_array_ndims

Rank of array datatype

rank = H5T.get_array_ndims(typeID) returns the rank of an array datatype specified by typeID.

Atomic Datatype Properties

H5T.get_cset

Character set of string datatype

cset = H5T.get_cset(typeID) returns the character set type of the datatype specified by typeID.

H5T.get_ebias

Exponent bias of floating-point type

output = H5T.get_ebias(typeID) returns the exponent bias of a floating-point datatype specified by typeID.

H5T.get_fields

Floating-point datatype bit field information

[spos,epos,esize,mpos,msize] = H5T.get_fields(typeID) returns information about the locations of the various bit fields of a floating point datatype.

 Details

Output Arguments

• spos — Floating-point sign bit.

• epos — Exponent bit-position.

• esize — Size of the exponent in bits.

• mpos — Mantissa bit-position.

• msize — Size of the mantissa in bits.

H5T.get_inpad

Internal padding type for floating-point datatypes

padType = H5T.get_inpad(typeID) returns the internal padding type for unused bits in the floating-point datatype specified by typeID.

 Details

The H5T.get_inpad function returns padType as a numeric constant corresponding to one of these values:

• "H5T_PAD_ZERO"

• "H5T_PAD_ONE"

• "H5T_PAD_BACKGROUND"

H5T.get_norm

Mantissa normalization type

normType = H5T.get_norm(typeID) returns the mantissa normalization of a floating-point datatype specified by typeID.

 Details

The H5T.get_norm function returns normType as a numeric constant corresponding to one of these values:

• "H5T_NORM_IMPLIED"

• "H5T_NORM_MSBSET"

• "H5T_NORM_NONE"

H5T.get_offset

Bit offset of first significant bit

offset = H5T.get_offset(typeID) returns the offset of the first significant bit.

H5T.get_order

Byte order of atomic datatype

byteorder = H5T.get_order(typeID) returns the byte order of an atomic datatype specified by typeID.

 Details

The H5T.get_order function returns output as one of these values:

• "H5T_ORDER_LE"

• "H5T_ORDER_BE"

• "H5T_ORDER_VAX"

H5T.get_pad

Padding type of least and most-significant bits

[lsb,msb] = H5T.get_pad(typeID) returns the padding type of the least-significant bit padding type, lsb, and most-significant bit padding types, msb, of a datatype specified by typeID.

 Details

The H5T.get_pad function returns lsb and msb as numeric constants corresponding to these values:

• "H5T_PAD_ZERO"

• "H5T_PAD_ONE"

• "H5T_PAD_BACKGROUND"

H5T.get_precision

Precision of atomic datatype

precision = H5T.get_precision(typeID) returns the precision of an atomic datatype specified by typeID.

H5T.get_sign

Sign type for integer datatype

signtype = H5T.get_sign(typeID) returns the sign type for an integer type specified by typeID.

 Details

The H5T.get_sign function returns signtype as a numeric constant corresponding to these values:

• "H5T_SGN_NONE"

• "H5T_SGN_2"

H5T.get_strpad

Storage mechanism for string datatype

padtype = H5T.get_strpad(typeID) returns the storage mechanism (padding type) for a string datatype.

 Details

The H5T.get_strpad function returns signType as numeric constant corresponding to one of these values:

• "H5T_STR_NULLPAD" — Pad with zeros.

• "H5T_STR_NULLTERM" — Null-terminate.

• "H5T_STR_SPACEPAD" — Pad with spaces.

H5T.set_cset

Set character dataset for string datatype

H5T.set_cset(typeID,cset) sets the character encoding used to create strings. Specify cset as "H5T_CSET_ASCII", "H5T_CSET_UTF8"or their equivalent numerical values.

H5T.set_ebias

Set exponent bias of floating-point datatype

H5T.set_ebias(typeID,ebias) sets the exponent bias ebias of a floating-point datatype specified by typeID.

H5T.set_fields

Set sizes and locations of floating-point bit fields

H5T.set_fields(typeID,spos,epos,esize,mpos,msize) sets the locations and sizes of the various floating-point bit fields.

 Details

Input Arguments

• typeID — Floating-point datatype identifier.

• spos — Floating-point sign bit.

• epos — Exponent bit-position.

• esize — Size of the exponent in bits.

• mpos — Mantissa bit-position.

• msize — Size of the mantissa in bits.

H5T.set_inpad

Specify how unused internal bits are to be filled

H5T.set_inpad(typeID,padType) sets how unused internal bits of a floating point type are filled for the datatype specified by typeID.

 Details

Specify padType as one of these values:

• "H5T_PAD_ZERO" — Pad with the value 0.

• "H5T_PAD_ONE" — Pad with the value 1.

• "H5T_PAD_BACKGROUND" — Does not pad background.

H5T.set_norm

Set mantissa normalization of floating-point datatype

H5T.set_norm(typeID,norm) sets the mantissa normalization of a floating-point datatype specified by typeID.

 Details

Specify norm as one of these values:

• "H5T_NORM_IMPLIED"

• "H5T_NORM_MSBSET"

• "H5T_NORM_NONE"

H5T.set_offset

Set bit offset of first significant bit

H5T.set_offset(typeID,offset) sets the bit offset of the first significant bit. typeID is the identifier of the datatype. offset specifies the number of bits of padding that appear.

H5T.set_order

Set byte ordering of atomic datatype

H5T.set_order(typeID,order) sets the byte ordering of an atomic datatype specified by typeID.

 Details

Specify order as one of these values:

• "H5T_ORDER_LE"

• "H5T_ORDER_BE"

• "H5T_ORDER_VAX"

H5T.set_pad

Set padding type for least and most significant bits

H5T.set_pad(typeID,lsb,msb) sets the padding type of the least-significant bit padding type, lsb, and most-significant bit padding type, msb, of a datatype specified by typeID.

 Details

Specify lsb and msb as any of these values:

• "H5T_PAD_ZERO"

• "H5T_PAD_ONE"

• "H5T_PAD_BACKGROUND"

H5T.set_precision

Set precision of atomic datatype

H5T.set_precision(typeID,prec) sets the number of bits of precision, prec, of an atomic datatype specified by typeID.

H5T.set_sign

Set sign property for integer datatype

H5T.set_sign(typeID,sign) sets the sign property for an integer type specified as typeID. Specify sign as either "H5T_SGN_NONE" or "H5T_SGN_2".

H5T.set_size

Set size of datatype in bytes

H5T.set_size(typeID,typeSize) sets the total size in bytes for the datatype specified by typeID. If a variable-length string is desired then typesize can be specified as "H5T_VARIABLE".

H5T.set_strpad

Set storage mechanism for string datatype

H5T.set_strpad(typeID,storage) defines the storage mechanism for the string datatype specified by typeID.

 Details

Specify storage as one of these values:

• "H5T_STR_NULLTERM" — Null terminated.

• "H5T_STR_NULLPAD" — Padded with zeros.

• "H5T_STR_SPACEPAD" — Padded with spaces.

Compound Datatype

H5T.get_member_class

Datatype class for compound datatype member

memclass = H5T.get_member_class(typeID,membno) returns the datatype class of the compound datatype member specified by membno. ThetypeID argument is the datatype identifier of a compound object.

H5T.get_member_index

Index of compound or enumeration type member

idx = H5T.get_member_index(typeID,name) returns the index of a field belonging to a compound datatype or an element of an enumeration datatype, specified by name and typeID.

H5T.get_member_name

Name of compound or enumeration type member

name = H5T.get_member_name(typeID,membno) returns the name of a field belonging to a compound datatype or an element of an enumeration datatype specified by typeID. Specify membno as a zero-based index of the field, or as the name of an element.

H5T.get_member_offset

Offset of field of compound datatype

offset = H5T.get_member_offset(typeID,membno) returns the byte offset of the field specified by membno in the compound datatype specified by typeID. The value 0 is a valid offset.

H5T.get_member_type

Datatype of specified member

typeID = H5T.get_member_type(typeID,membno) returns the datatype of the member specified by membno in the datatype specified by typeID.

H5T.get_nmembers

Number of elements in compound or enumeration datatype

membs = H5T.get_nmembers(typeID) returns the number of fields in a compound datatype or the number of members belonging to an enumeration datatype, specified by typeID.

H5T.insert

Add member to compound datatype

H5T.insert(typeID,name,offset,membID) adds another member to the compound datatype specified by typeID.

 Details

Input Arguments

• typeID — Compound datatype identifier.

• name — String scalar or character vector specifying the name of new member, which must be unique in the compound datatype.

• offset — Offset specifying where to insert the new member in the compound datatype.

• membID — Datatype identifier of the new member.

H5T.pack

Recursively remove padding from compound datatype

H5T.pack(typeID) recursively removes padding from within a compound datatype specified by typeID to make it more efficient (space-wise) to store that data.

Enumeration Datatype

H5T.enum_create

Create new enumeration datatype

typeID = H5T.enum_create(parentID) creates a new enumeration datatype based on the base datatype parentID. typeID is a datatype identifier for the new enumeration datatype.

H5T.enum_insert

Insert enumeration datatype member

H5T.enum_insert(typeID,name,value) inserts a new enumeration datatype member into the enumeration datatype specified by typeID. The name argument is a string scalar or character vector that specifies the name of the new member of the enumeration, and value is the value of the member.

H5T.enum_nameof

Name of enumeration datatype member

name = H5T.enum_nameof(typeID,membno) returns the symbol name corresponding to a member of an enumeration datatype specified by typeID.

H5T.enum_valueof

Value of enumeration datatype member

value = H5T.enum_valueof(typeID,membname) returns the value corresponding to the name of a specified member of an enumeration datatype specified by typeID.

H5T.get_member_value

Value of enumeration datatype member

value = H5T.get_member_value(typeID,membno) returns the value of the member specified by membno that belongs to enumeration datatype specified by typeID.

Opaque Datatype Properties

H5T.get_tag

Tag associated with opaque datatype

tag = H5T.get_tag(typeID) returns the tag associated with the opaque datatype specified by typeID.

H5T.set_tag

Tag opaque datatype with description

H5T.set_tag(typeID,tag) tags the opaque datatype specified by typeID with the descriptive text tag. Specify tag as a string scalar or character vector.

Variable-length Datatype

H5T.is_variable_str

Determine if datatype is variable-length string

output = H5T.is_variable_str(typeID) returns a positive value if the datatype specified by typeID is a variable-length string, and 0 if it is not.

H5T.vlen_create

Create new variable-length datatype

vlentypeID = H5T.vlen_create(baseID) creates a new variable-length datatype. baseID specifies the base type of the datatype to create.

 Details

Limitations

• You can create variable-length datatypes only if the base datatype class is one of these:

  • "H5T_INTEGER"

  • "H5T_FLOAT"

  • "H5T_STRING" with variable-length or a fixed length of 1.

Metadata Cache Fine-Tuning Properties

H5T.flush

Flush all data buffers to disk

H5T.flush(typeID) causes all the buffers associated with a committed datatype to be flushed to disk without removing the data from the cache.

H5T.refresh

Clear and reload all data buffers

H5T.refresh(typeID) causes all the buffers associated with a committed datatype to be cleared and immediately re-loaded with updated contents from disk. This function closes the committed datatype, evicts all metadata associated with it from the cache, and then reopens the datatype with the same identifier.

Examples

Query Information About Compound Datatype in Dataset

Open a dataset, copy its datatype, then query information about it.

Ope the HDF5 file example.h5 and the dataset "/g3/compound".

fid = H5F.open("example.h5");
dsID = H5D.open(fid,"/g3/compound");

Create a copy of the datatype.

typeID = H5D.get_type(dsID);

Get the name and index of the compound member.

memberName = H5T.get_member_name(typeID,0);
idx = H5T.get_member_index(typeID,"b");

Get the datatype class for compound datatype member.

memberClass = H5T.get_member_class(typeID,0);

Get the offset of a field of the compound datatype.

offset = H5T.get_member_offset(typeID,1);

Get the datatype of the specified member.

memberTypeID = H5T.get_member_type(typeID,0);

Get the number of fields in a compound dataset, then close the resources.

nmembers = H5T.get_nmembers(typeID);
H5T.close(memberTypeID);
H5T.close(typeID);
H5D.close(dsID);
H5F.close(fid);

Set Properties of Array Datatype

Open a dataset with an array datatype, create a copy of its datatype, then set the properties of the copy.

Copy the datatype and create an array datatype object.

baseTypeID = H5T.copy("H5T_NATIVE_DOUBLE");
dims = [100 200];
h5_dims = fliplr(dims);
arrayTypeID = H5T.array_create(baseTypeID,h5_dims);
typeID = H5T.copy(baseTypeID);

Set the size of the datatype in bytes and query the size.

H5T.set_size(typeID, 16);
typeSize = H5T.get_size(typeID);

Set the bit offset of the first significant bit, then query the offset.

H5T.set_offset(typeID,8);
offset = H5T.get_offset(typeID);

Set the padding type for the least and most significant bits.

lsb = H5ML.get_constant_value("H5T_PAD_ONE");
msb = H5ML.get_constant_value("H5T_PAD_ZERO");
H5T.set_pad(typeID,lsb,msb);

Retrieve the padding.

[lsb_ret,msb_ret] = H5T.get_pad(typeID);
 switch(lsb_ret)
     case H5ML.get_constant_value("H5T_PAD_ZERO")
         fprintf("lsb pad type is zeros\n");
     case H5ML.get_constant_value("H5T_PAD_ONE");
         fprintf("lsb pad type is ones\n");
     case H5ML.get_constant_value("H5T_PAD_BACKGROUND")
         fprintf("lsb pad type is background\n");
 end
 switch(msb_ret)
     case H5ML.get_constant_value("H5T_PAD_ZERO")
         fprintf("msb pad type is zeros\n");
     case H5ML.get_constant_value("H5T_PAD_ONE");
         fprintf("msb pad type is ones\n");
     case H5ML.get_constant_value("H5T_PAD_BACKGROUND")
         fprintf("msb pad type is background\n");
 end

Close resources.

H5T.close(typeID);
H5T.close(baseTypeID);

Create Compound Datatype and Add Members

Create a compound datatype, then add members to it.

Create a new compound datatype.

typeID = H5T.create("H5T_COMPOUND",16);

Add members to the compound datatype.

H5T.insert(typeID,"first",0,"H5T_NATIVE_DOUBLE");
H5T.insert(typeID,"second",8,"H5T_NATIVE_INT");
H5T.insert(typeID,"third",12,"H5T_NATIVE_UINT");

Lock the datatype. If you try to add a new member to the datatype after it is locked, the operation will fail.

H5T.lock(typeID)
H5T.insert(typeID,"fourth",12,"H5T_NATIVE_UINT"); % This should fail.

Close resources.

H5T.close(typeID);

Determine Whether Two Datatypes Are Equal

Determine whether two datatypes are equal.

Open the dataset "/g3/integer2D" and get its datatype.

fid = H5F.open("example.h5");
dsID = H5D.open(fid,"/g3/integer2D");
dtypeID = H5D.get_type(dsID);

Check if the datatype of dtypeID is equal to the HDF5 datatype "H5T_STD_I32LE". Then, close the datatype, dataset, and HDF5 file.

if H5T.equal(dtypeID,"H5T_STD_I32LE")
    fprintf("32-bit little endian integer\n");
end
H5T.close(dtypeID);
H5D.close(dsID);
H5F.close(fid);

Version History

Introduced before R2006a

R2021b: Flush and refresh buffers associated with a committed datatype

You can use H5T.flush to flush the buffers associated with a committed datatype to disk and H5T.refresh to clear the buffer associated with a committed datatype and reload with updated contents from disk.