Iterate through links in group specified by name
[status,idx_out,opdata_out] = H5L.iterate_by_name(loc_id,group_name,index_type,order,idx_in,iter_func,opdata_in,lapl_id)
[status,idx_out,opdata_out] = H5L.iterate_by_name(loc_id,group_name,index_type,order,idx_in,iter_func,opdata_in,lapl_id)
iterates through the links in a group to perform a common function
whose function handle is iter_func. The starting
point of the iteration is pairing of a specified by the location id
and a relative group name. H5L.iterate_by_name does
not recursively follow links into subgroups of the specified group.
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 will first be sorted by that index then the
iteration will begin. If the links have been so indexed, the sorting step will be
unnecessary, so the iteration may 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 |
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 |
idx_in specifies the starting point of the
iteration. idx_out returns the point at which iteration
was stopped. This allows an interrupted iteration to be resumed.
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 |