HDF5  1.13.0
Atomic Datatypes

Functions

H5_DLL H5T_cset_t H5Tget_cset (hid_t type_id)
 Retrieves the character set type of a string datatype. More...
 
H5_DLL size_t H5Tget_ebias (hid_t type_id)
 Retrieves the exponent bias of a floating-point type. More...
 
H5_DLL 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...
 
H5_DLL H5T_pad_t H5Tget_inpad (hid_t type_id)
 Retrieves the internal padding type for unused bits in floating-point datatypes. More...
 
H5_DLL H5T_norm_t H5Tget_norm (hid_t type_id)
 Retrieves mantissa normalization of a floating-point datatype. More...
 
H5_DLL int H5Tget_offset (hid_t type_id)
 Retrieves the bit offset of the first significant bit. More...
 
H5_DLL H5T_order_t H5Tget_order (hid_t type_id)
 Returns the byte order of an atomic datatype. More...
 
H5_DLL 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...
 
H5_DLL size_t H5Tget_precision (hid_t type_id)
 Returns the precision of an atomic datatype. More...
 
H5_DLL H5T_sign_t H5Tget_sign (hid_t type_id)
 Retrieves the sign type for an integer type. More...
 
H5_DLL H5T_str_t H5Tget_strpad (hid_t type_id)
 Retrieves the type of padding used for a string datatype. More...
 
H5_DLL htri_t H5Tis_variable_str (hid_t type_id)
 Determines whether datatype is a variable-length string. More...
 
H5_DLL 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...
 
H5_DLL herr_t H5Tset_ebias (hid_t type_id, size_t ebias)
 Sets the exponent bias of a floating-point type. More...
 
H5_DLL 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...
 
H5_DLL herr_t H5Tset_inpad (hid_t type_id, H5T_pad_t pad)
 Fills unused internal floating point bits. More...
 
H5_DLL herr_t H5Tset_norm (hid_t type_id, H5T_norm_t norm)
 Sets the mantissa normalization of a floating-point datatype. More...
 
H5_DLL herr_t H5Tset_offset (hid_t type_id, size_t offset)
 Sets the bit offset of the first significant bit. More...
 
H5_DLL herr_t H5Tset_order (hid_t type_id, H5T_order_t order)
 Sets the byte order of a datatype. More...
 
H5_DLL 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...
 
H5_DLL herr_t H5Tset_precision (hid_t type_id, size_t prec)
 Sets the precision of an atomic datatype. More...
 
H5_DLL herr_t H5Tset_sign (hid_t type_id, H5T_sign_t sign)
 Sets the sign property for an integer type. More...
 
H5_DLL herr_t H5Tset_strpad (hid_t type_id, H5T_str_t strpad)
 Defines the type of padding used for character strings. More...
 

Detailed Description

Function Documentation

◆ H5Tget_cset()

H5T_cset_t H5Tget_cset ( hid_t  type_id)

Retrieves the character set type of a string datatype.


Parameters
[in]dtype_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]dtype_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]dtype_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]dtype_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:

H5T_PAD_ZERO 0 Set background to zeros
H5T_PAD_ONE 1 Set background to ones
H5T_PAD_BACKGROUND 2 Leave background alone
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]dtype_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:

H5T_NORM_IMPLIED0MSB of mantissa is not stored, always 1
H5T_NORM_MSBSET1MSB of mantissa is always 1
H5T_NORM_NONE2Mantissa is not normalized
H5T_NORM_IMPLIED 0 MSB of mantissa is not stored, always 1
H5T_NORM_MSBSET 1 MSB of mantissa is always 1
H5T_NORM_NONE 2 Mantissa is not normalized

delete when done

Since
1.2.0

◆ H5Tget_offset()

int H5Tget_offset ( hid_t  type_id)

Retrieves the bit offset of the first significant bit.


Parameters
[in]dtype_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]dtype_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:
     <table>
     <tr><td>#H5T_ORDER_LE</td>
         <td>0</td>
         <td>Little-endian byte order</td></tr>
     <tr><td>#H5T_ORDER_BE</td>
         <td>1</td>
         <td>Big-endian byte order</td></tr>
     <tr><td>#H5T_ORDER_VAX</td>
         <td>2</td>
         <td>VAX mixed byte order</td></tr>
     <tr><td>#H5T_ORDER_MIXED</td>
         <td>3</td>
         <td>Mixed byte order among members of a compound datatype</td></tr>
     <tr><td>#H5T_ORDER_NONE</td>
         <td>4</td>
         <td>No particular order (fixed-length strings, object and region references)</td></tr>
     </table>
     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]dtype_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:

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

◆ H5Tget_precision()

size_t H5Tget_precision ( hid_t  type_id)

Returns the precision of an atomic datatype.


Parameters
[in]dtype_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]dtype_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:

H5T_SGN_NONE0Unsigned integer type
H5T_SGN_21Two's complement signed integer type

H5T_SGN_NONE (0) Unsigned integer type H5T_SGN_2 (1) Two's complement signed integer type

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]dtype_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]dtype_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]dtype_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

H5T_CSET_ASCII Character set is US ASCII H5T_CSET_UTF8 Character set is UTF-8, enabling UTF-8 Unicode encoding

        For example, if the character set for the datatype dtype_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 H5T_SET_CSET  sets the character set for a character or
        string datatype while H5P_SET_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]dtype_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]dtype_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]dtype_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:

H5T_PAD_ZERO0Set background to zeros
H5T_PAD_ONE1Set background to ones
H5T_PAD_BACKGROUND2Leave background alone
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]dtype_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:

H5T_NORM_IMPLIED0MSB of mantissa is not stored, always 1
H5T_NORM_MSBSET1MSB of mantissa is always 1
H5T_NORM_NONE2Mantissa is not normalized

H5T_NORM_IMPLIED (0) MSB of mantissa is not stored, always 1 H5T_NORM_MSBSET (1) MSB of mantissa is always 1 H5T_NORM_NONE (2) Mantissa is not normalized

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]dtype_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]dtype_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:
     <table>
     <tr><td>#H5T_ORDER_LE</td>
         <td>0</td>
         <td>Little-endian byte order</td></tr>
     <tr><td>#H5T_ORDER_BE</td>
         <td>1</td>
         <td>Big-endian byte order</td></tr>
     <tr><td>#H5T_ORDER_VAX</td>
         <td>2</td>
         <td>VAX mixed byte order</td></tr>
     </table>
     #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]dtype_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

H5T_PAD_ZERO (0) Set background to zeros H5T_PAD_ONE (1) Set background to ones H5T_PAD_BACKGROUND (2) Leave 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]dtype_idDatatype identifier
[in]precisionNumber 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]dtype_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

delete when done H5T_SGN_NONE (0) Unsigned integer type H5T_SGN_2 (1) Two'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]dtype_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)

H5T_STR_NULLTERM (0) Null terminate (as C does)

H5T_STR_NULLPAD (1) Pad with zeros

H5T_STR_SPACEPAD (2) Pad 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