 |
HDF5 2.0.0.258fa78
API Reference
|
|
HDF5 2.0.0.258fa78
API Reference
|
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. | |
| #define H5Sencode H5Sencode2 |
H5Sencode() is a macro that is mapped to either H5Sencode1() or H5Sencode2().
Releases and terminates access to a dataspace.
| [in] | space_id | Dataspace identifier |
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.
| 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.
| [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 |
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).
| 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.
| [in] | space1_id | Dataspace identifier |
| [in] | op | Selection operator |
| [in] | space2_id | Dataspace identifier |
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).
Creates an exact copy of a dataspace.
| [in] | space_id | Dataspace identifier |
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.
| hid_t H5Screate | ( | H5S_class_t | type | ) |
Creates a new dataspace of a specified type.
| [in] | type | Type of dataspace to be created |
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.
Creates a new simple dataspace and opens it for access.
| [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 |
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.
| hid_t H5Sdecode | ( | const void * | buf | ) |
Decodes a binary object description of data space and returns a new object handle.
| [in] | buf | Buffer for the data space object to be decoded |
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.
Encodes a data space object description into a binary buffer.
| [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 |
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.
Encodes a data space object description into a binary buffer.
| [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 |
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.
Copies the extent of a dataspace.
| [in] | dst_id | Dataspace identifier |
| [in] | src_id | Dataspace identifier |
H5Sextent_copy() copies the extent from src_id to dst_id. This action may change the type of the dataspace.
Determines whether two dataspace extents are equal.
| [in] | space1_id | Dataspace identifier |
| [in] | space2_id | Dataspace identifier |
H5Sextent_equal() determines whether the dataspace extents of two dataspaces, space1_id and space2_id, 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.
| [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 |
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.
Gets the bounding box containing the current selection.
| [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 |
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.
start and end parameters have changed from type hsize_t * to hssize_t *. Gets the number of element points in the current selection.
| [in] | spaceid | Dataspace identifier |
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.
| 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.
| [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.
| 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.
| [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 |
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.
Get number of hyperslab blocks.
| [in] | spaceid | Dataspace identifier |
H5Sget_select_hyper_nblocks() returns the number of hyperslab blocks in the current dataspace selection.
Determines the number of elements in a dataspace selection.
| [in] | spaceid | Dataspace identifier |
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.
| H5S_sel_type H5Sget_select_type | ( | hid_t | spaceid | ) |
Determines the type of the dataspace selection.
| [in] | spaceid | Dataspace identifier |
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.
Retrieves dataspace dimension size and maximum size.
| [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 |
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.
| int H5Sget_simple_extent_ndims | ( | hid_t | space_id | ) |
Determines the dimensionality of a dataspace.
| [in] | space_id | Dataspace identifier |
H5Sget_simple_extent_ndims() determines the dimensionality (or rank) of a dataspace.
Determines the number of elements in a dataspace.
| [in] | space_id | Dataspace identifier |
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.
| H5S_class_t H5Sget_simple_extent_type | ( | hid_t | space_id | ) |
Determines the current class of a dataspace.
| [in] | space_id | Dataspace identifier |
H5Sget_simple_extent_type() determines the current class of a dataspace space_id.
Determines if a hyperslab selection is regular.
| [in] | spaceid | Dataspace identifier |
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.
Determines whether a dataspace is a simple dataspace.
| [in] | space_id | Dataspace identifier |
H5Sis_simple() determines whether or not 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.
| [in] | space1_id | Dataspace identifier |
| [in] | op | Selection operator |
| [in] | space2_id | Dataspace identifier |
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).
Sets the offset of a simple dataspace.
| [in] | space_id | Dataspace identifier |
| [in] | offset | The offset at which to position the selection |
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.
Closes a dataspace selection iterator.
| [in] | sel_iter_id | Identifier of the dataspace selection iterator |
H5Ssel_iter_close() closes a dataspace selection iterator specified by sel_iter_id, releasing its state.
Creates a dataspace selection iterator for a dataspace's selection.
| [in] | spaceid | Dataspace identifier |
| [in] | elmt_size | Size of element in the selection |
| [in] | flags | Selection iterator flag, valid values are: |
H5Ssel_iter_create() creates a selection iterator and initializes it to start at the first element selected in the dataspace.
| 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.
| [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 |
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.
Resets a dataspace selection iterator back to an initial state.
| [in] | sel_iter_id | Identifier of the dataspace selection iterator to reset |
| [in] | space_id | Identifier of the dataspace with selection to iterate over |
H5Ssel_iter_reset() resets a dataspace selection iterator back to an initial state so that the iterator may be used for iteration once again.
Adjusts a selection by subtracting an offset.
| [in] | spaceid | Dataspace identifier |
| [in] | offset | Offset to subtract |
H5Sselect_adjust() shifts a dataspace selection by a specified logical offset within the dataspace extent.
Selects an entire dataspace.
| [in] | spaceid | Dataspace identifier |
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.
Copies a selection from one dataspace to another.
| [in] | dst_id | Dataspace identifier |
| [in] | src_id | Dataspace identifier |
H5Sselect_copy() copies all selection information (including offset) from the source dataspace src_id to the destination dataspace dst_id.
| 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.
| [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 |
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
const hsize_t. coord parameter type changed to INTEGER(HSIZE_T). | 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.
| [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 |
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.
Checks if current selection intersects with a block.
| [in] | space_id | Dataspace identifier |
| [in] | start | Starting coordinate of block |
| [in] | end | Opposite ("ending") coordinate of block |
H5Sselect_intersect_block() checks to see if the current selection space_id in the dataspace intersects with the block specified by start and end.
start & end block bounds are inclusive, so start == end value is OK.Resets the selection region to include no elements.
| [in] | spaceid | Dataspace identifier |
H5Sselect_none() resets the selection region for the dataspace space_id 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.
| [in] | src_space_id | Dataspace identifier |
| [in] | dst_space_id | Dataspace identifier |
| [in] | src_intersect_space_id | Dataspace identifier |
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.
Checks if two selections are the same shape.
| [in] | space1_id | Dataspace identifier |
| [in] | space2_id | Dataspace identifier |
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.
Verifies that the selection is within the extent of the dataspace.
| [in] | spaceid | Dataspace identifier |
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.
Resets the extent of a dataspace back to "none".
| [in] | space_id | Dataspace identifier |
H5Sset_extent_none() resets the type of a dataspace to H5S_NULL with no extent information stored for the dataspace.
Sets or resets the size of an existing dataspace.
| [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 |
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.
1.9.7