upgrade to v4.1.0 (#121)

* upgrade to v4.1.0

* Add PR number

* add cellToChildrenSize

* update release date

CHANGELOG.md

@@ -7,6 +7,14 @@ file [H3Core.java](./src/main/java/com/uber/h3core/H3Core.java), and support
 for the Linux x64 and Darwin x64 platforms.
 
 ## Unreleased Changes
+## [4.1.0] - 2023-01-19
+### Added
+- `cellToChildPos` and `childPosToCell` functions. (#121)
+- Made the `cellToChildrenSize` function public. (#121)
+
+### Changed
+- Upgraded the core library to v4.1.0. (#121)
+
 ## [4.0.2] - 2022-09-21
 ### Changed
 - Upgraded the core library to v4.0.1. (#113)

README.md

@@ -6,7 +6,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/uber/h3-java/badge.svg?branch=master)](https://coveralls.io/github/uber/h3-java?branch=master)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.uber/h3/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.uber/h3)
-[![H3 Version](https://img.shields.io/badge/h3-v4.0.1-blue.svg)](https://github.com/uber/h3/releases/tag/v4.0.1)
+[![H3 Version](https://img.shields.io/badge/h3-v4.1.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.1.0)
 
 This library provides Java bindings for the [H3 Core Library](https://github.com/uber/h3). For API reference, please see the [H3 Documentation](https://h3geo.org/).
 
@@ -18,14 +18,14 @@ Add it to your pom.xml:
 <dependency>
     <groupId>com.uber</groupId>
     <artifactId>h3</artifactId>
-    <version>4.0.2</version>
+    <version>4.1.0</version>
 </dependency>
 ```
 
 Or, using Gradle:
 
 ```gradle
-compile("com.uber:h3:4.0.2")
+compile("com.uber:h3:4.1.0")
 ```
 
 Encode a location into a hexagon address:

docs/releasing.md

@@ -26,3 +26,7 @@ export GPG_TTY=$(tty)
 ### docker: Error response from daemon: error while creating mount source path
 
 This has been seen when the source path is not shared from the host in the Docker settings. Even if the source path appears to have been shared, if the source path is a symbolic link, you may need to reshare it from Docker Preferences.
+
+### fatal error: jni.h: No such file or directory
+
+This can occur when `JAVA_HOME` is not set.

h3version.properties

@@ -1 +1 @@
-h3.git.reference=v4.0.1
+h3.git.reference=v4.1.0

src/main/c/h3-java/CMakeLists.txt

@@ -38,10 +38,16 @@ project(h3-java LANGUAGES C)
 include_directories(${H3_BUILD_ROOT}/src/h3lib/include)
 
 if(USE_NATIVE_JNI)
+    message("USE_NATIVE_JNI")
+    # Disable unneeded parts of FindJNI
+    # https://stackoverflow.com/questions/51047978/cmake-could-not-find-jni
+    set(JAVA_AWT_LIBRARY NotNeeded)
+    set(JAVA_JVM_LIBRARY NotNeeded)
     find_package(JNI REQUIRED)
 
     include_directories(${JNI_INCLUDE_DIRS})
 else()
+    message("using /java")
     include_directories(/java/include)
     # TODO Provide correct jni_md.h
     include_directories(/java/include/linux)

src/main/c/h3-java/src/jniapi.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2019, 2022 Uber Technologies, Inc.
+ * Copyright 2017-2019, 2022-2023 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -1353,3 +1353,35 @@ JNIEXPORT jboolean JNICALL Java_com_uber_h3core_NativeMethods_isValidVertex(
     JNIEnv *env, jobject thiz, jlong h3) {
     return isValidVertex(h3);
 }
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    cellToChildPos
+ * Signature: (JI)J
+ */
+JNIEXPORT jlong JNICALL Java_com_uber_h3core_NativeMethods_cellToChildPos(
+    JNIEnv *env, jobject thiz, jlong child, jint parentRes) {
+    jlong pos;
+    H3Error err = cellToChildPos(child, parentRes, &pos);
+    if (err) {
+        ThrowH3Exception(env, err);
+        return 0;
+    }
+    return pos;
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    childPosToCell
+ * Signature: (JJI)J
+ */
+JNIEXPORT jlong JNICALL Java_com_uber_h3core_NativeMethods_childPosToCell(
+    JNIEnv *env, jobject thiz, jlong childPos, jlong parent, jint childRes) {
+    H3Index out;
+    H3Error err = childPosToCell(childPos, parent, childRes, &out);
+    if (err) {
+        ThrowH3Exception(env, err);
+        return 0;
+    }
+    return out;
+}

src/main/java/com/uber/h3core/H3Core.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2019, 2022 Uber Technologies, Inc.
+ * Copyright 2017-2019, 2022-2023 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -719,6 +719,16 @@ public String cellToCenterChild(String h3, int childRes) {
     return h3ToString(cellToCenterChild(stringToH3(h3), childRes));
   }
 
+  /** Returns the number of children the cell index has at the given resolution. */
+  public long cellToChildrenSize(long cell, int childRes) {
+    return h3Api.cellToChildrenSize(cell, childRes);
+  }
+
+  /** Returns the number of children the cell index has at the given resolution. */
+  public long cellToChildrenSize(String cellAddress, int childRes) {
+    return cellToChildrenSize(stringToH3(cellAddress), childRes);
+  }
+
   /**
    * Returns the center child at the given resolution.
    *
@@ -1118,6 +1128,38 @@ public boolean isValidVertex(String h3Address) {
     return h3Api.isValidVertex(stringToH3(h3Address));
   }
 
+  /**
+   * Returns the position of the child cell within an ordered list of all children of the cell's
+   * parent at the specified resolution parentRes.
+   */
+  public long cellToChildPos(String childAddress, int parentRes) {
+    return cellToChildPos(stringToH3(childAddress), parentRes);
+  }
+
+  /**
+   * Returns the position of the child cell within an ordered list of all children of the cell's
+   * parent at the specified resolution parentRes.
+   */
+  public long cellToChildPos(long child, int parentRes) {
+    return h3Api.cellToChildPos(child, parentRes);
+  }
+
+  /**
+   * Returns the child cell at a given position within an ordered list of all children of parent at
+   * the specified resolution childRes.
+   */
+  public long childPosToCell(long childPos, long parent, int childRes) {
+    return h3Api.childPosToCell(childPos, parent, childRes);
+  }
+
+  /**
+   * Returns the child cell at a given position within an ordered list of all children of parent at
+   * the specified resolution childRes.
+   */
+  public String childPosToCell(long childPos, String parentAddress, int childRes) {
+    return h3ToString(childPosToCell(childPos, stringToH3(parentAddress), childRes));
+  }
+
   /** Transforms a collection of H3 indexes in string form to a list of H3 indexes in long form. */
   private List<Long> stringToH3List(Collection<String> collection) {
     return collection.stream().map(this::stringToH3).collect(Collectors.toList());

src/main/java/com/uber/h3core/NativeMethods.java

@@ -139,4 +139,8 @@ native void polygonToCells(
   native void vertexToLatLng(long h3, double[] latLng);
 
   native boolean isValidVertex(long h3);
+
+  native long cellToChildPos(long child, int parentRes);
+
+  native long childPosToCell(long childPos, long parent, int childRes);
 }

src/test/java/com/uber/h3core/TestHierarchy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019, 2022 Uber Technologies, Inc.
+ * Copyright 2019, 2022-2023 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,10 +16,13 @@
 package com.uber.h3core;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotEquals;
 import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
 
 import com.google.common.collect.ImmutableList;
 import com.uber.h3core.exceptions.H3Exception;
+import com.uber.h3core.util.LatLng;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashSet;
@@ -74,8 +77,8 @@ public void testH3ToChildren() {
 
     // res 0 pentagon has 5 hexagon children and 1 pentagon child at res 1.
     // Total output will be:
-    //   5 * 7 children of res 1 hexagons
-    //   6 children of res 1 pentagon
+    // 5 * 7 children of res 1 hexagons
+    // 6 children of res 1 pentagon
     assertEquals(5 * 7 + 6, pentagonChildren.size());
 
     // Don't crash
@@ -188,4 +191,105 @@ public void testH3ToCenterChildNegative() {
   public void testH3ToCenterChildOutOfRange() {
     h3.cellToCenterChild("8928308280fffff", 16);
   }
+
+  @Test
+  public void testCellToChildPos() {
+    assertEquals(0, h3.cellToChildPos(0x88283080ddfffffL, 8));
+    assertEquals(6, h3.cellToChildPos(0x88283080ddfffffL, 7));
+    assertEquals(41, h3.cellToChildPos("88283080ddfffff", 6));
+  }
+
+  @Test(expected = H3Exception.class)
+  public void testCellToChildPosError() {
+    h3.cellToChildPos(0x88283080ddfffffL, 9);
+  }
+
+  @Test(expected = H3Exception.class)
+  public void testCellToChildPosError2() {
+    h3.cellToChildPos("88283080ddfffff", 9);
+  }
+
+  @Test
+  public void childPosToCell() {
+    assertEquals(0x88283080ddfffffL, h3.childPosToCell(0, 0x88283080ddfffffL, 8));
+    assertEquals(
+        0x88283080ddfffffL, h3.childPosToCell(6, h3.cellToParent(0x88283080ddfffffL, 7), 8));
+    assertEquals(
+        "88283080ddfffff", h3.childPosToCell(41, h3.cellToParentAddress("88283080ddfffff", 6), 8));
+  }
+
+  @Test(expected = H3Exception.class)
+  public void testChildPosToCellError() {
+    h3.childPosToCell(-1, 0x88283080ddfffffL, 9);
+  }
+
+  @Test(expected = H3Exception.class)
+  public void testChildPosToCellError2() {
+    h3.childPosToCell(10000, "88283080ddfffff", 9);
+  }
+
+  @Test
+  public void cellToChildPosRoundTrip() {
+    // These are somewhat arbitrary, but cover a few different parts of the globe
+    List<LatLng> testLatLngs =
+        ImmutableList.of(
+            new LatLng(37.81331899988944, -122.409290778685),
+            new LatLng(64.2868041, 8.7824902),
+            new LatLng(5.8815246, 54.3336044),
+            new LatLng(-41.4486737, 143.918175));
+
+    for (LatLng ll : testLatLngs) {
+      for (int res = 0; res < 16; res++) {
+        long child = h3.latLngToCell(ll.lat, ll.lng, res);
+        long parent = h3.cellToParent(child, 0);
+        long pos = h3.cellToChildPos(child, 0);
+        long cell = h3.childPosToCell(pos, parent, res);
+        assertNotEquals("sanity check that pos is not a reference to child", child, pos);
+        assertEquals("round trip produced the same cell", child, cell);
+      }
+    }
+  }
+
+  @Test
+  public void childPosAndChildrenSize() {
+    // one hexagon, one pentagon
+    for (String index : ImmutableList.of("80bffffffffffff", "80a7fffffffffff")) {
+      for (int res = 0; res < 16; res++) {
+        long count = h3.cellToChildrenSize(index, res);
+        assertTrue(
+            "count has the right order of magnitude",
+            Math.pow(6, res) <= count && count <= Math.pow(7, res));
+
+        String child = h3.childPosToCell(count - 1, index, res);
+        long pos = h3.cellToChildPos(child, 0);
+        assertEquals("got expected round trip", count - 1, pos);
+
+        try {
+          h3.childPosToCell(count, index, res);
+          fail("Should have thrown, one more is out of range");
+        } catch (H3Exception e) {
+          // expected
+          assertEquals(2 /* E_DOMAIN */, e.getCode());
+        }
+      }
+    }
+  }
+
+  @Test(expected = H3Exception.class)
+  public void cellToChildrenSizeError() {
+    // Invalid resolution
+    h3.cellToChildrenSize("88283080ddfffff", 5);
+  }
+
+  @Test(expected = H3Exception.class)
+  public void cellToChildrenSizeError2() {
+    // Invalid resolution
+    h3.cellToChildrenSize(0x88283080ddfffffL, -1);
+  }
+
+  @Test(expected = H3Exception.class)
+  public void cellToChildrenSizeError3() {
+    // Invalid index
+    h3.cellToChildrenSize(0xffffffffffffffffL, 9);
+  }
 }