EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-09-18 09:39:19
0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 0002 * Copyright by The HDF Group. * 0003 * All rights reserved. * 0004 * * 0005 * This file is part of HDF5. The full HDF5 copyright notice, including * 0006 * terms governing use, modification, and redistribution, is contained in * 0007 * the COPYING file, which can be found at the root of the source code * 0008 * distribution tree, or in https://www.hdfgroup.org/licenses. * 0009 * If you do not have access to either file, you may request a copy from * 0010 * help@hdfgroup.org. * 0011 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 0012 0013 /* 0014 * This file contains public declarations for the H5S module. 0015 */ 0016 #ifndef H5Spublic_H 0017 #define H5Spublic_H 0018 0019 #include "H5public.h" /* Generic Functions */ 0020 #include "H5Ipublic.h" /* Identifiers */ 0021 0022 /* Define special dataspaces for dataset I/O operations */ 0023 0024 /** 0025 * Used with @ref H5Dread and @ref H5Dwrite to indicate that the entire 0026 * dataspace will be selected. In the case of a file dataspace, this means 0027 * that the entire file dataspace, as defined by the dataset's dimensions, 0028 * will be selected. In the case of a memory dataspace, this means that 0029 * the specified file dataspace will also be used for the memory dataspace. 0030 * Used in place of a file or memory dataspace @ref hid_t value. 0031 */ 0032 #define H5S_ALL 0 0033 0034 /** 0035 * Indicates that the buffer provided in a call to @ref H5Dread or @ref H5Dwrite 0036 * is a single contiguous block of memory, with the same number of elements 0037 * as the file dataspace. Used in place of a memory dataspace @ref hid_t value. 0038 */ 0039 #define H5S_BLOCK 1 0040 0041 /** 0042 * Used with @ref H5Dread and @ref H5Dwrite to indicate that the file dataspace 0043 * selection was set via @ref H5Pset_dataset_io_hyperslab_selection calls. 0044 * Used in place of a file dataspace @ref hid_t value. 0045 */ 0046 #define H5S_PLIST 2 0047 0048 #define H5S_UNLIMITED HSIZE_UNDEF /**< Value for 'unlimited' dimensions */ 0049 0050 /** 0051 * The maximum dataspace rank or number of dimensions 0052 */ 0053 #define H5S_MAX_RANK 32 0054 0055 /* Flags for selection iterators */ 0056 #define H5S_SEL_ITER_GET_SEQ_LIST_SORTED \ 0057 0x0001 /**< Retrieve elements from iterator in increasing offset order, for \ 0058 * each call to retrieve sequences. Currently, this only applies to \ 0059 * point selections, as hyperslab selections are always returned in \ 0060 * increasing offset order. Note that the order is only increasing \ 0061 * for each call to H5Sget_seq_list(), the next set of sequences \ 0062 * could start with an earlier offset than the previous one. \ 0063 * \ 0064 * \since 1.12.0 \ 0065 */ 0066 #define H5S_SEL_ITER_SHARE_WITH_DATASPACE \ 0067 0x0002 /**< Don't copy the dataspace selection when creating the selection \ 0068 * iterator. This can improve performance of creating the iterator, \ 0069 * but the dataspace \Bold{MUST NOT} be modified or closed until the \ 0070 * selection iterator is closed or the iterator's behavior will be \ 0071 * undefined. \ 0072 * \ 0073 * \since 1.12.0 \ 0074 */ 0075 0076 /** 0077 * Types of dataspaces 0078 */ 0079 typedef enum H5S_class_t { 0080 H5S_NO_CLASS = -1, /**< Error \since 1.0.0 */ 0081 H5S_SCALAR = 0, /**< Singleton (scalar) \since 1.0.0 */ 0082 H5S_SIMPLE = 1, /**< Regular grid \since 1.0.0 */ 0083 H5S_NULL = 2 /**< Empty set \since 1.8.0 */ 0084 } H5S_class_t; 0085 0086 /** 0087 * Different ways of combining selections 0088 */ 0089 typedef enum H5S_seloper_t { 0090 H5S_SELECT_NOOP = -1, /**< Error \since 1.0.0 */ 0091 H5S_SELECT_SET = 0, /**< Select "set" operation \since 1.0.0 */ 0092 H5S_SELECT_OR, /**< Binary "or" operation for hyperslabs 0093 * (add new selection to existing selection) 0094 * \code 0095 * Original region: AAAAAAAAAA 0096 * New region: BBBBBBBBBB 0097 * A or B: CCCCCCCCCCCCCCCC 0098 * \endcode 0099 * 0100 * \since 1.0.0 0101 */ 0102 H5S_SELECT_AND, /**< Binary "and" operation for hyperslabs 0103 * (only leave overlapped regions in selection) 0104 * \code 0105 * Original region: AAAAAAAAAA 0106 * New region: BBBBBBBBBB 0107 * A and B: CCCC 0108 * \endcode 0109 * 0110 * \since 1.6.0 0111 */ 0112 H5S_SELECT_XOR, /**< Binary "xor" operation for hyperslabs 0113 * (only leave non-overlapped regions in selection) 0114 * \code 0115 * Original region: AAAAAAAAAA 0116 * New region: BBBBBBBBBB 0117 * A xor B: CCCCCC CCCCCC 0118 * \endcode 0119 * 0120 * \since 1.6.0 0121 */ 0122 H5S_SELECT_NOTB, /**< Binary "not" operation for hyperslabs 0123 * (only leave non-overlapped regions in original selection) 0124 * \code 0125 * Original region: AAAAAAAAAA 0126 * New region: BBBBBBBBBB 0127 * A not B: CCCCCC 0128 * \endcode 0129 * 0130 * \since 1.6.0 0131 */ 0132 H5S_SELECT_NOTA, /**< Binary "not" operation for hyperslabs 0133 * (only leave non-overlapped regions in new selection) 0134 * \code 0135 * Original region: AAAAAAAAAA 0136 * New region: BBBBBBBBBB 0137 * B not A: CCCCCC 0138 * \endcode 0139 * 0140 * \since 1.6.0 0141 */ 0142 H5S_SELECT_APPEND, /**< Append elements to end of point selection \since 1.4.0 */ 0143 H5S_SELECT_PREPEND, /**< Prepend elements to beginning of point selection \since 1.4.0 */ 0144 H5S_SELECT_INVALID /**< Invalid upper bound on selection operations \since 1.0.0 */ 0145 } H5S_seloper_t; 0146 0147 /** 0148 * Selection type 0149 */ 0150 typedef enum { 0151 H5S_SEL_ERROR = -1, /**< Error \since 1.0.0 */ 0152 H5S_SEL_NONE = 0, /**< Empty selection \since 1.0.0 */ 0153 H5S_SEL_POINTS = 1, /**< Set of points \since 1.0.0 */ 0154 H5S_SEL_HYPERSLABS = 2, /**< Hyperslab \since 1.0.0 */ 0155 H5S_SEL_ALL = 3, /**< Everything \since 1.0.0 */ 0156 H5S_SEL_N /**< Sentinel \internal THIS MUST BE LAST \since 1.0.0 */ 0157 } H5S_sel_type; 0158 0159 #ifdef __cplusplus 0160 extern "C" { 0161 #endif 0162 0163 /* Operations on dataspaces, dataspace selections and selection iterators */ 0164 0165 /** 0166 * \ingroup H5S 0167 * 0168 * \brief Releases and terminates access to a dataspace 0169 * 0170 * \space_id 0171 * 0172 * \return \herr_t 0173 * 0174 * \details H5Sclose() releases a dataspace. Further access through the 0175 * dataspace identifier is illegal. Failure to release a dataspace with this 0176 * call will result in resource leaks. 0177 * 0178 * \version 1.4.0 Fortran subroutine introduced in this release. 0179 * \since 1.0.0 0180 * 0181 */ 0182 H5_DLL herr_t H5Sclose(hid_t space_id); 0183 /** 0184 * \ingroup H5S 0185 * 0186 * \brief Performs an operation on a hyperslab and an existing selection and 0187 * returns the resulting selection 0188 * 0189 * \space_id 0190 * \param[in] op Operation to perform on the current selection 0191 * \param[in] start Offset of the start of of the hyperslab 0192 * \param[in] stride Hyperslab stride 0193 * \param[in] count Number of blocks included in the hyperslab 0194 * \param[in] block Size of a block in the hyperslab 0195 * 0196 * \return \hid_t{dataspace} 0197 * 0198 * \details H5Scombine_hyperslab() combines a hyperslab selection specified 0199 * by \p start, \p stride, \p count and \p block with the current 0200 * selection for the dataspace \p space_id, creating a new dataspace 0201 * to return the generated selection. If the current selection is 0202 * not a hyperslab, it is freed and the hyperslab parameters passed 0203 * in are combined with the #H5S_SEL_ALL hyperslab (ie. a selection 0204 * composing the entire current extent). If either \p stride or 0205 * \p block is NULL, then it will be set to \p 1. 0206 * 0207 * See H5Sselect_hyperslab() for valid operators (\p op). 0208 * 0209 * \since 1.10.6 0210 * 0211 */ 0212 H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], 0213 const hsize_t stride[], const hsize_t count[], const hsize_t block[]); 0214 /** 0215 * \ingroup H5S 0216 * 0217 * \brief Combine two hyperslab selections with an operation, returning a 0218 * dataspace with the resulting selection 0219 * 0220 * \space_id{space1_id} 0221 * \param[in] op Selection operator 0222 * \space_id{space2_id} 0223 * 0224 * \return \hid_t{dataspace} 0225 * 0226 * \details H5Scombine_select() combines two hyperslab selections 0227 * \p space1_id and \p space2_id with an operation, returning a 0228 * new dataspace with the resulting selection. The dataspace extent 0229 * from \p space1_id is copied for the dataspace extent of the 0230 * newly created dataspace. 0231 * 0232 * See H5Sselect_hyperslab() for valid operators (\p op). 0233 * 0234 * \since 1.10.6 0235 * 0236 */ 0237 H5_DLL hid_t H5Scombine_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); 0238 /** 0239 * \ingroup H5S 0240 * 0241 * \brief Creates an exact copy of a dataspace 0242 * 0243 * \space_id 0244 * 0245 * \return \hid_t{dataspace} 0246 * 0247 * \details H5Scopy() creates a new dataspace which is an exact copy of the 0248 * dataspace identified by \p space_id. The dataspace identifier 0249 * returned from this function should be released with H5Sclose() 0250 * or resource leaks will occur. 0251 * 0252 * \version 1.4.0 Fortran subroutine introduced. 0253 * \since 1.0.0 0254 * 0255 */ 0256 H5_DLL hid_t H5Scopy(hid_t space_id); 0257 /** 0258 * \ingroup H5S 0259 * 0260 * \brief Creates a new dataspace of a specified type 0261 * 0262 * \param[in] type Type of dataspace to be created 0263 * 0264 * \return \hid_t{dataspace} 0265 * 0266 * \details H5Screate() creates a new dataspace of a particular type. Currently 0267 * supported types are #H5S_SCALAR, #H5S_SIMPLE, and #H5S_NULL. 0268 * 0269 * Further dataspace types may be added later. 0270 * 0271 * A scalar dataspace, #H5S_SCALAR, has a single element, though that 0272 * element may be of a composite datatype, such as a compound or array 0273 * datatype. By convention, the rank of a scalar dataspace is always \p 0 0274 * (zero); think of it geometrically as a single, dimensionless point, 0275 * though that point can be composite. 0276 * 0277 * A simple dataspace, #H5S_SIMPLE, consists of a regular array of elements. 0278 * 0279 * A null dataspace, #H5S_NULL, has no data elements. 0280 * 0281 * The dataspace identifier returned by this function can be released with 0282 * H5Sclose() so that resource leaks will not occur. 0283 * 0284 * \version 1.4.0 Fortran subroutine introduced. 0285 * \since 1.0.0 0286 * 0287 */ 0288 H5_DLL hid_t H5Screate(H5S_class_t type); 0289 /** 0290 * \ingroup H5S 0291 * \brief Creates a new simple dataspace and opens it for access 0292 * 0293 * \param[in] rank Number of dimensions of dataspace 0294 * \param[in] dims Array specifying the size of each dimension 0295 * \param[in] maxdims Array specifying the maximum size of each dimension 0296 * 0297 * \return \hid_t{dataspace} 0298 * 0299 * \details H5Screate_simple() creates a new simple dataspace and opens it 0300 * for access, returning a dataspace identifier. 0301 * 0302 * \p rank is the number of dimensions used in the dataspace. 0303 * 0304 * \p dims is a one-dimensional array of size rank specifying the 0305 * size of each dimension of the dataset. \p maxdims is an array of 0306 * the same size specifying the upper limit on the size of each 0307 * dimension. 0308 * 0309 * Any element of \p dims can be \p 0 (zero). Note that no data can 0310 * be written to a dataset if the size of any dimension of its current 0311 * dataspace is \p 0. This is sometimes a useful initial state for 0312 * a dataset. 0313 * 0314 * \p maxdims may be the null pointer, in which case the upper limit 0315 * is the same as \p dims. Otherwise, no element of \p maxdims 0316 * should be smaller than the corresponding element of \p dims. 0317 * 0318 * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of 0319 * the corresponding dimension is unlimited. 0320 * 0321 * Any dataset with an unlimited dimension must also be chunked; see 0322 * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims 0323 * does not equal \p maxdims. 0324 * 0325 * The dataspace identifier returned from this function must be 0326 * released with H5Sclose() or resource leaks will occur. 0327 * 0328 * \note Once a dataspace has been created, specific regions or elements in 0329 * the dataspace can be selected and selections can be removed, as well. 0330 * For example, H5Sselect_hyperslab() selects a region in a dataspace and 0331 * H5Sselect_elements() selects array elements in a dataspace. These 0332 * functions are used for subsetting. H5Sselect_none() removes all 0333 * selections from a dataspace and is used in Parallel HDF5 when a process 0334 * does not have or need to write data. 0335 * 0336 * \version 1.4.0 Fortran subroutine introduced. 0337 * 0338 * \since 1.0.0 0339 * 0340 */ 0341 H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]); 0342 /** 0343 * \ingroup H5S 0344 * 0345 * \brief Decodes a binary object description of data space and returns a 0346 * new object handle 0347 * 0348 * \param[in] buf Buffer for the data space object to be decoded 0349 * 0350 * \return \hid_t{dataspace} 0351 * 0352 * \details Given an object description of a dataspace in binary in a 0353 * buffer, H5Sdecode() reconstructs the HDF5 data type object and 0354 * returns a new object handle for it. The binary description of the 0355 * object is encoded by H5Sencode(). The user is responsible for 0356 * passing in the right buffer. The types of dataspace addressed 0357 * in this function are null, scalar, and simple space. For a 0358 * simple dataspace, the selection information (for example, 0359 * hyperslab selection) is also encoded and decoded. A complex 0360 * dataspace has not been implemented in the library. 0361 * 0362 * \since 1.8.0 0363 * 0364 */ 0365 H5_DLL hid_t H5Sdecode(const void *buf); 0366 /** 0367 * \ingroup H5S 0368 * 0369 * \brief Encodes a data space object description into a binary buffer 0370 * 0371 * \space_id{obj_id} 0372 * \param[in,out] buf Buffer for the object to be encoded into; 0373 * If the provided buffer is NULL, only the size 0374 * of buffer needed is returned through \p nalloc. 0375 * \param[in,out] nalloc The size of the allocated buffer 0376 * \fapl_id{fapl} 0377 * 0378 * \return \herr_t 0379 * 0380 * \details Given the data space identifier \p obj_id, H5Sencode2() converts 0381 * a data space description into binary form in a buffer. Using this 0382 * binary form in the buffer, a data space object can be 0383 * reconstructed with H5Sdecode() to return a new object handle 0384 * (#hid_t) for this data space. 0385 * 0386 * A preliminary H5Sencode2() call can be made to determine the 0387 * size of the buffer needed. This value is returned in \p nalloc. 0388 * That value can then be assigned to \p nalloc for a second 0389 * H5Sencode2() call, which will retrieve the actual encoded object. 0390 * 0391 * If the library determines that \p nalloc is not big enough for the 0392 * object, it simply returns the size of the buffer needed through 0393 * \p nalloc without encoding the provided buffer. 0394 * 0395 * The file access property list \p fapl_id is used to control the 0396 * encoding via the \a libver_bounds property (see 0397 * H5Pset_libver_bounds()). If the \a libver_bounds property is missing, 0398 * H5Sencode2() proceeds as if the \a libver_bounds property were set to 0399 * (#H5F_LIBVER_EARLIEST, #H5F_LIBVER_LATEST). (Functionally, 0400 * H5Sencode1() is identical to H5Sencode2() with \a libver_bounds set to 0401 * (#H5F_LIBVER_EARLIEST, #H5F_LIBVER_LATEST).) 0402 * 0403 * The types of data space that are addressed in this function are 0404 * null, scalar, and simple space. For a simple data space, the 0405 * information on the selection, for example, hyperslab selection, 0406 * is also encoded and decoded. A complex data space has not been 0407 * implemented in the library. 0408 * 0409 * \note Motivation: This function was introduced in HDF5-1.12 as part of the 0410 * H5Sencode() format change to enable 64-bit selection encodings and 0411 * a dataspace selection that is tied to a file. See the \ref_news_112 0412 * as well as the \ref_sencode_fmt_change. 0413 * 0414 * \since 1.12.0 0415 * 0416 */ 0417 H5_DLL herr_t H5Sencode2(hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl); 0418 /** 0419 * \ingroup H5S 0420 * 0421 * \brief Copies the extent of a dataspace 0422 * 0423 * \space_id{dst_id} 0424 * \space_id{src_id} 0425 * 0426 * \return \herr_t 0427 * 0428 * \details H5Sextent_copy() copies the extent from \p src_id to \p dst_id. 0429 * This action may change the type of the dataspace. 0430 * 0431 * \version 1.4.0 Fortran subroutine was introduced. 0432 * \since 1.0.0 0433 * 0434 */ 0435 H5_DLL herr_t H5Sextent_copy(hid_t dst_id, hid_t src_id); 0436 /** 0437 * \ingroup H5S 0438 * 0439 * \brief Determines whether two dataspace extents are equal 0440 * 0441 * \space_id{space1_id} 0442 * \space_id{space2_id} 0443 * 0444 * \return \htri_t 0445 * 0446 * \details H5Sextent_equal() determines whether the dataspace extents of 0447 * two dataspaces, \p space1_id and \p space2_id, are equal. 0448 * 0449 * \since 1.8.0 0450 * 0451 */ 0452 H5_DLL htri_t H5Sextent_equal(hid_t space1_id, hid_t space2_id); 0453 /** 0454 * \ingroup H5S 0455 * 0456 * \brief Retrieves a regular hyperslab selection 0457 * 0458 * \space_id{spaceid} 0459 * \param[out] start Offset of the start of the regular hyperslab 0460 * \param[out] stride Stride of the regular hyperslab 0461 * \param[out] count Number of blocks in the regular hyperslab 0462 * \param[out] block Size of a block in the regular hyperslab 0463 * 0464 * \return \herr_t 0465 * 0466 * \details H5Sget_regular_hyperslab() takes the dataspace identifier, 0467 * \p spaceid, and retrieves the values of \p start, \p stride, 0468 * \p count, and \p block for the regular hyperslab selection. 0469 * 0470 * A regular hyperslab selection is a hyperslab selection 0471 * described by setting the \p offset, \p stride, \p count, and 0472 * \p block parameters to the H5Sselect_hyperslab() call. If 0473 * several calls to H5Sselect_hyperslab() are needed, the 0474 * hyperslab selection is irregular. 0475 * 0476 * See H5Sselect_hyperslab() for descriptions of \p offset, 0477 * \p stride, \p count, and \p block. 0478 * 0479 * \note If a hyperslab selection is originally regular, then becomes 0480 * irregular through selection operations, and then becomes regular 0481 * again, the final regular selection may be equivalent but not 0482 * identical to the original regular selection. 0483 * 0484 * \since 1.10.0 0485 * 0486 */ 0487 H5_DLL htri_t H5Sget_regular_hyperslab(hid_t spaceid, hsize_t start[], hsize_t stride[], hsize_t count[], 0488 hsize_t block[]); 0489 /** 0490 * \ingroup H5S 0491 * 0492 * \brief Gets the bounding box containing the current selection 0493 * 0494 * \space_id{spaceid} 0495 * \param[out] start Starting coordinates of the bounding box 0496 * \param[out] end Ending coordinates of the bounding box, i.e., the 0497 * coordinates of the diagonally opposite corner 0498 * 0499 * \return \herr_t 0500 * 0501 * \details H5Sget_select_bounds() retrieves the coordinates of the bounding 0502 * box containing the current selection and places them into 0503 * user-supplied buffers. 0504 * 0505 * The \p start and \p end buffers must be large enough to hold 0506 * the dataspace rank number of coordinates. 0507 * 0508 * The bounding box exactly contains the selection. I.e., if a 0509 * 2-dimensional element selection is currently defined as containing 0510 * the points (4,5), (6,8), and (10,7), then the bounding box 0511 * will be (4, 5), (10, 8). 0512 * 0513 * The bounding box calculation includes the current offset of the 0514 * selection within the dataspace extent. 0515 * 0516 * Calling this function on a \a none selection will fail. 0517 * 0518 * \version 1.6.0 The \p start and \p end parameters have changed from type 0519 * \p hsize_t * to \p hssize_t *. 0520 * \version 1.4.0 Fortran subroutine was introduced. 0521 * \since 1.2.0 0522 * 0523 */ 0524 H5_DLL herr_t H5Sget_select_bounds(hid_t spaceid, hsize_t start[], hsize_t end[]); 0525 /** 0526 * \ingroup H5S 0527 * 0528 * \brief Gets the number of element points in the current selection 0529 * 0530 * \space_id{spaceid} 0531 * 0532 * \return Returns the number of element points in the current dataspace 0533 * selection if successful. Otherwise returns a negative value. 0534 * 0535 * \details H5Sget_select_elem_npoints() returns the number of element 0536 * points in the current dataspace selection, so that the element 0537 * points can be retrieved with H5Sget_select_elem_pointlist(). 0538 * (This is similar to the way that H5Sget_select_hyper_nblocks() 0539 * and H5Sget_select_hyper_blocklist() work with hyperslab 0540 * selections.) 0541 * 0542 * Coincidentally, H5Sget_select_npoints() and 0543 * H5Sget_select_elem_npoints() will always return the same value 0544 * when an element selection is queried, but 0545 * H5Sget_select_elem_npoints() does not work with other selection 0546 * types. 0547 * 0548 * \since 1.2.0 0549 * 0550 */ 0551 H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid); 0552 /** 0553 * \ingroup H5S 0554 * 0555 * \brief Gets the list of element points currently selected 0556 * 0557 * \space_id{spaceid} 0558 * \param[in] startpoint Element point to start with 0559 * \param[in] numpoints Number of element points to get 0560 * \param[out] buf List of element points selected 0561 * 0562 * \return \herr_t 0563 * 0564 * \details H5Sget_select_elem_pointlist() returns the list of element 0565 * points in the current dataspace selection \p space_id. Starting 0566 * with the \p startpoint in the list of points, \p numpoints 0567 * points are put into the user's buffer. If the user's buffer 0568 * fills up before \p numpoints points are inserted, the buffer 0569 * will contain only as many points as fit. 0570 * 0571 * The element point coordinates have the same dimensionality 0572 * (rank) as the dataspace they are located within. The list of 0573 * element points is formatted as follows:\n 0574 * \<coordinate\>, followed by\n 0575 * the next coordinate,\n 0576 * etc.\n 0577 * until all of the selected element points have been listed. 0578 * 0579 * The points are returned in the order they will be iterated 0580 * through when the selection is read/written from/to disk. 0581 * 0582 * \since 1.2.0 0583 * 0584 */ 0585 H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, 0586 hsize_t buf[/*numpoints*/]); 0587 /** 0588 * \ingroup H5S 0589 * 0590 * \brief Gets the list of hyperslab blocks currently selected 0591 * 0592 * \space_id{spaceid} 0593 * \param[in] startblock Hyperslab block to start with 0594 * \param[in] numblocks Number of hyperslab blocks to get 0595 * \param[out] buf List of hyperslab blocks selected 0596 * 0597 * \return \herr_t 0598 * 0599 * \details H5Sget_select_hyper_blocklist() returns a list of the hyperslab 0600 * blocks currently selected. Starting with the \p startblock-th block 0601 * in the list of blocks, \p numblocks blocks are put into the 0602 * user's buffer. If the user's buffer fills up before \p numblocks 0603 * blocks are inserted, the buffer will contain only as many blocks 0604 * as fit. 0605 * 0606 * The block coordinates have the same dimensionality (rank) as the 0607 * dataspace they are located within. The list of blocks is 0608 * formatted as follows:\n 0609 * \<"start" coordinate\>, immediately followed by\n 0610 * \<"opposite" corner coordinate\>, followed by\n 0611 * the next "start" and "opposite" coordinates,\n 0612 * etc. until all of the selected blocks have been listed.\n 0613 * No guarantee of any order of the blocks is implied. 0614 * 0615 * \since 1.2.0 0616 * 0617 */ 0618 H5_DLL herr_t H5Sget_select_hyper_blocklist(hid_t spaceid, hsize_t startblock, hsize_t numblocks, 0619 hsize_t buf[/*numblocks*/]); 0620 /** 0621 * \ingroup H5S 0622 * 0623 * \brief Get number of hyperslab blocks 0624 * 0625 * \space_id{spaceid} 0626 * 0627 * \return Returns the number of hyperslab blocks in the current dataspace 0628 * selection if successful. Otherwise returns a negative value. 0629 * 0630 * \details H5Sget_select_hyper_nblocks() returns the number of hyperslab 0631 * blocks in the current dataspace selection. 0632 * 0633 * \since 1.2.0 0634 * 0635 */ 0636 H5_DLL hssize_t H5Sget_select_hyper_nblocks(hid_t spaceid); 0637 /** 0638 * \ingroup H5S 0639 * 0640 * \brief Determines the number of elements in a dataspace selection 0641 * 0642 * \space_id{spaceid} 0643 * 0644 * \return Returns the number of elements in the selection if successful; 0645 * otherwise returns a negative value. 0646 * 0647 * \details H5Sget_select_npoints() determines the number of elements in 0648 * the current selection of a dataspace. It works with any 0649 * selection type, and is the correct way to retrieve the number 0650 * of elements in a selection. 0651 * 0652 * \version 1.4.0 Fortran subroutine introduced in this release. 0653 * \since 1.0.0 0654 * 0655 */ 0656 H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); 0657 /** 0658 * \ingroup H5S 0659 * 0660 * \brief Determines the type of the dataspace selection 0661 * 0662 * \space_id{spaceid} 0663 * 0664 * \return Returns the dataspace selection type, a value of the enumerated 0665 * datatype #H5S_sel_type, if successful. 0666 * 0667 * \details H5Sget_select_type() retrieves the type of dataspace selection 0668 * currently defined for the dataspace \p space_id. Valid values 0669 * for the dataspace selection type are: 0670 * 0671 * <table> 0672 * <tr> 0673 * <td>#H5S_SEL_NONE</td> 0674 * <td>No selection is defined</td> 0675 * </tr> 0676 * <tr> 0677 * <td>#H5S_SEL_POINTS</td> 0678 * <td>A sequence of points is selected</td> 0679 * </tr> 0680 * <tr> 0681 * <td>#H5S_SEL_HYPERSLABS</td> 0682 * <td>A hyperslab or compound hyperslab is selected</td> 0683 * </tr> 0684 * <tr> 0685 * <td>#H5S_SEL_ALL</td> 0686 * <td>The entire dataset is selected</td> 0687 * </tr> 0688 * </table> 0689 * 0690 * Otherwise returns a negative value. 0691 * 0692 * \since 1.6.0 0693 * 0694 */ 0695 H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid); 0696 /** 0697 * \ingroup H5S 0698 * 0699 * \brief Retrieves dataspace dimension size and maximum size 0700 * 0701 * \space_id 0702 * \param[out] dims Pointer to array to store the size of each dimension 0703 * \param[out] maxdims Pointer to array to store the maximum size of each 0704 * dimension 0705 * 0706 * \return Returns the number of dimensions in the dataspace if successful; 0707 * otherwise returns a negative value. 0708 * 0709 * \details H5Sget_simple_extent_dims() returns the size and maximum sizes 0710 * of each dimension of a dataspace \p space_id through the \p dims 0711 * and \p maxdims parameters. 0712 * 0713 * Either or both of \p dims and \p maxdims may be NULL. 0714 * 0715 * If a value in the returned array \p maxdims is #H5S_UNLIMITED (-1), 0716 * the maximum size of that dimension is unlimited. 0717 * 0718 * \version 1.4.0 Fortran subroutine introduced. 0719 * \since 1.0.0 0720 * 0721 */ 0722 H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]); 0723 /** 0724 * \ingroup H5S 0725 * 0726 * \brief Determines the dimensionality of a dataspace 0727 * 0728 * \space_id 0729 * 0730 * \return Returns the number of dimensions in the dataspace if successful; 0731 * otherwise returns a negative value. 0732 * 0733 * \details H5Sget_simple_extent_ndims() determines the dimensionality (or 0734 * rank) of a dataspace. 0735 * 0736 * \version 1.4.0 Fortran subroutine introduced. 0737 * \since 1.0.0 0738 * 0739 */ 0740 H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); 0741 /** 0742 * \ingroup H5S 0743 * 0744 * \brief Determines the number of elements in a dataspace 0745 * 0746 * \space_id 0747 * 0748 * \return Returns the number of elements in the dataspace if successful; 0749 * otherwise returns a negative value. 0750 * 0751 * \details H5Sget_simple_extent_npoints() determines the number of elements 0752 * in a dataspace \p space_id. For example, a simple 3-dimensional 0753 * dataspace with dimensions 2, 3, and 4 would have 24 elements. 0754 * 0755 * \version 1.4.0 Fortran subroutine introduced. 0756 * \since 1.0.0 0757 * 0758 */ 0759 H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id); 0760 /** 0761 * \ingroup H5S 0762 * 0763 * \brief Determines the current class of a dataspace 0764 * 0765 * \space_id 0766 * 0767 * \return Returns a dataspace class name if successful; 0768 * otherwise #H5S_NO_CLASS (-1). 0769 * 0770 * \details H5Sget_simple_extent_type() determines the current class of a 0771 * dataspace \p space_id. 0772 * 0773 * \version 1.4.0 Fortran subroutine was introduced. 0774 * \since 1.0.0 0775 * 0776 */ 0777 H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id); 0778 /** 0779 * \ingroup H5S 0780 * 0781 * \brief Determines if a hyperslab selection is regular 0782 * 0783 * \space_id{spaceid} 0784 * 0785 * \return \htri_t 0786 * 0787 * \details H5Sis_regular_hyperslab() takes the dataspace identifier, 0788 * \p spaceid, and queries the type of the hyperslab selection. 0789 * 0790 * A regular hyperslab selection is a hyperslab selection described 0791 * by setting the offset, stride, count, and block parameters for 0792 * a single H5Sselect_hyperslab() call. If several calls to 0793 * H5Sselect_hyperslab() are needed, then the hyperslab selection 0794 * is irregular. 0795 * 0796 * \since 1.10.0 0797 * 0798 */ 0799 H5_DLL htri_t H5Sis_regular_hyperslab(hid_t spaceid); 0800 /** 0801 * \ingroup H5S 0802 * 0803 * \brief Determines whether a dataspace is a simple dataspace 0804 * 0805 * \space_id 0806 * 0807 * \return \htri_t 0808 * 0809 * \details H5Sis_simple() determines whether or not a dataspace is a simple 0810 * dataspace. 0811 * 0812 * \note Currently, all dataspace objects are simple dataspaces; complex 0813 * dataspace support will be added in the future. 0814 * 0815 * \version 1.4.0 Fortran subroutine was introduced. 0816 * \since 1.0.0 0817 * 0818 */ 0819 H5_DLL htri_t H5Sis_simple(hid_t space_id); 0820 /** 0821 * \ingroup H5S 0822 * 0823 * \brief Refines a hyperslab selection with an operation, using a second 0824 * hyperslab to modify it 0825 * 0826 * \space_id{space1_id} 0827 * \param[in] op Selection operator 0828 * \space_id{space2_id} 0829 * 0830 * \return \herr_t 0831 * 0832 * \details H5Smodify_select() refines an existing hyperslab selection 0833 * \p space1_id with an operation \p op, using a second hyperslab 0834 * \p space2_id. The first selection is modified to contain the 0835 * result of \p space1_id operated on by \p space2_id. 0836 * 0837 * See H5Sselect_hyperslab() for valid operators (\p op). 0838 * 0839 * \since 1.10.6 0840 * 0841 */ 0842 H5_DLL herr_t H5Smodify_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); 0843 /** 0844 * \ingroup H5S 0845 * 0846 * \brief Sets the offset of a simple dataspace 0847 * 0848 * \space_id 0849 * \param[in] offset The offset at which to position the selection 0850 * 0851 * \return \herr_t 0852 * 0853 * \details H5Soffset_simple() sets the offset of a simple dataspace 0854 * \p space_id. The offset array must be the same number of 0855 * elements as the number of dimensions for the dataspace. If the 0856 * \p offset array is set to NULL, the offset for the dataspace is 0857 * reset to 0 in all dimensions. 0858 * 0859 * This function allows the same shaped selection to be moved to 0860 * different locations within a dataspace without requiring it to 0861 * be redefined. 0862 * 0863 * \note Until 1.14.4, setting the offset parameter to NULL was considered 0864 * an error, despite the reference manual stating that it had the 0865 * behavior described above. 0866 * 0867 * \version 1.4.0 Fortran subroutine was introduced. 0868 * \since 1.0.0 0869 * 0870 */ 0871 H5_DLL herr_t H5Soffset_simple(hid_t space_id, const hssize_t *offset); 0872 /** 0873 * \ingroup H5S 0874 * 0875 * \brief Closes a dataspace selection iterator 0876 * 0877 * \param[in] sel_iter_id Identifier of the dataspace selection iterator 0878 * 0879 * \return \herr_t 0880 * 0881 * \details H5Ssel_iter_close() closes a dataspace selection iterator 0882 * specified by \p sel_iter_id, releasing its state. 0883 * 0884 * \since 1.12.0 0885 * 0886 */ 0887 H5_DLL herr_t H5Ssel_iter_close(hid_t sel_iter_id); 0888 /**\ingroup H5S 0889 * 0890 * \brief Creates a dataspace selection iterator for a dataspace's selection 0891 * 0892 * \space_id{spaceid} 0893 * \param[in] elmt_size Size of element in the selection 0894 * \param[in] flags Selection iterator flag, valid values are: 0895 * \li @ref H5S_SEL_ITER_GET_SEQ_LIST_SORTED 0896 * \li @ref H5S_SEL_ITER_SHARE_WITH_DATASPACE 0897 * \return \hid_t{valid dataspace selection iterator} 0898 * 0899 * \details H5Ssel_iter_create() creates a selection iterator and initializes 0900 * it to start at the first element selected in the dataspace. 0901 * 0902 * \since 1.12.0 0903 * 0904 */ 0905 H5_DLL hid_t H5Ssel_iter_create(hid_t spaceid, size_t elmt_size, unsigned flags); 0906 /** 0907 * \ingroup H5S 0908 * 0909 * \brief Retrieves a list of offset / length sequences for the elements in 0910 * an iterator 0911 * 0912 * \param[in] sel_iter_id Identifier of the dataspace selection iterator 0913 * \param[in] maxseq Maximum number of sequences to retrieve 0914 * \param[in] maxelmts Maximum number of elements to retrieve in sequences 0915 * \param[out] nseq Number of sequences retrieved 0916 * \param[out] nelmts Number of elements retrieved, in all sequences 0917 * \param[out] off Array of sequence offsets 0918 * \param[out] len Array of sequence lengths 0919 * 0920 * \return \herr_t 0921 * 0922 * \details H5Ssel_iter_get_seq_list() retrieves a list of offset / length 0923 * pairs (a list of "sequences") matching the selected elements for 0924 * an iterator \p sel_iter_id, according to the iteration order for 0925 * the iterator. The lengths returned are in bytes, not elements. 0926 * 0927 * Note that the iteration order for "all" and "hyperslab" 0928 * selections is row-major (i.e. "C-ordered"), but the iteration 0929 * order for "point" selections is "in order selected", unless the 0930 * #H5S_SEL_ITER_GET_SEQ_LIST_SORTED flag is passed to 0931 * H5Ssel_iter_create() for a point selection. 0932 * 0933 * \p maxseq and \p maxelmts specify the most sequences or elements 0934 * possible to place into the \p off and \p len arrays. \p nseq and 0935 * \p nelmts return the actual number of sequences and elements put 0936 * into the arrays. 0937 * 0938 * Each call to H5Ssel_iter_get_seq_list() will retrieve the next 0939 * set of sequences for the selection being iterated over. 0940 * 0941 * The total number of bytes possible to retrieve from a selection 0942 * iterator is the \p elmt_size passed to H5Ssel_iter_create() 0943 * multiplied by the number of elements selected in the dataspace 0944 * the iterator was created from (which can be retrieved with 0945 * H5Sget_select_npoints(). When there are no further sequences of 0946 * elements to retrieve, calls to this routine will set \p nseq 0947 * and \p nelmts to zero. 0948 * 0949 * \since 1.12.0 0950 * 0951 */ 0952 H5_DLL herr_t H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq, size_t maxelmts, size_t *nseq, 0953 size_t *nelmts, hsize_t *off, size_t *len); 0954 /** 0955 * \ingroup H5S 0956 * 0957 * \brief Resets a dataspace selection iterator back to an initial state 0958 * 0959 * \param[in] sel_iter_id Identifier of the dataspace selection iterator 0960 * to reset 0961 * \param[in] space_id Identifier of the dataspace with selection to 0962 * iterate over 0963 * 0964 * \return \herr_t 0965 * 0966 * \details H5Ssel_iter_reset() resets a dataspace selection iterator back to 0967 * an initial state so that the iterator may be used for iteration 0968 * once again. 0969 * 0970 * \since 1.12.1 0971 * 0972 */ 0973 H5_DLL herr_t H5Ssel_iter_reset(hid_t sel_iter_id, hid_t space_id); 0974 /** 0975 * \ingroup H5S 0976 * 0977 * \brief Adjusts a selection by subtracting an offset 0978 * 0979 * \space_id{spaceid} 0980 * \param[in] offset Offset to subtract 0981 * 0982 * \return \herr_t 0983 * 0984 * \details H5Sselect_adjust() shifts a dataspace selection by a specified 0985 * logical offset within the dataspace extent. 0986 * 0987 * \note This can be useful for VOL developers to implement chunked datasets. 0988 * 0989 * \since 1.10.6 0990 */ 0991 H5_DLL herr_t H5Sselect_adjust(hid_t spaceid, const hssize_t *offset); 0992 /** 0993 * \ingroup H5S 0994 * 0995 * \brief Selects an entire dataspace 0996 * 0997 * \space_id{spaceid} 0998 * 0999 * \return \herr_t 1000 * 1001 * \details H5Sselect_all() selects the entire extent of the dataspace 1002 * \p dspace_id. 1003 * 1004 * More specifically, H5Sselect_all() sets the selection type to 1005 * #H5S_SEL_ALL, which specifies the entire dataspace anywhere it 1006 * is applied. 1007 * 1008 * \since 1.0.0 1009 * 1010 */ 1011 H5_DLL herr_t H5Sselect_all(hid_t spaceid); 1012 /** 1013 * \ingroup H5S 1014 * 1015 * \brief Copies a selection from one dataspace to another 1016 * 1017 * \space_id{dst_id} 1018 * \space_id{src_id} 1019 * 1020 * \return \herr_t 1021 * 1022 * \details H5Sselect_copy() copies all selection information (including 1023 * offset) from the source dataspace \p src_id to the destination 1024 * dataspace \p dst_id. 1025 * 1026 * \since 1.10.6 1027 * 1028 */ 1029 H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id); 1030 /** 1031 * \ingroup H5S 1032 * 1033 * \brief Selects array elements to be included in the selection for a 1034 * dataspace 1035 * 1036 * \space_id 1037 * \param[in] op Operator specifying how the new selection is to be 1038 * combined with the existing selection for the dataspace 1039 * \param[in] num_elem Number of elements to be selected 1040 * \param[in] coord A pointer to a buffer containing a serialized copy of 1041 * a 2-dimensional array of zero-based values specifying 1042 * the coordinates of the elements in the point selection 1043 * 1044 * \return \herr_t 1045 * 1046 * \details H5Sselect_elements() selects array elements to be included in 1047 * the selection for the \p space_id dataspace. This is referred 1048 * to as a point selection. 1049 * 1050 * The number of elements selected is set in the \p num_elements 1051 * parameter. 1052 * 1053 * The \p coord parameter is a pointer to a buffer containing a 1054 * serialized 2-dimensional array of size \p num_elements by the 1055 * rank of the dataspace. The array lists dataset elements in the 1056 * point selection; that is, it's a list of zero-based values 1057 * specifying the coordinates in the dataset of the selected 1058 * elements. The order of the element coordinates in the \p coord 1059 * array specifies the order in which the array elements are 1060 * iterated through when I/O is performed. Duplicate coordinate 1061 * locations are not checked for. See below for examples of the 1062 * mapping between the serialized contents of the buffer and the 1063 * point selection array that it represents. 1064 * 1065 * The selection operator \p op determines how the new selection 1066 * is to be combined with the previously existing selection for 1067 * the dataspace. The following operators are supported: 1068 * 1069 * <table> 1070 * <tr> 1071 * <td>#H5S_SELECT_SET</td> 1072 * <td>Replaces the existing selection with the parameters from 1073 * this call. Overlapping blocks are not supported with this 1074 * operator. Adds the new selection to the existing selection. 1075 * </td> 1076 * </tr> 1077 * <tr> 1078 * <td>#H5S_SELECT_APPEND</td> 1079 * <td>Adds the new selection following the last element of the 1080 * existing selection.</td> 1081 * </tr> 1082 * <tr> 1083 * <td>#H5S_SELECT_PREPEND</td> 1084 * <td>Adds the new selection preceding the first element of the 1085 * existing selection.</td> 1086 * </tr> 1087 * </table> 1088 * 1089 * <b>Mapping the serialized \p coord buffer to a 2-dimensional 1090 * point selection array:</b> 1091 * To illustrate the construction of the contents of the \p coord 1092 * buffer, consider two simple examples: a selection of 5 points in 1093 * a 1-dimensional array and a selection of 3 points in a 1094 * 4-dimensional array. 1095 * 1096 * In the 1D case, we will be selecting five points and a 1D 1097 * dataspace has rank 1, so the selection will be described in a 1098 * 5-by-1 array. To select the 1st, 14th, 17th, 23rd and 8th elements 1099 * of the dataset, the selection array would be as follows 1100 * (remembering that point coordinates are zero-based): 1101 * \n 0 1102 * \n 13 1103 * \n 16 1104 * \n 22 1105 * \n 7 1106 * 1107 * This point selection array will be serialized in the \p coord 1108 * buffer as: 1109 * \n 0 13 16 22 7 1110 * 1111 * In the 4D case, we will be selecting three points and a 4D 1112 * dataspace has rank 4, so the selection will be described in a 1113 * 3-by-4 array. To select the points (1,1,1,1), (14,6,12,18), and 1114 * (8,22,30,22), the point selection array would be as follows: 1115 * \n 0 0 0 0 1116 * \n 13 5 11 17 1117 * \n 7 21 29 21 1118 * 1119 * This point selection array will be serialized in the \p coord 1120 * buffer as: 1121 * \n 0 0 0 0 13 5 11 17 7 21 29 21 1122 * 1123 * \version 1.6.4 C coord parameter type changed to \p const hsize_t. 1124 * \version 1.6.4 Fortran \p coord parameter type changed to \p INTEGER(HSIZE_T). 1125 * \since 1.0.0 1126 * 1127 */ 1128 H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_elem, const hsize_t *coord); 1129 /** 1130 * \ingroup H5S 1131 * 1132 * \brief Selects a hyperslab region to add to the current selected region 1133 * 1134 * \space_id 1135 * \param[in] op Operation to perform on current selection 1136 * \param[in] start Offset of start of hyperslab 1137 * \param[in] stride Hyperslab stride 1138 * \param[in] count Number of blocks included in hyperslab 1139 * \param[in] block Size of block in hyperslab 1140 * 1141 * \return \herr_t 1142 * 1143 * \details H5Sselect_hyperslab() selects a hyperslab region to add to the 1144 * current selected region for the dataspace specified by 1145 * \p space_id. 1146 * 1147 * The \p start, \p stride, \p count, and \p block arrays must be the 1148 * same size as the rank of the dataspace. For example, if the 1149 * dataspace is 4-dimensional, each of these parameters must be a 1150 * 1-dimensional array of size 4. 1151 * 1152 * The selection operator \p op determines how the new selection 1153 * is to be combined with the already existing selection for the 1154 * dataspace. The following operators are supported: 1155 * 1156 * <table> 1157 * <tr> 1158 * <td>#H5S_SELECT_SET</td> 1159 * <td>Replaces the existing selection with the 1160 * parameters from this call. Overlapping blocks 1161 * are not supported with this operator.</td> 1162 * </tr> 1163 * <tr> 1164 * <td>#H5S_SELECT_OR</td> 1165 * <td>Adds the new selection to the existing selection. 1166 * (Binary OR)</td> 1167 * </tr> 1168 * <tr> 1169 * <td>#H5S_SELECT_AND</td> 1170 * <td>Retains only the overlapping portions of the 1171 * new selection and the existing selection. 1172 * (Binary AND)</td> 1173 * </tr> 1174 * <tr> 1175 * <td>#H5S_SELECT_XOR</td> 1176 * <td>Retains only the elements that are members of 1177 * the new selection or the existing selection, 1178 * excluding elements that are members of both 1179 * selections. (Binary exclusive-OR, XOR) 1180 * </td> 1181 * </tr> 1182 * <tr> 1183 * <td>#H5S_SELECT_NOTB</td> 1184 * <td>Retains only elements of the existing selection 1185 * that are not in the new selection.</td> 1186 * </tr> 1187 * <tr> 1188 * <td>#H5S_SELECT_NOTA</td> 1189 * <td>Retains only elements of the new selection that 1190 * are not in the existing selection.</td> 1191 * </tr> 1192 * </table> 1193 * 1194 * The \p start array specifies the offset of the starting element 1195 * of the specified hyperslab. 1196 * 1197 * The \p stride array chooses array locations from the dataspace with 1198 * each value in the \p stride array determining how many elements to 1199 * move in each dimension. Setting a value in the \p stride array to 1200 * \p 1 moves to each element in that dimension of the dataspace; 1201 * setting a value of \p 2 in allocation in the \p stride array moves 1202 * to every other element in that dimension of the dataspace. In 1203 * other words, the \p stride determines the number of elements to 1204 * move from the \p start location in each dimension. Stride values 1205 * of \p 0 are not allowed. If the \p stride parameter is NULL, a 1206 * contiguous hyperslab is selected (as if each value in the \p stride 1207 * array were set to \p 1). 1208 * 1209 * The \p count array determines how many blocks to select from the 1210 * dataspace, in each dimension. 1211 * 1212 * The \p block array determines the size of the element block 1213 * selected from the dataspace. If the \p block parameter is set to 1214 * NULL, the block size defaults to a single element in each dimension 1215 * (as if each value in the \p block array were set to \p 1). 1216 * 1217 * For example, consider a 2-dimensional dataspace with hyperslab 1218 * selection settings as follows: the \p start offset is specified as 1219 * [1,1], \p stride is [4,4], \p count is [3,7], and \p block is [2,2]. 1220 * In C, these settings will specify a hyperslab consisting of 21 1221 * 2x2 blocks of array elements starting with location (1,1) with the 1222 * selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.; 1223 * in Fortran, they will specify a hyperslab consisting of 21 2x2 1224 * blocks of array elements starting with location (2,2), since \p start 1225 * is 0-based indexed, with the selected blocks at 1226 * locations (2,2), (6,2), (10,2), (2,6), (6,6), etc. 1227 * 1228 * Regions selected with this function call default to C order 1229 * iteration when I/O is performed. 1230 * 1231 * \version 1.4.0 Fortran subroutine introduced in this release. 1232 * \since 1.0.0 1233 * 1234 */ 1235 H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], 1236 const hsize_t stride[], const hsize_t count[], const hsize_t block[]); 1237 /*--------------------------------------------------------------------------*/ 1238 /**\ingroup H5S 1239 * 1240 * \brief Checks if current selection intersects with a block 1241 * 1242 * \space_id 1243 * \param[in] start Starting coordinate of block 1244 * \param[in] end Opposite ("ending") coordinate of block 1245 * 1246 * \return \htri_t 1247 * 1248 * \details H5Sselect_intersect_block() checks to see if the current 1249 * selection \p space_id in the dataspace intersects with the block 1250 * specified by \p start and \p end. 1251 * 1252 * \note Assumes that \p start & \p end block bounds are inclusive, so 1253 * \p start == \p end value is OK. 1254 * 1255 * \since 1.10.6 1256 * 1257 */ 1258 H5_DLL htri_t H5Sselect_intersect_block(hid_t space_id, const hsize_t *start, const hsize_t *end); 1259 /*--------------------------------------------------------------------------*/ 1260 /**\ingroup H5S 1261 * 1262 * \brief Resets the selection region to include no elements 1263 * 1264 * \space_id{spaceid} 1265 * 1266 * \return \herr_t 1267 * 1268 * \details H5Sselect_none() resets the selection region for the dataspace 1269 * \p space_id to include no elements. 1270 * 1271 * \since 1.0.0 1272 * 1273 */ 1274 H5_DLL herr_t H5Sselect_none(hid_t spaceid); 1275 /*--------------------------------------------------------------------------*/ 1276 /**\ingroup H5S 1277 * 1278 * \brief Projects the intersection of two source selections to a 1279 * destination selection 1280 * 1281 * \space_id{src_space_id} 1282 * \space_id{dst_space_id} 1283 * \space_id{src_intersect_space_id} 1284 * 1285 * \return Returns a dataspace with a selection equal to the intersection of 1286 * \p src_intersect_space_id and \p src_space_id projected from 1287 * \p src_space to \p dst_space on success, negative on failure. 1288 * 1289 * \details H5Sselect_project_intersection() computes the intersection 1290 * between two dataspace selections and projects that intersection 1291 * into a third selection.This can be useful for VOL developers to 1292 * implement chunked or virtual datasets. 1293 * 1294 * \since 1.10.6 1295 * 1296 */ 1297 H5_DLL hid_t H5Sselect_project_intersection(hid_t src_space_id, hid_t dst_space_id, 1298 hid_t src_intersect_space_id); 1299 /*--------------------------------------------------------------------------*/ 1300 /**\ingroup H5S 1301 * 1302 * \brief Checks if two selections are the same shape 1303 * 1304 * \space_id{space1_id} 1305 * \space_id{space2_id} 1306 * 1307 * \return \htri_t 1308 * 1309 * \details H5Sselect_shape_same() checks to see if the current selection 1310 * in the dataspaces are the same dimensionality and shape. 1311 * 1312 * This is primarily used for reading the entire selection in 1313 * one swoop. 1314 * 1315 * \since 1.10.7 1316 * 1317 */ 1318 H5_DLL htri_t H5Sselect_shape_same(hid_t space1_id, hid_t space2_id); 1319 /*--------------------------------------------------------------------------*/ 1320 /**\ingroup H5S 1321 * 1322 * \brief Verifies that the selection is within the extent of the dataspace 1323 * 1324 * \space_id{spaceid} 1325 * 1326 * \return \htri_t 1327 * 1328 * \details H5Sselect_valid() verifies that the selection for the dataspace 1329 * \p space_id is within the extent of the dataspace if the current 1330 * offset for the dataspace is used. 1331 * 1332 * \version 1.4.0 Fortran subroutine introduced in this release. 1333 * \since 1.0.0 1334 * 1335 */ 1336 H5_DLL htri_t H5Sselect_valid(hid_t spaceid); 1337 /*--------------------------------------------------------------------------*/ 1338 /**\ingroup H5S 1339 * 1340 * \brief Resets the extent of a dataspace back to "none" 1341 * 1342 * \space_id 1343 * 1344 * \return \herr_t 1345 * 1346 * \details H5Sset_extent_none() resets the type of a dataspace to 1347 * #H5S_NULL with no extent information stored for the dataspace. 1348 * 1349 * \version 1.10.7, 1.12.1 The function behavior changed. The previous 1350 * behavior was to set the class to #H5S_NO_CLASS. 1351 * \version 1.4.0 Fortran subroutine was introduced. 1352 * \since 1.0.0 1353 * 1354 */ 1355 H5_DLL herr_t H5Sset_extent_none(hid_t space_id); 1356 /*--------------------------------------------------------------------------*/ 1357 /**\ingroup H5S 1358 * 1359 * \brief Sets or resets the size of an existing dataspace 1360 * 1361 * \space_id 1362 * \param[in] rank Rank, or dimensionality, of the dataspace 1363 * \param[in] dims Array containing current size of dataspace 1364 * \param[in] max Array containing maximum size of dataspace 1365 * 1366 * \return \herr_t 1367 * 1368 * \details H5Sset_extent_simple() sets or resets the size of an existing 1369 * dataspace. 1370 * 1371 * \p dims is an array of size \p rank that contains the new size 1372 * of each dimension in the dataspace. \p max is an array of size 1373 * \p rank that contains the maximum size of each dimension in 1374 * the dataspace. 1375 * 1376 * Any previous extent is removed from the dataspace, the dataspace 1377 * type is set to #H5S_SIMPLE, and the extent is set as specified. 1378 * 1379 * \version 1.4.0 Fortran subroutine was introduced. 1380 * \since 1.0.0 1381 * 1382 */ 1383 H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]); 1384 1385 /* Symbols defined for compatibility with previous versions of the HDF5 API. 1386 * 1387 * Use of these symbols is deprecated. 1388 */ 1389 #ifndef H5_NO_DEPRECATED_SYMBOLS 1390 /* Function prototypes */ 1391 /* --------------------------------------------------------------------------*/ 1392 /**\ingroup H5S 1393 * 1394 * \brief Encodes a data space object description into a binary buffer 1395 * 1396 * \space_id{obj_id} 1397 * \param[in,out] buf Buffer for the object to be encoded into; 1398 * If the provided buffer is NULL, only the size of 1399 * buffer needed is returned through \p nalloc. 1400 * \param[in,out] nalloc The size of the allocated buffer 1401 * 1402 * \return \herr_t 1403 * 1404 * \deprecated Deprecated in favor of H5Sencode2() 1405 * 1406 * \details Given the data space identifier \p obj_id, H5Sencode1() converts 1407 * a data space description into binary form in a buffer. Using 1408 * this binary form in the buffer, a data space object can be 1409 * reconstructed using H5Sdecode() to return a new object handle 1410 * (\p hid_t) for this data space. 1411 * 1412 * A preliminary H5Sencode1() call can be made to find out the size 1413 * of the buffer needed. This value is returned as \p nalloc. That 1414 * value can then be assigned to \p nalloc for a second H5Sencode1() 1415 * call, which will retrieve the actual encoded object. 1416 * 1417 * If the library finds out \p nalloc is not big enough for the 1418 * object, it simply returns the size of the buffer needed through 1419 * \p nalloc without encoding the provided buffer. 1420 * 1421 * The types of data space addressed in this function are null, 1422 * scalar, and simple space. For a simple data space, the information 1423 * on the selection, for example, hyperslab selection, is also 1424 * encoded and decoded. A complex data space has not been 1425 * implemented in the library. 1426 * 1427 * \version 1.12.0 The function H5Sencode() was renamed H5Sencode1() and 1428 * deprecated. 1429 * \since 1.8.0 1430 * 1431 */ 1432 H5_DLL herr_t H5Sencode1(hid_t obj_id, void *buf, size_t *nalloc); 1433 1434 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 1435 1436 #ifdef __cplusplus 1437 } 1438 #endif 1439 #endif /* H5Spublic_H */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|