change H3_INVALID_INDEX to H3_NULL (#379)

* change H3_INVALID_INDEX to H3_NULL

* document H3_NULL in the naming RFC

* some formatting happened

* tell the people about `git clean -ffdx`

* H3_INVALID_INDEX -> H3_NULL from Nick's change

* formatting happened

* build and clean instructions

* where to run `make`

* brew to `brew`, and no need to be stingy

* Docs on Mode 0 vs H3_NULL

* to the future!

* add the `build` back into the .gitignore

* I get H3_INIT now

* going backwards on going forward

Author: ajfriend

README.md

@@ -19,7 +19,7 @@ Documentation is available at [https://uber.github.io/h3/](https://uber.github.i
 
 We recommend using prebuilt bindings if they are available for your programming language. Bindings for [Go](https://github.com/uber/h3-go), [Java](https://github.com/uber/h3-java), [JavaScript](https://github.com/uber/h3-js), [Python](https://github.com/uber/h3-py), and [others](https://uber.github.io/h3/#/documentation/community/bindings) are available.
 
-On macOS, you can install H3 using brew:
+On macOS, you can install H3 using `brew`:
 ```
 brew install h3
 ```
@@ -46,7 +46,7 @@ sudo apt install cmake make gcc libtool
 sudo apt install clang-format cmake-curses-gui lcov doxygen
 ```
 
-* macOS (using brew)
+* macOS (using `brew`)
 
 First make sure you [have the developer tools installed](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/) and then
 
@@ -63,19 +63,31 @@ You will need to install CMake and Visual Studio, including the Visual C++ compi
 
 #### Compilation
 
-From the repository you would then compile like so:
+From the repository root, you can compile H3 with:
 
 ```
-cmake .
+mkdir build
+cd build
+cmake ..
 make
 ```
 
+All subsequent `make` commands should be run from within the `build` directory.
+
+**Note**: There are several ways to build H3 with CMake; the method above is just one example that restricts all build artifacts to the `build` directory.
+
 You can install system-wide with:
 
 ```
 sudo make install
 ```
 
+If using the method above, from the repository root, you can clean all build artifacts with:
+
+```
+rm -rf build
+```
+
 #### Testing
 
 After making the project, you can test with `make test`, and if `lcov` is installed you can `make coverage` to generate a code coverage report.

dev-docs/RFCs/v4.0.0/names_for_concepts_types_functions.md

@@ -66,6 +66,10 @@ The following technical terms should be used in the documentation, the H3 codeba
     - may include more than 6 points in the case that a cell is not a geometric hexagon, such as when a hexagon crosses an icosahedron boundary
     - may also be used to describe the boundary between two geometric cells, as in the case of an edge
     - represented in the H3 codebase with the `CellBoundary` struct (previously `GeoBoundary` before v4.0)
+- `H3_NULL`;
+    - equivalent to `0` and guaranteed to never be a valid `H3Index` (even after any future H3 **modes** are added)
+    - returned by functions to denote an error, or to denote missing data in arrays of `H3Index`
+    - analogous to `NaN` in floating point
 
 
 ### Use of "hex", "hexagon", "cell", "pentagon", etc.

docs/core-library/h3indexing.md

@@ -13,7 +13,18 @@ Child hexagons are linearly smaller than their parent hexagons.
 
 ## H3Index Representation
 
-The **H3Index** is the integer representation of an **H3** index, which can be placed into multiple modes to indicate the kind of concept being indexed. Mode 1 is an **H3** Cell (Hexagon) Index, mode 2 is an **H3** Unidirectional Edge (Hexagon A -> Hexagon B) Index, mode 3 is planned to be a bidirectional edge (Hexagon A <-> Hexagon B). Mode 0 is reserved and indicates an invalid **H3** index.
+The **H3Index** is the integer representation of an **H3** index, which can be placed into multiple modes to indicate the concept being indexed.
+
+* Mode 1 is an **H3** Cell (Hexagon/Pentagon) index.
+* Mode 2 is an **H3** Unidirectional Edge (Cell A -> Cell B) index.
+* Mode 3 is planned to be a bidirectional edge (Cell A <-> Cell B).
+* Mode 0 is reserved and indicates an invalid **H3** index.
+  * This mode remains, partially, for backwards compatibility with an older version of H3.
+
+Mode 0 contains a special index, `H3_NULL`, which is unique: it is bit-equivalent to `0`.
+This index indicates, *specifically*, an invalid, missing, or uninitialized **H3** index;
+it is analogous to `NaN` in floating point.
+It should be used instead of an arbitrary Mode 0 index, due to its uniqueness and easy identifiability.
 
 The components of the **H3** cell index (mode 1) are packed into a 64-bit integer in order, highest bit first, as follows:
 

src/apps/applib/lib/utility.c

@@ -242,7 +242,7 @@ void randomGeo(GeoCoord* g) {
 int countActualHexagons(H3Index* hexagons, int numHexagons) {
     int actualNumHexagons = 0;
     for (int i = 0; i < numHexagons; i++) {
-        if (hexagons[i] != H3_INVALID_INDEX) {
+        if (hexagons[i] != H3_NULL) {
             actualNumHexagons++;
         }
     }

src/apps/testapps/testH3ToLocalIj.c

@@ -90,16 +90,19 @@ SUITE(h3ToLocalIj) {
         const int numCoords = 7;
         const CoordIJ coords[] = {{0, 0}, {1, 0},  {2, 0}, {3, 0},
                                   {4, 0}, {-4, 0}, {0, 4}};
-        const H3Index expected[] = {0x81283ffffffffff, 0x81293ffffffffff,
-                                    0x8150bffffffffff, 0x8151bffffffffff,
-                                    H3_INVALID_INDEX,  H3_INVALID_INDEX,
-                                    H3_INVALID_INDEX};
+        const H3Index expected[] = {0x81283ffffffffff,
+                                    0x81293ffffffffff,
+                                    0x8150bffffffffff,
+                                    0x8151bffffffffff,
+                                    H3_NULL,
+                                    H3_NULL,
+                                    H3_NULL};
 
         for (int i = 0; i < numCoords; i++) {
             H3Index result;
             const int err = H3_EXPORT(experimentalLocalIjToH3)(
                 expected[0], &coords[i], &result);
-            if (expected[i] == H3_INVALID_INDEX) {
+            if (expected[i] == H3_NULL) {
                 t_assert(err != 0, "coordinates out of range");
             } else {
                 t_assert(err == 0, "coordinates in range");

src/apps/testapps/testH3UniEdgeExhaustive.c

@@ -38,8 +38,7 @@ static void h3UniEdge_correctness_assertions(H3Index h3) {
 
     for (int i = 0; i < 6; i++) {
         if (isPentagon && i == 0) {
-            t_assert(edges[i] == H3_INVALID_INDEX,
-                     "last pentagon edge is empty");
+            t_assert(edges[i] == H3_NULL, "last pentagon edge is empty");
             continue;
         }
         t_assert(H3_EXPORT(h3UnidirectionalEdgeIsValid)(edges[i]) == 1,
@@ -64,7 +63,7 @@ static void h3UniEdge_boundary_assertions(H3Index h3) {
     GeoBoundary revEdgeBoundary;
 
     for (int i = 0; i < 6; i++) {
-        if (edges[i] == H3_INVALID_INDEX) continue;
+        if (edges[i] == H3_NULL) continue;
         H3_EXPORT(getH3UnidirectionalEdgeBoundary)(edges[i], &edgeBoundary);
         destination =
             H3_EXPORT(getDestinationH3IndexFromUnidirectionalEdge)(edges[i]);

src/apps/testapps/testPolyfill.c

@@ -92,7 +92,7 @@ static void fillIndex_assertions(H3Index h) {
 
         for (int i = 0; i < childrenSize; i++) {
             bool found = false;
-            if (children[i] == H3_INVALID_INDEX) continue;
+            if (children[i] == H3_NULL) continue;
             for (int j = 0; j < polyfillSize; j++) {
                 if (polyfillOut[j] == children[i]) {
                     found = true;

src/h3lib/include/h3Index.h

@@ -82,7 +82,11 @@
 /** 0's in the 7 base cell bits, 1's everywhere else. */
 #define H3_DIGIT_MASK_NEGATIVE (~H3_DIGIT_MASK)
 
-/** H3 index with mode 0, res 0, base cell 0, and 7 for all index digits. */
+/**
+ * H3 index with mode 0, res 0, base cell 0, and 7 for all index digits.
+ * Typically used to initialize the creation of an H3 cell index, which
+ * expects all direction digits to be 7 beyond the cell's resolution.
+ */
 #define H3_INIT (UINT64_C(35184372088831))
 
 /**
@@ -161,9 +165,10 @@
              << ((MAX_H3_RES - (res)) * H3_PER_DIGIT_OFFSET)))
 
 /**
- * Invalid index used to indicate an error from geoToH3 and related functions.
+ * Invalid index used to indicate an error from geoToH3 and related functions
+ * or missing data in arrays of h3 indices. Analogous to NaN in floating point.
  */
-#define H3_INVALID_INDEX 0
+#define H3_NULL 0
 
 /*
  * Return codes for compact

src/h3lib/lib/algos.c

@@ -278,7 +278,7 @@ void _kRingInternal(H3Index origin, int k, H3Index* out, int* distances,
  * @param rotations Number of ccw rotations to perform to reorient the
  *                  translation vector. Will be modified to the new number of
  *                  rotations to perform (such as when crossing a face edge.)
- * @return H3Index of the specified neighbor or 0 if deleted k-subsequence
+ * @return H3Index of the specified neighbor or H3_NULL if deleted k-subsequence
  *         distortion is encountered.
  */
 H3Index h3NeighborRotations(H3Index origin, Direction dir, int* rotations) {
@@ -363,7 +363,7 @@ H3Index h3NeighborRotations(H3Index origin, Direction dir, int* rotations) {
                 // base cell.
                 if (oldLeadingDigit == CENTER_DIGIT) {
                     // Undefined: the k direction is deleted from here
-                    return H3_INVALID_INDEX;
+                    return H3_NULL;
                 } else if (oldLeadingDigit == JK_AXES_DIGIT) {
                     // Rotate out of the deleted k subsequence
                     // We also need an additional change to the direction we're
@@ -378,7 +378,7 @@ H3Index h3NeighborRotations(H3Index origin, Direction dir, int* rotations) {
                     *rotations = *rotations + 5;
                 } else {
                     // Should never occur
-                    return H3_INVALID_INDEX;  // LCOV_EXCL_LINE
+                    return H3_NULL;  // LCOV_EXCL_LINE
                 }
             }
         }
@@ -693,7 +693,7 @@ void H3_EXPORT(polyfill)(const GeoPolygon* geoPolygon, int res, H3Index* out) {
     // LCOV_EXCL_START
     if (failure) {
         int numHexagons = H3_EXPORT(maxPolyfillSize)(geoPolygon, res);
-        for (int i = 0; i < numHexagons; i++) out[i] = H3_INVALID_INDEX;
+        for (int i = 0; i < numHexagons; i++) out[i] = H3_NULL;
     }
     // LCOV_EXCL_STOP
 }
@@ -865,7 +865,7 @@ int _polyfillInternal(const GeoPolygon* geoPolygon, int res, H3Index* out) {
             H3Index searchHex = search[i];
             H3_EXPORT(kRing)(searchHex, 1, ring);
             for (int j = 0; j < MAX_ONE_RING_SIZE; j++) {
-                if (ring[j] == H3_INVALID_INDEX) {
+                if (ring[j] == H3_NULL) {
                     continue;  // Skip if this was a pentagon and only had 5
                                // neighbors
                 }

src/h3lib/lib/h3Index.c

@@ -51,11 +51,12 @@ int H3_EXPORT(h3GetBaseCell)(H3Index h) { return H3_GET_BASE_CELL(h); }
 /**
  * Converts a string representation of an H3 index into an H3 index.
  * @param str The string representation of an H3 index.
- * @return The H3 index corresponding to the string argument, or 0 if invalid.
+ * @return The H3 index corresponding to the string argument, or H3_NULL if
+ * invalid.
  */
 H3Index H3_EXPORT(stringToH3)(const char* str) {
-    H3Index h = H3_INVALID_INDEX;
-    // If failed, h will be unmodified and we should return 0 anyways.
+    H3Index h = H3_NULL;
+    // If failed, h will be unmodified and we should return H3_NULL anyways.
     sscanf(str, "%" PRIx64, &h);
     return h;
 }
@@ -138,16 +139,16 @@ void setH3Index(H3Index* hp, int res, int baseCell, Direction initDigit) {
  * @param h H3Index to find parent of
  * @param parentRes The resolution to switch to (parent, grandparent, etc)
  *
- * @return H3Index of the parent, or 0 if you actually asked for a child
+ * @return H3Index of the parent, or H3_NULL if you actually asked for a child
  */
 H3Index H3_EXPORT(h3ToParent)(H3Index h, int parentRes) {
     int childRes = H3_GET_RESOLUTION(h);
     if (parentRes > childRes) {
-        return H3_INVALID_INDEX;
+        return H3_NULL;
     } else if (parentRes == childRes) {
         return h;
     } else if (parentRes < 0 || parentRes > MAX_H3_RES) {
-        return H3_INVALID_INDEX;
+        return H3_NULL;
     }
     H3Index parentH = H3_SET_RESOLUTION(h, parentRes);
     for (int i = parentRes + 1; i <= childRes; i++) {
@@ -231,7 +232,7 @@ void H3_EXPORT(h3ToChildren)(H3Index h, int childRes, H3Index* children) {
         if (isAPentagon && i == K_AXES_DIGIT) {
             H3Index* nextChild = children + bufferChildStep;
             while (children < nextChild) {
-                *children = H3_INVALID_INDEX;
+                *children = H3_NULL;
                 children++;
             }
         } else {
@@ -248,12 +249,13 @@ void H3_EXPORT(h3ToChildren)(H3Index h, int childRes, H3Index* children) {
  * @param h H3Index to find center child of
  * @param childRes The resolution to switch to
  *
- * @return H3Index of the center child, or 0 if you actually asked for a parent
+ * @return H3Index of the center child, or H3_NULL if you actually asked for a
+ * parent
  */
 H3Index H3_EXPORT(h3ToCenterChild)(H3Index h, int childRes) {
     int parentRes = H3_GET_RESOLUTION(h);
     if (!_isValidChildRes(parentRes, childRes)) {
-        return H3_INVALID_INDEX;
+        return H3_NULL;
     } else if (childRes == parentRes) {
         return h;
     }
@@ -343,7 +345,7 @@ int H3_EXPORT(compact)(const H3Index* h3Set, H3Index* compactedSet,
                             return COMPACT_DUPLICATE;
                         }
                         H3_SET_RESERVED_BITS(parent, count);
-                        hashSetArray[loc] = H3_INVALID_INDEX;
+                        hashSetArray[loc] = H3_NULL;
                     } else {
                         loc = (loc + 1) % numRemainingHexes;
                     }
@@ -394,7 +396,7 @@ int H3_EXPORT(compact)(const H3Index* h3Set, H3Index* compactedSet,
         int uncompactableCount = 0;
         for (int i = 0; i < numRemainingHexes; i++) {
             H3Index currIndex = remainingHexes[i];
-            if (currIndex != H3_INVALID_INDEX) {
+            if (currIndex != H3_NULL) {
                 H3Index parent = H3_EXPORT(h3ToParent)(currIndex, parentRes);
                 // Modulus hash the parent into the temp array
                 // to determine if this index was included in
@@ -634,7 +636,7 @@ H3Index _h3Rotate60cw(H3Index h) {
  * Convert an FaceIJK address to the corresponding H3Index.
  * @param fijk The FaceIJK address.
  * @param res The cell resolution.
- * @return The encoded H3Index (or 0 on failure).
+ * @return The encoded H3Index (or H3_NULL on failure).
  */
 H3Index _faceIjkToH3(const FaceIJK* fijk, int res) {
     // initialize the index
@@ -647,7 +649,7 @@ H3Index _faceIjkToH3(const FaceIJK* fijk, int res) {
         if (fijk->coord.i > MAX_FACE_COORD || fijk->coord.j > MAX_FACE_COORD ||
             fijk->coord.k > MAX_FACE_COORD) {
             // out of range input
-            return H3_INVALID_INDEX;
+            return H3_NULL;
         }
 
         H3_SET_BASE_CELL(h, _faceIjkToBaseCell(fijk));
@@ -691,7 +693,7 @@ H3Index _faceIjkToH3(const FaceIJK* fijk, int res) {
     if (fijkBC.coord.i > MAX_FACE_COORD || fijkBC.coord.j > MAX_FACE_COORD ||
         fijkBC.coord.k > MAX_FACE_COORD) {
         // out of range input
-        return H3_INVALID_INDEX;
+        return H3_NULL;
     }
 
     // lookup the correct base cell
@@ -730,14 +732,14 @@ H3Index _faceIjkToH3(const FaceIJK* fijk, int res) {
  *
  * @param g The spherical coordinates to encode.
  * @param res The desired H3 resolution for the encoding.
- * @return The encoded H3Index (or 0 on failure).
+ * @return The encoded H3Index (or H3_NULL on failure).
  */
 H3Index H3_EXPORT(geoToH3)(const GeoCoord* g, int res) {
     if (res < 0 || res > MAX_H3_RES) {
-        return H3_INVALID_INDEX;
+        return H3_NULL;
     }
     if (!isfinite(g->lat) || !isfinite(g->lon)) {
-        return H3_INVALID_INDEX;
+        return H3_NULL;
     }
 
     FaceIJK fijk;