H5G: Group Interface

Proposed New Group API Functions

Two new Group API functions are proposed. First one finds number of objects in the group, second one returns name of the specified object in the group. These two functions will allow users to iterate easily through the group without writing their own iterators.


Name: H5Gget_num_objects
Signature:
herr_t H5Gget_num_objects(hid_t loc_id, hsize_t* num_obj)
Purpose:
Returns number of objects in the group specified by its identifier
Description:
H5Gget_num_objects returns number of objects in a group. Group is specified by its identifier loc_id. If file identifier is passed in, then number of objects in the root group is returned.
Parameters:
hid_t loc_id
IN: Identifier of the group or the file
hsize_t* num_obj
OUT: Number of objects in the group.
Returns:
Returns positive value if successful; otherwise returns a negative value.

Name: H5Gget_objname_from_idx
Signature:
herr_t H5Gget_objname_from_idx(hid_t loc_id, hsize_t idx, size_t max_size, char* name, size_t* name_len )
Purpose:
Returns a name of the object specified by its transient index into a buffer provided by user and name length.
Description:
H5Gget_objname_from_idx returns a name of the object in the group to the buffer name provided by user. Group is specified by its identifier loc_id. If file identifier is passed in, then root group is specified.

Object is identified by its transient index idx. The value of index idx is any nonnegative number less than the total number of objects in the group returned by H5Gget_num_objects. Please note that the same object may have a different index next time the group is opened if objects were added/deleted from/to the group.

If the size of the provided buffer name is less or equal the actual object name length, the object name is trancated to the max_size - 1 characters.

Parameters:
hid_t loc_id
IN: Identifier of the group or the file
hsize_t idx
IN: Transient index
size_t max_size
IN: Size of the buffer name
char* name
IN/OUT: pointer to the user provided buffer to hold up to namelen - 1 object name characters.
size_t* name_len
OUT: Name length
Returns:
Returns positive value if successful, otherwise returns a negative value.

Elena Pourmal
Last modified: April 19, 2002