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.

Create	Read
{ __label__ fail_dspace; hid_t dspace; // create a 2D chess board shape (8x8) if ((dspace = H5Screate_simple(2, (hsize_t[]){8, 8}, NULL)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_dspace; } H5Sclose(dspace); fail_dspace:; }	{ __label__ fail_dspace; hid_t dspace; if ((dspace = H5Screate(H5S_NULL)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_dspace; } // make changes to the selection on DSPACE // ... // parse the resulting selection switch (H5Sget_select_type(dspace)) { case H5S_SEL_HYPERSLABS: // we are dealing with a hyperslab selection // determine the regularity and block structure break; case H5S_SEL_POINTS: // we are dealing with a point selection // for example, retrieve the point list break; case H5S_SEL_ALL: // all dataset elements are selected break; case H5S_SEL_NONE: // the selection is empty break; default: ret_val = EXIT_FAILURE; break; } if (dspace != H5S_ALL) H5Sclose(dspace); fail_dspace:; }
Update	Delete
{ __label__ fail_select, fail_dspace; hid_t dspace; // create a 2D chess board shape (8x8) if ((dspace = H5Screate_simple(2, (hsize_t[]){8, 8}, NULL)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_dspace; } // select all black fields: do this w/ a hyperslab union in two steps // select the black fields on even rows if (H5Sselect_hyperslab(dspace, H5S_SELECT_SET, (hsize_t[]){0, 0}, (hsize_t[]){2, 2}, (hsize_t[]){4, 4}, NULL) < 0) { ret_val = EXIT_FAILURE; goto fail_select; } // select the black fields on odd rows // notice the H5S_SELECT_OR operator if (H5Sselect_hyperslab(dspace, H5S_SELECT_OR, (hsize_t[]){1, 1}, (hsize_t[]){2, 2}, (hsize_t[]){4, 4}, NULL) < 0) { ret_val = EXIT_FAILURE; goto fail_select; } // should be 32 printf("%lld elements selected.\n", H5Sget_select_npoints(dspace)); fail_select: H5Sclose(dspace); fail_dspace:; }	{ __label__ fail_select, fail_dspace; hid_t dspace; if ((dspace = H5Screate(H5S_NULL)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_dspace; } // make changes to and work with the selection on DSPACE // ... // finally, clear the selection if (H5Sselect_none(dspace) < 0) { ret_val = EXIT_FAILURE; goto fail_select; } fail_select: if (dspace != H5S_ALL) H5Sclose(dspace); fail_dspace:; }

Functions
herr_t	H5Sclose (hid_t space_id)
	Releases and terminates access to a dataspace. More...
hid_t	H5Scopy (hid_t space_id)
	Creates an exact copy of a dataspace. More...
hid_t	H5Screate (H5S_class_t type)
	Creates a new dataspace of a specified type. More...
hid_t	H5Screate_simple (int rank, const hsize_t dims[], const hsize_t maxdims[])
	Creates a new simple dataspace and opens it for access. More...
hid_t	H5Sdecode (const void *buf)
	Decodes a binary object description of data space and returns a new object handle. More...
herr_t	H5Sencode (hid_t obj_id, void *buf, size_t *nalloc)
	Encodes a data space object description into a binary buffer. More...
herr_t	H5Sextent_copy (hid_t dst_id, hid_t src_id)
	Copies the extent of a dataspace. More...
htri_t	H5Sextent_equal (hid_t space1_id, hid_t space2_id)
	Determines whether two dataspace extents are equal. More...
int	H5Sget_simple_extent_dims (hid_t space_id, hsize_t dims[], hsize_t maxdims[])
	Retrieves dataspace dimension size and maximum size. More...
int	H5Sget_simple_extent_ndims (hid_t space_id)
	Determines the dimensionality of a dataspace. More...
hssize_t	H5Sget_simple_extent_npoints (hid_t space_id)
	Determines the number of elements in a dataspace. More...
H5S_class_t	H5Sget_simple_extent_type (hid_t space_id)
	Determines the current class of a dataspace. More...
htri_t	H5Sis_simple (hid_t space_id)
	Determines whether a dataspace is a simple dataspace. More...
herr_t	H5Sset_extent_none (hid_t space_id)
	Resets the extent of a dataspace back to "none". More...
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. More...
herr_t	H5Sget_select_bounds (hid_t spaceid, hsize_t start[], hsize_t end[])
	Gets the bounding box containing the current selection. More...
hssize_t	H5Sget_select_elem_npoints (hid_t spaceid)
	Gets the number of element points in the current selection. More...
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. More...
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. More...
hssize_t	H5Sget_select_hyper_nblocks (hid_t spaceid)
	Get number of hyperslab blocks. More...
hssize_t	H5Sget_select_npoints (hid_t spaceid)
	Determines the number of elements in a dataspace selection. More...
H5S_sel_type	H5Sget_select_type (hid_t spaceid)
	Determines the type of the dataspace selection. More...
herr_t	H5Soffset_simple (hid_t space_id, const hssize_t *offset)
	Sets the offset of a simple dataspace. More...
herr_t	H5Sselect_all (hid_t spaceid)
	Selects an entire dataspace. More...
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. More...
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. More...
herr_t	H5Sselect_none (hid_t spaceid)
	Resets the selection region to include no elements. More...
htri_t	H5Sselect_valid (hid_t spaceid)
	Verifies that the selection is within the extent of the dataspace. More...

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

H5Scopy()

hid_t H5Scopy

(

hid_t

space_id

)

Creates an exact copy of a dataspace.

Parameters

[in]

space_id

Dataspace 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]

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 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]	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

H5Sencode()

herr_t H5Sencode	(	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.

Given the data space identifier obj_id, H5Sencode() 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 H5Sencode() 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 H5Sencode()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 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.

Since

1.8.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_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

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_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

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.

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

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_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 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, 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) 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_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_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 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.

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

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

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

Note that a dataset must be chunked if dims does not equal max.

Version

1.4.0 Fortran subroutine was introduced.

Since

1.0.0