Main Content

Datatype (H5T)

Datatype of elements in a dataset

Description

Use the MATLAB® HDF5 datatype interface, H5T,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 date-times, enumerations, strings, bit strings, and references (pointers to objects in the HDF5 file). 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

H5T.committed

Determine if datatype is committed

tf = H5T.committed(typeID) returns a positive value to indicate that the datatype has been committed, and zero to indicate that it has not. A negative value indicates failure.

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

tf = 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. A negative value indicates an error.

H5T.equal

Determine equality of datatypes

tf = H5T.equal(type1ID,type2ID) returns a positive value if the datatype identifiers, type1ID and type2ID, refer to the same datatype, and 0 if they are not. A negative value indicates an error.

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

H5T.get_class

Return datatype class identifier

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

 Details

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

H5T.get_size

Size of datatype in bytes

typeSize = H5T.get_size(typeID) returns the size of the datatype specified bytypeID 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,dims) creates a new array datatype object. This syntax corresponds to the H5Tarray_create interface in version 1.8 of the HDF5 C library.

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 parameter is not used at this time and can be omitted.

 Details

H5T.get_array_dims

Return 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(type_id) corresponds to the interface in version 1.6 of the HDF5 C library. It is strongly deprecated.

 Details

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

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

H5T.get_norm

Mantissa normalization type

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

 Details

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

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

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.

The H5T.get_sign function returns signType as numeric constants corresponding to either 'H5T_SGN_NONE' or '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

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' or its equivalent numerical value.

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

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

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

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

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

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

Compound Datatype

H5T.get_member_class

Datatype class for compound datatype member

memclass = H5T.get_member_class(typeID,memb) returns the datatype class of the compound datatype member specified by memb. 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,memb) returns the name of a field belonging to a compound datatype or an element of an enumeration datatype specified by typeID. Specify memb 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,memb) returns the byte offset of the field specified by memb 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,memb) returns the datatype of the member specified by memb 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

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 character vector or string scalar 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,memb) 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,membnum) returns the value of the member specified by membnum 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 character vector or string scalar.

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. A negative value indicates an error.

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

Metadata Cache Fine-Tuning Properties

H5T.flush

Flush all data buffers to disk (since R2021b)

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 (since R2021b)

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

expand all

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');
dset_id = H5D.open(fid,'/g3/compound');

Create a copy of the datatype.

type_id = H5D.get_type(dset_id);

Get the name and index of the compound member.

member_name = H5T.get_member_name(type_id,0);
idx = H5T.get_member_index(type_id,'b');

Get the datatype class for compound datatype member.

member_class = H5T.get_member_class(type_id,0);

Get the offset of a field of the compound datatype.

offset = H5T.get_member_offset(type_id,1);

Get the datatype of the specified member.

member_type_id = H5T.get_member_type(type_id,0);

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

nmembers = H5T.get_nmembers(type_id);
H5F.close(fid);

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.

base_type_id = H5T.copy('H5T_NATIVE_DOUBLE');
dims = [100 200];
h5_dims = fliplr(dims);
array_type = H5T.array_create(base_type_id,h5_dims);
type_id = H5T.copy(base_type_id);

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

H5T.set_size(type_id, 16);
type_size = H5T.get_size(type_id);

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

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

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(type_id,lsb,msb);

Retrieve the padding.

[lsb_ret,msb_ret] = H5T.get_pad(type_id);
 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

Create a compound datatype, then add members to it.

Create a new compound datatype.

type_id = H5T.create('H5T_COMPOUND',16);

Add members to the compound datatype.

H5T.insert(type_id,'first',0,'H5T_NATIVE_DOUBLE');
H5T.insert(type_id,'second',8,'H5T_NATIVE_INT');
H5T.insert(type_id,'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(type_id)
H5T.insert(type_id,'fourth',12,'H5T_NATIVE_UINT'); % This should fail.

Determine whether two datatypes are equal.

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

fid = H5F.open('example.h5');
dset_id = H5D.open(fid,'/g3/integer2D');
dtype_id = H5D.get_type(dset_id);

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

if H5T.equal(dtype_id,'H5T_STD_I32LE')
    fprintf('32-bit little endian integer\n');
end
H5T.close(dtype_id);
H5D.close(dset_id);
H5F.close(fid);
Introduced before R2006a