Merge pull request #198 from isaacbrodsky/bump-4.2.0

Upgrade to h3 v4.2.0

Author: nrabinowitz

H3_VERSION

@@ -1 +1 @@
-4.1.0
+4.2.0

README.md

@@ -99,6 +99,7 @@ const coordinates = h3.cellsToMultiPolygon(hexagons, true);
 
 * [h3](#module_h3)
     * [.UNITS](#module_h3.UNITS)
+    * [.POLYGON_TO_CELLS_FLAGS](#module_h3.POLYGON_TO_CELLS_FLAGS)
     * [.h3IndexToSplitLong(h3Index)](#module_h3.h3IndexToSplitLong) ⇒ <code>SplitLong</code>
     * [.splitLongToH3Index(lower, upper)](#module_h3.splitLongToH3Index) ⇒ <code>H3Index</code>
     * [.isValidCell(h3Index)](#module_h3.isValidCell) ⇒ <code>boolean</code>
@@ -120,6 +121,7 @@ const coordinates = h3.cellsToMultiPolygon(hexagons, true);
     * [.gridDiskDistances(h3Index, ringSize)](#module_h3.gridDiskDistances) ⇒ <code>Array.&lt;Array.&lt;H3Index&gt;&gt;</code>
     * [.gridRingUnsafe(h3Index, ringSize)](#module_h3.gridRingUnsafe) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.polygonToCells(coordinates, res, [isGeoJson])](#module_h3.polygonToCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
+    * [.polygonToCellsExperimental(coordinates, res, flags, [isGeoJson])](#module_h3.polygonToCellsExperimental) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.cellsToMultiPolygon(h3Indexes, [formatAsGeoJson])](#module_h3.cellsToMultiPolygon) ⇒ <code>Array.&lt;Array.&lt;Array.&lt;CoordPair&gt;&gt;&gt;</code>
     * [.compactCells(h3Set)](#module_h3.compactCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.uncompactCells(compactedSet, res)](#module_h3.uncompactCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
@@ -176,6 +178,23 @@ Length/Area units
 | rads2 | <code>string</code> | 
 
 
+* * *
+
+<a name="module_h3.POLYGON_TO_CELLS_FLAGS"></a>
+
+### h3.POLYGON\_TO\_CELLS\_FLAGS
+Mode flags for polygonToCells
+
+**Properties**
+
+| Name | Type |
+| --- | --- |
+| containmentCenter | <code>string</code> | 
+| containmentFull | <code>string</code> | 
+| containmentOverlapping | <code>string</code> | 
+| containmentOverlappingBbox | <code>string</code> | 
+
+
 * * *
 
 <a name="module_h3.h3IndexToSplitLong"></a>
@@ -555,6 +574,31 @@ expected to be holes.
 | [isGeoJson] | <code>boolean</code> | Whether to expect GeoJson-style [lng, lat]                                  pairs instead of [lat, lng] |
 
 
+* * *
+
+<a name="module_h3.polygonToCellsExperimental"></a>
+
+### h3.polygonToCellsExperimental(coordinates, res, flags, [isGeoJson]) ⇒ <code>Array.&lt;H3Index&gt;</code>
+Get all hexagons with centers contained in a given polygon. The polygon
+is specified with GeoJson semantics as an array of loops. Each loop is
+an array of [lat, lng] pairs (or [lng, lat] if isGeoJson is specified).
+The first loop is the perimeter of the polygon, and subsequent loops are
+expected to be holes.
+
+**Returns**: <code>Array.&lt;H3Index&gt;</code> - H3 indexes for all hexagons in polygon  
+**Throws**:
+
+- <code>H3Error</code> If input is invalid or output is too large for JS
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| coordinates | <code>Array.&lt;Array.&lt;number&gt;&gt;</code> \| <code>Array.&lt;Array.&lt;Array.&lt;number&gt;&gt;&gt;</code> | Array of loops, or a single loop |
+| res | <code>number</code> | Resolution of hexagons to return |
+| flags | <code>string</code> | Value from POLYGON_TO_CELLS_FLAGS |
+| [isGeoJson] | <code>boolean</code> | Whether to expect GeoJson-style [lng, lat]                                  pairs instead of [lat, lng] |
+
+
 * * *
 
 <a name="module_h3.cellsToMultiPolygon"></a>

lib/bindings.js

@@ -50,6 +50,12 @@ export default [
     ['gridRingUnsafe', H3_ERROR, [H3_LOWER, H3_UPPER, NUMBER, POINTER]],
     ['maxPolygonToCellsSize', H3_ERROR, [POINTER, RESOLUTION, NUMBER, POINTER]],
     ['polygonToCells', H3_ERROR, [POINTER, RESOLUTION, NUMBER, POINTER]],
+    ['maxPolygonToCellsSizeExperimental', H3_ERROR, [POINTER, RESOLUTION, NUMBER, POINTER]],
+    [
+        'polygonToCellsExperimental',
+        H3_ERROR,
+        [POINTER, RESOLUTION, NUMBER, NUMBER, NUMBER, POINTER]
+    ],
     ['cellsToLinkedMultiPolygon', H3_ERROR, [POINTER, NUMBER, POINTER]],
     ['destroyLinkedMultiPolygon', null, [POINTER]],
     ['compactCells', H3_ERROR, [POINTER, POINTER, NUMBER, NUMBER]],

lib/h3core.js

@@ -28,7 +28,8 @@ import {
     E_UNKNOWN_UNIT,
     E_ARRAY_LENGTH,
     E_NULL_INDEX,
-    E_CELL_INVALID
+    E_CELL_INVALID,
+    E_OPTION_INVALID
 } from './errors';
 
 /**
@@ -131,9 +132,48 @@ export const UNITS = {
     rads2: 'rads2'
 };
 
+// ----------------------------------------------------------------------------
+// Flags
+
+/**
+ * Mode flags for polygonToCells
+ * @static
+ * @property {string} containmentCenter
+ * @property {string} containmentFull
+ * @property {string} containmentOverlapping
+ * @property {string} containmentOverlappingBbox
+ */
+export const POLYGON_TO_CELLS_FLAGS = {
+    containmentCenter: 'containmentCenter',
+    containmentFull: 'containmentFull',
+    containmentOverlapping: 'containmentOverlapping',
+    containmentOverlappingBbox: 'containmentOverlappingBbox'
+};
+
 // ----------------------------------------------------------------------------
 // Utilities and helpers
 
+/**
+ * @private
+ * @param {string} flags Value from POLYGON_TO_CELLS_FLAGS
+ * @returns {number} Flag value
+ * @throws {H3Error} If invalid
+ */
+function polygonToCellsFlagsToNumber(flags) {
+    switch (flags) {
+        case POLYGON_TO_CELLS_FLAGS.containmentCenter:
+            return 0;
+        case POLYGON_TO_CELLS_FLAGS.containmentFull:
+            return 1;
+        case POLYGON_TO_CELLS_FLAGS.containmentOverlapping:
+            return 2;
+        case POLYGON_TO_CELLS_FLAGS.containmentOverlappingBbox:
+            return 3;
+        default:
+            throw JSBindingError(E_OPTION_INVALID, flags);
+    }
+}
+
 /**
  * Validate a resolution, throwing an error if invalid
  * @private
@@ -1029,6 +1069,63 @@ export function polygonToCells(coordinates, res, isGeoJson) {
     }
 }
 
+/**
+ * Get all hexagons with centers contained in a given polygon. The polygon
+ * is specified with GeoJson semantics as an array of loops. Each loop is
+ * an array of [lat, lng] pairs (or [lng, lat] if isGeoJson is specified).
+ * The first loop is the perimeter of the polygon, and subsequent loops are
+ * expected to be holes.
+ * @static
+ * @param  {number[][] | number[][][]} coordinates
+ *                                  Array of loops, or a single loop
+ * @param  {number} res             Resolution of hexagons to return
+ * @param  {string} flags           Value from POLYGON_TO_CELLS_FLAGS
+ * @param  {boolean} [isGeoJson]    Whether to expect GeoJson-style [lng, lat]
+ *                                  pairs instead of [lat, lng]
+ * @return {H3Index[]}              H3 indexes for all hexagons in polygon
+ * @throws {H3Error}                If input is invalid or output is too large for JS
+ */
+export function polygonToCellsExperimental(coordinates, res, flags, isGeoJson) {
+    validateRes(res);
+    isGeoJson = Boolean(isGeoJson);
+    const flagsInt = polygonToCellsFlagsToNumber(flags);
+    // Guard against empty input
+    if (coordinates.length === 0 || coordinates[0].length === 0) {
+        return [];
+    }
+    // Wrap to expected format if a single loop is provided
+    const polygon = typeof coordinates[0][0] === 'number' ? [coordinates] : coordinates;
+    const geoPolygon = coordinatesToGeoPolygon(
+        // @ts-expect-error - There's no way to convince TS that polygon is now number[][][]
+        polygon,
+        isGeoJson
+    );
+    const countPtr = C._malloc(SZ_INT64);
+    try {
+        throwIfError(H3.maxPolygonToCellsSizeExperimental(geoPolygon, res, flagsInt, countPtr));
+        const count = validateArrayLength(readInt64AsDoubleFromPointer(countPtr));
+        const hexagons = C._calloc(count, SZ_H3INDEX);
+        try {
+            throwIfError(
+                H3.polygonToCellsExperimental(
+                    geoPolygon,
+                    res,
+                    flagsInt,
+                    count,
+                    UNUSED_UPPER_32_BITS,
+                    hexagons
+                )
+            );
+            return readArrayOfH3Indexes(hexagons, count);
+        } finally {
+            C._free(hexagons);
+        }
+    } finally {
+        C._free(countPtr);
+        destroyGeoPolygon(geoPolygon);
+    }
+}
+
 /**
  * Get the outlines of a set of H3 hexagons, returned in GeoJSON MultiPolygon
  * format (an array of polygons, each with an array of loops, each an array of

out/binding-functions

@@ -1,10 +1,12 @@
+describeH3Error
 latLngToCell
 cellToLatLng
 cellToBoundary
 gridDisk
 gridDiskDistances
 gridRingUnsafe
 polygonToCells
+polygonToCellsExperimental
 cellsToMultiPolygon
 degsToRads
 radsToDegs

out/libh3.js

@@ -4,7 +4,8 @@
   "description": "Pure-Javascript version of the H3 library, a hexagon-based geographic grid system",
   "author": "Nick Rabinowitz <nickr@uber.com>",
   "contributors": [
-    "David Ellis <isv.damocles@gmail.com>"
+    "David Ellis <isv.damocles@gmail.com>",
+    "Isaac Brodsky <isaac@isaacbrodsky.com>"
   ],
   "license": "Apache-2.0",
   "repository": {