H5A_ITERATE2 iterates over the attributes attached to a dataset, named datatype, or group, as specified by obj_id
. For each attribute, user-provided data, op_data
, with additional information as defined below, is passed to a user-defined function, op
, which operates on that attribute.
The order of the iteration and the attributes iterated over are specified by three parameters: the index type, idx_type
; the order in which the index is to be traversed, order
; and the attribute’s position in the index, n
.
The type of index specified by idx_type
can be one of the following:
H5_INDEX_NAME | An alpha-numeric index by attribute name |
H5_INDEX_CRT_ORDER | An index by creation order |
The order in which the index is to be traversed, as specified by order
, can be one of the following:
H5_ITER_INC | Iteration is from beginning to end, i.e., a top-down iteration incrementing the index position at each step. |
H5_ITER_DEC | Iteration starts at the end of the index, i.e., a bottom-up iteration decrementing the index position at each step. |
H5_ITER_NATIVE | HDF5 iterates in the fastest-available order. No information is provided as to the order, but HDF5 ensures that each element in the index will be visited if the iteration completes successfully. |
The next attribute to be operated on is specified by n
, a position in the index.
For example, if idx_type
, order
, and n
are set to H5_INDEX_NAME
, H5_ITER_INC
, and 5
, respectively, the attribute in question is the fifth attribute from the beginning of the alpha-numeric index of attribute names. If order
were set to H5_ITER_DEC
, it would be the fifth attribute from the end of the index.
The parameter n
is passed in on an H5A_ITERATE2 call with one value and may be returned with another value. The value passed in identifies the parameter to be operated on first; the value returned identifies the parameter to be operated on in the next step of the iteration.
The H5A_operator2_t
prototype for the op
parameter is as follows:
typedef herr_t (*
H5A_operator2_t
)(
hid_t location_id/*in*/
,
const char *
attr_name/*in*/
,
const H5A_info_t *
ainfo/*in*/
,
void *
op_data/*in,out*/
)
The operation receives the location identifier for the group or dataset being iterated over, location_id
; the name of the current object attribute, attr_name
; the attribute’s info struct, ainfo
; and a pointer to the operator data passed into H5Aiterate2
, op_data
.
Valid return values from an operator and the resulting H5A_ITERATE2 and op
behavior are as follows:
- Zero causes the iterator to continue, returning zero when all attributes have been processed.
- A positive value causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the next attribute, as indicated by the return value of
n
. - A negative value causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the next attribute, as indicated by the return value of
n
.
Returns a non-negative value if successful; otherwise returns a negative value.
Further note that this function returns the return value of the last operator if it was non-zero, which can be a negative value, zero if all attributes were processed, or a positive value indicating short-circuit success (see above).