Calls user-defined function for each attribute on an object
H5A_ITERATE2 ( obj_id, idx_type, order, n, op, op_data )
herr_t H5Aiterate2( hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *n, H5A_operator2_t op, void *op_data, )
|hid_t ||IN: Identifier for object to which attributes are attached; may be a group, dataset, or named datatype identifier|
|H5_index_t ||IN: Type of index|
|H5_iter_order_t ||IN: Order in which to iterate over index|
|hsize_t *||IN/OUT: Initial and returned offset within index|
|H5A_operator2_t ||IN: User-defined function to pass each attribute to|
|void *||IN/OUT: User data to pass through to and to be returned by iterator operator function|
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,
The type of index specified by
idx_type can be one of the following:
|An alpha-numeric index by attribute name|
|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:
|Iteration is from beginning to end, i.e., a top-down iteration incrementing the index position at each step.|
|Iteration starts at the end of the index, i.e., a bottom-up iteration decrementing the index position at each step.|
|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
n are set to
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.
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.
H5A_operator2_t prototype for the
op parameter is as follows:
location_id/*in*/, const char *
attr_name/*in*/, const H5A_info_t *
ainfo/*in*/, void *
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
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
- 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
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).
|1.8.0||Function introduced in this release.|