Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Conversion Function
Datatypes (H5T)

## Detailed Description

## Functions
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.
H5T_conv_t | H5Tfind (hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata)
| Finds a conversion function.
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.

## 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;
bool 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.