Add isValidIndex function (#1056)

* Add isValidIndex function

Implement a general validation function that checks if an H3 index
is valid for any mode (cell, directed edge, or vertex).

Changes:
- Add isValidIndex() function declaration to h3api.h.in
- Implement isValidIndex() in h3Index.c
- Add includes for directedEdge.h and vertex.h in h3Index.c
- Add comprehensive test coverage in testH3Index.c

The function returns true if the index is valid as a cell, directed edge,
or vertex, providing a single validation function for any H3 index type.

Fixes #1043

* Fix neighbor retrieval in isValidIndex test

Replace incorrect neighbor++ with proper gridRingUnsafe call to get
an actual neighboring cell for directed edge testing. Simply incrementing
an H3Index will almost never produce a valid neighboring cell.

This addresses the review feedback from ajfriend on lines 224-227.

* Fix clang-format formatting in isValidIndex function

Apply clang-format style to match project formatting conventions:
- Put first two conditions on same line
- Wrap long comment to 80 characters

* Fix clang-format formatting in h3api.h.in header

Apply clang-format style to isValidIndex documentation comment:
- Wrap comment across 3 lines for proper formatting

Author: cnaples79

src/apps/testapps/testH3Index.c

@@ -212,4 +212,39 @@ SUITE(h3Index) {
                      "matches existing definition");
         }
     }
+
+    TEST(isValidIndex) {
+        // Test with valid cell
+        LatLng coord = {0, 0};
+        H3Index cell;
+        t_assertSuccess(H3_EXPORT(latLngToCell)(&coord, 5, &cell));
+        t_assert(H3_EXPORT(isValidIndex)(cell),
+                 "isValidIndex returns true for valid cell");
+
+        // Test with valid directed edge
+        H3Index ring[7] = {0};
+        t_assertSuccess(H3_EXPORT(gridRingUnsafe)(cell, 1, ring));
+        H3Index neighbor = ring[0];
+        H3Index edge;
+        t_assertSuccess(H3_EXPORT(cellsToDirectedEdge)(cell, neighbor, &edge));
+        t_assert(H3_EXPORT(isValidIndex)(edge),
+                 "isValidIndex returns true for valid directed edge");
+
+        // Test with valid vertex
+        H3Index vertex;
+        t_assertSuccess(H3_EXPORT(cellToVertex)(cell, 0, &vertex));
+        t_assert(H3_EXPORT(isValidIndex)(vertex),
+                 "isValidIndex returns true for valid vertex");
+
+        // Test with invalid index
+        H3Index invalid = 0;
+        t_assert(!H3_EXPORT(isValidIndex)(invalid),
+                 "isValidIndex returns false for invalid index");
+
+        // Test with corrupted index
+        H3Index corrupted = cell;
+        H3_SET_HIGH_BIT(corrupted, 1);
+        t_assert(!H3_EXPORT(isValidIndex)(corrupted),
+                 "isValidIndex returns false for corrupted index");
+    }
 }

src/h3lib/include/h3api.h.in

@@ -552,6 +552,17 @@ DECLSPEC H3Error H3_EXPORT(h3ToString)(H3Index h, char *str, size_t sz);
 DECLSPEC int H3_EXPORT(isValidCell)(H3Index h);
 /** @} */
 
+/** @defgroup isValidIndex isValidIndex
+ * Functions for isValidIndex
+ * @{
+ */
+/** @brief confirms if an H3Index is valid for any mode (cell, directed edge, or
+ * vertex) Returns 1 if the H3 index is valid for any supported type, 0
+ * otherwise
+ */
+DECLSPEC int H3_EXPORT(isValidIndex)(H3Index h);
+/** @} */
+
 /** @defgroup cellToParent cellToParent
  * Functions for cellToParent
  * @{

src/h3lib/lib/h3Index.c

@@ -26,10 +26,12 @@
 
 #include "alloc.h"
 #include "baseCells.h"
+#include "directedEdge.h"
 #include "faceijk.h"
 #include "h3Assert.h"
 #include "iterators.h"
 #include "mathExtensions.h"
+#include "vertex.h"
 
 /** @var H3ErrorDescriptions
  *  @brief An array of strings describing each of the H3ErrorCodes enum values
@@ -325,6 +327,17 @@ int H3_EXPORT(isValidCell)(H3Index h) {
     return true;
 }
 
+/**
+ * Returns whether or not an H3 index is valid for any mode (cell, directed
+ * edge, or vertex).
+ * @param h The H3 index to validate.
+ * @return 1 if the H3 index is valid for any supported type, 0 otherwise.
+ */
+int H3_EXPORT(isValidIndex)(H3Index h) {
+    return H3_EXPORT(isValidCell)(h) || H3_EXPORT(isValidDirectedEdge)(h) ||
+           H3_EXPORT(isValidVertex)(h);
+}
+
 /**
  * Initializes an H3 index.
  * @param hp The H3 index to initialize.