H5Pset_type_conv_cb
and
H5Pget_type_conv_cb
:
H5Pset_type_conv_cb
H5Pget_type_conv_cb
H5Tset_overflow
and H5Tget_overflow
have been removed from the HDF5 Library.
This note inserted: January 2010.)
The HDF5 library's current behavior when converting a value from one datatype to another is to issue a call to the "overflow" callback whenever a source value is outside of the range of values representable by the destination datatype. If the overflow callback is not set or is set, but indicates that it hasn't handled the overflow (by returning a negative value when called), the destination value is set to either the maximum or minimum destination value (depending if the source value was beyond the maximum or minimum destination value respectively). The development branch of the HDF5 library (v1.7.x) extends this behavior to it's support for int <-> float type conversions.
For example, when converting from a signed 16-bit integer to an unsigned 16-bit integer, negative source values would trigger a call to the overflow callback, and if it didn't exist or handle the overflow, the minimum unsigned 16-bit integer (0) would be used as the destination value. Likewise, when converting from a signed 32-bit integer to a signed 16-bit integer, source values greater than 32767 or less than -32768 would trigger a call to the overflow callback and would be set to 32767 or -32768 (respectively) if the overflow callback didn't exist or didn't handle the exception.
Here's the prototype for the overflow callback routine:
herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf);
There are several new requirements listed here, in order of decreasing importance:
To accomodate the requirements above, changing the prototype of the "overflow" callback is necessary, as well as attaching it to a data transfer property list and changing the library's behavior for the return values of the callback. I would also suggest changing the name from an "overflow" callback to the more generic "type conversion exception callback".
After accomodating the changes above, the prototype would look like this:
H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf, void *user_data);
The parameters are as follows:
exception_type
- The type of exception (enum described
below).
src_id
- A datatype ID describing the source datatype.
dst_id
- A datatype ID describing the destination datatype.
src_buf
- A pointer to the buffer containing the source value.
dst_buf
- A pointer to the buffer where the destination value should
be placed.
user_data
- A pointer to the "user data" set by the application that
registered the conversion callback.
The H5T_conv_except_t
enumerated type has the following values:
H5T_CONV_EXCEPT_RANGE_HI
- The source value is greater
than the range of values that can be encoded in the destination value.
H5T_CONV_EXCEPT_RANGE_LOW
- The source value is less than
the range of values that can be encoded in the destination value.
H5T_CONV_EXCEPT_PRECISION
- The source value will suffer a
loss of precision when it is represented in the destination type.
(This generally occurs when very large integers are converted to
floating-point types)
H5T_CONV_EXCEPT_TRUNCATE
- The source value will suffer a
truncation in value when it is represented in the destination type.
(This generally occurs when floating-point values with fractional
values are converted to integer datatypes)
The return value from conversion callbacks is H5T_conv_ret_t
,
a new enumerated type with the following values:
H5T_CONV_ABORT
- Abort type conversion immediately (-1).
H5T_CONV_UNHANDLED
- Conversion callback did not
handled the conversion exception and the HDF5 library should perform
whatever default conversion it normally applies (0).
H5T_CONV_HANDLED
- Conversion callback
handled the conversion exception and the HDF5 library should
not perform whatever default conversion it normally applies (1).
Additionally, the H5Tset_overflow
and
H5Tget_overflow
routines would be retired in favor of
the following routines:
This function sets the callback function that the HDF5 library will call when a type conversion exception occurs. Type conversion exceptions occur under the following circumstances:
The conversion exception callback (H5T_conv_except_func_t
)
has the following prototype: (QAK: Fill in description from above
when creating final reference manual page)
This function retrieves the callback function that the HDF5 library will call when a type conversion exception occurs.
As we try to switch the API from H5Tset(get)_overflow to H5Pset(get)_type_conv_cb, we may encounter backward compatibility issue. We have a few options here:
With the above changes to the library, the datatype conversion code will be able to fulfill all the new requirements listed. Supporting the new type conversion exception callback and detecting the new exception types (loss of precision and truncation) will require some additional coding, but not a huge amount. Adding support for detecting the new exception types will make the int <-> float conversions slightly slower and more complex though.
If fill value is needed when conversion exception happens, it can be passed in through the user data(a void pointer) in the callback or can be made a global variable. To find the fill value is user's responsibility. They can retrieve it from the dataset transfer property list easily.
H5Tset_overflow
and
H5Tget_overflow
have been removed from HDF5.