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