H5A_ITERATE_BY_NAME iterates over the attributes attached to the dataset or group specified with loc_id
and obj_name
. 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.
If loc_id
fully specifies the object to which these attributes are attached, obj_name
should be '.'
(a dot).
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 H5Aiterate_by_name
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:
typedef herr_t (*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 H5Aiterate_by_name
, op_data
.
Valid return values from an operator and the resulting H5Aiterate_by_name
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
.
The link access property list, lapl_id
, may provide information regarding the properties of links required to access the object, obj_name
. See “Link Access Properties” in the H5P APIs.