IN/OUT: input the index to start iterating, output the next index to visit. If NULL, start at the first position.
IN: the visitor function
IN: arbitrary data to pass to the visitor function.
H5DSiterate_scales iterates over the scales attached to dimension dim of dataset did. For each scale in the list, the visitor_data and some additional information, specified below, are passed to the visitor function. The iteration begins with the idx object in the group and the next element to be processed by the operator is returned in idx. If idx is NULL, then the iterator starts at the first group member; since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns non-zero.
The prototype for H5DS_iterate_t is: typedef herr_t (*H5DS_iterate_t)(hid_t did, unsigned dim, hid_t dsid, void *visitor_data);
The operation receives the Dimension Scale dataset identifier, dsid, and the pointer to the operator data passed in to H5DDiterate_scales, visitor_data.
The return values from an operator are:
Zero causes the iterator to continue, returning zero when all group members have been processed.
Positive causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the next group member.
Negative causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the next group member.
H5DSiterate_scales assumes that the scales of the dimension identified by dim remain unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.
Returns the return value of the last operator if it was non-zero, or zero if all scales were processed.