H5G: Group Interface

Proposed New Group API Functions

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.