Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.15.0.f39b228
API Reference
Atomic Datatypes

Detailed Description

+ Collaboration diagram for Atomic Datatypes:

Functions

H5T_order_t H5Tget_order (hid_t type_id)
 Returns the byte order of an atomic datatype. More...
 
size_t H5Tget_precision (hid_t type_id)
 Returns the precision of an atomic datatype. More...
 
int H5Tget_offset (hid_t type_id)
 Retrieves the bit offset of the first significant bit. More...
 
herr_t H5Tget_pad (hid_t type_id, H5T_pad_t *lsb, H5T_pad_t *msb)
 Retrieves the padding type of the least and most-significant bit padding. More...
 
H5T_sign_t H5Tget_sign (hid_t type_id)
 Retrieves the sign type for an integer type. More...
 
herr_t H5Tget_fields (hid_t type_id, size_t *spos, size_t *epos, size_t *esize, size_t *mpos, size_t *msize)
 Retrieves floating point datatype bit field information. More...
 
size_t H5Tget_ebias (hid_t type_id)
 Retrieves the exponent bias of a floating-point type. More...
 
H5T_norm_t H5Tget_norm (hid_t type_id)
 Retrieves mantissa normalization of a floating-point datatype. More...
 
H5T_pad_t H5Tget_inpad (hid_t type_id)
 Retrieves the internal padding type for unused bits in floating-point datatypes. More...
 
H5T_str_t H5Tget_strpad (hid_t type_id)
 Retrieves the type of padding used for a string datatype. More...
 
H5T_cset_t H5Tget_cset (hid_t type_id)
 Retrieves the character set type of a string datatype. More...
 
htri_t H5Tis_variable_str (hid_t type_id)
 Determines whether datatype is a variable-length string. More...
 
herr_t H5Tset_order (hid_t type_id, H5T_order_t order)
 Sets the byte order of a datatype. More...
 
herr_t H5Tset_precision (hid_t type_id, size_t prec)
 Sets the precision of an atomic datatype. More...
 
herr_t H5Tset_offset (hid_t type_id, size_t offset)
 Sets the bit offset of the first significant bit. More...
 
herr_t H5Tset_pad (hid_t type_id, H5T_pad_t lsb, H5T_pad_t msb)
 Sets the least and most-significant bits padding types. More...
 
herr_t H5Tset_sign (hid_t type_id, H5T_sign_t sign)
 Sets the sign property for an integer type. More...
 
herr_t H5Tset_fields (hid_t type_id, size_t spos, size_t epos, size_t esize, size_t mpos, size_t msize)
 Sets locations and sizes of floating point bit fields. More...
 
herr_t H5Tset_ebias (hid_t type_id, size_t ebias)
 Sets the exponent bias of a floating-point type. More...
 
herr_t H5Tset_norm (hid_t type_id, H5T_norm_t norm)
 Sets the mantissa normalization of a floating-point datatype. More...
 
herr_t H5Tset_inpad (hid_t type_id, H5T_pad_t pad)
 Fills unused internal floating-point bits. More...
 
herr_t H5Tset_cset (hid_t type_id, H5T_cset_t cset)
 Sets character set to be used in a string or character datatype. More...
 
herr_t H5Tset_strpad (hid_t type_id, H5T_str_t strpad)
 Defines the type of padding used for character strings. More...
 

Function Documentation

◆ H5Tget_cset()

H5T_cset_t H5Tget_cset ( hid_t  type_id)

Retrieves the character set type of a string datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns a valid character set type if successful; otherwise H5T_CSET_ERROR (-1).

H5Tget_cset() retrieves the character set type of a string datatype. Valid character set types are:

H5T_CSET_ASCIIUS ASCII
H5T_CSET_UTF8UTF-8 Unicode encoding
Since
1.2.0

◆ H5Tget_ebias()

size_t H5Tget_ebias ( hid_t  type_id)

Retrieves the exponent bias of a floating-point type.

Parameters
[in]type_idDatatype identifier
Returns
Returns the bias if successful and 0, otherwise.

H5Tget_ebias() retrieves the exponent bias of a floating-point type.

Since
1.2.0

◆ H5Tget_fields()

herr_t H5Tget_fields ( hid_t  type_id,
size_t *  spos,
size_t *  epos,
size_t *  esize,
size_t *  mpos,
size_t *  msize 
)

Retrieves floating point datatype bit field information.

Parameters
[in]type_idDatatype identifier
[out]sposPointer to location to return floating-point sign bit
[out]eposPointer to location to return exponent bit-position
[out]esizePointer to location to return size of exponent in bits
[out]mposPointer to location to return mantissa bit-position
[out]msizePointer to location to return size of mantissa in bits
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tget_fields() retrieves information about the locations of the various bit fields of a floating point datatype. The field positions are bit positions in the significant region of the datatype. Bits are numbered with the least significant bit number zero. Any (or even all) of the arguments can be null pointers.

Since
1.2.0

◆ H5Tget_inpad()

H5T_pad_t H5Tget_inpad ( hid_t  type_id)

Retrieves the internal padding type for unused bits in floating-point datatypes.

Parameters
[in]type_idDatatype identifier
Returns
Returns a valid padding type if successful; otherwise returns H5T_PAD_ERROR (-1).

H5Tget_inpad() retrieves the internal padding type for unused bits in floating-point datatypes. Valid padding types are:

typedef enum H5T_pad_t {
H5T_NPAD = 3
H5T_pad_t
Definition: H5Tpublic.h:143
@ H5T_PAD_ONE
Definition: H5Tpublic.h:146
@ H5T_NPAD
Definition: H5Tpublic.h:149
@ H5T_PAD_ERROR
Definition: H5Tpublic.h:144
@ H5T_PAD_BACKGROUND
Definition: H5Tpublic.h:147
@ H5T_PAD_ZERO
Definition: H5Tpublic.h:145
Since
1.2.0

◆ H5Tget_norm()

H5T_norm_t H5Tget_norm ( hid_t  type_id)

Retrieves mantissa normalization of a floating-point datatype.


Parameters
[in]type_idDatatype identifier
Returns
Returns a valid normalization type if successful; otherwise returns H5T_NORM_ERROR (-1)

H5Tget_norm() retrieves the mantissa normalization of a floating-point datatype. Valid normalization types are:

typedef enum H5T_norm_t {
/*H5T_NORM_NONE must be last */
H5T_norm_t
Definition: H5Tpublic.h:80
@ H5T_NORM_IMPLIED
Definition: H5Tpublic.h:82
@ H5T_NORM_ERROR
Definition: H5Tpublic.h:81
@ H5T_NORM_MSBSET
Definition: H5Tpublic.h:83
@ H5T_NORM_NONE
Definition: H5Tpublic.h:84
Since
1.2.0

◆ H5Tget_offset()

int H5Tget_offset ( hid_t  type_id)

Retrieves the bit offset of the first significant bit.

Parameters
[in]type_idDatatype identifier
Returns
Returns an offset value if successful; otherwise returns a negative value.

H5Tget_offset() retrieves the bit offset of the first significant bit. The significant bits of an atomic datum can be offset from the beginning of the memory for that datum by an amount of padding. The 'offset' property specifies the number of bits of padding that appear to the "right of" the value. That is, if we have a 32-bit datum with 16-bits of precision having the value 0x1122 then it will be laid out in memory as (from small byte address toward larger byte addresses):

0: [ pad] [0x11] [0x22] [ pad]
1: [ pad] [0x22] [0x11] [ pad]
2: [0x11] [ pad] [ pad] [0x22]
3: [0x22] [ pad] [ pad] [0x11]
Since
1.2.0

◆ H5Tget_order()

H5T_order_t H5Tget_order ( hid_t  type_id)

Returns the byte order of an atomic datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns a byte order constant if successful; otherwise returns H5T_ORDER_ERROR (-1)

H5Tget_order() returns the byte order of an atomic datatype. Possible return values are:

typedef enum H5T_order_t {
/*H5T_ORDER_NONE must be last */
H5T_order_t
Definition: H5Tpublic.h:52
@ H5T_ORDER_NONE
Definition: H5Tpublic.h:58
@ H5T_ORDER_MIXED
Definition: H5Tpublic.h:57
@ H5T_ORDER_ERROR
Definition: H5Tpublic.h:53
@ H5T_ORDER_BE
Definition: H5Tpublic.h:55
@ H5T_ORDER_LE
Definition: H5Tpublic.h:54
@ H5T_ORDER_VAX
Definition: H5Tpublic.h:56

Members of a compound datatype need not have the same byte order. If members of a compound datatype have more than one of little endian, big endian, or VAX byte order, H5Tget_order() will return H5T_ORDER_MIXED for the compound datatype. A byte order of H5T_ORDER_NONE will, however, be ignored; for example, if one or more members of a compound datatype have byte order H5T_ORDER_NONE but all other members have byte order H5T_ORDER_LE, H5Tget_order() will return H5T_ORDER_LE for the compound datatype.

Since
1.2.0

◆ H5Tget_pad()

herr_t H5Tget_pad ( hid_t  type_id,
H5T_pad_t lsb,
H5T_pad_t msb 
)

Retrieves the padding type of the least and most-significant bit padding.

Parameters
[in]type_idDatatype identifier
[out]lsbBuffer for the least-significant bit padding type
[out]msbBuffer for the most-significant bit padding type
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tget_pad() retrieves the padding type of the least and most-significant bit padding. Valid padding types are:

Since
1.2.0

◆ H5Tget_precision()

size_t H5Tget_precision ( hid_t  type_id)

Returns the precision of an atomic datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns the number of significant bits if successful; otherwise 0

H5Tget_precision() returns the precision of an atomic datatype (for example, integer or float) or a datatype whose base (parent) type is an atomic type (for example, array, enum and variable length). The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size().

Since
1.2.0

◆ H5Tget_sign()

H5T_sign_t H5Tget_sign ( hid_t  type_id)

Retrieves the sign type for an integer type.

Parameters
[in]type_idDatatype identifier
Returns
Returns a valid sign type if successful; otherwise H5T_SGN_ERROR (-1)

H5Tget_sign() retrieves the sign type for an integer type. Valid types are:

typedef enum H5T_sign_t {
H5T_SGN_2 = 1,
H5T_NSGN = 2
H5T_sign_t
Definition: H5Tpublic.h:67
@ H5T_SGN_2
Definition: H5Tpublic.h:70
@ H5T_NSGN
Definition: H5Tpublic.h:72
@ H5T_SGN_ERROR
Definition: H5Tpublic.h:68
@ H5T_SGN_NONE
Definition: H5Tpublic.h:69
Since
1.2.0

◆ H5Tget_strpad()

H5T_str_t H5Tget_strpad ( hid_t  type_id)

Retrieves the type of padding used for a string datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns a valid string of the padding if successful; otherwise returns H5T_STR_ERROR (-1)

H5Tget_strpad() retrieves the type of padding used for a string datatype.

The string padding type is set with H5Tset_strpad(). Possible values returned are:

H5T_STR_NULLTERM0Null terminate (as C does)
H5T_STR_NULLPAD1Pad with zeros
H5T_STR_SPACEPAD2Pad with spaces (as FORTRAN does)
Since
1.2.0

◆ H5Tis_variable_str()

htri_t H5Tis_variable_str ( hid_t  type_id)

Determines whether datatype is a variable-length string.

Parameters
[in]type_idDatatype identifier
Returns
Returns:
  • a positive value if the specified datatype is a variable-length string
  • 0 if the specified datatype is not a variable-length string
  • a negative value when the function fails
H5Tis_variable_str() determines whether the datatype identified by dtype_id is a variable-length string.

This function can be used to distinguish between fixed and variable-length string datatypes.

Since
1.6.0

◆ H5Tset_cset()

herr_t H5Tset_cset ( hid_t  type_id,
H5T_cset_t  cset 
)

Sets character set to be used in a string or character datatype.

Parameters
[in]type_idDatatype identifier
[in]csetCharacter set type
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_cset() sets the character set to be used in a dataset with a string or character datatype.

Valid values for cset include the following:

H5T_CSET_ASCIIUS ASCII
H5T_CSET_UTF8UTF-8 Unicode encoding

For example, if the character set for the datatype type_id is set to H5T_CSET_UTF8, string or character data of datatype dtype_id will be encoded using the UTF-8 Unicode character set.

ASCII and UTF-8 Unicode are the only currently supported character encodings. Extended ASCII encodings (for example, ISO 8859) are not supported. This encoding policy is not enforced by the HDF5 library. Using encodings other than ASCII and UTF-8 can lead to compatibility and usability problems.

Note that H5Tset_cset() sets the character set for a character or string datatype while H5Pset_char_encoding() sets the character set used for an HDF5 link or attribute name.

Since
1.2.0

◆ H5Tset_ebias()

herr_t H5Tset_ebias ( hid_t  type_id,
size_t  ebias 
)

Sets the exponent bias of a floating-point type.

Parameters
[in]type_idDatatype identifier
[in]ebiasExponent bias value
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_ebias() sets the exponent bias of a floating-point type.

Since
1.2.0

◆ H5Tset_fields()

herr_t H5Tset_fields ( hid_t  type_id,
size_t  spos,
size_t  epos,
size_t  esize,
size_t  mpos,
size_t  msize 
)

Sets locations and sizes of floating point bit fields.

Parameters
[in]type_idDatatype identifier
[in]sposSign position, i.e., the bit offset of the floating-point sign bit
[in]eposExponent bit position
[in]esizeSize of exponent in bits
[in]mposMantissa bit position
[in]msizeSize of mantissa in bits
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_fields() sets the locations and sizes of the various floating-point bit fields. The field positions are bit positions in the significant region of the datatype. Bits are numbered with the least significant bit number zero.

Fields are not allowed to extend beyond the number of bits of precision, nor are they allowed to overlap with one another.

Since
1.2.0

◆ H5Tset_inpad()

herr_t H5Tset_inpad ( hid_t  type_id,
H5T_pad_t  pad 
)

Fills unused internal floating-point bits.

Parameters
[in]type_idDatatype identifier
[in]padPadding type
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_inpad() If any internal bits of a floating point-type are unused (that is, those significant bits which are not part of the sign, exponent, or mantissa), then H5Tset_inpad() will be filled according to the value of the padding value property inpad. Valid padding types are:

Since
1.2.0

◆ H5Tset_norm()

herr_t H5Tset_norm ( hid_t  type_id,
H5T_norm_t  norm 
)

Sets the mantissa normalization of a floating-point datatype.

Parameters
[in]type_idDatatype identifier
[in]normMantissa normalization type
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_norm() sets the mantissa normalization of a floating-point datatype. Valid normalization types are:

typedef enum H5T_norm_t {
/*H5T_NORM_NONE must be last */
Since
1.2.0

◆ H5Tset_offset()

herr_t H5Tset_offset ( hid_t  type_id,
size_t  offset 
)

Sets the bit offset of the first significant bit.

Parameters
[in]type_idDatatype identifier
[in]offsetOffset of first significant bit
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_offset() sets the bit offset of the first significant bit. The significant bits of an atomic datum can be offset from the beginning of the memory for that datum by an amount of padding. The offset property specifies the number of bits of padding that appear “to the right of” the value. That is, if we have a 32-bit datum with 16-bits of precision having the value 0x1122, then it will be laid out in memory as (from small byte address toward larger byte addresses):

0: [ pad] [0x11] [0x22] [ pad]
1: [ pad] [0x22] [0x11] [ pad]
2: [0x11] [ pad] [ pad] [0x22]
3: [0x22] [ pad] [ pad] [0x11]

If the offset is incremented then the total size is incremented also if necessary to prevent significant bits of the value from hanging over the edge of the datatype.

The offset of an H5T_STRING cannot be set to anything but zero.

Since
1.2.0

◆ H5Tset_order()

herr_t H5Tset_order ( hid_t  type_id,
H5T_order_t  order 
)

Sets the byte order of a datatype.

Parameters
[in]type_idDatatype identifier
[in]orderByte order constant
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_order() sets the byte order of a datatype.
Byte order can currently be set to any of the following:

typedef enum H5T_order_t {
/*H5T_ORDER_NONE must be last */

H5T_ORDER_MIXED (3) is a valid value for order only when returned by the function H5Tget_order(); it cannot be set with H5Tset_order().

H5T_ORDER_NONE (4) is a valid value for order, but it has no effect. It is valid only for fixed-length strings and object and region references and specifies “no particular order.”

The byte order of a derived datatype is initially the same as that of the parent type, but can be changed with H5Tset_order().

This function cannot be used with a datatype after it has been committed.

Note
Special considerations:
  • ENUM datatypes: Byte order must be set before any member on an ENUM is defined.
  • Compound datatypes: Byte order is set individually on each member of a compound datatype; members of a compound datatype need not have the same byte order.
  • Opaque datatypes: Byte order can be set but has no effect.
Since
1.2.0

◆ H5Tset_pad()

herr_t H5Tset_pad ( hid_t  type_id,
H5T_pad_t  lsb,
H5T_pad_t  msb 
)

Sets the least and most-significant bits padding types.

Parameters
[in]type_idDatatype identifier
[in]lsbPadding type for least-significant bits
[in]msbPadding type for most-significant bits
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_pad() sets the least and most-significant bits padding types. Available values are:

H5T_PAD_ZERO0Set background to zeros
H5T_PAD_ONE1Set background to ones
H5T_PAD_BACKGROUND2Leave background alone
Since
1.2.0

◆ H5Tset_precision()

herr_t H5Tset_precision ( hid_t  type_id,
size_t  prec 
)

Sets the precision of an atomic datatype.

Parameters
[in]type_idDatatype identifier
[in]precNumber of bits of precision for datatype
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_precision() sets the precision of an atomic datatype. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size().

If the precision is increased then the offset is decreased and then the size is increased to insure that significant bits do not "hang over" the edge of the datatype.

Changing the precision of an H5T_STRING automatically changes the size as well. The precision must be a multiple of 8.

When decreasing the precision of a floating point type, set the locations and sizes of the sign, mantissa, and exponent fields first.

Since
1.2.0

◆ H5Tset_sign()

herr_t H5Tset_sign ( hid_t  type_id,
H5T_sign_t  sign 
)

Sets the sign property for an integer type.

Parameters
[in]type_idDatatype identifier
[in]signSign type
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_sign() sets the sign property for an integer type:

H5T_SGN_NONE0Unsigned integer type
H5T_SGN_21Two's complement signed integer type
Since
1.2.0

◆ H5Tset_strpad()

herr_t H5Tset_strpad ( hid_t  type_id,
H5T_str_t  strpad 
)

Defines the type of padding used for character strings.

Parameters
[in]type_idDatatype identifier
[in]strpadString padding type
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Tset_strpad() defines the type of padding used for a string datatype.

The method used to store character strings differs with the programming language. C usually null terminates strings while Fortran left-justifies and space-pads strings.

Valid values of strpad are as follows:

H5T_STR_NULLTERM0Null terminate (as C does)
H5T_STR_NULLPAD1Pad with zeros
H5T_STR_SPACEPAD2Pad with spaces (as FORTRAN does)

When converting from a longer string to a shorter string, the behavior is as follows. If the shorter string is H5T_STR_NULLPAD or H5T_STR_SPACEPAD, then the string is simply truncated. If the short string is H5T_STR_NULLTERM, it is truncated and a null terminator is appended.

When converting from a shorter string to a longer string, the longer string is padded on the end by appending nulls or spaces.

Since
1.2.0