For each attribute, user-provided data, op_data, with additional information as defined below, is passed to a user-defined function, fcn, 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, idx_in.

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 idx_in, a position in the index. The index of the last attibute operated on is returned as idx_out

For example, if idx_type, order, and idx_in 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 prototype for the fcn callback function is as follows:

[status, op_data_out] = op_fcn (location_id, attr_name, op_data_in)

The operation receives the location identifier location_id for the group or dataset being iterated over; the name of the current object dataset or attribute, attr_name; and the operator data passed into iterate function, op_data_in.

Valid return values status from an operator and the resulting H5A.iterate_by_name and fcn behavior are as follows:

status == 0

Causes the iterator to continue, returning zero when all attributes have been processed.

status > 0

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 idx_out.

status < 0

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 idx_out.

See original function at https://portal.hdfgroup.org/display/HDF5/H5A_ITERATE2.

See also: H5A.iterate_by_name

Source Code: H5A.iterate