Recursively iterate through links in group specified by location and group name
[status,opdata_out] = H5L.visit_by_name(loc_id,group_name,index_type,order,iter_func,opdata_in,lapl_id)
[status,opdata_out] = H5L.visit_by_name(loc_id,group_name,index_type,order,iter_func,opdata_in,lapl_id)
recursively iterates though all links in and below a group to perform
a common function whose function handle is iter_func.
The starting point of the iteration is specified by the pairing of
a location id and a relative group name. A link access property list,
lapl_id, may affect the outcome depending upon
the type of link being traversed.
index_type and order establish the iteration.
index_type specifies the index to be used. If the links 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.
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 |