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_id Datatype 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_ASCII	US ASCII
H5T_CSET_UTF8	UTF-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_id Datatype 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_id	Datatype identifier
[out]	spos	Pointer to location to return floating-point sign bit
[out]	epos	Pointer to location to return exponent bit-position
[out]	esize	Pointer to location to return size of exponent in bits
[out]	mpos	Pointer to location to return mantissa bit-position
[out]	msize	Pointer 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_id Datatype 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_PAD_ERROR      = -1, 
    H5T_PAD_ZERO       = 0,  
    H5T_PAD_ONE        = 1,  
    H5T_PAD_BACKGROUND = 2,  
    H5T_NPAD = 3 
} H5T_pad_t;

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_id Datatype 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_ERROR   = -1, 
    H5T_NORM_IMPLIED = 0,  
    H5T_NORM_MSBSET  = 1,  
    H5T_NORM_NONE    = 2   
    /*H5T_NORM_NONE must be last */
} H5T_norm_t;

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_id Datatype 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):

 [ pad]  [0x11]  [0x22]  [ pad]
 [ pad]  [0x22]  [0x11]  [ pad]
 [0x11]  [ pad]  [ pad]  [0x22]
 [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_id Datatype 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_ERROR = -1, 
    H5T_ORDER_LE    = 0,  
    H5T_ORDER_BE    = 1,  
    H5T_ORDER_VAX   = 2,  
    H5T_ORDER_MIXED = 3,  
    H5T_ORDER_NONE  = 4   
    /*H5T_ORDER_NONE must be last */
} H5T_order_t;

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_id	Datatype identifier
[out]	lsb	Buffer for the least-significant bit padding type
[out]	msb	Buffer 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:

typedef enum H5T_pad_t {
    H5T_PAD_ERROR      = -1, 
    H5T_PAD_ZERO       = 0,  
    H5T_PAD_ONE        = 1,  
    H5T_PAD_BACKGROUND = 2,  
    H5T_NPAD = 3 
} H5T_pad_t;

Since: 1.2.0

◆ H5Tget_precision()

size_t H5Tget_precision ( hid_t type_id )

Returns the precision of an atomic datatype.

Parameters

[in] type_id Datatype 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_id Datatype 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_ERROR = -1, 
    H5T_SGN_NONE  = 0,  
    H5T_SGN_2     = 1,  
    H5T_NSGN = 2 
} H5T_sign_t;

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_id Datatype 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_NULLTERM	0	Null terminate (as C does)
H5T_STR_NULLPAD	1	Pad with zeros
H5T_STR_SPACEPAD	2	Pad 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_id Datatype 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_id	Datatype identifier
[in]	cset	Character 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_ASCII	US ASCII
H5T_CSET_UTF8	UTF-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_id	Datatype identifier
[in]	ebias	Exponent 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_id	Datatype identifier
[in]	spos	Sign position, i.e., the bit offset of the floating-point sign bit
[in]	epos	Exponent bit position
[in]	esize	Size of exponent in bits
[in]	mpos	Mantissa bit position
[in]	msize	Size 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_id	Datatype identifier
[in]	pad	Padding 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:

typedef enum H5T_pad_t {
    H5T_PAD_ERROR      = -1, 
    H5T_PAD_ZERO       = 0,  
    H5T_PAD_ONE        = 1,  
    H5T_PAD_BACKGROUND = 2,  
    H5T_NPAD = 3 
} H5T_pad_t;

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_id	Datatype identifier
[in]	norm	Mantissa 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_ERROR   = -1, 
    H5T_NORM_IMPLIED = 0,  
    H5T_NORM_MSBSET  = 1,  
    H5T_NORM_NONE    = 2   
    /*H5T_NORM_NONE must be last */
} H5T_norm_t;

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_id	Datatype identifier
[in]	offset	Offset 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):

 [ pad]  [0x11]  [0x22]  [ pad]
 [ pad]  [0x22]  [0x11]  [ pad]
 [0x11]  [ pad]  [ pad]  [0x22]
 [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_id	Datatype identifier
[in]	order	Byte 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_ERROR = -1, 
    H5T_ORDER_LE    = 0,  
    H5T_ORDER_BE    = 1,  
    H5T_ORDER_VAX   = 2,  
    H5T_ORDER_MIXED = 3,  
    H5T_ORDER_NONE  = 4   
    /*H5T_ORDER_NONE must be last */
} H5T_order_t;

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_id	Datatype identifier
[in]	lsb	Padding type for least-significant bits
[in]	msb	Padding 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_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]	type_id	Datatype identifier
[in]	prec	Number 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_id	Datatype identifier
[in]	sign	Sign 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_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]	type_id	Datatype identifier
[in]	strpad	String 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_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

Detailed Description

Functions

Function Documentation

◆ H5Tget_cset()

◆ H5Tget_ebias()

◆ H5Tget_fields()

◆ H5Tget_inpad()

◆ H5Tget_norm()

◆ H5Tget_offset()

◆ H5Tget_order()

◆ H5Tget_pad()

◆ H5Tget_precision()

◆ H5Tget_sign()

◆ H5Tget_strpad()

◆ H5Tis_variable_str()

◆ H5Tset_cset()

◆ H5Tset_ebias()

◆ H5Tset_fields()

◆ H5Tset_inpad()

◆ H5Tset_norm()

◆ H5Tset_offset()

◆ H5Tset_order()

◆ H5Tset_pad()

◆ H5Tset_precision()

◆ H5Tset_sign()

◆ H5Tset_strpad()