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,
)
H5Aiterate2 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 H5Aiterate2
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
H5Aiterate2 and op behavior are as follows:
n.
n.
hid_t obj_id
|
IN: Identifier for object to which attributes are attached; may be group, dataset, or named datatype. |
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 |
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).
| Release | C |
| 1.8.0 | Function introduced in this release. |