Name: H5Diterate
Signature:
  herr_t `H5Diterate`( void *`buf`, hid_t `type_id`, hid_t `space_id`, H5D_operator_t `operator`, void *`operator_data` )

Purpose:
  Iterates over all selected elements in a dataspace.

Description:
  `H5Diterate` iterates over all the data elements in the memory buffer `buf`, executing the callback function `operator` once for each such data element.

  The protoype of the callback function `operator` is as follows (as defined in the source code file `H5Lpublic.h`): `herr_t (*H5D_operator_t)(void elem, hid_t type_id, unsigned ndim,
  const hsize_t *point, void *operator_data)`

  The parameters of this callback function have the following values or meanings:

  `` | `void *elem` |  | IN/OUT: Pointer to the memory buffer containing the current data element
  | `hid_t type_id` |  | IN: Datatype identifier for the elements stored in `elem`
  | `unsigned ndim` |  | IN: Number of dimensions for the `point` array
  | `const hsize_t *point` |  | IN: Array containing the location of the element within the original dataspace
  | `void *operator_data` |  | IN/OUT: Pointer to any user-defined data associated with the operation

  The possible return values from the callback function, and the effect of each, are as follows:

  - Zero causes the iterator to continue, returning zero when all data elements have been processed.
  - A positive value causes the iterator to immediately return that positive value, indicating short-circuit success.
  - A negative value causes the iterator to immediately return that value, indicating failure.

  The `H5Diterate` `operator_data` parameter is a user-defined pointer to the data required to process dataset elements in the course of the iteration. If `operator` needs to pass data back to the application, such data can be returned in this same buffer. This pointer is passed back to each step of the iteration in the `operator` callback function’s `operator_data` parameter.

  Unlike other HDF5 iterators, this iteration operation cannot be restarted at the point of exit; a second `H5Diterate` call will always restart at the beginning.

Parameters:

void *`buf` | IN/OUT: Pointer to the buffer in memory containing the elements to iterate over
hid_t `type_id` | IN: Datatype identifier for the elements stored in `buf`
hid_t `space_id` | IN: Dataspace identifier for `buf`
H5D_operator_t `operator` | IN: Function pointer to the routine to be called for each element in `buf` iterated over
void *`operator_data` | IN/OUT: Pointer to any user-defined data associated with the operation

Returns:
  Returns the return value of the last operator if it was non-zero, or zero if all elements have been processed. Otherwise returns a negative value.

Fortran90 Interface:
  None.

History:

Release | C
1.6.4 | The following changes occured in the `H5D_operator_t` function in this release: `ndim` parameter type was changed to unsigned `point` parameter type was changed to const hsize_t