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
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. More...
 
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...
 
H5T_conv_t H5Tfind (hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata)
 Finds a conversion function. More...
 
htri_t H5Tcompiler_conv (hid_t src_id, hid_t dst_id)
 Check whether the library's default conversion is hard conversion. More...
 
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. More...
 

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_idDatatype identifier of source datatype
[in]dst_idDatatype 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_idDatatype identifier of source datatype
[in]dst_idDatatype identifier of destination datatype
[in]nelmtsSize of array buf
[in,out]bufArray containing pre- and post-conversion values
[in]backgroundOptional background buffer
[in]plist_idDataset 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.

◆ H5Tfind()

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

Finds a conversion function.

Parameters
[in]src_idDatatype identifier of source datatype
[in]dst_idDatatype identifier of destination datatype
[out]pcdataPointer 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]persConversion function type
[in]nameName displayed in diagnostic output
[in]src_idDatatype identifier of source datatype
[in]dst_idDatatype identifier of destination datatype
[in]funcFunction 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);
int64_t hid_t
Definition: H5Ipublic.h:60
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)
Definition: H5Tdevelop.h:75
int herr_t
Definition: H5public.h:235
Definition: H5Tdevelop.h:54

The H5T_cdata_t struct is declared as:

typedef struct H5T_cdata_t {
void *priv;
H5T_bkg_t
Definition: H5Tdevelop.h:44
H5T_cmd_t
Definition: H5Tdevelop.h:35
bool hbool_t
Definition: H5public.h:249
hbool_t recalc
Definition: H5Tdevelop.h:57
H5T_cmd_t command
Definition: H5Tdevelop.h:55
H5T_bkg_t need_bkg
Definition: H5Tdevelop.h:56
void * priv
Definition: H5Tdevelop.h:58
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]persConversion function type
[in]nameName displayed in diagnostic output
[in]src_idDatatype identifier of source datatype
[in]dst_idDatatype identifier of destination datatype
[in]funcFunction 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.