Last modified: 17 August 2010
Name: H5Sselect_elements
Signature:
  herr_t `H5Sselect_elements`( hid_t `space_id`, H5S_seloper_t `op`, size_t `num_elements`, const hsize_t *`coord` )

Purpose:
  Selects array elements to be included in the selection for a dataspace.

Description:
  `H5Sselect_elements` selects array elements to be included in the selection for the `space_id` dataspace. This is referred to as a point selection.

  The number of elements selected is set in the `num_elements` parameter.

  The `coord` parameter is a pointer to a buffer containing a serialized 2-dimensional array of size `num_elements` by the rank of the dataspace. The array lists dataset elements in the point selection; that is, it’s a list of of zero-based values specifying the coordinates in the dataset of the selected elements. The order of the element coordinates in the `coord` array specifies the order in which the array elements are iterated through when I/O is performed. Duplicate coordinate locations are not checked for. See below for examples of the mapping between the serialized contents of the buffer and the point selection array that it represents.

  The selection operator `op` determines how the new selection is to be combined with the previously existing selection for the dataspace. The following operators are supported:

  `H5S_SELECT_SET` | Replaces the existing selection with the parameters from this call. Overlapping blocks are not supported with this operator. Adds the new selection to the existing selection.
  `H5S_SELECT_APPEND` | Adds the new selection following the last element of the existing selection.
  `H5S_SELECT_PREPEND` | Adds the new selection preceding the first element of the existing selection.

  Mapping the serialized `coord` buffer to a 2-dimensional point selection array: To illustrate the construction of the contents of the `coord` buffer, consider two simple examples: a selection of 5 points in a 1-dimensional array and a selection of 3 points in a 4-dimensional array.

  In the 1D case, we will be selecting five points and a 1D dataspace has rank 1, so the selection will be described in a 5-by-1 array. To select the 1st, 14th, 17th, 23rd, 8th elements of the dataset, the selection array would be as follows (remembering that point coordinates are zero-based):

               0
              13
              16
              22
               7

  This point selection array will be serialized in the `coord` buffer as:

               0 13 16 22 7

  In the 4D case, we will be selecting three points and a 4D dataspace has rank 4, so the selection will be described in a 3-by-4 array. To select the points (1,1,1,1), (14,6,12,18), and (8,22,30,22), the point selection array would be as follows:

               0  0  0  0
              13  5 11 17
               7 21 29 21

  This point selection array will be serialized in the `coord` buffer as:

               0 0 0 0 13 5 11 17 7 21 29 21

Parameters:

  hid_t `space_id` | IN: Identifier of the dataspace.
  H5S_seloper_t `op` | IN: Operator specifying how the new selection is to be combined with the existing selection for the dataspace.
  size_t `num_elements` | IN: Number of elements to be selected.
  const hsize_t *`coord` | IN: A pointer to a buffer containing a serialized copy of a 2-dimensional array of zero-based values specifying the coordinates of the elements in the point selection.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5sselect_elements_f

      SUBROUTINE h5sselect_elements_f(space_id, operator, rank, num_elements,
                                      coord, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: space_id  ! Dataspace identifier
        INTEGER, INTENT(IN) :: operator         ! Flag, valid values are:
                                                !    H5S_SELECT_SET_F
                                                !    H5S_SELECT_APPEND_F
                                                !    H5S_SELECT_PREPEND_F
        INTEGER, INTENT(IN) :: rank             ! Number of dataspace
                                                ! dimensions
        INTEGER(SIZE_T), INTENT(IN) :: num_elements
                                                ! Number of elements to be
                                                ! selected
        INTEGER(HSIZE_T), DIMENSION(rank,num_elements), INTENT(IN) :: coord
                                                ! A 1-based array containing the
                                                ! coordinates of the selected
                                                ! elements
                                                ! NOTE: Reversed dimension declaration
                                                ! compared to the C specification
                                                ! of coord(num_elements, rank)
        INTEGER, INTENT(OUT) :: hdferr          ! Error code
                                                ! 0 on success and -1 on failure
      END SUBROUTINE h5sselect_elements_f

History:

  Release | Change
  1.6.4 | C `coord` parameter type changed to const hsize_t. Fortran `coord` parameter type changed to `INTEGER(HSIZE_T)`.