Visit objects specified by location and object name
[status,opdata_out] = H5O.visit_by_name(loc_id,obj_name,index_type,order,iter_func,opdata_in,lapl_id)
[status,opdata_out] = H5O.visit_by_name(loc_id,obj_name,index_type,order,iter_func,opdata_in,lapl_id)
specifies the object by the pairing of the location identifier and
object name. loc_id specifies a file or an object
in a file and obj_name specifies an object in the
file with either an absolute name or relative to loc_id.
A link access property list can affect the outcome if links are involved.
Two parameters are used to establish the iteration: index_type and
order. The index_type parameter specifies the index to be
used. If the links in a group have not been indexed by the index type, they are first sorted by
that index, and then the iteration will begin; if the links have been so indexed, the sorting
step is unnecessary, so the iteration can begin more quickly. Specify
index_type as one of these character vectors or string scalars.
'H5_INDEX_NAME' | Alpha-numeric index on name |
'H5_INDEX_CRT_ORDER' | Index on creation order |
Note that the index type passed in index_type is a best effort setting. If
the application passes in a value indicating iteration in creation order and a group is
encountered that was not tracked in creation order, that group will be iterated over in
alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5
Library and is always available.) order specifies the order in which objects
are to be inspected along the index specified in index_type. Specify
order as one of these character vectors or string scalars.
'H5_ITER_INC' | Increasing order |
'H5_ITER_DEC' | Decreasing order |
'H5_ITER_NATIVE' | Fastest available order |
The callback function iter_func must have
the following signature:
function [status,opdata_out] = iter_func(group_id,name,opdata_in)
opdata_in is a user-defined value or structure
and is passed to the first step of the iteration in the iter_func opdata_in parameter.
The opdata_out of an iteration step forms the opdata_in for
the next iteration step. The final opdata_out at
the end of the iteration is then returned to the caller as opdata_out.
lapl_id is a link access property list. When
default link access properties are acceptable, 'H5P_DEFAULT' can
be used.
status value returned by iter_func is
interpreted as follows.
| zero | Continues with the iteration or returns zero status value to the caller if all members have been processed |
| positive | Stops the iteration and returns the positive status value to the caller |
| negative | Stops the iteration and throws an error indicating failure |