Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

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 | H5Sencode1 (hid_t obj_id, void *buf, size_t *nalloc)
| Encodes a data space object description into a binary buffer.
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.

## 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_id | Dataspace 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_id | Dataspace identifier
  [in] | op | Operation to perform on the current selection
  [in] | start | Offset of the start of of the hyperslab
  [in] | stride | Hyperslab stride
  [in] | count | Number of blocks included in the hyperslab
  [in] | block | Size of a block in the hyperslab

Returns
  Returns a dataspace identifier if successful; otherwise returns H5I_INVALID_HID.

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`.

See H5Sselect_hyperslab() for valid operators (`op`).

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_id | Dataspace identifier
  [in] | op | Selection operator
  [in] | space2_id | Dataspace 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.

See H5Sselect_hyperslab() for valid operators (`op`).

Since
  1.10.6

## ◆ H5Scopy()

hid_t H5Scopy | ( | hid_t | space_id | ) |

Creates an exact copy of a dataspace.

Parameters

  [in] | space_id | Dataspace identifier

Returns
  Returns a dataspace identifier if successful; otherwise returns H5I_INVALID_HID.

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] | type | Type 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 composite 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 composite.

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] | rank | Number of dimensions of dataspace
  [in] | dims | Array specifying the size of each dimension
  [in] | maxdims | Array 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] | buf | Buffer 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_id | Dataspace identifier
  [in,out] | buf | Buffer 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] | nalloc | The 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_id | Dataspace identifier
  [in,out] | buf | Buffer 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] | nalloc | The size of the allocated buffer
  [in] | fapl | File 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 H5Sencode() / 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_id | Dataspace identifier
  [in] | src_id | Dataspace 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_id | Dataspace identifier
  [in] | space2_id | Dataspace 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] | spaceid | Dataspace identifier
  [out] | start | Offset of the start of the regular hyperslab
  [out] | stride | Stride of the regular hyperslab
  [out] | count | Number of blocks in the regular hyperslab
  [out] | block | Size 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] | spaceid | Dataspace identifier
  [out] | start | Starting coordinates of the bounding box
  [out] | end | Ending 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] | spaceid | Dataspace 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] | spaceid | Dataspace identifier
  [in] | startpoint | Element point to start with
  [in] | numpoints | Number of element points to get
  [out] | buf | List of element points selected

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

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] | spaceid | Dataspace identifier
  [in] | startblock | Hyperslab block to start with
  [in] | numblocks | Number of hyperslab blocks to get
  [out] | buf | List 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] | spaceid | Dataspace 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] | spaceid | Dataspace 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] | spaceid | Dataspace 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_id | Dataspace identifier
  [out] | dims | Pointer to array to store the size of each dimension
  [out] | maxdims | Pointer 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_id | Dataspace 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_id | Dataspace 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_id | Dataspace 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] | spaceid | Dataspace 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_id | Dataspace 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_id | Dataspace identifier
  [in] | op | Selection operator
  [in] | space2_id | Dataspace 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`.

See H5Sselect_hyperslab() for valid operators (`op`).

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_id | Dataspace identifier
  [in] | offset | The 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 in all dimensions.

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

Note
  Until 1.14.4, setting the offset parameter to NULL was considered an error, despite the reference manual stating that it had the behavior described above.

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_id | Identifier of the dataspace selection iterator

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] | spaceid | Dataspace identifier
  [in] | elmt_size | Size of element in the selection
  [in] | flags | Selection iterator flag, valid values are: H5S_SEL_ITER_GET_SEQ_LIST_SORTED H5S_SEL_ITER_SHARE_WITH_DATASPACE

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_id | Identifier of the dataspace selection iterator
  [in] | maxseq | Maximum number of sequences to retrieve
  [in] | maxelmts | Maximum number of elements to retrieve in sequences
  [out] | nseq | Number of sequences retrieved
  [out] | nelmts | Number of elements retrieved, in all sequences
  [out] | off | Array of sequence offsets
  [out] | len | Array 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_id | Identifier of the dataspace selection iterator to reset
  [in] | space_id | Identifier 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] | spaceid | Dataspace identifier
  [in] | offset | Offset 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] | spaceid | Dataspace 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_id | Dataspace identifier
  [in] | src_id | Dataspace 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_id | Dataspace identifier
  [in] | op | Operator specifying how the new selection is to be combined with the existing selection for the dataspace
  [in] | num_elem | Number of elements to be selected
  [in] | coord | A 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_id | Dataspace identifier
  [in] | op | Operation to perform on current selection
  [in] | start | Offset of start of hyperslab
  [in] | stride | Hyperslab stride
  [in] | count | Number of blocks included in hyperslab
  [in] | block | Size 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_id | Dataspace identifier
  [in] | start | Starting coordinate of block
  [in] | end | Opposite ("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] | spaceid | Dataspace 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_id | Dataspace identifier
  [in] | dst_space_id | Dataspace identifier
  [in] | src_intersect_space_id | Dataspace 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_id | Dataspace identifier
  [in] | space2_id | Dataspace 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.7

## ◆ H5Sselect_valid()

htri_t H5Sselect_valid | ( | hid_t | spaceid | ) |

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

Parameters

  [in] | spaceid | Dataspace 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_id | Dataspace 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_id | Dataspace identifier
  [in] | rank | Rank, or dimensionality, of the dataspace
  [in] | dims | Array containing current size of dataspace
  [in] | max | Array 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