- Created by Barbara Jones, last modified on May 08, 2018
H5A_ITERATE2
Calls user-defined function for each attribute on an object
Procedure:
H5A_ITERATE2 ( obj_id, idx_type, order, n, op, op_data )
Signature:
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,
)
Parameters:
hid_t obj_id | IN: Identifier for object to which attributes are attached; may be a group, dataset, or named datatype identifier |
H5_index_t idx_type | IN: Type of index |
H5_iter_order_t order | IN: Order in which to iterate over index |
hsize_t *n | IN/OUT: Initial and returned offset within index |
H5A_operator2_t op | IN: User-defined function to pass each attribute to |
void *op_data | IN/OUT: User data to pass through to and to be returned by iterator operator function |
Description:
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:
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:
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).
Example:
Include Bitbucket Server for Confluence: File content cannot be shown
Unauthenticated access to this resource is not allowed. Please login to Confluence first.
History:
| Release | C |
| 1.8.0 | Function introduced in this release. |
--- Last Modified: May 08, 2018 | 10:14 AM