Last modified: 1 February 2013
Name: H5Tconvert
Signature:
  herr_t `H5Tconvert`( hid_t `src_type_id`, hid_t `dest_type_id`, size_t `nelmts`, void *`buf`, void *`background`, hid_t `plist_id` )

Purpose:
  Converts data from one specified datatype to another.

Description:
  `H5Tconvert` converts `nelmts` elements from a source datatype, specified by `src_type_id`, to a destination datatype, `dest_type_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.

Programming Note for C++ Developers Using C Functions:

  If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

  Examples of this kind of routine include callbacks such as `H5Pset_elink_cb` and `H5Pset_type_conv_cb` and functions such as `H5Tconvert` and `H5Ewalk2`.

  Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Parameters:

  hid_t `src_type_id` | IN: Identifier for the source datatype.
  hid_t `dest_type_id` | IN: Identifier for the destination datatype.
  size_t `nelmts` | IN: Size of array `buf`.
  void *`buf` | IN/OUT: Array containing pre- and post-conversion values. `H5Tconvert` will not resize this buffer; it must be large enough to hold the larger of the input and output data.
  void *`background` | IN: Optional background buffer.
  hid_t `plist_id` | IN: Dataset transfer property list identifier.

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

Fortran2003 Interface: h5tconvert_f

History:

  Release | Change
  1.8.8 | Fortran subroutine added.
  1.6.3 | In C function, `nelmts` parameter type changed to size_t.
  1.4.0 | In C function, `nelmts` parameter type changed to hsize_t.