Bump core library to 4.1.0, adding cellToChildPos, childPosToCell, and cellToChildrenSize

CHANGELOG.md

@@ -3,9 +3,15 @@
 All notable changes to this project will be documented in this file. This library adheres to a versioning policy described in [the README](./README.md#versioning). The public API of this library consists of the functions exported in [h3core.js](./lib/h3core.js).
 
 ## [Unreleased]
+### Added
+- Add `cellToChildPos`, `childPosToCell`, and `cellToChildrenSize` functions. (#170)
+
+### Changed
+- Updated the core library to `v4.1.0` (#170)
+
 ### Fixed
-- Patch libh3 bundles to check for `typeof document != "undefined"` before accessing `document`. This allows h3-js to be used in a Web Worker and React Native
-- Fix H3Index type hints for `cellToBoundary`, `cellArea`, `edgeLength`
+- Patch libh3 bundles to check for `typeof document != "undefined"` before accessing `document`. This allows h3-js to be used in a Web Worker and React Native (#169)
+- Fix H3Index type hints for `cellToBoundary`, `cellArea`, `edgeLength` (#171)
 
 ## [4.0.1] - 2022-09-19
 ### Changed

H3_VERSION

@@ -1 +1 @@
-4.0.1
+4.1.0

README.md

@@ -8,7 +8,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/uber/h3-js/badge.svg?branch=master)](https://coveralls.io/github/uber/h3-js?branch=master)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![npm version](https://badge.fury.io/js/h3-js.svg)](https://badge.fury.io/js/h3-js)
-[![H3 Version](https://img.shields.io/static/v1?label=h3%20api&message=v4.0.0&color=blue)](https://github.com/uber/h3/releases/tag/v4.0.1)
+[![H3 Version](https://img.shields.io/static/v1?label=h3%20api&message=v4.1.0&color=blue)](https://github.com/uber/h3/releases/tag/v4.1.0)
 
 The `h3-js` library provides a pure-JavaScript version of the [H3 Core Library](https://github.com/uber/h3), a hexagon-based geographic grid system. It can be used either in Node >= 6 or in the browser. The core library is transpiled from C using [emscripten](http://kripken.github.io/emscripten-site), offering full parity with the C API and highly efficient operations.
 
@@ -112,7 +112,10 @@ const coordinates = h3.cellsToMultiPolygon(hexagons, true);
     * [.cellToBoundary(h3Index, [formatAsGeoJson])](#module_h3.cellToBoundary) ⇒ <code>Array.&lt;CoordPair&gt;</code>
     * [.cellToParent(h3Index, res)](#module_h3.cellToParent) ⇒ <code>H3Index</code>
     * [.cellToChildren(h3Index, res)](#module_h3.cellToChildren) ⇒ <code>Array.&lt;H3Index&gt;</code>
+    * [.cellToChildrenSize(h3Index, res)](#module_h3.cellToChildrenSize) ⇒ <code>number</code>
     * [.cellToCenterChild(h3Index, res)](#module_h3.cellToCenterChild) ⇒ <code>H3Index</code>
+    * [.cellToChildPos(h3Index, parentRes)](#module_h3.cellToChildPos) ⇒ <code>number</code>
+    * [.childPosToCell(childPos, h3Index, childRes)](#module_h3.childPosToCell) ⇒ <code>H3Index</code>
     * [.gridDisk(h3Index, ringSize)](#module_h3.gridDisk) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.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>
@@ -389,6 +392,25 @@ Get the children/descendents of the given hexagon at a particular resolution
 | res | <code>number</code> | Resolution of hexagons to return |
 
 
+* * *
+
+<a name="module_h3.cellToChildrenSize"></a>
+
+### h3.cellToChildrenSize(h3Index, res) ⇒ <code>number</code>
+Get the number of children for a cell at a given resolution
+
+**Returns**: <code>number</code> - Number of children at res for the given cell  
+**Throws**:
+
+- <code>H3Error</code> If cell or parentRes are invalid
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| h3Index | <code>H3IndexInput</code> | H3 index to get child count for |
+| res | <code>number</code> | Child resolution |
+
+
 * * *
 
 <a name="module_h3.cellToCenterChild"></a>
@@ -405,7 +427,48 @@ Get the center child of the given hexagon at a particular resolution
 | Param | Type | Description |
 | --- | --- | --- |
 | h3Index | <code>H3IndexInput</code> | H3 index to get center child for |
-| res | <code>number</code> | Resolution of hexagon to return |
+| res | <code>number</code> | Resolution of cell to return |
+
+
+* * *
+
+<a name="module_h3.cellToChildPos"></a>
+
+### h3.cellToChildPos(h3Index, parentRes) ⇒ <code>number</code>
+Get the position of the cell within an ordered list of all children of the
+cell's parent at the specified resolution.
+
+**Returns**: <code>number</code> - Position of child within parent at parentRes  
+**Throws**:
+
+- <code>H3Error</code> If cell or parentRes are invalid
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| h3Index | <code>H3IndexInput</code> | H3 index to get child pos for |
+| parentRes | <code>number</code> | Resolution of reference parent |
+
+
+* * *
+
+<a name="module_h3.childPosToCell"></a>
+
+### h3.childPosToCell(childPos, h3Index, childRes) ⇒ <code>H3Index</code>
+Get the child cell at a given position within an ordered list of all children
+at the specified resolution
+
+**Returns**: <code>H3Index</code> - H3 index of child  
+**Throws**:
+
+- <code>H3Error</code> If input is invalid
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| childPos | <code>number</code> | Position of the child cell to get |
+| h3Index | <code>H3IndexInput</code> | H3 index of the parent cell |
+| childRes | <code>number</code> | Resolution of child cell to return |
 
 
 * * *

benchmark/benchmarks.js

@@ -62,6 +62,22 @@ export default function makeBenchmarks() {
         h3core.getIcosahedronFaces(h3Index);
     });
 
+    suite.add('cellToChildren', () => {
+        h3core.cellToChildren(h3Index, 14);
+    });
+
+    suite.add('cellToParent', () => {
+        h3core.cellToParent(h3Index, 0);
+    });
+
+    suite.add('cellToChildPos', () => {
+        h3core.cellToChildPos(h3Index, 0);
+    });
+
+    suite.add('childPosToCell', () => {
+        h3core.childPosToCell(16800, h3Index, 14);
+    });
+
     suite.add('gridDisk', () => {
         h3core.gridDisk(h3Index, 1);
     });

doc-files/README.tmpl.md

@@ -8,7 +8,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/uber/h3-js/badge.svg?branch=master)](https://coveralls.io/github/uber/h3-js?branch=master)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![npm version](https://badge.fury.io/js/h3-js.svg)](https://badge.fury.io/js/h3-js)
-[![H3 Version](https://img.shields.io/static/v1?label=h3%20api&message=v4.0.0&color=blue)](https://github.com/uber/h3/releases/tag/v4.0.1)
+[![H3 Version](https://img.shields.io/static/v1?label=h3%20api&message=v4.1.0&color=blue)](https://github.com/uber/h3/releases/tag/v4.1.0)
 
 The `h3-js` library provides a pure-JavaScript version of the [H3 Core Library](https://github.com/uber/h3), a hexagon-based geographic grid system. It can be used either in Node >= 6 or in the browser. The core library is transpiled from C using [emscripten](http://kripken.github.io/emscripten-site), offering full parity with the C API and highly efficient operations.
 

lib/bindings.js

@@ -65,6 +65,8 @@ export default [
     ['cellToChildren', H3_ERROR, [H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
     ['cellToCenterChild', H3_ERROR, [H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
     ['cellToChildrenSize', H3_ERROR, [H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
+    ['cellToChildPos', H3_ERROR, [H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
+    ['childPosToCell', H3_ERROR, [NUMBER, NUMBER, H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
     ['areNeighborCells', H3_ERROR, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER, POINTER]],
     ['cellsToDirectedEdge', H3_ERROR, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER, POINTER]],
     ['getDirectedEdgeOrigin', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],

lib/h3core.js

@@ -27,7 +27,8 @@ import {
     E_RES_DOMAIN,
     E_UNKNOWN_UNIT,
     E_ARRAY_LENGTH,
-    E_NULL_INDEX
+    E_NULL_INDEX,
+    E_CELL_INVALID
 } from './errors';
 
 /**
@@ -248,6 +249,23 @@ function zeroPad(fullLen, numStr) {
     return outStr;
 }
 
+// One more than the max size of an unsigned 32-bit int.
+// Dividing by this number is equivalent to num >>> 32
+const UPPER_BIT_DIVISOR = Math.pow(2, 32);
+
+/**
+ * Convert a JS double-precision floating point number to a split long
+ * @private
+ * @param  {number} num  Number to convert
+ * @return {SplitLong}     A two-element array with 32 lower bits and 32 upper bits
+ */
+function numberToSplitLong(num) {
+    if (typeof num !== 'number') {
+        return [0, 0];
+    }
+    return [num | 0, (num / UPPER_BIT_DIVISOR) | 0];
+}
+
 /**
  * Populate a C-appropriate GeoLoop struct from a polygon array
  * @private
@@ -778,17 +796,33 @@ export function cellToChildren(h3Index, res) {
         return [];
     }
     const [lower, upper] = h3IndexToSplitLong(h3Index);
+    const count = validateArrayLength(cellToChildrenSize(h3Index, res));
+    const hexagons = C._calloc(count, SZ_H3INDEX);
+    try {
+        throwIfError(H3.cellToChildren(lower, upper, res, hexagons));
+        return readArrayOfH3Indexes(hexagons, count);
+    } finally {
+        C._free(hexagons);
+    }
+}
+
+/**
+ * Get the number of children for a cell at a given resolution
+ * @static
+ * @param  {H3IndexInput} h3Index  H3 index to get child count for
+ * @param  {number} res            Child resolution
+ * @return {number}                Number of children at res for the given cell
+ * @throws {H3Error}               If cell or parentRes are invalid
+ */
+export function cellToChildrenSize(h3Index, res) {
+    if (!isValidCell(h3Index)) {
+        throw H3LibraryError(E_CELL_INVALID);
+    }
+    const [lower, upper] = h3IndexToSplitLong(h3Index);
     const countPtr = C._malloc(SZ_INT64);
     try {
         throwIfError(H3.cellToChildrenSize(lower, upper, res, countPtr));
-        const count = validateArrayLength(readInt64AsDoubleFromPointer(countPtr));
-        const hexagons = C._calloc(count, SZ_H3INDEX);
-        try {
-            throwIfError(H3.cellToChildren(lower, upper, res, hexagons));
-            return readArrayOfH3Indexes(hexagons, count);
-        } finally {
-            C._free(hexagons);
-        }
+        return readInt64AsDoubleFromPointer(countPtr);
     } finally {
         C._free(countPtr);
     }
@@ -798,7 +832,7 @@ export function cellToChildren(h3Index, res) {
  * Get the center child of the given hexagon at a particular resolution
  * @static
  * @param  {H3IndexInput} h3Index  H3 index to get center child for
- * @param  {number} res       Resolution of hexagon to return
+ * @param  {number} res       Resolution of cell to return
  * @return {H3Index}          H3 index of child, or null for invalid input
  * @throws {H3Error}          If resolution is invalid
  */
@@ -813,6 +847,48 @@ export function cellToCenterChild(h3Index, res) {
     }
 }
 
+/**
+ * Get the position of the cell within an ordered list of all children of the
+ * cell's parent at the specified resolution.
+ * @static
+ * @param  {H3IndexInput} h3Index  H3 index to get child pos for
+ * @param  {number} parentRes      Resolution of reference parent
+ * @return {number}                Position of child within parent at parentRes
+ * @throws {H3Error}               If cell or parentRes are invalid
+ */
+export function cellToChildPos(h3Index, parentRes) {
+    const [lower, upper] = h3IndexToSplitLong(h3Index);
+    const childPos = C._malloc(SZ_INT64);
+    try {
+        throwIfError(H3.cellToChildPos(lower, upper, parentRes, childPos));
+        return readInt64AsDoubleFromPointer(childPos);
+    } finally {
+        C._free(childPos);
+    }
+}
+
+/**
+ * Get the child cell at a given position within an ordered list of all children
+ * at the specified resolution
+ * @static
+ * @param  {number} childPos       Position of the child cell to get
+ * @param  {H3IndexInput} h3Index  H3 index of the parent cell
+ * @param  {number} childRes       Resolution of child cell to return
+ * @return {H3Index}          H3 index of child
+ * @throws {H3Error}          If input is invalid
+ */
+export function childPosToCell(childPos, h3Index, childRes) {
+    const [cpLower, cpUpper] = numberToSplitLong(childPos);
+    const [lower, upper] = h3IndexToSplitLong(h3Index);
+    const child = C._malloc(SZ_H3INDEX);
+    try {
+        throwIfError(H3.childPosToCell(cpLower, cpUpper, lower, upper, childRes, child));
+        return validateH3Index(readH3IndexFromPointer(child));
+    } finally {
+        C._free(child);
+    }
+}
+
 /**
  * Get all hexagons in a k-ring around a given center. The order of the hexagons is undefined.
  * @static

out/binding-functions

@@ -24,6 +24,8 @@ isValidCell
 cellToParent
 cellToChildren
 cellToCenterChild
+cellToChildPos
+childPosToCell
 compactCells
 uncompactCells
 isResClassIII