/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* * This file contains public declarations for the H5S module. */ #ifndef H5Spublic_H #define H5Spublic_H /**\defgroup H5S H5S * * Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections. * * HDF5 dataspaces describe the \Emph{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 \Emph{selections}. Furthermore, certain set operations are supported * for selections. * * * * * * * * * * * *
CreateRead
* \snippet{lineno} H5S_examples.c create * * \snippet{lineno} H5S_examples.c read *
UpdateDelete
* \snippet{lineno} H5S_examples.c update * * \snippet{lineno} H5S_examples.c delete *
* */ /* Public headers needed by this file */ #include "H5public.h" #include "H5Ipublic.h" /* Define atomic datatypes */ #define H5S_ALL (hid_t)0 #define H5S_UNLIMITED ((hsize_t)(hssize_t)(-1)) /** * The maximum dataspace rank or number of dimensions */ #define H5S_MAX_RANK 32 /** * Types of dataspaces */ typedef enum H5S_class_t { H5S_NO_CLASS = -1, /**< Error */ H5S_SCALAR = 0, /**< Singleton (scalar) */ H5S_SIMPLE = 1, /**< Regular grid */ H5S_NULL = 2 /**< Empty set */ } H5S_class_t; /** * Different ways of combining selections */ typedef enum H5S_seloper_t { H5S_SELECT_NOOP = -1, /**< Error */ H5S_SELECT_SET = 0, /**< Select "set" operation */ H5S_SELECT_OR, /**< Binary "or" operation for hyperslabs * (add new selection to existing selection) * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A or B: CCCCCCCCCCCCCCCC * \endcode */ H5S_SELECT_AND, /**< Binary "and" operation for hyperslabs * (only leave overlapped regions in selection) * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A and B: CCCC * \endcode */ H5S_SELECT_XOR, /**< Binary "xor" operation for hyperslabs * (only leave non-overlapped regions in selection) * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A xor B: CCCCCC CCCCCC * \endcode */ H5S_SELECT_NOTB, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in original selection) * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A not B: CCCCCC * \endcode */ H5S_SELECT_NOTA, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in new selection) * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * B not A: CCCCCC * \endcode */ H5S_SELECT_APPEND, /**< Append elements to end of point selection */ H5S_SELECT_PREPEND, /**< Prepend elements to beginning of point selection */ H5S_SELECT_INVALID /**< Invalid upper bound on selection operations */ } H5S_seloper_t; /** * Selection type */ typedef enum { H5S_SEL_ERROR = -1, /**< Error */ H5S_SEL_NONE = 0, /**< Empty selection */ H5S_SEL_POINTS = 1, /**< Set of points */ H5S_SEL_HYPERSLABS = 2, /**< Hyperslab */ H5S_SEL_ALL = 3, /**< Everything */ H5S_SEL_N /**< Sentinel \internal THIS MUST BE LAST */ } H5S_sel_type; #ifdef __cplusplus extern "C" { #endif /* Operations on dataspaces, dataspace selections and selection iterators */ /** * \ingroup H5S * * \brief Releases and terminates access to a dataspace * * \space_id * * \return \herr_t * * \details 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 * */ H5_DLL herr_t H5Sclose(hid_t space_id); /** * \ingroup H5S * * \brief Creates an exact copy of a dataspace * * \space_id * * \return \hid_tv{dataspace} * * \details H5Scopy() creates a new dataspace which is an exact copy of the * dataspace identified by \p 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 * */ H5_DLL hid_t H5Scopy(hid_t space_id); /** * \ingroup H5S * * \brief Creates a new dataspace of a specified type * * \param[in] type Type of dataspace to be created * * \return \hid_t{dataspace} * * \details 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 \p 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 * */ H5_DLL hid_t H5Screate(H5S_class_t type); /** * \ingroup H5S * \brief Creates a new simple dataspace and opens it for access * * \param[in] rank Number of dimensions of dataspace * \param[in] dims Array specifying the size of each dimension * \param[in] maxdims Array specifying the maximum size of each dimension * * \return \hid_t{dataspace} * * \details H5Screate_simple() creates a new simple dataspace and opens it * for access, returning a dataspace identifier. * * \p rank is the number of dimensions used in the dataspace. * * \p dims is a one-dimensional array of size rank specifying the * size of each dimension of the dataset. \p maxdims is an array of * the same size specifying the upper limit on the size of each * dimension. * * Any element of \p dims can be \p 0 (zero). Note that no data can * be written to a dataset if the size of any dimension of its current * dataspace is \p 0. This is sometimes a useful initial state for * a dataset. * * \p maxdims may be the null pointer, in which case the upper limit * is the same as \p dims. Otherwise, no element of \p maxdims * should be smaller than the corresponding element of \p dims. * * If an element of \p 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 \p dims * does not equal \p 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 * */ H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]); /** * \ingroup H5S * * \brief Decodes a binary object description of data space and returns a * new object handle * * \param[in] buf Buffer for the data space object to be decoded * * \return \hid_t{dataspace} * * \details 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 * */ H5_DLL hid_t H5Sdecode(const void *buf); /** * \ingroup H5S * * \brief Encodes a data space object description into a binary buffer * * \space_id{obj_id} * \param[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 \p nalloc. * \param[in,out] nalloc The size of the allocated buffer * * \return \herr_t * * \details Given the data space identifier \p 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 \p nalloc. * That value can then be assigned to \p nalloc for a second * H5Sencode()call, which will retrieve the actual encoded object. * * If the library determines that \p nalloc is not big enough for the * object, it simply returns the size of the buffer needed through * \p 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 * */ H5_DLL herr_t H5Sencode(hid_t obj_id, void *buf, size_t *nalloc); /** * \ingroup H5S * * \brief Copies the extent of a dataspace * * \space_id{dst_id} * \space_id{src_id} * * \return \herr_t * * \details H5Sextent_copy() copies the extent from \p src_id to \p dst_id. * This action may change the type of the dataspace. * * \version 1.4.0 Fortran subroutine was introduced. * \since 1.0.0 * */ H5_DLL herr_t H5Sextent_copy(hid_t dst_id, hid_t src_id); /** * \ingroup H5S * * \brief Determines whether two dataspace extents are equal * * \space_id{space1_id} * \space_id{space2_id} * * \return \htri_t * * \details H5Sextent_equal() determines whether the dataspace extents of * two dataspaces, \p space1_id and \p space2_id, are equal. * * \since 1.8.0 * */ H5_DLL htri_t H5Sextent_equal(hid_t space1_id, hid_t space2_id); /** * \ingroup H5S * * \brief Retrieves dataspace dimension size and maximum size * * \space_id * \param[out] dims Pointer to array to store the size of each dimension * \param[out] maxdims Pointer to array to store the maximum size of each * dimension * * \return Returns the number of dimensions in the dataspace if successful; * otherwise returns a negative value. * * \details H5Sget_simple_extent_dims() returns the size and maximum sizes * of each dimension of a dataspace \p space_id through the \p dims * and \p maxdims parameters. * * Either or both of \p dims and \p maxdims may be NULL. * * If a value in the returned array \p maxdims is #H5S_UNLIMITED (-1), * the maximum size of that dimension is unlimited. * * \version 1.4.0 Fortran subroutine introduced. * \since 1.0.0 * */ H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]); /** * \ingroup H5S * * \brief Determines the dimensionality of a dataspace * * \space_id * * \return Returns the number of dimensions in the dataspace if successful; * otherwise returns a negative value. * * \details H5Sget_simple_extent_ndims() determines the dimensionality (or * rank) of a dataspace. * * \version 1.4.0 Fortran subroutine introduced. * \since 1.0.0 * */ H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); /** * \ingroup H5S * * \brief Determines the number of elements in a dataspace * * \space_id * * \return Returns the number of elements in the dataspace if successful; * otherwise returns a negative value. * * \details H5Sget_simple_extent_npoints() determines the number of elements * in a dataspace \p 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 * */ H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id); /** * \ingroup H5S * * \brief Determines the current class of a dataspace * * \space_id * * \return Returns a dataspace class name if successful; * otherwise #H5S_NO_CLASS (-1). * * \details H5Sget_simple_extent_type() determines the current class of a * dataspace \p space_id. * * \version 1.4.0 Fortran subroutine was introduced. * \since 1.0.0 * */ H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id); /** * \ingroup H5S * * \brief Determines whether a dataspace is a simple dataspace * * \space_id * * \return \htri_t * * \details 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 * */ H5_DLL htri_t H5Sis_simple(hid_t space_id); /*--------------------------------------------------------------------------*/ /**\ingroup H5S * * \brief Resets the extent of a dataspace back to "none" * * \space_id * * \return \herr_t * * \details 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. * \version 1.4.0 Fortran subroutine was introduced. * \since 1.0.0 * */ H5_DLL herr_t H5Sset_extent_none(hid_t space_id); /*--------------------------------------------------------------------------*/ /**\ingroup H5S * * \brief Sets or resets the size of an existing dataspace * * \space_id * \param[in] rank Rank, or dimensionality, of the dataspace * \param[in] dims Array containing current size of dataspace * \param[in] max Array containing maximum size of dataspace * * \return \herr_t * * \details H5Sset_extent_simple() sets or resets the size of an existing * dataspace. * * \p rank is the dimensionality, or number of dimensions, of the * dataspace. * * \p dims is an array of size \p rank which contains the new size * of each dimension in the dataspace. \p max is an array of size * \p 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 \p dims does not equal * \p max. * * * \version 1.4.0 Fortran subroutine was introduced. * \since 1.0.0 * */ H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]); /* #define NEW_HYPERSLAB_API */ #ifdef NEW_HYPERSLAB_API /* Operations on dataspace selections */ /** * \ingroup H5S * * \brief Performs an operation on a hyperslab and an existing selection and * returns the resulting selection * * \space_id * \param[in] op Operation to perform on the current selection * \param[in] start Offset of the start of of the hyperslab * \param[in] stride Hyperslab stride * \param[in] count Number of blocks included in the hyperslab * \param[in] block Size of a block in the hyperslab * * \return \hid_tv{dataspace} * * \details H5Scombine_hyperslab() combines a hyperslab selection specified * by \p start, \p stride, \p count and \p block with the current * selection for the dataspace \p 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 \p stride or * \p block is NULL, then it will be set to \p 1. * * \since 1.10.6 * */ H5_DLL 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[]); /** * \ingroup H5S * * \brief Combine two hyperslab selections with an operation, returning a * dataspace with the resulting selection * * \space_id{space1_id} * \param[in] op Selection operator * \space_id{space2_id} * * \return \hid_t{dataspace} * * \details H5Scombine_select() combines two hyperslab selections * \p space1_id and \p space2_id with an operation, returning a * new dataspace with the resulting selection. The dataspace extent * from \p space1_id is copied for the dataspace extent of the * newly created dataspace. * * \since 1.10.6 * */ H5_DLL hid_t H5Scombine_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); #endif /* NEW_HYPERSLAB_API */ /** * \ingroup H5S * * \brief Gets the bounding box containing the current selection * * \space_id{spaceid} * \param[out] start Starting coordinates of the bounding box * \param[out] end Ending coordinates of the bounding box, i.e., the * coordinates of the diagonally opposite corner * * \return \herr_t * * \details H5Sget_select_bounds() retrieves the coordinates of the bounding * box containing the current selection and places them into * user-supplied buffers. * * The \p start and \p 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 \a none selection will fail. * * \version 1.6.0 The \p start and \p end parameters have changed from type * \p hsize_t * to \p hssize_t *. * \version 1.4.0 Fortran subroutine was introduced. * \since 1.2.0 * */ H5_DLL herr_t H5Sget_select_bounds(hid_t spaceid, hsize_t start[], hsize_t end[]); /** * \ingroup H5S * * \brief Gets the number of element points in the current selection * * \space_id{spaceid} * * \return Returns the number of element points in the current dataspace * selection if successful. Otherwise returns a negative value. * * \details 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 * */ H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid); /** * \ingroup H5S * * \brief Gets the list of element points currently selected * * \space_id{spaceid} * \param[in] startpoint Element point to start with * \param[in] numpoints Number of element points to get * \param[out] buf List of element points selected * * \details H5Sget_select_elem_pointlist() returns the list of element * points in the current dataspace selection \p space_id. Starting * with the \p startpoint in the list of points, \p numpoints * points are put into the user's buffer. If the user's buffer * fills up before \p 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:\n * \, followed by\n * the next coordinate,\n * etc.\n * 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 * */ H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, hsize_t buf[/*numpoints*/]); /** * \ingroup H5S * * \brief Gets the list of hyperslab blocks currently selected * * \space_id{spaceid} * \param[in] startblock Hyperslab block to start with * \param[in] numblocks Number of hyperslab blocks to get * \param[out] buf List of hyperslab blocks selected * * \return \herr_t * * \details H5Sget_select_hyper_blocklist() returns a list of the hyperslab * blocks currently selected. Starting with the \p startblock-th block * in the list of blocks, \p numblocks blocks are put into the * user's buffer. If the user's buffer fills up before \p 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:\n * \<"start" coordinate\>, immediately followed by\n * \<"opposite" corner coordinate\>, followed by\n * the next "start" and "opposite" coordinates,\n * etc. until all of the selected blocks have been listed.\n * No guarantee of any order of the blocks is implied. * * \since 1.2.0 * */ H5_DLL herr_t H5Sget_select_hyper_blocklist(hid_t spaceid, hsize_t startblock, hsize_t numblocks, hsize_t buf[/*numblocks*/]); /** * \ingroup H5S * * \brief Get number of hyperslab blocks * * \space_id{spaceid} * * \return Returns the number of hyperslab blocks in the current dataspace * selection if successful. Otherwise returns a negative value. * * \details H5Sget_select_hyper_nblocks() returns the number of hyperslab * blocks in the current dataspace selection. * * \since 1.2.0 * */ H5_DLL hssize_t H5Sget_select_hyper_nblocks(hid_t spaceid); /** * \ingroup H5S * * \brief Determines the number of elements in a dataspace selection * * \space_id{spaceid} * * \return Returns the number of elements in the selection if successful; * otherwise returns a negative value. * * \details 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 * */ H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); /** * \ingroup H5S * * \brief Determines the type of the dataspace selection * * \space_id{spaceid} * * \return Returns the dataspace selection type, a value of the enumerated * datatype #H5S_sel_type, if successful. * * \details H5Sget_select_type() retrieves the type of dataspace selection * currently defined for the dataspace \p space_id. Valid values * for the dataspace selection type are: * * * * * * * * * * * * * * * * * * *
#H5S_SEL_NONENo selection is defined
#H5S_SEL_POINTSA sequence of points is selected
#H5S_SEL_HYPERSLABSA hyperslab or compound hyperslab is selected
#H5S_SEL_ALLThe entire dataset is selected
* * Otherwise returns a negative value. * * \since 1.6.0 * */ H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid); /** * \ingroup H5S * * \brief Sets the offset of a simple dataspace * * \space_id * \param[in] offset The offset at which to position the selection * * \return \herr_t * * \details H5Soffset_simple() sets the offset of a simple dataspace * \p space_id. The offset array must be the same number of * elements as the number of dimensions for the dataspace. If the * \p 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 * */ H5_DLL herr_t H5Soffset_simple(hid_t space_id, const hssize_t *offset); /** * \ingroup H5S * * \brief Selects an entire dataspace * * \space_id{spaceid} * * \return \herr_t * * \details H5Sselect_all() selects the entire extent of the dataspace * \p 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 * */ H5_DLL herr_t H5Sselect_all(hid_t spaceid); /** * \ingroup H5S * * \brief Selects array elements to be included in the selection for a * dataspace * * \space_id * \param[in] op Operator specifying how the new selection is to be * combined with the existing selection for the dataspace * \param[in] num_elem Number of elements to be selected * \param[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 * * \return \herr_t * * \details H5Sselect_elements() selects array elements to be included in * the selection for the \p space_id dataspace. This is referred * to as a point selection. * * The number of elements selected is set in the \p num_elements * parameter. * * The \p coord parameter is a pointer to a buffer containing a * serialized 2-dimensional array of size \p 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 \p 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 \p 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_SETReplaces 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_APPENDAdds the new selection following the last element of the * existing selection.
#H5S_SELECT_PREPENDAdds the new selection preceding the first element of the * existing selection.
* * Mapping the serialized \p coord buffer to a 2-dimensional * point selection array: * To illustrate the construction of the contents of the \p 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): * \n 0 * \n 13 * \n 16 * \n 22 * \n 7 * * This point selection array will be serialized in the \p coord * buffer as: * \n 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: * \n 0 0 0 0 * \n 13 5 11 17 * \n 7 21 29 21 * * This point selection array will be serialized in the \p coord * buffer as: * \n 0 0 0 0 13 5 11 17 7 21 29 21 * * \version 1.6.4 C coord parameter type changed to \p const hsize_t. * \version 1.6.4 Fortran \p coord parameter type changed to \p INTEGER(HSIZE_T). * \since 1.0.0 * */ H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_elem, const hsize_t *coord); /** * \ingroup H5S * * \brief Selects a hyperslab region to add to the current selected region * * \space_id * \param[in] op Operation to perform on current selection * \param[in] start Offset of start of hyperslab * \param[in] stride Hyperslab stride * \param[in] count Number of blocks included in hyperslab * \param[in] block Size of block in hyperslab * * \return \herr_t * * \details H5Sselect_hyperslab() selects a hyperslab region to add to the * current selected region for the dataspace specified by * \p space_id. * * The \p start, \p stride, \p count, and \p 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 \p 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_SETReplaces the existing selection with the * parameters from this call. Overlapping blocks * are not supported with this operator.
#H5S_SELECT_ORAdds the new selection to the existing selection. * (Binary OR)
#H5S_SELECT_ANDRetains only the overlapping portions of the * new selection and the existing selection. * (Binary AND)
#H5S_SELECT_XORRetains 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_NOTBRetains only elements of the existing selection * that are not in the new selection.
#H5S_SELECT_NOTARetains only elements of the new selection that * are not in the existing selection.
* * The \p start array specifies the offset of the starting element * of the specified hyperslab. * * The \p stride array chooses array locations from the dataspace with * each value in the \p stride array determining how many elements to * move in each dimension. Setting a value in the \p stride array to * \p 1 moves to each element in that dimension of the dataspace; * setting a value of \p 2 in allocation in the \p stride array moves * to every other element in that dimension of the dataspace. In * other words, the \p stride determines the number of elements to * move from the \p start location in each dimension. Stride values * of \p 0 are not allowed. If the \p stride parameter is NULL, a * contiguous hyperslab is selected (as if each value in the \p stride * array were set to \p 1). * * The \p count array determines how many blocks to select from the * dataspace, in each dimension. * * The \p block array determines the size of the element block * selected from the dataspace. If the \p block parameter is set to * NULL, the block size defaults to a single element in each dimension * (as if each value in the \p block array were set to \p 1). * * For example, consider a 2-dimensional dataspace with hyperslab * selection settings as follows: the \p start offset is specified as * [1,1], \p stride is [4,4], \p count is [3,7], and \p 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 * */ H5_DLL 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[]); /*--------------------------------------------------------------------------*/ /**\ingroup H5S * * \brief Resets the selection region to include no elements * * \space_id{spaceid} * * \return \herr_t * * \details H5Sselect_none() resets the selection region for the dataspace * \p space_id to include no elements. * * \since 1.0.0 * */ H5_DLL herr_t H5Sselect_none(hid_t spaceid); /*--------------------------------------------------------------------------*/ /**\ingroup H5S * * \brief Verifies that the selection is within the extent of the dataspace * * \space_id{spaceid} * * \return \htri_t * * \details H5Sselect_valid() verifies that the selection for the dataspace * \p 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 * */ H5_DLL htri_t H5Sselect_valid(hid_t spaceid); #ifdef __cplusplus } #endif #endif /* H5Spublic_H */