Functions
H5_DLL htri_t	H5Tcompiler_conv (hid_t src_id, hid_t dst_id)
	Check whether the library’s default conversion is hard conversion. More...

H5_DLL herr_t	H5Tconvert (hid_t src_id, hid_t dst_id, size_t nelmts, void buf, void background, hid_t dxpl_id)
	Converts data from one specified datatype to another. More...

H5_DLL hid_t	H5Tdecode (const void *buf)
	Decodes a binary object description of datatype and return a new object handle. More...

H5_DLL herr_t	H5Tencode (hid_t obj_id, void buf, size_t nalloc)
	Encodes a datatype object description into a binary buffer. More...

H5_DLL H5T_conv_t	H5Tfind (hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata)
	Finds a conversion function. More...

H5_DLL herr_t	H5Tregister (H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func)
	Registers a datatype conversion function. More...

H5_DLL herr_t	H5Tunregister (H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func)
	Removes a conversion function. More...

Detailed Description

Function Documentation

◆ H5Tcompiler_conv()

htri_t H5Tcompiler_conv	(	hid_t	src_id,
		hid_t	dst_id
	)

Check whether the library’s default conversion is hard conversion.

Parameters

[in]	src_id	Datatype identifier of source datatype
[in]	dst_id	Datatype identifier of destination datatype

Returns: Returns zero (false), a positive (true) or a negative (failure) value.

H5Tcompiler_conv() determines whether the library’s conversion function from type src_id to type dst_id is a compiler (hard) conversion or not. A compiler conversion uses compiler’s casting; a library (soft) conversion uses the library’s own conversion function.

Since: 1.8.0

\type_id{src_id} of source datatype \type_id{dst_id} of destination datatype

Returns: Returns zero (false), a positive (true) or a negative (failure) value.

H5Tcompiler_conv() determines whether the library’s conversion function from type src_id to type dst_id is a compiler (hard) conversion or not. A compiler conversion uses compiler’s casting; a library (soft) conversion uses the library’s own conversion function.

Since: 1.8.0

◆ H5Tconvert()

herr_t H5Tconvert	(	hid_t	src_id,
		hid_t	dst_id,
		size_t	nelmts,
		void *	buf,
		void *	background,
		hid_t	dxpl_id
	)

Converts data from one specified datatype to another.

Parameters

[in]	src_id	Datatype identifier of source datatype
[in]	dst_id	Datatype identifier of destination datatype
[in]	nelmts	Size of array `buf`
[in,out]	buf	Array containing pre- and post-conversion values
[in]	background	Optional background buffer
[in]	dxpl_id	Dataset transfer property list identifier

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

Note: H5Tconvert() will not resize the buffer buf; it must be large enough to hold the larger of the input and output data.

H5Tconvert() converts nelmts elements from a source datatype, specified by src_id, to a destination datatype, dst_id. The source elements are packed in buf and on return the destination elements will be packed in buf. That is, the conversion is performed in place.

The optional background buffer is for use with compound datatypes. It is an array of nelmts values for the destination datatype which can then be merged with the converted values to recreate the compound datatype. For instance, background might be an array of structs with the a and b fields already initialized and the conversion of buf supplies the c and d field values.

The parameter plist_id contains the dataset transfer property list identifier which is passed to the conversion functions. As of Release 1.2, this parameter is only used to pass along the variable-length datatype custom allocation information.

Version: 1.6.3 nelmts parameter type changed to size_t.; 1.4.0 nelmts parameter type changed to hsize_t.

\type_id{src_id} of source datatype \type_id{dst_id} of destination datatype

Parameters

[in]	nelmts	Size of array `buf`
[in,out]	buf	Array containing pre- and post-conversion values
[in]	background	Optional background buffer
[in]	plist_id	Dataset transfer property list identifier

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

Note: H5Tconvert() will not resize the buffer buf; it must be large enough to hold the larger of the input and output data.

H5Tconvert() converts nelmts elements from a source datatype, specified by src_id, to a destination datatype, dst_id. The source elements are packed in buf and on return the destination elements will be packed in buf. That is, the conversion is performed in place.

The optional background buffer is for use with compound datatypes. It is an array of nelmts values for the destination datatype which can then be merged with the converted values to recreate the compound datatype. For instance, background might be an array of structs with the a and b fields already initialized and the conversion of buf supplies the c and d field values.

The parameter plist_id contains the dataset transfer property list identifier which is passed to the conversion functions. As of Release 1.2, this parameter is only used to pass along the variable-length datatype custom allocation information.

Version: 1.6.3 nelmts parameter type changed to size_t.; 1.4.0 nelmts parameter type changed to hsize_t.

◆ H5Tdecode()

hid_t H5Tdecode ( const void * buf )

Decodes a binary object description of datatype and return a new object handle.

Parameters

[in] buf Buffer for the datatype object to be decoded

Returns: Returns a datatype identifier if successful; otherwise returns H5I_INVALID_HID.

H5Tdecode() Given an object description of datatype in binary in a buffer, H5Tdecode() reconstructs the HDF5 datatype object and returns a new object handle for it. The binary description of the object is encoded by H5Tencode(). User is responsible for passing in the right buffer.

The datatype identifier returned by this function can be released with H5Tclose() when the identifier is no longer needed so that resource leaks will not develop.

◆ H5Tencode()

herr_t H5Tencode	(	hid_t	obj_id,
		void *	buf,
		size_t *	nalloc
	)

Encodes a datatype object description into a binary buffer.

Parameters

[in]	obj_id	Identifier of the object to be encoded
[in,out]	buf	Buffer for the object to be encoded into.
[in,out]	nalloc	IN: The size of the allocated buffer OUT: The size of the buffer needed

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Tencode() Given datatype identifier, H5Tencode() converts a datatype description into binary form in a buffer. Using this binary form in the buffer, a datatype object can be reconstructed using H5Tdecode() to return a new object handle (hid_t) for this datatype.

If the provided buffer is NULL, only the size of buffer needed is returned through nalloc.

A preliminary H5Tencode() call can be made to find out the size of the buffer needed. This value is returned as nalloc. That value can then be assigned to nalloc for a second H5Tencode() call, which will retrieve the actual encoded object.

If the library finds that nalloc is not big enough for the object, it simply returns the size of the buffer needed through nalloc without encoding the provided buffer.

Since: 1.2.0

◆ H5Tfind()

H5T_conv_t H5Tfind	(	hid_t	src_id,
		hid_t	dst_id,
		H5T_cdata_t **	pcdata
	)

Finds a conversion function.

Parameters

[in]	src_id	Datatype identifier of source datatype
[in]	dst_id	Datatype identifier of destination datatype
[out]	pcdata	Pointer to type conversion data

Returns: Returns a pointer to a suitable conversion function if successful. Otherwise returns NULL.

H5Tfind() finds a conversion function that can handle a conversion from type src_id to type dst_id. The pcdata argument is a pointer to a pointer to type conversion data which was created and initialized by the soft type conversion function of this path when the conversion function was installed on the path.

\type_id{src_id} of source datatype \type_id{dst_id} of destination datatype

Parameters

[out] pcdata Pointer to type conversion data

Returns: Returns a pointer to a suitable conversion function if successful. Otherwise returns NULL.

H5Tfind() finds a conversion function that can handle a conversion from type src_id to type dst_id. The pcdata argument is a pointer to a pointer to type conversion data which was created and initialized by the soft type conversion function of this path when the conversion function was installed on the path.

◆ H5Tregister()

herr_t H5Tregister	(	H5T_pers_t	pers,
		const char *	name,
		hid_t	src_id,
		hid_t	dst_id,
		H5T_conv_t	func
	)

Registers a datatype conversion function.

Parameters

[in]	pers	Conversion function type
[in]	name	Name displayed in diagnostic output
[in]	src_id	Datatype identifier of source datatype
[in]	dst_id	Datatype identifier of destination datatype
[in]	func	Function to convert between source and destination datatypes

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Tregister() registers a hard or soft conversion function for a datatype conversion path. The parameter pers indicates whether a conversion function is hard (H5T_PERS_HARD) or soft (H5T_PERS_SOFT). User-defined functions employing compiler casting are designated as hard; other user-defined conversion functions registered with the HDF5 library (with H5Tregister() ) are designated as soft. The HDF5 library also has its own hard and soft conversion functions.

A conversion path can have only one hard function. When type is H5T_PERS_HARD, func replaces any previous hard function.

When type is H5T_PERS_SOFT, H5Tregister() adds the function to the end of the master soft list and replaces the soft function in all applicable existing conversion paths. Soft functions are used when determining which conversion function is appropriate for this path.

The name is used only for debugging and should be a short identifier for the function.

The path is specified by the source and destination datatypes src_id and dst_id. For soft conversion functions, only the class of these types is important.

The type of the conversion function pointer is declared as:

typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata,
      size_t nelmts, size_t buf_stride, size_t bkg_stride, void *buf,
      void *bkg, hid_t dset_xfer_plist);

The H5T_cdata_t struct is declared as:

typedef struct H5T_cdata_t {
    H5T_cmd_t       command;
    H5T_bkg_t       need_bkg;
    hbool_t     recalc; 
    void        *priv;  
} H5T_cdata_t;

Since: 1.6.3 The following change occurred in the H5T_conv_t function: the nelmts parameter type changed to size_t.

Parameters

[in]	pers	Conversion function type
[in]	name	Name displayed in diagnostic output \type_id{src_id} of source datatype \type_id{dst_id} of destination datatype
[in]	func	Function to convert between source and destination datatypes

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Tregister() registers a hard or soft conversion function for a datatype conversion path. The parameter pers indicates whether a conversion function is hard (H5T_PERS_HARD) or soft (H5T_PERS_SOFT). User-defined functions employing compiler casting are designated as hard; other user-defined conversion functions registered with the HDF5 library (with H5Tregister() ) are designated as soft. The HDF5 library also has its own hard and soft conversion functions.

A conversion path can have only one hard function. When type is H5T_PERS_HARD, func replaces any previous hard function.

When type is H5T_PERS_SOFT, H5Tregister() adds the function to the end of the master soft list and replaces the soft function in all applicable existing conversion paths. Soft functions are used when determining which conversion function is appropriate for this path.

The name is used only for debugging and should be a short identifier for the function.

The path is specified by the source and destination datatypes src_id and dst_id. For soft conversion functions, only the class of these types is important.

The type of the conversion function pointer is declared as:

typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata,
      size_t nelmts, size_t buf_stride, size_t bkg_stride, void *buf,
      void *bkg, hid_t dset_xfer_plist);

The H5T_cdata_t struct is declared as:

typedef struct H5T_cdata_t {
    H5T_cmd_t       command;
    H5T_bkg_t       need_bkg;
    hbool_t     recalc; 
    void        *priv;  
} H5T_cdata_t;

Since: 1.6.3 The following change occurred in the H5T_conv_t function: the nelmts parameter type changed to size_t.

◆ H5Tunregister()

herr_t H5Tunregister	(	H5T_pers_t	pers,
		const char *	name,
		hid_t	src_id,
		hid_t	dst_id,
		H5T_conv_t	func
	)

Removes a conversion function.

Parameters

[in]	pers	Conversion function type
[in]	name	Name displayed in diagnostic output
[in]	src_id	Datatype identifier of source datatype
[in]	dst_id	Datatype identifier of destination datatype
[in]	func	Function to convert between source and destination datatypes

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Tunregister() removes a conversion function matching criteria such as soft or hard conversion, source and destination types, and the conversion function.

If a user is trying to remove a conversion function he registered, all parameters can be used. If he is trying to remove a library’s default conversion function, there is no guarantee the name and func parameters will match the user’s chosen values. Passing in some values may cause this function to fail. A good practice is to pass in NULL as their values.

All parameters are optional. The missing parameters will be used to generalize the search criteria.

The conversion function pointer type declaration is described in H5Tregister().

Since: 1.6.3 The following change occurred in the H5T_conv_t function: the nelmts parameter type changed to size_t.

Parameters

[in]	pers	Conversion function type
[in]	name	Name displayed in diagnostic output \type_id{src_id} of source datatype \type_id{dst_id} of destination datatype
[in]	func	Function to convert between source and destination datatypes

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Tunregister() removes a conversion function matching criteria such as soft or hard conversion, source and destination types, and the conversion function.

If a user is trying to remove a conversion function he registered, all parameters can be used. If he is trying to remove a library’s default conversion function, there is no guarantee the name and func parameters will match the user’s chosen values. Passing in some values may cause this function to fail. A good practice is to pass in NULL as their values.

All parameters are optional. The missing parameters will be used to generalize the search criteria.

The conversion function pointer type declaration is described in H5Tregister().

Since: 1.6.3 The following change occurred in the H5T_conv_t function: the nelmts parameter type changed to size_t.

Functions

Detailed Description

Function Documentation

◆ H5Tcompiler_conv()

◆ H5Tconvert()

◆ H5Tdecode()

◆ H5Tencode()

◆ H5Tfind()

◆ H5Tregister()

◆ H5Tunregister()