1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the COPYING file, which can be found at the root of the source code * 9 * distribution tree, or in https://www.hdfgroup.org/licenses. * 10 * If you do not have access to either file, you may request a copy from * 11 * help@hdfgroup.org. * 12 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 13 14 /* 15 * This file contains public declarations for the H5S module. 16 */ 17 #ifndef H5Spublic_H 18 #define H5Spublic_H 19 20 /* Public headers needed by this file */ 21 #include "H5public.h" 22 #include "H5Ipublic.h" 23 24 /* Define atomic datatypes */ 25 #define H5S_ALL (hid_t)0 26 #define H5S_UNLIMITED HSIZE_UNDEF 27 28 /* Define user-level maximum number of dimensions */ 29 #define H5S_MAX_RANK 32 30 31 /* Flags for selection iterators */ 32 #define H5S_SEL_ITER_GET_SEQ_LIST_SORTED \ 33 0x0001 /* Retrieve elements from iterator \ 34 * in increasing offset order, for \ 35 * each call to retrieve sequences. \ 36 * Currently, this only applies to \ 37 * point selections, as hyperslab \ 38 * selections are always returned \ 39 * in increasing offset order. \ 40 * \ 41 * Note that the order is only \ 42 * increasing for each call to \ 43 * get_seq_list, the next set of \ 44 * sequences could start with an \ 45 * earlier offset than the previous \ 46 * one. \ 47 */ 48 #define H5S_SEL_ITER_SHARE_WITH_DATASPACE \ 49 0x0002 /* Don't copy the dataspace \ 50 * selection when creating the \ 51 * selection iterator. \ 52 * \ 53 * This can improve performance \ 54 * of creating the iterator, but \ 55 * the dataspace _MUST_NOT_ be \ 56 * modified or closed until the \ 57 * selection iterator is closed \ 58 * or the iterator's behavior \ 59 * will be undefined. \ 60 */ 61 62 /* Different types of dataspaces */ 63 typedef enum H5S_class_t { 64 H5S_NO_CLASS = -1, /*error */ 65 H5S_SCALAR = 0, /*scalar variable */ 66 H5S_SIMPLE = 1, /*simple dataspace */ 67 H5S_NULL = 2 /*null dataspace */ 68 } H5S_class_t; 69 70 /* Different ways of combining selections */ 71 typedef enum H5S_seloper_t { 72 H5S_SELECT_NOOP = -1, /* error */ 73 H5S_SELECT_SET = 0, /* Select "set" operation */ 74 H5S_SELECT_OR, /* Binary "or" operation for hyperslabs 75 * (add new selection to existing selection) 76 * Original region: AAAAAAAAAA 77 * New region: BBBBBBBBBB 78 * A or B: CCCCCCCCCCCCCCCC 79 */ 80 H5S_SELECT_AND, /* Binary "and" operation for hyperslabs 81 * (only leave overlapped regions in selection) 82 * Original region: AAAAAAAAAA 83 * New region: BBBBBBBBBB 84 * A and B: CCCC 85 */ 86 H5S_SELECT_XOR, /* Binary "xor" operation for hyperslabs 87 * (only leave non-overlapped regions in selection) 88 * Original region: AAAAAAAAAA 89 * New region: BBBBBBBBBB 90 * A xor B: CCCCCC CCCCCC 91 */ 92 H5S_SELECT_NOTB, /* Binary "not" operation for hyperslabs 93 * (only leave non-overlapped regions in original selection) 94 * Original region: AAAAAAAAAA 95 * New region: BBBBBBBBBB 96 * A not B: CCCCCC 97 */ 98 H5S_SELECT_NOTA, /* Binary "not" operation for hyperslabs 99 * (only leave non-overlapped regions in new selection) 100 * Original region: AAAAAAAAAA 101 * New region: BBBBBBBBBB 102 * B not A: CCCCCC 103 */ 104 H5S_SELECT_APPEND, /* Append elements to end of point selection */ 105 H5S_SELECT_PREPEND, /* Prepend elements to beginning of point selection */ 106 H5S_SELECT_INVALID /* Invalid upper bound on selection operations */ 107 } H5S_seloper_t; 108 109 /* Enumerated type for the type of selection */ 110 typedef enum { 111 H5S_SEL_ERROR = -1, /* Error */ 112 H5S_SEL_NONE = 0, /* Nothing selected */ 113 H5S_SEL_POINTS = 1, /* Points / elements selected */ 114 H5S_SEL_HYPERSLABS = 2, /* Hyperslab selected */ 115 H5S_SEL_ALL = 3, /* Entire extent selected */ 116 H5S_SEL_N /*THIS MUST BE LAST */ 117 } H5S_sel_type; 118 119 #ifdef __cplusplus 120 extern "C" { 121 #endif 122 123 /* Operations on dataspaces, dataspace selections and selection iterators */ 124 125 /** 126 * \ingroup H5S 127 * 128 * \brief Releases and terminates access to a dataspace 129 * 130 * \space_id 131 * 132 * \return \herr_t 133 * 134 * \details H5Sclose() releases a dataspace. Further access through the 135 * dataspace identifier is illegal. Failure to release a dataspace with this 136 * call will result in resource leaks. 137 * 138 * \version 1.4.0 Fortran subroutine introduced in this release. 139 * \since 1.0.0 140 * 141 */ 142 H5_DLL herr_t H5Sclose(hid_t space_id); 143 /** 144 * \ingroup H5S 145 * 146 * \brief Performs an operation on a hyperslab and an existing selection and 147 * returns the resulting selection 148 * 149 * \space_id 150 * \param[in] op Operation to perform on the current selection 151 * \param[in] start Offset of the start of of the hyperslab 152 * \param[in] stride Hyperslab stride 153 * \param[in] count Number of blocks included in the hyperslab 154 * \param[in] block Size of a block in the hyperslab 155 * 156 * \return \hid_tv{dataspace} 157 * 158 * \details H5Scombine_hyperslab() combines a hyperslab selection specified 159 * by \p start, \p stride, \p count and \p block with the current 160 * selection for the dataspace \p space_id, creating a new dataspace 161 * to return the generated selection. If the current selection is 162 * not a hyperslab, it is freed and the hyperslab parameters passed 163 * in are combined with the #H5S_SEL_ALL hyperslab (ie. a selection 164 * composing the entire current extent). If either \p stride or 165 * \p block is NULL, then it will be set to \p 1. 166 * 167 * \since 1.10.6 168 * 169 */ 170 H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], 171 const hsize_t stride[], const hsize_t count[], const hsize_t block[]); 172 /** 173 * \ingroup H5S 174 * 175 * \brief Combine two hyperslab selections with an operation, returning a 176 * dataspace with the resulting selection 177 * 178 * \space_id{space1_id} 179 * \param[in] op Selection operator 180 * \space_id{space2_id} 181 * 182 * \return \hid_t{dataspace} 183 * 184 * \details H5Scombine_select() combines two hyperslab selections 185 * \p space1_id and \p space2_id with an operation, returning a 186 * new dataspace with the resulting selection. The dataspace extent 187 * from \p space1_id is copied for the dataspace extent of the 188 * newly created dataspace. 189 * 190 * \since 1.10.6 191 * 192 */ 193 H5_DLL hid_t H5Scombine_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); 194 /** 195 * \ingroup H5S 196 * 197 * \brief Creates an exact copy of a dataspace 198 * 199 * \space_id 200 * 201 * \return \hid_tv{dataspace} 202 * 203 * \details H5Scopy() creates a new dataspace which is an exact copy of the 204 * dataspace identified by \p space_id. The dataspace identifier 205 * returned from this function should be released with H5Sclose() 206 * or resource leaks will occur. 207 * 208 * \version 1.4.0 Fortran subroutine introduced. 209 * \since 1.0.0 210 * 211 */ 212 H5_DLL hid_t H5Scopy(hid_t space_id); 213 /** 214 * \ingroup H5S 215 * 216 * \brief Creates a new dataspace of a specified type 217 * 218 * \param[in] type Type of dataspace to be created 219 * 220 * \return \hid_t{dataspace} 221 * 222 * \details H5Screate() creates a new dataspace of a particular type. Currently 223 * supported types are #H5S_SCALAR, #H5S_SIMPLE, and #H5S_NULL. 224 * 225 * Further dataspace types may be added later. 226 * 227 * A scalar dataspace, #H5S_SCALAR, has a single element, though that 228 * element may be of a complex datatype, such as a compound or array 229 * datatype. By convention, the rank of a scalar dataspace is always \p 0 230 * (zero); think of it geometrically as a single, dimensionless point, 231 * though that point can be complex. 232 * 233 * A simple dataspace, #H5S_SIMPLE, consists of a regular array of elements. 234 * 235 * A null dataspace, #H5S_NULL, has no data elements. 236 * 237 * The dataspace identifier returned by this function can be released with 238 * H5Sclose() so that resource leaks will not occur. 239 * 240 * \version 1.4.0 Fortran subroutine introduced. 241 * \since 1.0.0 242 * 243 */ 244 H5_DLL hid_t H5Screate(H5S_class_t type); 245 /** 246 * \ingroup H5S 247 * \brief Creates a new simple dataspace and opens it for access 248 * 249 * \param[in] rank Number of dimensions of dataspace 250 * \param[in] dims Array specifying the size of each dimension 251 * \param[in] maxdims Array specifying the maximum size of each dimension 252 * 253 * \return \hid_t{dataspace} 254 * 255 * \details H5Screate_simple() creates a new simple dataspace and opens it 256 * for access, returning a dataspace identifier. 257 * 258 * \p rank is the number of dimensions used in the dataspace. 259 * 260 * \p dims is a one-dimensional array of size rank specifying the 261 * size of each dimension of the dataset. \p maxdims is an array of 262 * the same size specifying the upper limit on the size of each 263 * dimension. 264 * 265 * Any element of \p dims can be \p 0 (zero). Note that no data can 266 * be written to a dataset if the size of any dimension of its current 267 * dataspace is \p 0. This is sometimes a useful initial state for 268 * a dataset. 269 * 270 * \p maxdims may be the null pointer, in which case the upper limit 271 * is the same as \p dims. Otherwise, no element of \p maxdims 272 * should be smaller than the corresponding element of \p dims. 273 * 274 * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of 275 * the corresponding dimension is unlimited. 276 * 277 * Any dataset with an unlimited dimension must also be chunked; see 278 * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims 279 * does not equal \p maxdims. 280 * 281 * The dataspace identifier returned from this function must be 282 * released with H5Sclose() or resource leaks will occur. 283 * 284 * \note Once a dataspace has been created, specific regions or elements in 285 * the dataspace can be selected and selections can be removed, as well. 286 * For example, H5Sselect_hyperslab() selects a region in a dataspace and 287 * H5Sselect_elements() selects array elements in a dataspace. These 288 * functions are used for subsetting. H5Sselect_none() removes all 289 * selections from a dataspace and is used in Parallel HDF5 when a process 290 * does not have or need to write data. 291 * 292 * \version 1.4.0 Fortran subroutine introduced. 293 * 294 * \since 1.0.0 295 * 296 */ 297 H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]); 298 /** 299 * \ingroup H5S 300 * 301 * \brief Decodes a binary object description of data space and returns a 302 * new object handle 303 * 304 * \param[in] buf Buffer for the data space object to be decoded 305 * 306 * \return \hid_t{dataspace} 307 * 308 * \details Given an object description of a dataspace in binary in a 309 * buffer, H5Sdecode() reconstructs the HDF5 data type object and 310 * returns a new object handle for it. The binary description of the 311 * object is encoded by H5Sencode(). The user is responsible for 312 * passing in the right buffer. The types of dataspace addressed 313 * in this function are null, scalar, and simple space. For a 314 * simple dataspace, the selection information (for example, 315 * hyperslab selection) is also encoded and decoded. A complex 316 * dataspace has not been implemented in the library. 317 * 318 * \since 1.8.0 319 * 320 */ 321 H5_DLL hid_t H5Sdecode(const void *buf); 322 /** 323 * \ingroup H5S 324 * 325 * \brief Encodes a data space object description into a binary buffer 326 * 327 * \space_id{obj_id} 328 * \param[in,out] buf Buffer for the object to be encoded into; 329 * If the provided buffer is NULL, only the size 330 * of buffer needed is returned through \p nalloc. 331 * \param[in,out] nalloc The size of the allocated buffer 332 * \fapl_id{fapl} 333 * 334 * \return \herr_t 335 * 336 * \details Given the data space identifier \p obj_id, H5Sencode2() converts 337 * a data space description into binary form in a buffer. Using this 338 * binary form in the buffer, a data space object can be 339 * reconstructed with H5Sdecode() to return a new object handle 340 * (#hid_t) for this data space. 341 * 342 * A preliminary H5Sencode2() call can be made to determine the 343 * size of the buffer needed. This value is returned in \p nalloc. 344 * That value can then be assigned to \p nalloc for a second 345 * H5Sencode2() call, which will retrieve the actual encoded object. 346 * 347 * If the library determines that \p nalloc is not big enough for the 348 * object, it simply returns the size of the buffer needed through 349 * \p nalloc without encoding the provided buffer. 350 * 351 * The file access property list \p fapl_id is used to control the 352 * encoding via the \a libver_bounds property (see 353 * H5Pset_libver_bounds()). If the \a libver_bounds property is missing, 354 * H5Sencode2() proceeds as if the \a libver_bounds property were set to 355 * (#H5F_LIBVER_EARLIEST, #H5F_LIBVER_LATEST). (Functionally, 356 * H5Sencode1() is identical to H5Sencode2() with \a libver_bounds set to 357 * (#H5F_LIBVER_EARLIEST, #H5F_LIBVER_LATEST).) 358 * 359 * The types of data space that are addressed in this function are 360 * null, scalar, and simple space. For a simple data space, the 361 * information on the selection, for example, hyperslab selection, 362 * is also encoded and decoded. A complex data space has not been 363 * implemented in the library. 364 * 365 * \note Motivation: This function was introduced in HDF5-1.12 as part of the 366 * H5Sencode() format change to enable 64-bit selection encodings and 367 * a dataspace selection that is tied to a file. See the \ref_news_112 368 * as well as the \ref_sencode_fmt_change. 369 * 370 * \since 1.12.0 371 * 372 */ 373 H5_DLL herr_t H5Sencode2(hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl); 374 /** 375 * \ingroup H5S 376 * 377 * \brief Copies the extent of a dataspace 378 * 379 * \space_id{dst_id} 380 * \space_id{src_id} 381 * 382 * \return \herr_t 383 * 384 * \details H5Sextent_copy() copies the extent from \p src_id to \p dst_id. 385 * This action may change the type of the dataspace. 386 * 387 * \version 1.4.0 Fortran subroutine was introduced. 388 * \since 1.0.0 389 * 390 */ 391 H5_DLL herr_t H5Sextent_copy(hid_t dst_id, hid_t src_id); 392 /** 393 * \ingroup H5S 394 * 395 * \brief Determines whether two dataspace extents are equal 396 * 397 * \space_id{space1_id} 398 * \space_id{space2_id} 399 * 400 * \return \htri_t 401 * 402 * \details H5Sextent_equal() determines whether the dataspace extents of 403 * two dataspaces, \p space1_id and \p space2_id, are equal. 404 * 405 * \since 1.8.0 406 * 407 */ 408 H5_DLL htri_t H5Sextent_equal(hid_t space1_id, hid_t space2_id); 409 /** 410 * \ingroup H5S 411 * 412 * \brief Retrieves a regular hyperslab selection 413 * 414 * \space_id{spaceid} 415 * \param[out] start Offset of the start of the regular hyperslab 416 * \param[out] stride Stride of the regular hyperslab 417 * \param[out] count Number of blocks in the regular hyperslab 418 * \param[out] block Size of a block in the regular hyperslab 419 * 420 * \return \herr_t 421 * 422 * \details H5Sget_regular_hyperslab() takes the dataspace identifier, 423 * \p spaceid, and retrieves the values of \p start, \p stride, 424 * \p count, and \p block for the regular hyperslab selection. 425 * 426 * A regular hyperslab selection is a hyperslab selection 427 * described by setting the \p offset, \p stride, \p count, and 428 * \p block parameters to the H5Sselect_hyperslab() call. If 429 * several calls to H5Sselect_hyperslab() are needed, the 430 * hyperslab selection is irregular. 431 * 432 * See H5Sselect_hyperslab() for descriptions of \p offset, 433 * \p stride, \p count, and \p block. 434 * 435 * \note If a hyperslab selection is originally regular, then becomes 436 * irregular through selection operations, and then becomes regular 437 * again, the final regular selection may be equivalent but not 438 * identical to the original regular selection. 439 * 440 * \since 1.10.0 441 * 442 */ 443 H5_DLL htri_t H5Sget_regular_hyperslab(hid_t spaceid, hsize_t start[], hsize_t stride[], hsize_t count[], 444 hsize_t block[]); 445 /** 446 * \ingroup H5S 447 * 448 * \brief Gets the bounding box containing the current selection 449 * 450 * \space_id{spaceid} 451 * \param[out] start Starting coordinates of the bounding box 452 * \param[out] end Ending coordinates of the bounding box, i.e., the 453 * coordinates of the diagonally opposite corner 454 * 455 * \return \herr_t 456 * 457 * \details H5Sget_select_bounds() retrieves the coordinates of the bounding 458 * box containing the current selection and places them into 459 * user-supplied buffers. 460 * 461 * The \p start and \p end buffers must be large enough to hold 462 * the dataspace rank number of coordinates. 463 * 464 * The bounding box exactly contains the selection. I.e., if a 465 * 2-dimensional element selection is currently defined as containing 466 * the points (4,5), (6,8), and (10,7), then the bounding box 467 * will be (4, 5), (10, 8). 468 * 469 * The bounding box calculation includes the current offset of the 470 * selection within the dataspace extent. 471 * 472 * Calling this function on a \a none selection will fail. 473 * 474 * \version 1.6.0 The \p start and \p end parameters have changed from type 475 * \p hsize_t * to \p hssize_t *. 476 * \version 1.4.0 Fortran subroutine was introduced. 477 * \since 1.2.0 478 * 479 */ 480 H5_DLL herr_t H5Sget_select_bounds(hid_t spaceid, hsize_t start[], hsize_t end[]); 481 /** 482 * \ingroup H5S 483 * 484 * \brief Gets the number of element points in the current selection 485 * 486 * \space_id{spaceid} 487 * 488 * \return Returns the number of element points in the current dataspace 489 * selection if successful. Otherwise returns a negative value. 490 * 491 * \details H5Sget_select_elem_npoints() returns the number of element 492 * points in the current dataspace selection, so that the element 493 * points can be retrieved with H5Sget_select_elem_pointlist(). 494 * (This is similar to the way that H5Sget_select_hyper_nblocks() 495 * and H5Sget_select_hyper_blocklist() work with hyperslab 496 * selections.) 497 * 498 * Coincidentally, H5Sget_select_npoints() and 499 * H5Sget_select_elem_npoints() will always return the same value 500 * when an element selection is queried, but 501 * H5Sget_select_elem_npoints() does not work with other selection 502 * types. 503 * 504 * \since 1.2.0 505 * 506 */ 507 H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid); 508 /** 509 * \ingroup H5S 510 * 511 * \brief Gets the list of element points currently selected 512 * 513 * \space_id{spaceid} 514 * \param[in] startpoint Element point to start with 515 * \param[in] numpoints Number of element points to get 516 * \param[out] buf List of element points selected 517 * 518 * \details H5Sget_select_elem_pointlist() returns the list of element 519 * points in the current dataspace selection \p space_id. Starting 520 * with the \p startpoint in the list of points, \p numpoints 521 * points are put into the user's buffer. If the user's buffer 522 * fills up before \p numpoints points are inserted, the buffer 523 * will contain only as many points as fit. 524 * 525 * The element point coordinates have the same dimensionality 526 * (rank) as the dataspace they are located within. The list of 527 * element points is formatted as follows:\n 528 * \<coordinate\>, followed by\n 529 * the next coordinate,\n 530 * etc.\n 531 * until all of the selected element points have been listed. 532 * 533 * The points are returned in the order they will be iterated 534 * through when the selection is read/written from/to disk. 535 * 536 * \since 1.2.0 537 * 538 */ 539 H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, 540 hsize_t buf[/*numpoints*/]); 541 /** 542 * \ingroup H5S 543 * 544 * \brief Gets the list of hyperslab blocks currently selected 545 * 546 * \space_id{spaceid} 547 * \param[in] startblock Hyperslab block to start with 548 * \param[in] numblocks Number of hyperslab blocks to get 549 * \param[out] buf List of hyperslab blocks selected 550 * 551 * \return \herr_t 552 * 553 * \details H5Sget_select_hyper_blocklist() returns a list of the hyperslab 554 * blocks currently selected. Starting with the \p startblock-th block 555 * in the list of blocks, \p numblocks blocks are put into the 556 * user's buffer. If the user's buffer fills up before \p numblocks 557 * blocks are inserted, the buffer will contain only as many blocks 558 * as fit. 559 * 560 * The block coordinates have the same dimensionality (rank) as the 561 * dataspace they are located within. The list of blocks is 562 * formatted as follows:\n 563 * \<"start" coordinate\>, immediately followed by\n 564 * \<"opposite" corner coordinate\>, followed by\n 565 * the next "start" and "opposite" coordinates,\n 566 * etc. until all of the selected blocks have been listed.\n 567 * No guarantee of any order of the blocks is implied. 568 * 569 * \since 1.2.0 570 * 571 */ 572 H5_DLL herr_t H5Sget_select_hyper_blocklist(hid_t spaceid, hsize_t startblock, hsize_t numblocks, 573 hsize_t buf[/*numblocks*/]); 574 /** 575 * \ingroup H5S 576 * 577 * \brief Get number of hyperslab blocks 578 * 579 * \space_id{spaceid} 580 * 581 * \return Returns the number of hyperslab blocks in the current dataspace 582 * selection if successful. Otherwise returns a negative value. 583 * 584 * \details H5Sget_select_hyper_nblocks() returns the number of hyperslab 585 * blocks in the current dataspace selection. 586 * 587 * \since 1.2.0 588 * 589 */ 590 H5_DLL hssize_t H5Sget_select_hyper_nblocks(hid_t spaceid); 591 /** 592 * \ingroup H5S 593 * 594 * \brief Determines the number of elements in a dataspace selection 595 * 596 * \space_id{spaceid} 597 * 598 * \return Returns the number of elements in the selection if successful; 599 * otherwise returns a negative value. 600 * 601 * \details H5Sget_select_npoints() determines the number of elements in 602 * the current selection of a dataspace. It works with any 603 * selection type, and is the correct way to retrieve the number 604 * of elements in a selection. 605 * 606 * \version 1.4.0 Fortran subroutine introduced in this release. 607 * \since 1.0.0 608 * 609 */ 610 H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); 611 /** 612 * \ingroup H5S 613 * 614 * \brief Determines the type of the dataspace selection 615 * 616 * \space_id{spaceid} 617 * 618 * \return Returns the dataspace selection type, a value of the enumerated 619 * datatype #H5S_sel_type, if successful. 620 * 621 * \details H5Sget_select_type() retrieves the type of dataspace selection 622 * currently defined for the dataspace \p space_id. Valid values 623 * for the dataspace selection type are: 624 * 625 * <table> 626 * <tr> 627 * <td>#H5S_SEL_NONE</td> 628 * <td>No selection is defined</td> 629 * </tr> 630 * <tr> 631 * <td>#H5S_SEL_POINTS</td> 632 * <td>A sequence of points is selected</td> 633 * </tr> 634 * <tr> 635 * <td>#H5S_SEL_HYPERSLABS</td> 636 * <td>A hyperslab or compound hyperslab is selected</td> 637 * </tr> 638 * <tr> 639 * <td>#H5S_SEL_ALL</td> 640 * <td>The entire dataset is selected</td> 641 * </tr> 642 * </table> 643 * 644 * Otherwise returns a negative value. 645 * 646 * \since 1.6.0 647 * 648 */ 649 H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid); 650 /** 651 * \ingroup H5S 652 * 653 * \brief Retrieves dataspace dimension size and maximum size 654 * 655 * \space_id 656 * \param[out] dims Pointer to array to store the size of each dimension 657 * \param[out] maxdims Pointer to array to store the maximum size of each 658 * dimension 659 * 660 * \return Returns the number of dimensions in the dataspace if successful; 661 * otherwise returns a negative value. 662 * 663 * \details H5Sget_simple_extent_dims() returns the size and maximum sizes 664 * of each dimension of a dataspace \p space_id through the \p dims 665 * and \p maxdims parameters. 666 * 667 * Either or both of \p dims and \p maxdims may be NULL. 668 * 669 * If a value in the returned array \p maxdims is #H5S_UNLIMITED (-1), 670 * the maximum size of that dimension is unlimited. 671 * 672 * \version 1.4.0 Fortran subroutine introduced. 673 * \since 1.0.0 674 * 675 */ 676 H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]); 677 /** 678 * \ingroup H5S 679 * 680 * \brief Determines the dimensionality of a dataspace 681 * 682 * \space_id 683 * 684 * \return Returns the number of dimensions in the dataspace if successful; 685 * otherwise returns a negative value. 686 * 687 * \details H5Sget_simple_extent_ndims() determines the dimensionality (or 688 * rank) of a dataspace. 689 * 690 * \version 1.4.0 Fortran subroutine introduced. 691 * \since 1.0.0 692 * 693 */ 694 H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); 695 /** 696 * \ingroup H5S 697 * 698 * \brief Determines the number of elements in a dataspace 699 * 700 * \space_id 701 * 702 * \return Returns the number of elements in the dataspace if successful; 703 * otherwise returns a negative value. 704 * 705 * \details H5Sget_simple_extent_npoints() determines the number of elements 706 * in a dataspace \p space_id. For example, a simple 3-dimensional 707 * dataspace with dimensions 2, 3, and 4 would have 24 elements. 708 * 709 * \version 1.4.0 Fortran subroutine introduced. 710 * \since 1.0.0 711 * 712 */ 713 H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id); 714 /** 715 * \ingroup H5S 716 * 717 * \brief Determines the current class of a dataspace 718 * 719 * \space_id 720 * 721 * \return Returns a dataspace class name if successful; 722 * otherwise #H5S_NO_CLASS (-1). 723 * 724 * \details H5Sget_simple_extent_type() determines the current class of a 725 * dataspace \p space_id. 726 * 727 * \version 1.4.0 Fortran subroutine was introduced. 728 * \since 1.0.0 729 * 730 */ 731 H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id); 732 /** 733 * \ingroup H5S 734 * 735 * \brief Determines if a hyperslab selection is regular 736 * 737 * \space_id{spaceid} 738 * 739 * \return \htri_t 740 * 741 * \details H5Sis_regular_hyperslab() takes the dataspace identifier, 742 * \p spaceid, and queries the type of the hyperslab selection. 743 * 744 * A regular hyperslab selection is a hyperslab selection described 745 * by setting the offset, stride, count, and block parameters for 746 * a single H5Sselect_hyperslab() call. If several calls to 747 * H5Sselect_hyperslab() are needed, then the hyperslab selection 748 * is irregular. 749 * 750 * \since 1.10.0 751 * 752 */ 753 H5_DLL htri_t H5Sis_regular_hyperslab(hid_t spaceid); 754 /** 755 * \ingroup H5S 756 * 757 * \brief Determines whether a dataspace is a simple dataspace 758 * 759 * \space_id 760 * 761 * \return \htri_t 762 * 763 * \details H5Sis_simple() determines whether or not a dataspace is a simple 764 * dataspace. 765 * 766 * \note Currently, all dataspace objects are simple dataspaces; complex 767 * dataspace support will be added in the future. 768 * 769 * \version 1.4.0 Fortran subroutine was introduced. 770 * \since 1.0.0 771 * 772 */ 773 H5_DLL htri_t H5Sis_simple(hid_t space_id); 774 /** 775 * \ingroup H5S 776 * 777 * \brief Refines a hyperslab selection with an operation, using a second 778 * hyperslab to modify it 779 * 780 * \space_id{space1_id} 781 * \param[in] op Selection operator 782 * \space_id{space2_id} 783 * 784 * \return \herr_t 785 * 786 * \details H5Smodify_select() refines an existing hyperslab selection 787 * \p space1_id with an operation \p op, using a second hyperslab 788 * \p space2_id. The first selection is modified to contain the 789 * result of \p space1_id operated on by \p space2_id. 790 * 791 * \since 1.10.6 792 * 793 */ 794 H5_DLL herr_t H5Smodify_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); 795 /** 796 * \ingroup H5S 797 * 798 * \brief Sets the offset of a simple dataspace 799 * 800 * \space_id 801 * \param[in] offset The offset at which to position the selection 802 * 803 * \return \herr_t 804 * 805 * \details H5Soffset_simple() sets the offset of a simple dataspace 806 * \p space_id. The offset array must be the same number of 807 * elements as the number of dimensions for the dataspace. If the 808 * \p offset array is set to NULL, the offset for the dataspace is 809 * reset to 0. 810 * 811 * This function allows the same shaped selection to be moved to 812 * different locations within a dataspace without requiring it to 813 * be redefined. 814 * 815 * \version 1.4.0 Fortran subroutine was introduced. 816 * \since 1.0.0 817 * 818 */ 819 H5_DLL herr_t H5Soffset_simple(hid_t space_id, const hssize_t *offset); 820 /** 821 * \ingroup H5S 822 * 823 * \brief Closes a dataspace selection iterator 824 * 825 * \space_id{sel_iter_id} 826 * 827 * \return \herr_t 828 * 829 * \details H5Ssel_iter_close() closes a dataspace selection iterator 830 * specified by \p sel_iter_id, releasing its state. 831 * 832 * \since 1.12.0 833 * 834 */ 835 H5_DLL herr_t H5Ssel_iter_close(hid_t sel_iter_id); 836 /**\ingroup H5S 837 * 838 * \brief Creates a dataspace selection iterator for a dataspace's selection 839 * 840 * \space_id{spaceid} 841 * \param[in] elmt_size Size of element in the selection 842 * \param[in] flags Selection iterator flag 843 * 844 * \return \hid_t{valid dataspace selection iterator} 845 * 846 * \details H5Ssel_iter_create() creates a selection iterator and initializes 847 * it to start at the first element selected in the dataspace. 848 * 849 * \since 1.12.0 850 * 851 */ 852 H5_DLL hid_t H5Ssel_iter_create(hid_t spaceid, size_t elmt_size, unsigned flags); 853 /** 854 * \ingroup H5S 855 * 856 * \brief Retrieves a list of offset / length sequences for the elements in 857 * an iterator 858 * 859 * \space_id{sel_iter_id} 860 * \param[in] maxseq Maximum number of sequences to retrieve 861 * \param[in] maxbytes Maximum number of bytes to retrieve in sequences 862 * \param[out] nseq Number of sequences retrieved 863 * \param[out] nbytes Number of bytes retrieved, in all sequences 864 * \param[out] off Array of sequence offsets 865 * \param[out] len Array of sequence lengths 866 * 867 * \return \herr_t 868 * 869 * \details H5Ssel_iter_get_seq_list() retrieves a list of offset / length 870 * pairs (a list of "sequences") matching the selected elements for 871 * an iterator \p sel_iter_id, according to the iteration order for 872 * the iterator. The lengths returned are in bytes, not elements. 873 * 874 * Note that the iteration order for "all" and "hyperslab" 875 * selections is row-major (i.e. "C-ordered"), but the iteration 876 * order for "point" selections is "in order selected", unless the 877 * #H5S_SEL_ITER_GET_SEQ_LIST_SORTED flag is passed to 878 * H5Ssel_iter_create() for a point selection. 879 * 880 * \p maxseq and \p maxbytes specify the most sequences or bytes 881 * possible to place into the \p off and \p len arrays. \p nseq and 882 * \p nbytes return the actual number of sequences and bytes put 883 * into the arrays. 884 * 885 * Each call to H5Ssel_iter_get_seq_list() will retrieve the next 886 * set of sequences for the selection being iterated over. 887 * 888 * The total number of bytes possible to retrieve from a selection 889 * iterator is the \p elmt_size passed to H5Ssel_iter_create() 890 * multiplied by the number of elements selected in the dataspace 891 * the iterator was created from (which can be retrieved with 892 * H5Sget_select_npoints(). When there are no further sequences of 893 * elements to retrieve, calls to this routine will set \p nseq 894 * and \p nbytes to zero. 895 * 896 * \since 1.12.0 897 * 898 */ 899 H5_DLL herr_t H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq, size_t maxbytes, size_t *nseq, 900 size_t *nbytes, hsize_t *off, size_t *len); 901 /** 902 * \ingroup H5S 903 * 904 * \brief Resets a dataspace selection iterator back to an initial state 905 * 906 * \param[in] sel_iter_id Identifier of the dataspace selection iterator 907 * to reset 908 * \param[in] space_id Identifier of the dataspace with selection to 909 * iterate over 910 * 911 * \return \herr_t 912 * 913 * \details H5Ssel_iter_reset() resets a dataspace selection iterator back to 914 * an initial state so that the iterator may be used for iteration 915 * once again. 916 * 917 * \since 1.12.1 918 * 919 */ 920 H5_DLL herr_t H5Ssel_iter_reset(hid_t sel_iter_id, hid_t space_id); 921 /** 922 * \ingroup H5S 923 * 924 * \brief Adjusts a selection by subtracting an offset 925 * 926 * \space_id{spaceid} 927 * \param[in] offset Offset to subtract 928 * 929 * \return \herr_t 930 * 931 * \details H5Sselect_adjust() shifts a dataspace selection by a specified 932 * logical offset within the dataspace extent. 933 * 934 * \note This can be useful for VOL developers to implement chunked datasets. 935 * 936 * \since 1.10.6 937 */ 938 H5_DLL herr_t H5Sselect_adjust(hid_t spaceid, const hssize_t *offset); 939 /** 940 * \ingroup H5S 941 * 942 * \brief Selects an entire dataspace 943 * 944 * \space_id{spaceid} 945 * 946 * \return \herr_t 947 * 948 * \details H5Sselect_all() selects the entire extent of the dataspace 949 * \p dspace_id. 950 * 951 * More specifically, H5Sselect_all() sets the selection type to 952 * #H5S_SEL_ALL, which specifies the entire dataspace anywhere it 953 * is applied. 954 * 955 * \since 1.0.0 956 * 957 */ 958 H5_DLL herr_t H5Sselect_all(hid_t spaceid); 959 /** 960 * \ingroup H5S 961 * 962 * \brief Copies a selection from one dataspace to another 963 * 964 * \space_id{dst_id} 965 * \space_id{src_id} 966 * 967 * \return \herr_t 968 * 969 * \details H5Sselect_copy() copies all selection information (including 970 * offset) from the source dataspace \p src_id to the destination 971 * dataspace \p dst_id. 972 * 973 * \since 1.10.6 974 * 975 */ 976 H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id); 977 /** 978 * \ingroup H5S 979 * 980 * \brief Selects array elements to be included in the selection for a 981 * dataspace 982 * 983 * \space_id 984 * \param[in] op Operator specifying how the new selection is to be 985 * combined with the existing selection for the dataspace 986 * \param[in] num_elem Number of elements to be selected 987 * \param[in] coord A pointer to a buffer containing a serialized copy of 988 * a 2-dimensional array of zero-based values specifying 989 * the coordinates of the elements in the point selection 990 * 991 * \return \herr_t 992 * 993 * \details H5Sselect_elements() selects array elements to be included in 994 * the selection for the \p space_id dataspace. This is referred 995 * to as a point selection. 996 * 997 * The number of elements selected is set in the \p num_elements 998 * parameter. 999 * 1000 * The \p coord parameter is a pointer to a buffer containing a 1001 * serialized 2-dimensional array of size \p num_elements by the 1002 * rank of the dataspace. The array lists dataset elements in the 1003 * point selection; that is, it’s a list of of zero-based values 1004 * specifying the coordinates in the dataset of the selected 1005 * elements. The order of the element coordinates in the \p coord 1006 * array specifies the order in which the array elements are 1007 * iterated through when I/O is performed. Duplicate coordinate 1008 * locations are not checked for. See below for examples of the 1009 * mapping between the serialized contents of the buffer and the 1010 * point selection array that it represents. 1011 * 1012 * The selection operator \p op determines how the new selection 1013 * is to be combined with the previously existing selection for 1014 * the dataspace. The following operators are supported: 1015 * 1016 * <table> 1017 * <tr> 1018 * <td>#H5S_SELECT_SET</td> 1019 * <td>Replaces the existing selection with the parameters from 1020 * this call. Overlapping blocks are not supported with this 1021 * operator. Adds the new selection to the existing selection. 1022 * </td> 1023 * </tr> 1024 * <tr> 1025 * <td>#H5S_SELECT_APPEND</td> 1026 * <td>Adds the new selection following the last element of the 1027 * existing selection.</td> 1028 * </tr> 1029 * <tr> 1030 * <td>#H5S_SELECT_PREPEND</td> 1031 * <td>Adds the new selection preceding the first element of the 1032 * existing selection.</td> 1033 * </tr> 1034 * </table> 1035 * 1036 * <b>Mapping the serialized \p coord buffer to a 2-dimensional 1037 * point selection array:</b> 1038 * To illustrate the construction of the contents of the \p coord 1039 * buffer, consider two simple examples: a selection of 5 points in 1040 * a 1-dimensional array and a selection of 3 points in a 1041 * 4-dimensional array. 1042 * 1043 * In the 1D case, we will be selecting five points and a 1D 1044 * dataspace has rank 1, so the selection will be described in a 1045 * 5-by-1 array. To select the 1st, 14th, 17th, 23rd, 8th elements 1046 * of the dataset, the selection array would be as follows 1047 * (remembering that point coordinates are zero-based): 1048 * \n 0 1049 * \n 13 1050 * \n 16 1051 * \n 22 1052 * \n 7 1053 * 1054 * This point selection array will be serialized in the \p coord 1055 * buffer as: 1056 * \n 0 13 16 22 7 1057 * 1058 * In the 4D case, we will be selecting three points and a 4D 1059 * dataspace has rank 4, so the selection will be described in a 1060 * 3-by-4 array. To select the points (1,1,1,1), (14,6,12,18), and 1061 * (8,22,30,22), the point selection array would be as follows: 1062 * \n 0 0 0 0 1063 * \n 13 5 11 17 1064 * \n 7 21 29 21 1065 * 1066 * This point selection array will be serialized in the \p coord 1067 * buffer as: 1068 * \n 0 0 0 0 13 5 11 17 7 21 29 21 1069 * 1070 * \version 1.6.4 C coord parameter type changed to \p const hsize_t. 1071 * \version 1.6.4 Fortran \p coord parameter type changed to \p INTEGER(HSIZE_T). 1072 * \since 1.0.0 1073 * 1074 */ 1075 H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_elem, const hsize_t *coord); 1076 /** 1077 * \ingroup H5S 1078 * 1079 * \brief Selects a hyperslab region to add to the current selected region 1080 * 1081 * \space_id 1082 * \param[in] op Operation to perform on current selection 1083 * \param[in] start Offset of start of hyperslab 1084 * \param[in] stride Hyperslab stride 1085 * \param[in] count Number of blocks included in hyperslab 1086 * \param[in] block Size of block in hyperslab 1087 * 1088 * \return \herr_t 1089 * 1090 * \details H5Sselect_hyperslab() selects a hyperslab region to add to the 1091 * current selected region for the dataspace specified by 1092 * \p space_id. 1093 * 1094 * The \p start, \p stride, \p count, and \p block arrays must be the 1095 * same size as the rank of the dataspace. For example, if the 1096 * dataspace is 4-dimensional, each of these parameters must be a 1097 * 1-dimensional array of size 4. 1098 * 1099 * The selection operator \p op determines how the new selection 1100 * is to be combined with the already existing selection for the 1101 * dataspace. The following operators are supported: 1102 * 1103 * <table> 1104 * <tr> 1105 * <td>#H5S_SELECT_SET</td> 1106 * <td>Replaces the existing selection with the 1107 * parameters from this call. Overlapping blocks 1108 * are not supported with this operator.</td> 1109 * </tr> 1110 * <tr> 1111 * <td>#H5S_SELECT_OR</td> 1112 * <td>Adds the new selection to the existing selection. 1113 * (Binary OR)</td> 1114 * </tr> 1115 * <tr> 1116 * <td>#H5S_SELECT_AND</td> 1117 * <td>Retains only the overlapping portions of the 1118 * new selection and the existing selection. 1119 * (Binary AND)</td> 1120 * </tr> 1121 * <tr> 1122 * <td>#H5S_SELECT_XOR</td> 1123 * <td>Retains only the elements that are members of 1124 * the new selection or the existing selection, 1125 * excluding elements that are members of both 1126 * selections. (Binary exclusive-OR, XOR) 1127 * </td> 1128 * </tr> 1129 * <tr> 1130 * <td>#H5S_SELECT_NOTB</td> 1131 * <td>Retains only elements of the existing selection 1132 * that are not in the new selection.</td> 1133 * </tr> 1134 * <tr> 1135 * <td>#H5S_SELECT_NOTA</td> 1136 * <td>Retains only elements of the new selection that 1137 * are not in the existing selection.</td> 1138 * </tr> 1139 * </table> 1140 * 1141 * The \p start array specifies the offset of the starting element 1142 * of the specified hyperslab. 1143 * 1144 * The \p stride array chooses array locations from the dataspace with 1145 * each value in the \p stride array determining how many elements to 1146 * move in each dimension. Setting a value in the \p stride array to 1147 * \p 1 moves to each element in that dimension of the dataspace; 1148 * setting a value of \p 2 in allocation in the \p stride array moves 1149 * to every other element in that dimension of the dataspace. In 1150 * other words, the \p stride determines the number of elements to 1151 * move from the \p start location in each dimension. Stride values 1152 * of \p 0 are not allowed. If the \p stride parameter is NULL, a 1153 * contiguous hyperslab is selected (as if each value in the \p stride 1154 * array were set to \p 1). 1155 * 1156 * The \p count array determines how many blocks to select from the 1157 * dataspace, in each dimension. 1158 * 1159 * The \p block array determines the size of the element block 1160 * selected from the dataspace. If the \p block parameter is set to 1161 * NULL, the block size defaults to a single element in each dimension 1162 * (as if each value in the \p block array were set to \p 1). 1163 * 1164 * For example, consider a 2-dimensional dataspace with hyperslab 1165 * selection settings as follows: the \p start offset is specified as 1166 * [1,1], \p stride is [4,4], \p count is [3,7], and \p block is [2,2]. 1167 * In C, these settings will specify a hyperslab consisting of 21 1168 * 2x2 blocks of array elements starting with location (1,1) with the 1169 * selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.; 1170 * in Fortran, they will specify a hyperslab consisting of 21 2x2 1171 * blocks of array elements starting with location (2,2) with the 1172 * selected blocks at locations (2,2), (6,2), (10,2), (2,6), (6,6), etc. 1173 * 1174 * Regions selected with this function call default to C order 1175 * iteration when I/O is performed. 1176 * 1177 * \version 1.4.0 Fortran subroutine introduced in this release. 1178 * \since 1.0.0 1179 * 1180 */ 1181 H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], 1182 const hsize_t stride[], const hsize_t count[], const hsize_t block[]); 1183 /*--------------------------------------------------------------------------*/ 1184 /**\ingroup H5S 1185 * 1186 * \brief Checks if current selection intersects with a block 1187 * 1188 * \space_id 1189 * \param[in] start Starting coordinate of block 1190 * \param[in] end Opposite ("ending") coordinate of block 1191 * 1192 * \return \htri_t 1193 * 1194 * \details H5Sselect_intersect_block() checks to see if the current 1195 * selection \p space_id in the dataspace intersects with the block 1196 * specified by \p start and \p end. 1197 * 1198 * \note Assumes that \p start & \p end block bounds are inclusive, so 1199 * \p start == \p end value is OK. 1200 * 1201 * \since 1.10.6 1202 * 1203 */ 1204 H5_DLL htri_t H5Sselect_intersect_block(hid_t space_id, const hsize_t *start, const hsize_t *end); 1205 /*--------------------------------------------------------------------------*/ 1206 /**\ingroup H5S 1207 * 1208 * \brief Resets the selection region to include no elements 1209 * 1210 * \space_id{spaceid} 1211 * 1212 * \return \herr_t 1213 * 1214 * \details H5Sselect_none() resets the selection region for the dataspace 1215 * \p space_id to include no elements. 1216 * 1217 * \since 1.0.0 1218 * 1219 */ 1220 H5_DLL herr_t H5Sselect_none(hid_t spaceid); 1221 /*--------------------------------------------------------------------------*/ 1222 /**\ingroup H5S 1223 * 1224 * \brief Projects the intersection of two source selections to a 1225 * destination selection 1226 * 1227 * \space_id{src_space_id} 1228 * \space_id{dst_space_id} 1229 * \space_id{src_intersect_space_id} 1230 * 1231 * \return Returns a dataspace with a selection equal to the intersection of 1232 * \p src_intersect_space_id and \p src_space_id projected from 1233 * \p src_space to \p dst_space on success, negative on failure. 1234 * 1235 * \details H5Sselect_project_intersection() computes the intersection 1236 * between two dataspace selections and projects that intersection 1237 * into a third selection.This can be useful for VOL developers to 1238 * implement chunked or virtual datasets. 1239 * 1240 * \since 1.10.6 1241 * 1242 */ 1243 H5_DLL hid_t H5Sselect_project_intersection(hid_t src_space_id, hid_t dst_space_id, 1244 hid_t src_intersect_space_id); 1245 /*--------------------------------------------------------------------------*/ 1246 /**\ingroup H5S 1247 * 1248 * \brief Checks if two selections are the same shape 1249 * 1250 * \space_id{space1_id} 1251 * \space_id{space2_id} 1252 * 1253 * \return \htri_t 1254 * 1255 * \details H5Sselect_shape_same() checks to see if the current selection 1256 * in the dataspaces are the same dimensionality and shape. 1257 * 1258 * This is primarily used for reading the entire selection in 1259 * one swoop. 1260 * 1261 * \since 1.10.6 1262 * 1263 */ 1264 H5_DLL htri_t H5Sselect_shape_same(hid_t space1_id, hid_t space2_id); 1265 /*--------------------------------------------------------------------------*/ 1266 /**\ingroup H5S 1267 * 1268 * \brief Verifies that the selection is within the extent of the dataspace 1269 * 1270 * \space_id{spaceid} 1271 * 1272 * \return \htri_t 1273 * 1274 * \details H5Sselect_valid() verifies that the selection for the dataspace 1275 * \p space_id is within the extent of the dataspace if the current 1276 * offset for the dataspace is used. 1277 * 1278 * \version 1.4.0 Fortran subroutine introduced in this release. 1279 * \since 1.0.0 1280 * 1281 */ 1282 H5_DLL htri_t H5Sselect_valid(hid_t spaceid); 1283 /*--------------------------------------------------------------------------*/ 1284 /**\ingroup H5S 1285 * 1286 * \brief Resets the extent of a dataspace back to "none" 1287 * 1288 * \space_id 1289 * 1290 * \return \herr_t 1291 * 1292 * \details H5Sset_extent_none() resets the type of a dataspace to 1293 * #H5S_NULL with no extent information stored for the dataspace. 1294 * 1295 * \version 1.10.7, 1.12.1 The function behavior changed. The previous 1296 * behavior was to set the class to #H5S_NO_CLASS. 1297 * \version 1.4.0 Fortran subroutine was introduced. 1298 * \since 1.0.0 1299 * 1300 */ 1301 H5_DLL herr_t H5Sset_extent_none(hid_t space_id); 1302 /*--------------------------------------------------------------------------*/ 1303 /**\ingroup H5S 1304 * 1305 * \brief Sets or resets the size of an existing dataspace 1306 * 1307 * \space_id 1308 * \param[in] rank Rank, or dimensionality, of the dataspace 1309 * \param[in] dims Array containing current size of dataspace 1310 * \param[in] max Array containing maximum size of dataspace 1311 * 1312 * \return \herr_t 1313 * 1314 * \details H5Sset_extent_simple() sets or resets the size of an existing 1315 * dataspace. 1316 * 1317 * \p rank is the dimensionality, or number of dimensions, of the 1318 * dataspace. 1319 * 1320 * \p dims is an array of size \p rank which contains the new size 1321 * of each dimension in the dataspace. \p max is an array of size 1322 * \p rank which contains the maximum size of each dimension in 1323 * the dataspace. 1324 * 1325 * Any previous extent is removed from the dataspace, the dataspace 1326 * type is set to #H5S_SIMPLE, and the extent is set as specified. 1327 * 1328 * Note that a dataset must be chunked if \p dims does not equal 1329 * \p max. 1330 * 1331 * 1332 * \version 1.4.0 Fortran subroutine was introduced. 1333 * \since 1.0.0 1334 * 1335 */ 1336 H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]); 1337 1338 /* Symbols defined for compatibility with previous versions of the HDF5 API. 1339 * 1340 * Use of these symbols is deprecated. 1341 */ 1342 #ifndef H5_NO_DEPRECATED_SYMBOLS 1343 /* Function prototypes */ 1344 /* --------------------------------------------------------------------------*/ 1345 /**\ingroup H5S 1346 * 1347 * \brief Encodes a data space object description into a binary buffer 1348 * 1349 * \space_id{obj_id} 1350 * \param[in,out] buf Buffer for the object to be encoded into; 1351 * If the provided buffer is NULL, only the size of 1352 * buffer needed is returned through \p nalloc. 1353 * \param[in,out] nalloc The size of the allocated buffer 1354 * 1355 * \return \herr_t 1356 * 1357 * \deprecated Deprecated in favor of H5Sencode2() 1358 * 1359 * \details Given the data space identifier \p obj_id, H5Sencode1() converts 1360 * a data space description into binary form in a buffer. Using 1361 * this binary form in the buffer, a data space object can be 1362 * reconstructed using H5Sdecode() to return a new object handle 1363 * (\p hid_t) for this data space. 1364 * 1365 * A preliminary H5Sencode1() call can be made to find out the size 1366 * of the buffer needed. This value is returned as \p nalloc. That 1367 * value can then be assigned to \p nalloc for a second H5Sencode1() 1368 * call, which will retrieve the actual encoded object. 1369 * 1370 * If the library finds out \p nalloc is not big enough for the 1371 * object, it simply returns the size of the buffer needed through 1372 * \p nalloc without encoding the provided buffer. 1373 * 1374 * The types of data space addressed in this function are null, 1375 * scalar, and simple space. For a simple data space, the information 1376 * on the selection, for example, hyperslab selection, is also 1377 * encoded and decoded. A complex data space has not been 1378 * implemented in the library. 1379 * 1380 * \version 1.12.0 The function H5Sencode() was renamed H5Sencode1() and 1381 * deprecated. 1382 * \since 1.8.0 1383 * 1384 */ 1385 H5_DLL herr_t H5Sencode1(hid_t obj_id, void *buf, size_t *nalloc); 1386 1387 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 1388 1389 #ifdef __cplusplus 1390 } 1391 #endif 1392 #endif /* H5Spublic_H */ 1393