H5S: Dataspace Interface

Dataspace Object API Functions

Name: H5Screate_simple

Signature:

hid_t H5Screate_simple(int rank, const hsize_t * dims, const hsize_t * maxdims )

Description:

This function creates a new simple data space object and opens it for access. The rank is the number of dimensions used in the dataspace. The dims argument is the size of the simple dataset and the maxdims argument is the upper limit on the size of the dataset. maxdims may be the null pointer in which case the upper limit is the same as dims. If an element of maxdims is zero then the corresponding dimension is unlimited, otherwise no element of maxdims should be smaller than the corresponding element of dims. The dataspace ID returned from this function should be released with H5Sclose or resource leaks will occur.

Parameters:

int rank

Number of dimensions of dataspace.

const hsize_t * dims

An array of the size of each dimension.

const hsize_t * maxdims

An array of the maximum size of each dimension.

Returns:

A dataspace ID on success, negative on failure.

Name: H5Scopy

Signature:

hid_t H5Scopy(hid_t space_id )

Description:

This function copies a dataspace. The dataspace ID returned from this function should be released with H5Sclose or resource leaks will occur.

Parameters:

hid_t space_id

ID of dataspace to copy.

Returns:

A dataspace ID on success, negative on failure.

Name: H5Sget_npoints

Signature:

hsize_t H5Sget_npoints(hid_t space_id)

Description:

This function determines the number of elements in a dataspace. For example, a simple 3-dimensional dataspace with dimensions 2, 3 and 4 would have 24 elements.

Parameters:

hid_t space_id

ID of the dataspace object to query

Returns:

Number of elements in the dataspace, 0 on failure

Name: H5Sget_ndims

Signature:

int H5Sget_ndims(hid_t space_id)

Description:

This function determines the dimensionality (or rank) of a dataspace.

Parameters:

hid_t space_id

ID of the dataspace object to query

Returns:

Number of dimensions in the dataspace, negative on failure

Name: H5Sget_dims

Signature:

int H5Sget_dims(hid_t space_id, hsize_t *dims, hsize_t *maxdims )

Description:

This function returns the size of each dimension in a dataspace through the dims parameter.

Parameters:

hid_t space_id

ID of the dataspace object to query

hsize_t *dims

Pointer to array to store the size of each dimension.

hsize_t *maxdims

Pointer to array to store the maximum size of each dimension.

Returns:

Number of dimensions in the dataspace, negative on failure

Name: H5Sis_simple

Signature:

hbool_t H5Sis_simple(hid_t space_id)

Description:

This function determines whether a dataspace object is a simple dataspace or not. [Currently, all dataspace objects are simple dataspaces, complex dataspace support will be added in the future]

Parameters:

hid_t space_id

ID of the dataspace object to query

Returns:

TRUE or FALSE on success, negative on failure

Name: H5Sset_space

Signature:

herr_t H5Sset_space(hid_t space_id, uint32 rank, uint32 *dims )

Description:

This function determines the number of dimensions and the size of each dimension for the space that a dataset is stored within. This function only creates simple dataspace objects. Setting the rank to a value of zero allows scalar objects to be created. Dimensions are specified from slowest to fastest changing in the dims array (i.e. 'C' order). Setting the size of a dimension to zero indicates that the dimension is of unlimited size and should be allowed to expand. Currently, only the first dimension in the array (the slowest) may be unlimited in size. [Currently, all dataspace objects are simple dataspaces, complex dataspace support will be added in the future]

Parameters:

hid_t space_id

ID of the dataspace object.

uint32 rank

The number of dimensions the object is composed of.

uint32 * dims

An array of the size of each dimension. (NULL for scalar objects)

Returns:

zero/negative

Name: H5Sset_hyperslab

Signature:

herr_t H5Sset_hyperslab(hid_t space_id, const hssize_t *start, const hsize_t *count, const hsize_t *stride )

Description:

This function selects a hyperslab from a simple dataspace. The stride array may be used to sub-sample the hyperslab chosen, a value of 1 in each position of the stride array selects contiguous elements in the array, a value of 2 selects every other element, etc. If the stride parameter is set to NULL, a contiguous hyperslab is chosen. The values in the start and count arrays may be negative, to allow for selecting hyperslabs in chunked datasets which extend in arbitrary directions.

Parameters:

hid_t space_id

ID of the dataspace object to set hyperslab in.

const hssize_t *start

Pointer to array of starting location for hyperslab.

const hsize_t *count

Pointer to array of magnitude of hyperslab.

const hsize_t *stride

Pointer to array of stride of hyperslab.

Returns:

zero/negative

Name: H5Sget_hyperslab

Signature:

int H5Sget_hyperslab(hid_t space_id, hssize_t *start, hsize_t *count, hsize_t *stride )

Description:

This function retrieves information about the hyperslab from a simple dataspace. If no hyperslab has been defined then the hyperslab is the same as the entire array.

Parameters:

hid_t space_id

ID of the dataspace object to set hyperslab in.

hssize_t *start

Pointer to array to store starting location of hyperslab.

hsize_t *count

Pointer to array to store magnitude of hyperslab.

hsize_t *stride

Pointer to array to store stride of hyperslab.

Returns:

Hyperslab dimensionality on success, negative on failure.

Name: H5Sclose

Signature:

herr_t H5Sclose(hid_t space_id )

Description:

This function releases a dataspace. Further access through the dataspace ID is illegal. Failure to release a dataspace with this call will result in resource leaks.

Parameters:

hid_t space_id

ID of dataspace to release.

Returns:

zero/negative