Merge pull request #2891 in HDFFV/hdf5 from ~JHENDERSON/hdf52:develop to develop

* commit '9b3a3445dbb72a95b2b9355e0196efdaa5b0f452':
  Add release note for new H5Ssel_iter_reset function
  Add H5Ssel_iter_init API call to reset a selection iterator

4 files changed, 231 insertions, 0 deletions

diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt
index dbf55a9..9577fbd 100644
--- a/release_docs/RELEASE.txt
+++ b/release_docs/RELEASE.txt
@@ -382,6 +382,16 @@ New Features
 
     Library:
     --------
+    - Add new public function H5Ssel_iter_reset
+
+      This function resets a dataspace selection iterator back to an
+      initial state so that it may be used for iteration once more.
+      This can be useful when needing to iterate over a selection
+      multiple times without having to repeatedly create/destroy
+      a selection iterator for that dataspace selection.
+
+      (JTH - 2020/09/18)
+
     - Remove HDFS VFD stubs
 
       The original implementation of the HDFS VFD included non-functional
diff --git a/src/H5Spublic.h b/src/H5Spublic.h
index 1ca79ea..6e5c652 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -178,6 +178,7 @@ H5_DLL hid_t H5Sselect_project_intersection(hid_t src_space_id,
 H5_DLL hid_t H5Ssel_iter_create(hid_t spaceid, size_t elmt_size, unsigned flags);
 H5_DLL herr_t H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq,
     size_t maxbytes, size_t *nseq, size_t *nbytes, hsize_t *off, size_t *len);
+H5_DLL herr_t H5Ssel_iter_reset(hid_t sel_iter_id, hid_t space_id);
 H5_DLL herr_t H5Ssel_iter_close(hid_t sel_iter_id);
 
 /* Symbols defined for compatibility with previous versions of the HDF5 API.
diff --git a/src/H5Sselect.c b/src/H5Sselect.c
index eb5cf1c..d021f0c 100644
--- a/src/H5Sselect.c
+++ b/src/H5Sselect.c
@@ -3116,6 +3116,52 @@ done:
 } /* end H5Ssel_iter_get_seq_list() */
 
 
+/*--------------------------------------------------------------------------
+ NAME
+    H5Ssel_iter_reset
+ PURPOSE
+    Resets a dataspace selection iterator back to an initial state.
+ USAGE
+    herr_t H5Ssel_iter_reset(sel_iter_id)
+        hid_t   sel_iter_id;  IN: ID of the dataspace selection iterator to
+                                  reset
+        hid_t   space_id;     IN: ID of the dataspace with selection to
+                                  iterate over
+ RETURNS
+    Non-negative on success / Negative on failure
+ DESCRIPTION
+    Resets a dataspace selection iterator back to an initial state so that
+    the iterator may be used for iteration once again.
+ GLOBAL VARIABLES
+ COMMENTS, BUGS, ASSUMPTIONS
+ EXAMPLES
+ REVISION LOG
+--------------------------------------------------------------------------*/
+herr_t
+H5Ssel_iter_reset(hid_t sel_iter_id, hid_t space_id)
+{
+    H5S_sel_iter_t *sel_iter;
+    H5S_t  *space;
+    herr_t ret_value = SUCCEED;
+
+    FUNC_ENTER_API(FAIL)
+    H5TRACE2("e", "ii", sel_iter_id, space_id);
+
+    /* Check args */
+    if(NULL == (sel_iter = (H5S_sel_iter_t *)H5I_object_verify(sel_iter_id, H5I_SPACE_SEL_ITER)))
+        HGOTO_ERROR(H5E_DATASPACE, H5E_BADTYPE, FAIL, "not a dataspace selection iterator")
+    if(NULL == (space = (H5S_t *)H5I_object_verify(space_id, H5I_DATASPACE)))
+        HGOTO_ERROR(H5E_DATASPACE, H5E_BADTYPE, FAIL, "not a dataspace")
+
+    /* Simply re-initialize iterator */
+    if(H5S_select_iter_init(sel_iter, space, sel_iter->elmt_size, sel_iter->flags) < 0)
+        HGOTO_ERROR(H5E_DATASPACE, H5E_CANTINIT, FAIL, "unable to re-initialize selection iterator")
+
+done:
+    FUNC_LEAVE_API(ret_value)
+} /* end H5Ssel_iter_reset() */
+
+
 /*-------------------------------------------------------------------------
  * Function:	H5S_sel_iter_close
  *
diff --git a/test/tselect.c b/test/tselect.c
index c98db5d..cdf0ba5 100644
--- a/test/tselect.c
+++ b/test/tselect.c
@@ -14990,6 +14990,16 @@ test_sel_iter(void)
         iter_id = H5Ssel_iter_create(sid, (size_t)1, (unsigned)sel_iter_flags);
         CHECK(iter_id, FAIL, "H5Ssel_iter_create");
 
+        /* Try resetting selection iterator with bad parameters */
+        H5E_BEGIN_TRY {
+            ret = H5Ssel_iter_reset(H5I_INVALID_HID, sid);
+        } H5E_END_TRY;
+        VERIFY(ret, FAIL, "H5Ssel_iter_reset");
+        H5E_BEGIN_TRY {
+            ret = H5Ssel_iter_reset(iter_id, H5I_INVALID_HID);
+        } H5E_END_TRY;
+        VERIFY(ret, FAIL, "H5Ssel_iter_reset");
+
         /* Try retrieving sequences, with bad parameters */
         H5E_BEGIN_TRY {     /* Invalid ID */
             ret = H5Ssel_iter_get_seq_list(H5I_INVALID_HID, (size_t)1, (size_t)1, &nseq, &nbytes, off, len);
@@ -15115,6 +15125,150 @@ test_sel_iter(void)
             CHECK(ret, FAIL, "H5Ssel_iter_close");
         } /* end for */
 
+        /* Create selection iterator object */
+        iter_id = H5Ssel_iter_create(sid, (size_t)1, (unsigned)sel_iter_flags);
+        CHECK(iter_id, FAIL, "H5Ssel_iter_create");
+
+        /* Test iterators on various basic selection types using
+         * H5Ssel_iter_reset instead of creating multiple iterators */
+        for(sel_type = H5S_SEL_NONE; sel_type <= H5S_SEL_ALL; sel_type = (H5S_sel_type)(sel_type + 1)) {
+            switch(sel_type) {
+                case H5S_SEL_NONE:          /* "None" selection */
+                    ret = H5Sselect_none(sid);
+                    CHECK(ret, FAIL, "H5Sselect_none");
+                    break;
+
+                case H5S_SEL_POINTS:        /* Point selection */
+                    /* Select sequence of ten points */
+                    coord1[0][0] = 0;       coord1[0][1] = 9;
+                    coord1[1][0] = 1;       coord1[1][1] = 2;
+                    coord1[2][0] = 2;       coord1[2][1] = 4;
+                    coord1[3][0] = 0;       coord1[3][1] = 6;
+                    coord1[4][0] = 1;       coord1[4][1] = 8;
+                    coord1[5][0] = 2;       coord1[5][1] = 10;
+                    coord1[6][0] = 0;       coord1[6][1] = 11;
+                    coord1[7][0] = 1;       coord1[7][1] = 4;
+                    coord1[8][0] = 2;       coord1[8][1] = 1;
+                    coord1[9][0] = 0;       coord1[9][1] = 3;
+                    ret = H5Sselect_elements(sid, H5S_SELECT_SET, (size_t)POINT1_NPOINTS, (const hsize_t *)coord1);
+                    CHECK(ret, FAIL, "H5Sselect_elements");
+                    break;
+
+                case H5S_SEL_HYPERSLABS:    /* Hyperslab selection */
+                    /* Select regular hyperslab */
+                    start[0] = 3;   start[1] = 0;
+                    stride[0] = 2;  stride[1] = 2;
+                    count[0] = 2;   count[1] = 5;
+                    block[0] = 1;   block[1] = 1;
+                    ret = H5Sselect_hyperslab(sid, H5S_SELECT_SET, start, stride, count, block);
+                    CHECK(ret, FAIL, "H5Sselect_hyperslab");
+                    break;
+
+                case H5S_SEL_ALL:           /* "All" selection */
+                    ret = H5Sselect_all(sid);
+                    CHECK(ret, FAIL, "H5Sselect_all");
+                    break;
+
+                case H5S_SEL_ERROR:
+                case H5S_SEL_N:
+                default:
+                    HDassert(0 && "Can't occur");
+                    break;
+            } /* end switch */
+
+            /* Try retrieving no sequences, with 0 for maxseq & maxbytes */
+            ret = H5Ssel_iter_get_seq_list(iter_id, (size_t)0, (size_t)1, &nseq, &nbytes, off, len);
+            CHECK(ret, FAIL, "H5Ssel_iter_get_seq_list");
+            VERIFY(nseq, 0, "H5Ssel_iter_get_seq_list");
+            VERIFY(nbytes, 0, "H5Ssel_iter_get_seq_list");
+            ret = H5Ssel_iter_get_seq_list(iter_id, (size_t)1, (size_t)0, &nseq, &nbytes, off, len);
+            CHECK(ret, FAIL, "H5Ssel_iter_get_seq_list");
+            VERIFY(nseq, 0, "H5Ssel_iter_get_seq_list");
+            VERIFY(nbytes, 0, "H5Ssel_iter_get_seq_list");
+
+            /* Reset iterator */
+            ret = H5Ssel_iter_reset(iter_id, sid);
+            CHECK(ret, FAIL, "H5Ssel_iter_reset");
+
+            /* Try retrieving all sequences */
+            ret = H5Ssel_iter_get_seq_list(iter_id, (size_t)SEL_ITER_MAX_SEQ, (size_t)(1024 * 1024), &nseq, &nbytes, off, len);
+            CHECK(ret, FAIL, "H5Ssel_iter_get_seq_list");
+
+            /* Check results from retrieving sequence list */
+            switch(sel_type) {
+                case H5S_SEL_NONE:          /* "None" selection */
+                    VERIFY(nseq, 0, "H5Ssel_iter_get_seq_list");
+                    VERIFY(nbytes, 0, "H5Ssel_iter_get_seq_list");
+                    break;
+
+                case H5S_SEL_POINTS:        /* Point selection */
+                    VERIFY(nseq, 10, "H5Ssel_iter_get_seq_list");
+                    VERIFY(nbytes, 10, "H5Ssel_iter_get_seq_list");
+                    break;
+
+                case H5S_SEL_HYPERSLABS:    /* Hyperslab selection */
+                    VERIFY(nseq, 10, "H5Ssel_iter_get_seq_list");
+                    VERIFY(nbytes, 10, "H5Ssel_iter_get_seq_list");
+                    break;
+
+                case H5S_SEL_ALL:           /* "All" selection */
+                    VERIFY(nseq, 1, "H5Ssel_iter_get_seq_list");
+                    VERIFY(nbytes, 72, "H5Ssel_iter_get_seq_list");
+                    break;
+
+                case H5S_SEL_ERROR:
+                case H5S_SEL_N:
+                default:
+                    HDassert(0 && "Can't occur");
+                    break;
+            } /* end switch */
+
+            /* Reset iterator */
+            ret = H5Ssel_iter_reset(iter_id, sid);
+            CHECK(ret, FAIL, "H5Ssel_iter_reset");
+
+            /* Try retrieving all sequences again */
+            ret = H5Ssel_iter_get_seq_list(iter_id, (size_t)SEL_ITER_MAX_SEQ, (size_t)(1024 * 1024), &nseq, &nbytes, off, len);
+            CHECK(ret, FAIL, "H5Ssel_iter_get_seq_list");
+
+            /* Check results from retrieving sequence list */
+            switch(sel_type) {
+                case H5S_SEL_NONE:          /* "None" selection */
+                    VERIFY(nseq, 0, "H5Ssel_iter_get_seq_list");
+                    VERIFY(nbytes, 0, "H5Ssel_iter_get_seq_list");
+                    break;
+
+                case H5S_SEL_POINTS:        /* Point selection */
+                    VERIFY(nseq, 10, "H5Ssel_iter_get_seq_list");
+                    VERIFY(nbytes, 10, "H5Ssel_iter_get_seq_list");
+                    break;
+
+                case H5S_SEL_HYPERSLABS:    /* Hyperslab selection */
+                    VERIFY(nseq, 10, "H5Ssel_iter_get_seq_list");
+                    VERIFY(nbytes, 10, "H5Ssel_iter_get_seq_list");
+                    break;
+
+                case H5S_SEL_ALL:           /* "All" selection */
+                    VERIFY(nseq, 1, "H5Ssel_iter_get_seq_list");
+                    VERIFY(nbytes, 72, "H5Ssel_iter_get_seq_list");
+                    break;
+
+                case H5S_SEL_ERROR:
+                case H5S_SEL_N:
+                default:
+                    HDassert(0 && "Can't occur");
+                    break;
+            } /* end switch */
+
+            /* Reset iterator */
+            ret = H5Ssel_iter_reset(iter_id, sid);
+            CHECK(ret, FAIL, "H5Ssel_iter_reset");
+        } /* end for */
+
+        /* Close selection iterator */
+        ret = H5Ssel_iter_close(iter_id);
+        CHECK(ret, FAIL, "H5Ssel_iter_close");
+
         /* Point selection which will merge into smaller # of sequences */
         coord1[0][0] = 0;       coord1[0][1] = 9;
         coord1[1][0] = 0;       coord1[1][1] = 10;
@@ -15139,6 +15293,16 @@ test_sel_iter(void)
         VERIFY(nseq, 6, "H5Ssel_iter_get_seq_list");
         VERIFY(nbytes, 10, "H5Ssel_iter_get_seq_list");
 
+        /* Reset iterator */
+        ret = H5Ssel_iter_reset(iter_id, sid);
+        CHECK(ret, FAIL, "H5Ssel_iter_reset");
+
+        /* Try retrieving all sequences again */
+        ret = H5Ssel_iter_get_seq_list(iter_id, (size_t)SEL_ITER_MAX_SEQ, (size_t)(1024 * 1024), &nseq, &nbytes, off, len);
+        CHECK(ret, FAIL, "H5Ssel_iter_get_seq_list");
+        VERIFY(nseq, 6, "H5Ssel_iter_get_seq_list");
+        VERIFY(nbytes, 10, "H5Ssel_iter_get_seq_list");
+
         /* Close selection iterator */
         ret = H5Ssel_iter_close(iter_id);
         CHECK(ret, FAIL, "H5Ssel_iter_close");
@@ -15169,6 +15333,16 @@ test_sel_iter(void)
         VERIFY(nseq, 6, "H5Ssel_iter_get_seq_list");
         VERIFY(nbytes, 20, "H5Ssel_iter_get_seq_list");
 
+        /* Reset iterator */
+        ret = H5Ssel_iter_reset(iter_id, sid);
+        CHECK(ret, FAIL, "H5Ssel_iter_reset");
+
+        /* Try retrieving all sequences again */
+        ret = H5Ssel_iter_get_seq_list(iter_id, (size_t)SEL_ITER_MAX_SEQ, (size_t)(1024 * 1024), &nseq, &nbytes, off, len);
+        CHECK(ret, FAIL, "H5Ssel_iter_get_seq_list");
+        VERIFY(nseq, 6, "H5Ssel_iter_get_seq_list");
+        VERIFY(nbytes, 20, "H5Ssel_iter_get_seq_list");
+
         /* Close selection iterator */
         ret = H5Ssel_iter_close(iter_id);
         CHECK(ret, FAIL, "H5Ssel_iter_close");