Conversion Function

Detailed Description

Collaboration diagram for Conversion Function:

Functions
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.
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.
H5T_conv_t	H5Tfind (hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata)
	Finds a conversion function.
htri_t	H5Tcompiler_conv (hid_t src_id, hid_t dst_id)
	Check whether the library's default conversion is hard conversion.
herr_t	H5Tconvert (hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background, hid_t plist_id)
	Converts data from one specified datatype to another.

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

H5Tconvert()

herr_t H5Tconvert	(	hid_t	src_id,
		hid_t	dst_id,
		size_t	nelmts,
		void *	buf,
		void *	background,
		hid_t	plist_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]	plist_id	Dataset transfer property list identifier

Returns

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

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.

Note

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

Version

1.6.3 nelmts parameter type changed to size_t.

1.4.0 nelmts parameter type changed to hsize_t.

Since

1.0.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.

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.

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().

Version

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