Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.15.0
API Reference
 
Loading...
Searching...
No Matches
Dataspaces (H5S)

Detailed Description

Use the functions in this module to manage HDF5 dataspaces and selections.

HDF5 dataspaces describe the shape of datasets in memory or in HDF5 files. Dataspaces can be empty (H5S_NULL), a singleton (H5S_SCALAR), or a multi-dimensional, regular grid (H5S_SIMPLE). Dataspaces can be re-shaped.

Subsets of dataspaces can be "book-marked" or used to restrict I/O operations using selections. Furthermore, certain set operations are supported for selections.

Macros

#define H5Sencode   H5Sencode2
 

Functions

herr_t H5Sclose (hid_t space_id)
 Releases and terminates access to a dataspace.
 
hid_t H5Scombine_hyperslab (hid_t space_id, H5S_seloper_t op, const hsize_t start[], const hsize_t stride[], const hsize_t count[], const hsize_t block[])
 Performs an operation on a hyperslab and an existing selection and returns the resulting selection.
 
hid_t H5Scombine_select (hid_t space1_id, H5S_seloper_t op, hid_t space2_id)
 Combine two hyperslab selections with an operation, returning a dataspace with the resulting selection.
 
hid_t H5Scopy (hid_t space_id)
 Creates an exact copy of a dataspace.
 
hid_t H5Screate (H5S_class_t type)
 Creates a new dataspace of a specified type.
 
hid_t H5Screate_simple (int rank, const hsize_t dims[], const hsize_t maxdims[])
 Creates a new simple dataspace and opens it for access.
 
hid_t H5Sdecode (const void *buf)
 Decodes a binary object description of data space and returns a new object handle.
 
herr_t H5Sencode2 (hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl)
 Encodes a data space object description into a binary buffer.
 
herr_t H5Sextent_copy (hid_t dst_id, hid_t src_id)
 Copies the extent of a dataspace.
 
htri_t H5Sextent_equal (hid_t space1_id, hid_t space2_id)
 Determines whether two dataspace extents are equal.
 
htri_t H5Sget_regular_hyperslab (hid_t spaceid, hsize_t start[], hsize_t stride[], hsize_t count[], hsize_t block[])
 Retrieves a regular hyperslab selection.
 
herr_t H5Sget_select_bounds (hid_t spaceid, hsize_t start[], hsize_t end[])
 Gets the bounding box containing the current selection.
 
hssize_t H5Sget_select_elem_npoints (hid_t spaceid)
 Gets the number of element points in the current selection.
 
herr_t H5Sget_select_elem_pointlist (hid_t spaceid, hsize_t startpoint, hsize_t numpoints, hsize_t buf[])
 Gets the list of element points currently selected.
 
herr_t H5Sget_select_hyper_blocklist (hid_t spaceid, hsize_t startblock, hsize_t numblocks, hsize_t buf[])
 Gets the list of hyperslab blocks currently selected.
 
hssize_t H5Sget_select_hyper_nblocks (hid_t spaceid)
 Get number of hyperslab blocks.
 
hssize_t H5Sget_select_npoints (hid_t spaceid)
 Determines the number of elements in a dataspace selection.
 
H5S_sel_type H5Sget_select_type (hid_t spaceid)
 Determines the type of the dataspace selection.
 
int H5Sget_simple_extent_dims (hid_t space_id, hsize_t dims[], hsize_t maxdims[])
 Retrieves dataspace dimension size and maximum size.
 
int H5Sget_simple_extent_ndims (hid_t space_id)
 Determines the dimensionality of a dataspace.
 
hssize_t H5Sget_simple_extent_npoints (hid_t space_id)
 Determines the number of elements in a dataspace.
 
H5S_class_t H5Sget_simple_extent_type (hid_t space_id)
 Determines the current class of a dataspace.
 
htri_t H5Sis_regular_hyperslab (hid_t spaceid)
 Determines if a hyperslab selection is regular.
 
htri_t H5Sis_simple (hid_t space_id)
 Determines whether a dataspace is a simple dataspace.
 
herr_t H5Smodify_select (hid_t space1_id, H5S_seloper_t op, hid_t space2_id)
 Refines a hyperslab selection with an operation, using a second hyperslab to modify it.
 
herr_t H5Soffset_simple (hid_t space_id, const hssize_t *offset)
 Sets the offset of a simple dataspace.
 
herr_t H5Ssel_iter_close (hid_t sel_iter_id)
 Closes a dataspace selection iterator.
 
hid_t H5Ssel_iter_create (hid_t spaceid, size_t elmt_size, unsigned flags)
 Creates a dataspace selection iterator for a dataspace's selection.
 
herr_t H5Ssel_iter_get_seq_list (hid_t sel_iter_id, size_t maxseq, size_t maxelmts, size_t *nseq, size_t *nelmts, hsize_t *off, size_t *len)
 Retrieves a list of offset / length sequences for the elements in an iterator.
 
herr_t H5Ssel_iter_reset (hid_t sel_iter_id, hid_t space_id)
 Resets a dataspace selection iterator back to an initial state.
 
herr_t H5Sselect_adjust (hid_t spaceid, const hssize_t *offset)
 Adjusts a selection by subtracting an offset.
 
herr_t H5Sselect_all (hid_t spaceid)
 Selects an entire dataspace.
 
herr_t H5Sselect_copy (hid_t dst_id, hid_t src_id)
 Copies a selection from one dataspace to another.
 
herr_t H5Sselect_elements (hid_t space_id, H5S_seloper_t op, size_t num_elem, const hsize_t *coord)
 Selects array elements to be included in the selection for a dataspace.
 
herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t op, const hsize_t start[], const hsize_t stride[], const hsize_t count[], const hsize_t block[])
 Selects a hyperslab region to add to the current selected region.
 
htri_t H5Sselect_intersect_block (hid_t space_id, const hsize_t *start, const hsize_t *end)
 Checks if current selection intersects with a block.
 
herr_t H5Sselect_none (hid_t spaceid)
 Resets the selection region to include no elements.
 
hid_t H5Sselect_project_intersection (hid_t src_space_id, hid_t dst_space_id, hid_t src_intersect_space_id)
 Projects the intersection of two source selections to a destination selection.
 
htri_t H5Sselect_shape_same (hid_t space1_id, hid_t space2_id)
 Checks if two selections are the same shape.
 
htri_t H5Sselect_valid (hid_t spaceid)
 Verifies that the selection is within the extent of the dataspace.
 
herr_t H5Sset_extent_none (hid_t space_id)
 Resets the extent of a dataspace back to "none".
 
herr_t H5Sset_extent_simple (hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[])
 Sets or resets the size of an existing dataspace.
 
herr_t H5Sencode1 (hid_t obj_id, void *buf, size_t *nalloc)
 Encodes a data space object description into a binary buffer.
 

Macro Definition Documentation

◆ H5Sencode

#define H5Sencode   H5Sencode2

H5Sencode() is a macro that is mapped to either H5Sencode1() or H5Sencode2().

See also
API Compatibility Macros

Function Documentation

◆ H5Sclose()

herr_t H5Sclose ( hid_t  space_id)

Releases and terminates access to a dataspace.

Parameters
[in]space_idDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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.

Version
1.4.0 Fortran subroutine introduced in this release.
Since
1.0.0

◆ H5Scombine_hyperslab()

hid_t H5Scombine_hyperslab ( hid_t  space_id,
H5S_seloper_t  op,
const hsize_t  start[],
const hsize_t  stride[],
const hsize_t  count[],
const hsize_t  block[] 
)

Performs an operation on a hyperslab and an existing selection and returns the resulting selection.

Parameters
[in]space_idDataspace identifier
[in]opOperation to perform on the current selection
[in]startOffset of the start of of the hyperslab
[in]strideHyperslab stride
[in]countNumber of blocks included in the hyperslab
[in]blockSize of a block in the hyperslab
Returns
Returns an dataspace identifier if successful; otherwise returns a negative value.

H5Scombine_hyperslab() combines a hyperslab selection specified by start, stride, count and block with the current selection for the dataspace space_id, creating a new dataspace to return the generated selection. If the current selection is not a hyperslab, it is freed and the hyperslab parameters passed in are combined with the H5S_SEL_ALL hyperslab (ie. a selection composing the entire current extent). If either stride or block is NULL, then it will be set to 1.

Since
1.10.6

◆ H5Scombine_select()

hid_t H5Scombine_select ( hid_t  space1_id,
H5S_seloper_t  op,
hid_t  space2_id 
)

Combine two hyperslab selections with an operation, returning a dataspace with the resulting selection.

Parameters
[in]space1_idDataspace identifier
[in]opSelection operator
[in]space2_idDataspace identifier
Returns
Returns a dataspace identifier if successful; otherwise returns H5I_INVALID_HID.

H5Scombine_select() combines two hyperslab selections space1_id and space2_id with an operation, returning a new dataspace with the resulting selection. The dataspace extent from space1_id is copied for the dataspace extent of the newly created dataspace.

Since
1.10.6

◆ H5Scopy()

hid_t H5Scopy ( hid_t  space_id)

Creates an exact copy of a dataspace.

Parameters
[in]space_idDataspace identifier
Returns
Returns an dataspace identifier if successful; otherwise returns a negative value.

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.

Version
1.4.0 Fortran subroutine introduced.
Since
1.0.0

◆ H5Screate()

hid_t H5Screate ( H5S_class_t  type)

Creates a new dataspace of a specified type.

Parameters
[in]typeType of dataspace to be created
Returns
Returns a dataspace identifier if successful; otherwise returns H5I_INVALID_HID.

H5Screate() creates a new dataspace of a particular type. Currently supported types are H5S_SCALAR, H5S_SIMPLE, and H5S_NULL.

Further dataspace types may be added later.

A scalar dataspace, H5S_SCALAR, has a single element, though that element may be of a complex datatype, such as a compound or array datatype. By convention, the rank of a scalar dataspace is always 0 (zero); think of it geometrically as a single, dimensionless point, though that point can be complex.

A simple dataspace, H5S_SIMPLE, consists of a regular array of elements.

A null dataspace, H5S_NULL, has no data elements.

The dataspace identifier returned by this function can be released with H5Sclose() so that resource leaks will not occur.

Version
1.4.0 Fortran subroutine introduced.
Since
1.0.0

◆ H5Screate_simple()

hid_t H5Screate_simple ( int  rank,
const hsize_t  dims[],
const hsize_t  maxdims[] 
)

Creates a new simple dataspace and opens it for access.

Parameters
[in]rankNumber of dimensions of dataspace
[in]dimsArray specifying the size of each dimension
[in]maxdimsArray specifying the maximum size of each dimension
Returns
Returns a dataspace identifier if successful; otherwise returns H5I_INVALID_HID.

H5Screate_simple() creates a new simple dataspace and opens it for access, returning a dataspace identifier.

rank is the number of dimensions used in the dataspace.

dims is a one-dimensional array of size rank specifying the size of each dimension of the dataset. maxdims is an array of the same size specifying the upper limit on the size of each dimension.

Any element of dims can be 0 (zero). Note that no data can be written to a dataset if the size of any dimension of its current dataspace is 0. This is sometimes a useful initial state for a dataset.

maxdims may be the null pointer, in which case the upper limit is the same as dims. Otherwise, no element of maxdims should be smaller than the corresponding element of dims.

If an element of maxdims is H5S_UNLIMITED, the maximum size of the corresponding dimension is unlimited.

Any dataset with an unlimited dimension must also be chunked; see H5Pset_chunk(). Similarly, a dataset must be chunked if dims does not equal maxdims.

The dataspace identifier returned from this function must be released with H5Sclose() or resource leaks will occur.

Note
Once a dataspace has been created, specific regions or elements in the dataspace can be selected and selections can be removed, as well. For example, H5Sselect_hyperslab() selects a region in a dataspace and H5Sselect_elements() selects array elements in a dataspace. These functions are used for subsetting. H5Sselect_none() removes all selections from a dataspace and is used in Parallel HDF5 when a process does not have or need to write data.
Version
1.4.0 Fortran subroutine introduced.
Since
1.0.0

◆ H5Sdecode()

hid_t H5Sdecode ( const void *  buf)

Decodes a binary object description of data space and returns a new object handle.

Parameters
[in]bufBuffer for the data space object to be decoded
Returns
Returns a dataspace identifier if successful; otherwise returns H5I_INVALID_HID.

Given an object description of a dataspace in binary in a buffer, H5Sdecode() reconstructs the HDF5 data type object and returns a new object handle for it. The binary description of the object is encoded by H5Sencode(). The user is responsible for passing in the right buffer. The types of dataspace addressed in this function are null, scalar, and simple space. For a simple dataspace, the selection information (for example, hyperslab selection) is also encoded and decoded. A complex dataspace has not been implemented in the library.

Since
1.8.0

◆ H5Sencode1()

herr_t H5Sencode1 ( hid_t  obj_id,
void *  buf,
size_t *  nalloc 
)

Encodes a data space object description into a binary buffer.

Parameters
[in]obj_idDataspace identifier
[in,out]bufBuffer for the object to be encoded into; If the provided buffer is NULL, only the size of buffer needed is returned through nalloc.
[in,out]nallocThe size of the allocated buffer
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
Deprecated in favor of H5Sencode2()

Given the data space identifier obj_id, H5Sencode1() converts a data space description into binary form in a buffer. Using this binary form in the buffer, a data space object can be reconstructed using H5Sdecode() to return a new object handle (hid_t) for this data space.

A preliminary H5Sencode1() call can be made to find out the size of the buffer needed. This value is returned as nalloc. That value can then be assigned to nalloc for a second H5Sencode1() call, which will retrieve the actual encoded object.

If the library finds out nalloc is not big enough for the object, it simply returns the size of the buffer needed through nalloc without encoding the provided buffer.

The types of data space addressed in this function are null, scalar, and simple space. For a simple data space, the information on the selection, for example, hyperslab selection, is also encoded and decoded. A complex data space has not been implemented in the library.

Version
1.12.0 The function H5Sencode() was renamed H5Sencode1() and deprecated.
Since
1.8.0

◆ H5Sencode2()

herr_t H5Sencode2 ( hid_t  obj_id,
void *  buf,
size_t *  nalloc,
hid_t  fapl 
)

Encodes a data space object description into a binary buffer.

Parameters
[in]obj_idDataspace identifier
[in,out]bufBuffer for the object to be encoded into; If the provided buffer is NULL, only the size of buffer needed is returned through nalloc.
[in,out]nallocThe size of the allocated buffer
[in]faplFile access property list identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

Given the data space identifier obj_id, H5Sencode2() converts a data space description into binary form in a buffer. Using this binary form in the buffer, a data space object can be reconstructed with H5Sdecode() to return a new object handle (hid_t) for this data space.

A preliminary H5Sencode2() call can be made to determine the size of the buffer needed. This value is returned in nalloc. That value can then be assigned to nalloc for a second H5Sencode2() call, which will retrieve the actual encoded object.

If the library determines that nalloc is not big enough for the object, it simply returns the size of the buffer needed through nalloc without encoding the provided buffer.

The file access property list fapl_id is used to control the encoding via the libver_bounds property (see H5Pset_libver_bounds()). If the libver_bounds property is missing, H5Sencode2() proceeds as if the libver_bounds property were set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST). (Functionally, H5Sencode1() is identical to H5Sencode2() with libver_bounds set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST).)

The types of data space that are addressed in this function are null, scalar, and simple space. For a simple data space, the information on the selection, for example, hyperslab selection, is also encoded and decoded. A complex data space has not been implemented in the library.

Note
Motivation: This function was introduced in HDF5-1.12 as part of the H5Sencode() format change to enable 64-bit selection encodings and a dataspace selection that is tied to a file. See the New Features in HDF5 Release 1.12 as well as the RFC H5Secnode() / H5Sdecode() Format Change.
Since
1.12.0

◆ H5Sextent_copy()

herr_t H5Sextent_copy ( hid_t  dst_id,
hid_t  src_id 
)

Copies the extent of a dataspace.

Parameters
[in]dst_idDataspace identifier
[in]src_idDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sextent_copy() copies the extent from src_id to dst_id. This action may change the type of the dataspace.

Version
1.4.0 Fortran subroutine was introduced.
Since
1.0.0

◆ H5Sextent_equal()

htri_t H5Sextent_equal ( hid_t  space1_id,
hid_t  space2_id 
)

Determines whether two dataspace extents are equal.

Parameters
[in]space1_idDataspace identifier
[in]space2_idDataspace identifier
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5Sextent_equal() determines whether the dataspace extents of two dataspaces, space1_id and space2_id, are equal.

Since
1.8.0

◆ H5Sget_regular_hyperslab()

htri_t H5Sget_regular_hyperslab ( hid_t  spaceid,
hsize_t  start[],
hsize_t  stride[],
hsize_t  count[],
hsize_t  block[] 
)

Retrieves a regular hyperslab selection.

Parameters
[in]spaceidDataspace identifier
[out]startOffset of the start of the regular hyperslab
[out]strideStride of the regular hyperslab
[out]countNumber of blocks in the regular hyperslab
[out]blockSize of a block in the regular hyperslab
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sget_regular_hyperslab() takes the dataspace identifier, spaceid, and retrieves the values of start, stride, count, and block for the regular hyperslab selection.

A regular hyperslab selection is a hyperslab selection described by setting the offset, stride, count, and block parameters to the H5Sselect_hyperslab() call. If several calls to H5Sselect_hyperslab() are needed, the hyperslab selection is irregular.

See H5Sselect_hyperslab() for descriptions of offset, stride, count, and block.

Note
If a hyperslab selection is originally regular, then becomes irregular through selection operations, and then becomes regular again, the final regular selection may be equivalent but not identical to the original regular selection.
Since
1.10.0

◆ H5Sget_select_bounds()

herr_t H5Sget_select_bounds ( hid_t  spaceid,
hsize_t  start[],
hsize_t  end[] 
)

Gets the bounding box containing the current selection.

Parameters
[in]spaceidDataspace identifier
[out]startStarting coordinates of the bounding box
[out]endEnding coordinates of the bounding box, i.e., the coordinates of the diagonally opposite corner
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sget_select_bounds() retrieves the coordinates of the bounding box containing the current selection and places them into user-supplied buffers.

The start and end buffers must be large enough to hold the dataspace rank number of coordinates.

The bounding box exactly contains the selection. I.e., if a 2-dimensional element selection is currently defined as containing the points (4,5), (6,8), and (10,7), then the bounding box will be (4, 5), (10, 8).

The bounding box calculation includes the current offset of the selection within the dataspace extent.

Calling this function on a none selection will fail.

Version
1.6.0 The start and end parameters have changed from type hsize_t * to hssize_t *.
1.4.0 Fortran subroutine was introduced.
Since
1.2.0

◆ H5Sget_select_elem_npoints()

hssize_t H5Sget_select_elem_npoints ( hid_t  spaceid)

Gets the number of element points in the current selection.

Parameters
[in]spaceidDataspace identifier
Returns
Returns the number of element points in the current dataspace selection if successful. Otherwise returns a negative value.

H5Sget_select_elem_npoints() returns the number of element points in the current dataspace selection, so that the element points can be retrieved with H5Sget_select_elem_pointlist(). (This is similar to the way that H5Sget_select_hyper_nblocks() and H5Sget_select_hyper_blocklist() work with hyperslab selections.)

Coincidentally, H5Sget_select_npoints() and H5Sget_select_elem_npoints() will always return the same value when an element selection is queried, but H5Sget_select_elem_npoints() does not work with other selection types.

Since
1.2.0

◆ H5Sget_select_elem_pointlist()

herr_t H5Sget_select_elem_pointlist ( hid_t  spaceid,
hsize_t  startpoint,
hsize_t  numpoints,
hsize_t  buf[] 
)

Gets the list of element points currently selected.

Parameters
[in]spaceidDataspace identifier
[in]startpointElement point to start with
[in]numpointsNumber of element points to get
[out]bufList of element points selected

H5Sget_select_elem_pointlist() returns the list of element points in the current dataspace selection space_id. Starting with the startpoint in the list of points, numpoints points are put into the user's buffer. If the user's buffer fills up before numpoints points are inserted, the buffer will contain only as many points as fit.

The element point coordinates have the same dimensionality (rank) as the dataspace they are located within. The list of element points is formatted as follows:
<coordinate>, followed by
the next coordinate,
etc.
until all of the selected element points have been listed.

The points are returned in the order they will be iterated through when the selection is read/written from/to disk.

Since
1.2.0

◆ H5Sget_select_hyper_blocklist()

herr_t H5Sget_select_hyper_blocklist ( hid_t  spaceid,
hsize_t  startblock,
hsize_t  numblocks,
hsize_t  buf[] 
)

Gets the list of hyperslab blocks currently selected.

Parameters
[in]spaceidDataspace identifier
[in]startblockHyperslab block to start with
[in]numblocksNumber of hyperslab blocks to get
[out]bufList of hyperslab blocks selected
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sget_select_hyper_blocklist() returns a list of the hyperslab blocks currently selected. Starting with the startblock-th block in the list of blocks, numblocks blocks are put into the user's buffer. If the user's buffer fills up before numblocks blocks are inserted, the buffer will contain only as many blocks as fit.

The block coordinates have the same dimensionality (rank) as the dataspace they are located within. The list of blocks is formatted as follows:
<"start" coordinate>, immediately followed by
<"opposite" corner coordinate>, followed by
the next "start" and "opposite" coordinates,
etc. until all of the selected blocks have been listed.
No guarantee of any order of the blocks is implied.

Since
1.2.0

◆ H5Sget_select_hyper_nblocks()

hssize_t H5Sget_select_hyper_nblocks ( hid_t  spaceid)

Get number of hyperslab blocks.

Parameters
[in]spaceidDataspace identifier
Returns
Returns the number of hyperslab blocks in the current dataspace selection if successful. Otherwise returns a negative value.

H5Sget_select_hyper_nblocks() returns the number of hyperslab blocks in the current dataspace selection.

Since
1.2.0

◆ H5Sget_select_npoints()

hssize_t H5Sget_select_npoints ( hid_t  spaceid)

Determines the number of elements in a dataspace selection.

Parameters
[in]spaceidDataspace identifier
Returns
Returns the number of elements in the selection if successful; otherwise returns a negative value.

H5Sget_select_npoints() determines the number of elements in the current selection of a dataspace. It works with any selection type, and is the correct way to retrieve the number of elements in a selection.

Version
1.4.0 Fortran subroutine introduced in this release.
Since
1.0.0

◆ H5Sget_select_type()

H5S_sel_type H5Sget_select_type ( hid_t  spaceid)

Determines the type of the dataspace selection.

Parameters
[in]spaceidDataspace identifier
Returns
Returns the dataspace selection type, a value of the enumerated datatype H5S_sel_type, if successful.

H5Sget_select_type() retrieves the type of dataspace selection currently defined for the dataspace space_id. Valid values for the dataspace selection type are:

H5S_SEL_NONE No selection is defined
H5S_SEL_POINTS A sequence of points is selected
H5S_SEL_HYPERSLABS A hyperslab or compound hyperslab is selected
H5S_SEL_ALL The entire dataset is selected

Otherwise returns a negative value.

Since
1.6.0

◆ H5Sget_simple_extent_dims()

int H5Sget_simple_extent_dims ( hid_t  space_id,
hsize_t  dims[],
hsize_t  maxdims[] 
)

Retrieves dataspace dimension size and maximum size.

Parameters
[in]space_idDataspace identifier
[out]dimsPointer to array to store the size of each dimension
[out]maxdimsPointer to array to store the maximum size of each dimension
Returns
Returns the number of dimensions in the dataspace if successful; otherwise returns a negative value.

H5Sget_simple_extent_dims() returns the size and maximum sizes of each dimension of a dataspace space_id through the dims and maxdims parameters.

Either or both of dims and maxdims may be NULL.

If a value in the returned array maxdims is H5S_UNLIMITED (-1), the maximum size of that dimension is unlimited.

Version
1.4.0 Fortran subroutine introduced.
Since
1.0.0

◆ H5Sget_simple_extent_ndims()

int H5Sget_simple_extent_ndims ( hid_t  space_id)

Determines the dimensionality of a dataspace.

Parameters
[in]space_idDataspace identifier
Returns
Returns the number of dimensions in the dataspace if successful; otherwise returns a negative value.

H5Sget_simple_extent_ndims() determines the dimensionality (or rank) of a dataspace.

Version
1.4.0 Fortran subroutine introduced.
Since
1.0.0

◆ H5Sget_simple_extent_npoints()

hssize_t H5Sget_simple_extent_npoints ( hid_t  space_id)

Determines the number of elements in a dataspace.

Parameters
[in]space_idDataspace identifier
Returns
Returns the number of elements in the dataspace if successful; otherwise returns a negative value.

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

Version
1.4.0 Fortran subroutine introduced.
Since
1.0.0

◆ H5Sget_simple_extent_type()

H5S_class_t H5Sget_simple_extent_type ( hid_t  space_id)

Determines the current class of a dataspace.

Parameters
[in]space_idDataspace identifier
Returns
Returns a dataspace class name if successful; otherwise H5S_NO_CLASS (-1).

H5Sget_simple_extent_type() determines the current class of a dataspace space_id.

Version
1.4.0 Fortran subroutine was introduced.
Since
1.0.0

◆ H5Sis_regular_hyperslab()

htri_t H5Sis_regular_hyperslab ( hid_t  spaceid)

Determines if a hyperslab selection is regular.

Parameters
[in]spaceidDataspace identifier
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5Sis_regular_hyperslab() takes the dataspace identifier, spaceid, and queries the type of the hyperslab selection.

A regular hyperslab selection is a hyperslab selection described by setting the offset, stride, count, and block parameters for a single H5Sselect_hyperslab() call. If several calls to H5Sselect_hyperslab() are needed, then the hyperslab selection is irregular.

Since
1.10.0

◆ H5Sis_simple()

htri_t H5Sis_simple ( hid_t  space_id)

Determines whether a dataspace is a simple dataspace.

Parameters
[in]space_idDataspace identifier
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5Sis_simple() determines whether or not a dataspace is a simple dataspace.

Note
Currently, all dataspace objects are simple dataspaces; complex dataspace support will be added in the future.
Version
1.4.0 Fortran subroutine was introduced.
Since
1.0.0

◆ H5Smodify_select()

herr_t H5Smodify_select ( hid_t  space1_id,
H5S_seloper_t  op,
hid_t  space2_id 
)

Refines a hyperslab selection with an operation, using a second hyperslab to modify it.

Parameters
[in]space1_idDataspace identifier
[in]opSelection operator
[in]space2_idDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Smodify_select() refines an existing hyperslab selection space1_id with an operation op, using a second hyperslab space2_id. The first selection is modified to contain the result of space1_id operated on by space2_id.

Since
1.10.6

◆ H5Soffset_simple()

herr_t H5Soffset_simple ( hid_t  space_id,
const hssize_t offset 
)

Sets the offset of a simple dataspace.

Parameters
[in]space_idDataspace identifier
[in]offsetThe offset at which to position the selection
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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.

Version
1.4.0 Fortran subroutine was introduced.
Since
1.0.0

◆ H5Ssel_iter_close()

herr_t H5Ssel_iter_close ( hid_t  sel_iter_id)

Closes a dataspace selection iterator.

Parameters
[in]sel_iter_idDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Ssel_iter_close() closes a dataspace selection iterator specified by sel_iter_id, releasing its state.

Since
1.12.0

◆ H5Ssel_iter_create()

hid_t H5Ssel_iter_create ( hid_t  spaceid,
size_t  elmt_size,
unsigned  flags 
)

Creates a dataspace selection iterator for a dataspace's selection.

Parameters
[in]spaceidDataspace identifier
[in]elmt_sizeSize of element in the selection
[in]flagsSelection iterator flag
Returns
Returns a valid dataspace selection iterator identifier if successful; otherwise returns H5I_INVALID_HID.

H5Ssel_iter_create() creates a selection iterator and initializes it to start at the first element selected in the dataspace.

Since
1.12.0

◆ H5Ssel_iter_get_seq_list()

herr_t H5Ssel_iter_get_seq_list ( hid_t  sel_iter_id,
size_t  maxseq,
size_t  maxelmts,
size_t *  nseq,
size_t *  nelmts,
hsize_t off,
size_t *  len 
)

Retrieves a list of offset / length sequences for the elements in an iterator.

Parameters
[in]sel_iter_idDataspace identifier
[in]maxseqMaximum number of sequences to retrieve
[in]maxelmtsMaximum number of elements to retrieve in sequences
[out]nseqNumber of sequences retrieved
[out]nelmtsNumber of elements retrieved, in all sequences
[out]offArray of sequence offsets
[out]lenArray of sequence lengths
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Ssel_iter_get_seq_list() retrieves a list of offset / length pairs (a list of "sequences") matching the selected elements for an iterator sel_iter_id, according to the iteration order for the iterator. The lengths returned are in bytes, not elements.

Note that the iteration order for "all" and "hyperslab" selections is row-major (i.e. "C-ordered"), but the iteration order for "point" selections is "in order selected", unless the H5S_SEL_ITER_GET_SEQ_LIST_SORTED flag is passed to H5Ssel_iter_create() for a point selection.

maxseq and maxelmts specify the most sequences or elements possible to place into the off and len arrays. nseq and nelmts return the actual number of sequences and elements put into the arrays.

Each call to H5Ssel_iter_get_seq_list() will retrieve the next set of sequences for the selection being iterated over.

The total number of bytes possible to retrieve from a selection iterator is the elmt_size passed to H5Ssel_iter_create() multiplied by the number of elements selected in the dataspace the iterator was created from (which can be retrieved with H5Sget_select_npoints(). When there are no further sequences of elements to retrieve, calls to this routine will set nseq and nelmts to zero.

Since
1.12.0

◆ H5Ssel_iter_reset()

herr_t H5Ssel_iter_reset ( hid_t  sel_iter_id,
hid_t  space_id 
)

Resets a dataspace selection iterator back to an initial state.

Parameters
[in]sel_iter_idIdentifier of the dataspace selection iterator to reset
[in]space_idIdentifier of the dataspace with selection to iterate over
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Ssel_iter_reset() resets a dataspace selection iterator back to an initial state so that the iterator may be used for iteration once again.

Since
1.12.1

◆ H5Sselect_adjust()

herr_t H5Sselect_adjust ( hid_t  spaceid,
const hssize_t offset 
)

Adjusts a selection by subtracting an offset.

Parameters
[in]spaceidDataspace identifier
[in]offsetOffset to subtract
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sselect_adjust() shifts a dataspace selection by a specified logical offset within the dataspace extent.

Note
This can be useful for VOL developers to implement chunked datasets.
Since
1.10.6

◆ H5Sselect_all()

herr_t H5Sselect_all ( hid_t  spaceid)

Selects an entire dataspace.

Parameters
[in]spaceidDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sselect_all() selects the entire extent of the dataspace dspace_id.

More specifically, H5Sselect_all() sets the selection type to H5S_SEL_ALL, which specifies the entire dataspace anywhere it is applied.

Since
1.0.0

◆ H5Sselect_copy()

herr_t H5Sselect_copy ( hid_t  dst_id,
hid_t  src_id 
)

Copies a selection from one dataspace to another.

Parameters
[in]dst_idDataspace identifier
[in]src_idDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sselect_copy() copies all selection information (including offset) from the source dataspace src_id to the destination dataspace dst_id.

Since
1.10.6

◆ H5Sselect_elements()

herr_t H5Sselect_elements ( hid_t  space_id,
H5S_seloper_t  op,
size_t  num_elem,
const hsize_t coord 
)

Selects array elements to be included in the selection for a dataspace.

Parameters
[in]space_idDataspace identifier
[in]opOperator specifying how the new selection is to be combined with the existing selection for the dataspace
[in]num_elemNumber of elements to be selected
[in]coordA pointer to a buffer containing a serialized copy of a 2-dimensional array of zero-based values specifying the coordinates of the elements in the point selection
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sselect_elements() selects array elements to be included in the selection for the space_id dataspace. This is referred to as a point selection.

The number of elements selected is set in the num_elements parameter.

The coord parameter is a pointer to a buffer containing a serialized 2-dimensional array of size num_elements by the rank of the dataspace. The array lists dataset elements in the point selection; that is, it's a list of zero-based values specifying the coordinates in the dataset of the selected elements. The order of the element coordinates in the coord array specifies the order in which the array elements are iterated through when I/O is performed. Duplicate coordinate locations are not checked for. See below for examples of the mapping between the serialized contents of the buffer and the point selection array that it represents.

The selection operator op determines how the new selection is to be combined with the previously existing selection for the dataspace. The following operators are supported:

H5S_SELECT_SET Replaces the existing selection with the parameters from this call. Overlapping blocks are not supported with this operator. Adds the new selection to the existing selection.
H5S_SELECT_APPEND Adds the new selection following the last element of the existing selection.
H5S_SELECT_PREPEND Adds the new selection preceding the first element of the existing selection.

Mapping the serialized coord buffer to a 2-dimensional point selection array: To illustrate the construction of the contents of the coord buffer, consider two simple examples: a selection of 5 points in a 1-dimensional array and a selection of 3 points in a 4-dimensional array.

In the 1D case, we will be selecting five points and a 1D dataspace has rank 1, so the selection will be described in a 5-by-1 array. To select the 1st, 14th, 17th, 23rd and 8th elements of the dataset, the selection array would be as follows (remembering that point coordinates are zero-based):
0
13
16
22
7

This point selection array will be serialized in the coord buffer as:
0 13 16 22 7

In the 4D case, we will be selecting three points and a 4D dataspace has rank 4, so the selection will be described in a 3-by-4 array. To select the points (1,1,1,1), (14,6,12,18), and (8,22,30,22), the point selection array would be as follows:
0 0 0 0
13 5 11 17
7 21 29 21

This point selection array will be serialized in the coord buffer as:
0 0 0 0 13 5 11 17 7 21 29 21

Version
1.6.4 C coord parameter type changed to const hsize_t.
1.6.4 Fortran coord parameter type changed to INTEGER(HSIZE_T).
Since
1.0.0

◆ H5Sselect_hyperslab()

herr_t H5Sselect_hyperslab ( hid_t  space_id,
H5S_seloper_t  op,
const hsize_t  start[],
const hsize_t  stride[],
const hsize_t  count[],
const hsize_t  block[] 
)

Selects a hyperslab region to add to the current selected region.

Parameters
[in]space_idDataspace identifier
[in]opOperation to perform on current selection
[in]startOffset of start of hyperslab
[in]strideHyperslab stride
[in]countNumber of blocks included in hyperslab
[in]blockSize of block in hyperslab
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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. For example, if the dataspace is 4-dimensional, each of these parameters must be a 1-dimensional array of size 4.

The selection operator op determines how the new selection is to be combined with the already existing selection for the dataspace. The following operators are supported:

H5S_SELECT_SET Replaces the existing selection with the parameters from this call. Overlapping blocks are not supported with this operator.
H5S_SELECT_OR Adds the new selection to the existing selection. (Binary OR)
H5S_SELECT_AND Retains only the overlapping portions of the new selection and the existing selection. (Binary AND)
H5S_SELECT_XOR Retains only the elements that are members of the new selection or the existing selection, excluding elements that are members of both selections. (Binary exclusive-OR, XOR)
H5S_SELECT_NOTB Retains only elements of the existing selection that are not in the new selection.
H5S_SELECT_NOTA Retains only elements of the new selection that are not in the existing selection.

The start array specifies the offset of the starting element of the specified hyperslab.

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 allocation 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 were set to 1).

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 each value in the block array were set to 1).

For example, consider a 2-dimensional dataspace with hyperslab selection settings as follows: the start offset is specified as [1,1], stride is [4,4], count is [3,7], and block is [2,2]. In C, these settings will specify a hyperslab consisting of 21 2x2 blocks of array elements starting with location (1,1) with the selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.; in Fortran, they will specify a hyperslab consisting of 21 2x2 blocks of array elements starting with location (2,2), since start is 0-based indexed, with the selected blocks at locations (2,2), (6,2), (10,2), (2,6), (6,6), etc.

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

Version
1.4.0 Fortran subroutine introduced in this release.
Since
1.0.0

◆ H5Sselect_intersect_block()

htri_t H5Sselect_intersect_block ( hid_t  space_id,
const hsize_t start,
const hsize_t end 
)

Checks if current selection intersects with a block.

Parameters
[in]space_idDataspace identifier
[in]startStarting coordinate of block
[in]endOpposite ("ending") coordinate of block
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5Sselect_intersect_block() checks to see if the current selection space_id in the dataspace intersects with the block specified by start and end.

Note
Assumes that start & end block bounds are inclusive, so start == end value is OK.
Since
1.10.6

◆ H5Sselect_none()

herr_t H5Sselect_none ( hid_t  spaceid)

Resets the selection region to include no elements.

Parameters
[in]spaceidDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sselect_none() resets the selection region for the dataspace space_id to include no elements.

Since
1.0.0

◆ H5Sselect_project_intersection()

hid_t H5Sselect_project_intersection ( hid_t  src_space_id,
hid_t  dst_space_id,
hid_t  src_intersect_space_id 
)

Projects the intersection of two source selections to a destination selection.

Parameters
[in]src_space_idDataspace identifier
[in]dst_space_idDataspace identifier
[in]src_intersect_space_idDataspace identifier
Returns
Returns a dataspace with a selection equal to the intersection of src_intersect_space_id and src_space_id projected from src_space to dst_space on success, negative on failure.

H5Sselect_project_intersection() computes the intersection between two dataspace selections and projects that intersection into a third selection.This can be useful for VOL developers to implement chunked or virtual datasets.

Since
1.10.6

◆ H5Sselect_shape_same()

htri_t H5Sselect_shape_same ( hid_t  space1_id,
hid_t  space2_id 
)

Checks if two selections are the same shape.

Parameters
[in]space1_idDataspace identifier
[in]space2_idDataspace identifier
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5Sselect_shape_same() checks to see if the current selection in the dataspaces are the same dimensionality and shape.

This is primarily used for reading the entire selection in one swoop.

Since
1.10.6

◆ H5Sselect_valid()

htri_t H5Sselect_valid ( hid_t  spaceid)

Verifies that the selection is within the extent of the dataspace.

Parameters
[in]spaceidDataspace identifier
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

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.

Version
1.4.0 Fortran subroutine introduced in this release.
Since
1.0.0

◆ H5Sset_extent_none()

herr_t H5Sset_extent_none ( hid_t  space_id)

Resets the extent of a dataspace back to "none".

Parameters
[in]space_idDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sset_extent_none() resets the type of a dataspace to H5S_NULL with no extent information stored for the dataspace.

Version
1.10.7, 1.12.1 The function behavior changed. The previous behavior was to set the class to H5S_NO_CLASS.
1.4.0 Fortran subroutine was introduced.
Since
1.0.0

◆ H5Sset_extent_simple()

herr_t H5Sset_extent_simple ( hid_t  space_id,
int  rank,
const hsize_t  dims[],
const hsize_t  max[] 
)

Sets or resets the size of an existing dataspace.

Parameters
[in]space_idDataspace identifier
[in]rankRank, or dimensionality, of the dataspace
[in]dimsArray containing current size of dataspace
[in]maxArray containing maximum size of dataspace
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Sset_extent_simple() sets or resets the size of an existing dataspace.

dims is an array of size rank that contains the new size of each dimension in the dataspace. max is an array of size rank that 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.

Version
1.4.0 Fortran subroutine was introduced.
Since
1.0.0