Add isValidVertex

CHANGELOG.md

@@ -12,6 +12,7 @@ The public API of this library consists of the functions declared in file
     - `cellToVertex(cell, vertexNum)`
     - `cellToVertexes(cell, out)`
     - `vertexToPoint(vertex, out)` 
+    - `isValidVertex(vertex)` 
 - closed-form implementation of `numHexagons`
 
 ### Breaking changes

src/apps/testapps/testVertex.c

@@ -85,4 +85,57 @@ SUITE(Vertex) {
         t_assert(directionForVertexNum(pentagon, 5) == INVALID_DIGIT,
                  "invalid pent vertex should return invalid direction");
     }
+
+    TEST(isValidVertex_hex) {
+        H3Index origin = 0x823d6ffffffffff;
+        H3Index vert = 0x2222597fffffffff;
+
+        t_assert(H3_EXPORT(isValidVertex)(vert), "known vertex is valid");
+
+        for (int i = 0; i < NUM_HEX_VERTS; i++) {
+            vert = H3_EXPORT(cellToVertex)(origin, i);
+            t_assert(H3_EXPORT(isValidVertex)(vert), "vertex is valid");
+        }
+    }
+
+    TEST(isValidVertex_badOwner) {
+        H3Index origin = 0x823d6ffffffffff;
+        int vertexNum = 0;
+        H3Index vert = H3_EXPORT(cellToVertex)(origin, vertexNum);
+
+        // Assert that origin does not own the vertex
+        H3Index owner = vert;
+        H3_SET_MODE(owner, H3_HEXAGON_MODE);
+        H3_SET_RESERVED_BITS(owner, 0);
+
+        t_assert(origin != owner, "origin does not own the canonical vertex");
+
+        H3Index nonCanonicalVertex = origin;
+        H3_SET_MODE(nonCanonicalVertex, H3_VERTEX_MODE);
+        H3_SET_RESERVED_BITS(nonCanonicalVertex, vertexNum);
+
+        t_assert(H3_EXPORT(isValidVertex)(nonCanonicalVertex) == 0,
+                 "vertex with incorrect owner is not valid");
+    }
+
+    TEST(isValidVertex_badVerts) {
+        H3Index origin = 0x823d6ffffffffff;
+        t_assert(H3_EXPORT(isValidVertex)(origin) == 0, "cell is not valid");
+
+        H3Index fakeEdge = origin;
+        H3_SET_MODE(fakeEdge, H3_UNIEDGE_MODE);
+        t_assert(H3_EXPORT(isValidVertex)(fakeEdge) == 0,
+                 "edge mode is not valid");
+
+        H3Index vert = H3_EXPORT(cellToVertex)(origin, 0);
+        H3_SET_RESERVED_BITS(vert, 6);
+        t_assert(H3_EXPORT(isValidVertex)(vert) == 0,
+                 "invalid vertexNum is not valid");
+
+        H3Index pentagon = 0x823007fffffffff;
+        H3Index vert2 = H3_EXPORT(cellToVertex)(pentagon, 0);
+        H3_SET_RESERVED_BITS(vert2, 5);
+        t_assert(H3_EXPORT(isValidVertex)(vert2) == 0,
+                 "invalid pentagon vertexNum is not valid");
+    }
 }

src/apps/testapps/testVertexExhaustive.c

@@ -63,6 +63,17 @@ static void cellToVertex_uniqueness_assertions(H3Index h3) {
     }
 }
 
+static void cellToVertex_validity_assertions(H3Index h3) {
+    H3Index verts[NUM_HEX_VERTS] = {0};
+    H3_EXPORT(cellToVertexes)(h3, verts);
+
+    for (int i = 0; i < NUM_HEX_VERTS - 1; i++) {
+        if (verts[i] != H3_NULL) {
+            t_assert(H3_EXPORT(isValidVertex(verts[i])), "vertex is valid");
+        }
+    }
+}
+
 static void cellToVertex_neighbor_assertions(H3Index h3) {
     H3Index neighbors[7] = {0};
     H3Index originVerts[NUM_HEX_VERTS] = {0};
@@ -130,4 +141,12 @@ SUITE(Vertex) {
         iterateAllIndexesAtRes(3, cellToVertex_uniqueness_assertions);
         iterateAllIndexesAtRes(4, cellToVertex_uniqueness_assertions);
     }
+
+    TEST(cellToVertex_validity) {
+        iterateAllIndexesAtRes(0, cellToVertex_validity_assertions);
+        iterateAllIndexesAtRes(1, cellToVertex_validity_assertions);
+        iterateAllIndexesAtRes(2, cellToVertex_validity_assertions);
+        iterateAllIndexesAtRes(3, cellToVertex_validity_assertions);
+        iterateAllIndexesAtRes(4, cellToVertex_validity_assertions);
+    }
 }

src/h3lib/include/h3api.h.in

@@ -634,6 +634,14 @@ DECLSPEC void H3_EXPORT(cellToVertexes)(H3Index origin, H3Index *vertexes);
 DECLSPEC void H3_EXPORT(vertexToPoint)(H3Index vertex, GeoCoord *coord);
 /** @} */
 
+/** @defgroup isValidVertex isValidVertex
+ * Functions for isValidVertex
+ * @{
+ */
+/** @brief Whether the input is a valid H3 vertex */
+DECLSPEC int H3_EXPORT(isValidVertex)(H3Index vertex);
+/** @} */
+
 /** @defgroup h3Distance h3Distance
  * Functions for h3Distance
  * @{

src/h3lib/lib/vertex.c

@@ -192,7 +192,7 @@ H3Index H3_EXPORT(cellToVertex)(H3Index cell, int vertexNum) {
     // Note that vertex - 1 is the right side, as vertex numbers are CCW
     Direction right = directionForVertexNum(
         cell, (vertexNum - 1 + cellNumVerts) % cellNumVerts);
-    // This case should be unreachable; invalid verts  fail the left side first
+    // This case should be unreachable; invalid verts fail the left side first
     if (right == INVALID_DIGIT) return H3_NULL;  // LCOV_EXCL_LINE
     int lRotations = 0;
     H3Index rightNeighbor = h3NeighborRotations(cell, right, &lRotations);
@@ -269,3 +269,29 @@ void H3_EXPORT(vertexToPoint)(H3Index vertex, GeoCoord* coord) {
     // Copy from boundary to output coord
     *coord = gb.verts[0];
 }
+
+/**
+ * Whether the input is a valid H3 vertex
+ * @param  vertex H3 index possibly describing a vertex
+ * @return        Whether the input is valid
+ */
+int H3_EXPORT(isValidVertex)(H3Index vertex) {
+    if (H3_GET_MODE(vertex) != H3_VERTEX_MODE) {
+        return 0;
+    }
+
+    int vertexNum = H3_GET_RESERVED_BITS(vertex);
+    H3Index owner = vertex;
+    H3_SET_MODE(owner, H3_HEXAGON_MODE);
+    H3_SET_RESERVED_BITS(owner, 0);
+
+    if (!H3_EXPORT(h3IsValid)(owner)) {
+        return 0;
+    }
+
+    // The easiest way to ensure that the owner + vertex number is valid,
+    // and that the vertex is canonical, is to recreate and compare.
+    H3Index canonical = H3_EXPORT(cellToVertex)(owner, vertexNum);
+
+    return vertex == canonical ? 1 : 0;
+}