HDF5 Reference Manual  H5   H5A   H5D   H5E   H5F   H5G   H5P   H5S   H5T   H5Z   Tools  

H5S: Dataspace Interface

Dataspace Object API Functions

These functions create and manipulate the dataspace in which to store the elements of a dataset.
             

The following H5S functions are included in the HDF5 specification, but have not yet been implemented. They are described in the The Dataspace Interface (H5S) section of the HDF5 User's Guide..
  • H5Scommit
  • H5Sis_subspace
  • H5Slock
  • H5Sopen
      
  • H5Sselect_name
  • H5Sselect_op
  • H5Sselect_order
      
  • H5Ssubspace
  • H5Ssubspace_name
  • H5Ssubspace_location


Name: H5Screate
Signature:
hid_t H5Screate(H5S_class_t type)
Purpose:
Creates a new dataspace of a specified type.
Description:
H5Screate creates a new dataspace of a particular type. The types currently supported are H5S_SCALAR, H5S_SIMPLE, and H5S_NONE; others are planned to be added later. The H5S_NONE dataspace can only hold a selection, not an extent.
Parameters:
H5S_class_t type
The type of dataspace to be created.
Returns:
Returns a dataspace identifier if successful; otherwise FAIL (-1).

Name: H5Screate_simple
Signature:
hid_t H5Screate_simple(int rank, const hsize_t * dims, const hsize_t * maxdims )
Purpose:
Creates a new simple data space and opens it for access.
Description:
H5Screate_simple creates a new simple data space 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 identifier 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:
Returns a dataspace identifier if successful; otherwise FAIL (-1).

Name: H5Scopy
Signature:
hid_t H5Scopy(hid_t space_id )
Purpose:
Creates an exact copy of a dataspace.
Description:
H5Scopy creates a new dataspace which is an exact copy of the dataspace identified by space_id. The dataspace identifier returned from this function should be released with H5Sclose or resource leaks will occur.
Parameters:
hid_t space_id
Identifier of dataspace to copy.
Returns:
Returns a dataspace identifier if successful; otherwise FAIL (-1).

Name: H5Sselect_elements
Signature:
herr_t H5Sselect_elements(hid_t space_id, dh5s_selopt_t op, const size_t num_elements, const hssize_t *coord[ ] )
Purpose:
Selects array elements to be included in the selection for a dataspace.
Description:
H5Sselect_elements selects array elements to be included in the selection for the space_id dataspace. The number of elements selected must be set with the num_elements. The coord array is a two-dimensional array of size dataspace rank by num_elements (ie. a list of coordinates in the array). The order of the element coordinates in the coord array also specifies the order in which the array elements are iterated through when I/O is performed. Duplicate coordinate locations are not checked for.

The selection operator op determines how the new selection is to be combined with the previously existing selection for the dataspace. Currently, only the H5S_SELECT_SET operator is supported, which replaces the existing selection with the parameters from this call. When operators other than H5S_SELECT_SET are used to combine a new selection with an existing selection, the selection ordering is reset to 'C' array ordering.

Parameters:
hid_t space_id
Identifier of the dataspace.
dh5s_selopt_t op
operator specifying how the new selection is to be combined with the existing selection for the dataspace.
const size_t num_elements
Number of elements to be selected.
const hssize_t *coord[ ]
A 2-dimensional array specifying the coordinates of the elements being selected.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Sselect_all
Signature:
herr_t H5Sselect_all(hid_t space_id)
Purpose:
Selects the entire dataspace.
Description:
H5Sselect_all selects the entire extent of the dataspace space_id.

More specifically, H5Sselect_all selects the special 5S_SELECT_ALL region for the dataspace space_id. H5S_SELECT_ALL selects the entire dataspace for any dataspace it is applied to.

Parameters:
hid_t space_id
IN: The identifier for the dataspace in which the selection is being made.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Sselect_none
Signature:
herr_t H5Sselect_none(hid_t space_id)
Purpose:
Resets the selection region to include no elements.
Description:
H5Sselect_none resets the selection region for the dataspace space_id to include no elements.
Parameters:
hid_t space_id
IN: The identifier for the dataspace in which the selection is being reset.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Sselect_valid
Signature:
hbool_t H5Sselect_valid(hid_t space_id)
Purpose:
Verifies that the selection is within the extent of the dataspace.
Description:
H5Sselect_valid verifies that the selection for the dataspace space_id is within the extent of the dataspace if the current offset for the dataspace is used.
Parameters:
hid_t space_id
The identifier for the dataspace in which the selection is being reset.
Returns:
Returns TRUE if the selection is contained within the extent and FALSE if it is not. Returns FAIL (-1) on error conditions such as the selection or extent not being defined.

Name: H5Sget_simple_extent_npoints
Signature:
hsize_t H5Sget_simple_extent_npoints(hid_t space_id)
Purpose:
Determines the number of elements in a dataspace.
Description:
H5Sget_simple_extent_npoints 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:
Returns the number of elements in the dataspace if successful; otherwise returns 0.

Name: H5Sget_select_npoints
Signature:
hsize_t H5Sget_select_npoints(hid_t space_id)
Purpose:
Determines the number of elements in a dataspace.
Description:
H5Sget_select_npoints determines the number of elements in the current selection of a dataspace.
Parameters:
hid_t space_id
Dataspace identifier.
Returns:
Returns the number of elements in the selection if successful; otherwise FAIL (-1).

Name: H5Sget_simple_extent_ndims
Signature:
int H5Sget_simple_extent_ndims(hid_t space_id)
Purpose:
Determines the dimensionality of a dataspace.
Description:
H5Sget_simple_extent_ndims determines the dimensionality (or rank) of a dataspace.
Parameters:
hid_t space_id
Identifier of the dataspace
Returns:
Returns the number of dimensions in the dataspace if successful; otherwise FAIL (-1)

Name: H5Sget_simple_extent_dims
Signature:
int H5Sget_simple_extent_dims(hid_t space_id, hsize_t *dims, hsize_t *maxdims )
Purpose:
Retrieves dataspace dimension size and maximum size.
Description:
H5Sget_simple_extent_dims returns the size and maximum sizes of each dimension of a dataspace through the dims and maxdims parameters.
Parameters:
hid_t space_id
IN: Identifier of the dataspace object to query
hsize_t *dims
OUT: Pointer to array to store the size of each dimension.
hsize_t *maxdims
OUT: Pointer to array to store the maximum size of each dimension.
Returns:
Returns the number of dimensions in the dataspace if successful; otherwise FAIL (-1).

Name: H5Sget_simple_extent_type
Signature:
H5S_class_t H5Sget_simple_extent_type(hid_t space_id)
Purpose:
Determine the current class of a dataspace.
Description:
H5Sget_simple_extent_type queries a dataspace to determine the current class of a dataspace.

The function returns a class name, one of the following: H5S_SCALAR, H5S_SIMPLE, or H5S_NONE.

Parameters:
hid_t space_id
Dataspace identifier.
Returns:
Returns a dataspace class name if successful; otherwise H5S_NO_CLASS (-1).

Name: H5Sset_extent_simple
Signature:
herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t *current_size, const hsize_t *maximum_size )
Purpose:
Sets or resets the size of an existing dataspace.
Description:
H5Sset_extent_simple sets or resets the size of an existing dataspace.

rank is the dimensionality, or number of dimensions, of the dataspace.

current_size is an array of size rank which contains the new size of each dimension in the dataspace. maximum_size is an array of size rank which contains the maximum size of each dimension in the dataspace.

Any previous extent is removed from the dataspace, the dataspace type is set to H5S_SIMPLE, and the extent is set as specified.

Parameters:
hid_t space_id
Dataspace identifier.
int rank
Rank, or dimensionality, of the dataspace.
const hsize_t *current_size
Array containing current size of dataspace.
const hsize_t *maximum_size
Array containing maximum size of dataspace.
Returns:
Returns a dataspace identifier if successful; otherwise FAIL (-1).

Name: H5Sis_simple
Signature:
hbool_t H5Sis_simple(hid_t space_id)
Purpose:
Determines whether a dataspace is a simple dataspace.
Description:
H5Sis_simple determines whether a dataspace is a simple dataspace. [Currently, all dataspace objects are simple dataspaces, complex dataspace support will be added in the future]
Parameters:
hid_t space_id
Identifier of the dataspace to query
Returns:
Returns TRUE or FALSE if Successful; otherwise FAIL (-1).

Name: H5Soffset_simple
Signature:
herr_t H5Soffset_simple(hid_t space_id, const hssize_t *offset )
Purpose:
Sets the offset of a simple dataspace.
Description:
H5Soffset_simple sets the offset of a simple dataspace space_id. The offset array must be the same number of elements as the number of dimensions for the dataspace. If the offset array is set to NULL, the offset for the dataspace is reset to 0.

This function allows the same shaped selection to be moved to different locations within a dataspace without requiring it to be redefined.

Parameters:
hid_t space_id
IN: The identifier for the dataspace object to reset.
const hssize_t *offset
IN: The offset at which to position the selection.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Sextent_class
Signature:
H5S_class_t H5Sextent_class(hid_t space_id)
Purpose:
Determine the current class of a dataspace.
Description:
H5Sextent_class queries a dataspace to determine the current class of a dataspace.

The function returns a class name, one of the following: H5S_SCALAR, H5S_SIMPLE.

Parameters:
hid_t space_id
Dataspace identifier.
Returns:
Returns a dataspace class name if successful; otherwise H5S_NO_CLASS (-1).

Name: H5Sextent_copy
Signature:
herr_t H5Sextent_copy(hid_t dest_space_id, hid_t source_space_id )
Purpose:
Copies the extent of a dataspace.
Description:
H5Sextent_copy copies the extent from source_space_id to dest_space_id. This action may change the type of the dataspace.
Parameters:
hid_t dest_space_id
IN: The identifier for the dataspace from which the extent is copied.
hid_t source_space_id
IN: The identifier for the dataspace to which the extent is copied.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Sset_extent_none
Signature:
herr_t H5Sset_extent_none(hid_t space_id)
Purpose:
Removes the extent from a dataspace.
Description:
H5Sset_extent_none removes the extent from a dataspace and sets the type to H5S_NONE.
Parameters:
hid_t space_id
The identifier for the dataspace from which the extent is to be removed.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Sselect_hyperslab
Signature:
herr_t H5Sselect_hyperslab(hid_t space_id, h5s_selopt_top, const hssize_t *start, const hsize_t *stride const hsize_t *count, const hsize_t *block )
Purpose:
Selects a hyperslab region to add to the current selected region.
Description:
H5Sselect_hyperslab selects a hyperslab region to add to the current selected region for the dataspace specified by space_id.

The start, stride, count, and block arrays must be the same size as the rank of the dataspace.

The selection operator op determines how the new selection is to be combined with the already existing selection for the dataspace.

Currently, only the H5S_SELECT_SET operator is supported; it replaces the existing selection with the parameters from this call. Overlapping blocks are not supported with the H5S_SELECT_SET operator.

The start array determines the starting coordinates of the hyperslab to select.

The stride array chooses array locations from the dataspace with each value in the stride array determining how many elements to move in each dimension. Setting a value in the stride array to 1 moves to each element in that dimension of the dataspace; setting a value of 2 in a location in the stride array moves to every other element in that dimension of the dataspace. In other words, the stride determines the number of elements to move from the start location in each dimension. Stride values of 0 are not allowed. If the stride parameter is NULL, a contiguous hyperslab is selected (as if each value in the stride array was set to all 1's).

The count array determines how many blocks to select from the dataspace, in each dimension.

The block array determines the size of the element block selected from the dataspace. If the block parameter is set to NULL, the block size defaults to a single element in each dimension (as if the block array was set to all 1's).

For example, in a 2-dimensional dataspace, setting start to [1,1], stride to [4,4], count to [3,7], and block to [2,2] selects 21 2x2 blocks of array elements starting with location (1,1) and selecting blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.

Regions selected with this function call default to C order iteration when I/O is performed.

Parameters:
hid_t space_id
IN: Identifier of dataspace selection to modify
H5S_seloper_t op
IN: Operation to perform on current selection.
const hssize_t *start
IN: Offset of start of hyperslab
const hsize_t *count
IN: Number of blocks included in hyperslab.
const hsize_t *stride
IN: Hyperslab stride.
const hsize_t *block
IN: Size of block in hyperslab.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Sclose
Signature:
herr_t H5Sclose(hid_t space_id )
Purpose:
Releases and terminates access to a dataspace.
Description:
H5Sclose releases a dataspace. Further access through the dataspace identifier is illegal. Failure to release a dataspace with this call will result in resource leaks.
Parameters:
hid_t space_id
Identifier of dataspace to release.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

HDF5 Reference Manual  H5   H5A   H5D   H5E   H5F   H5G   H5P   H5S   H5T   H5Z   Tools  

HDF Help Desk
Last modified: 1 September 1998