Upgrade to h3 4.3.0 (#169)

Author: isaacbrodsky

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.2.1-blue.svg)](https://github.com/uber/h3/releases/tag/v4.2.1)
+[![H3 Version](https://img.shields.io/badge/h3-v4.3.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.3.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/).
 
@@ -62,22 +62,10 @@ You may be able to build H3-Java locally if you need to use an operating system
 
 # Development
 
-Building the library requires a JDK, Maven, CMake, and a C compiler. To install to your local Maven cache, run:
+Building the library requires a JDK, Gradle, CMake, and a C compiler. To build:
 
 ```sh
-mvn install
-```
-
-To build the library, run:
-
-```sh
-mvn package
-```
-
-To format source code as required by CI, run:
-
-```sh
-mvn com.spotify.fmt:fmt-maven-plugin:format
+./gradlew assemble test -Ph3UseDocker=false
 ```
 
 Additional information on how the build process works is available in the [build process documentaiton](docs/library-build.md).
@@ -86,7 +74,7 @@ Additional information on how the build process works is available in the [build
 
 ```sh
 # To install build dependencies
-sudo pkg install openjdk11 maven cmake bash
+sudo pkg install openjdk11 cmake bash
 # Ensure /usr/local/openjdk11/bin is on your path
 ```
 
@@ -95,15 +83,17 @@ sudo pkg install openjdk11 maven cmake bash
 To build Javadocs documentation:
 
 ```sh
-mvn site
+./gradlew javadoc -Ph3UseDocker=false
 ```
 
-Then open the file `target/site/apidocs/index.html`.
+Then open the file `build/docs/javadoc/index.html`.
 
 ## Benchmarking
 
 To run benchmarks, either execute them from IntelliJ or run the following from shell: (Replace the class name as needed)
 
+::: Note: These instructions need to be updated for Gradle.
+
 ```sh
 mvn exec:exec -Dexec.executable="java" -Dexec.args="-classpath %classpath com.uber.h3core.benchmarking.H3CoreBenchmark" -Dexec.classpathScope="test"
 ```

build.gradle

@@ -114,6 +114,10 @@ jar {
     duplicatesStrategy = DuplicatesStrategy.WARN
 }
 
+sourcesJar {
+    dependsOn buildH3
+}
+
 publishing {
     publications {
         mavenJava(MavenPublication) {

h3version.properties

@@ -1 +1 @@
-h3.git.reference=v4.2.1
+h3.git.reference=v4.3.0

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

@@ -423,6 +423,28 @@ JNIEXPORT void JNICALL Java_com_uber_h3core_NativeMethods_gridDiskUnsafe(
     }
 }
 
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    gridRing
+ * Signature: (JI[J)V
+ */
+JNIEXPORT void JNICALL Java_com_uber_h3core_NativeMethods_gridRing(
+    JNIEnv *env, jobject thiz, jlong h3, jint k, jlongArray results) {
+    jlong *resultsElements = (**env).GetLongArrayElements(env, results, 0);
+
+    if (resultsElements != NULL) {
+        // if sz is too small, bad things will happen
+        H3Error err = gridRing(h3, k, resultsElements);
+
+        (**env).ReleaseLongArrayElements(env, results, resultsElements, 0);
+        if (err) {
+            ThrowH3Exception(env, err);
+        }
+    } else {
+        ThrowOutOfMemoryError(env);
+    }
+}
+
 /*
  * Class:     com_uber_h3core_NativeMethods
  * Method:    gridRingUnsafe

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

@@ -318,6 +318,34 @@ public List<List<Long>> gridDiskUnsafe(long h3, int k) {
     return ret;
   }
 
+  /**
+   * Returns in order neighbor traversal, of indexes with distance of <code>k</code>.
+   *
+   * @param h3Address Origin index
+   * @param k Number of rings around the origin
+   * @return All indexes <code>k</code> away from the origin
+   */
+  public List<String> gridRing(String h3Address, int k) {
+    return h3ToStringList(gridRing(stringToH3(h3Address), k));
+  }
+
+  /**
+   * Returns in order neighbor traversal, of indexes with distance of <code>k</code>.
+   *
+   * @param h3 Origin index
+   * @param k Number of rings around the origin
+   * @return All indexes <code>k</code> away from the origin
+   */
+  public List<Long> gridRing(long h3, int k) {
+    int sz = k == 0 ? 1 : 6 * k;
+
+    long[] out = new long[sz];
+
+    h3Api.gridRing(h3, k, out);
+
+    return nonZeroLongArrayToList(out);
+  }
+
   /**
    * Returns in order neighbor traversal, of indexes with distance of <code>k</code>.
    *

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

@@ -54,6 +54,8 @@ final class NativeMethods {
 
   native void gridDiskUnsafe(long h3, int k, long[] results);
 
+  native void gridRing(long h3, int k, long[] results);
+
   native void gridRingUnsafe(long h3, int k, long[] results);
 
   native long gridDistance(long a, long b);

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

@@ -182,7 +182,7 @@ void hexRangePentagon() {
 
   @Test
   void hexRing() {
-    List<String> hexagons = h3.gridRingUnsafe("8928308280fffff", 1);
+    List<String> hexagons = h3.gridRing("8928308280fffff", 1);
 
     assertEquals(6, hexagons.size());
 
@@ -196,7 +196,7 @@ void hexRing() {
 
   @Test
   void hexRing2() {
-    List<String> hexagons = h3.gridRingUnsafe("8928308280fffff", 2);
+    List<String> hexagons = h3.gridRing("8928308280fffff", 2);
 
     assertEquals(12, hexagons.size());
 
@@ -217,7 +217,7 @@ void hexRing2() {
   @Test
   void hexRingLarge() {
     int k = 50;
-    List<String> hexagons = h3.gridRingUnsafe("8928308280fffff", k);
+    List<String> hexagons = h3.gridRing("8928308280fffff", k);
 
     int expectedCount = 50 * 6;
 
@@ -226,16 +226,104 @@ void hexRingLarge() {
 
   @Test
   void hexRingPentagon() {
-    assertThrows(H3Exception.class, () -> h3.gridRingUnsafe("821c07fffffffff", 1));
+    List<String> hexagons = h3.gridRing("821c07fffffffff", 1);
+
+    assertEquals(5, hexagons.size());
+
+    assertTrue(hexagons.contains("821c37fffffffff"));
+    assertTrue(hexagons.contains("821c17fffffffff"));
+    assertTrue(hexagons.contains("821c1ffffffffff"));
+    assertTrue(hexagons.contains("821c27fffffffff"));
+    assertTrue(hexagons.contains("821c2ffffffffff"));
+
+    List<String> hexagons2 = h3.gridRing("821c07fffffffff", 2);
+
+    assertEquals(10, hexagons2.size());
   }
 
   @Test
   void hexRingAroundPentagon() {
-    assertThrows(H3Exception.class, () -> h3.gridRingUnsafe("821c37fffffffff", 2));
+    List<String> hexagons = h3.gridRing("821c37fffffffff", 1);
+
+    assertEquals(6, hexagons.size());
+
+    assertTrue(hexagons.contains("821d8ffffffffff"));
+    assertTrue(hexagons.contains("821c07fffffffff"));
+    assertTrue(hexagons.contains("821c17fffffffff"));
+    assertTrue(hexagons.contains("821d1ffffffffff"));
+    assertTrue(hexagons.contains("821c27fffffffff"));
+    assertTrue(hexagons.contains("821daffffffffff"));
+
+    List<String> hexagons2 = h3.gridRing("821c37fffffffff", 2);
+
+    assertEquals(11, hexagons2.size());
   }
 
   @Test
   void hexRingSingle() {
+    String origin = "8928308280fffff";
+    List<String> hexagons = h3.gridRing(origin, 0);
+
+    assertEquals(1, hexagons.size());
+    assertEquals("8928308280fffff", hexagons.get(0));
+  }
+
+  @Test
+  void hexRingUnsafe() {
+    List<String> hexagons = h3.gridRingUnsafe("8928308280fffff", 1);
+
+    assertEquals(6, hexagons.size());
+
+    assertTrue(hexagons.contains("8928308280bffff"));
+    assertTrue(hexagons.contains("89283082807ffff"));
+    assertTrue(hexagons.contains("89283082877ffff"));
+    assertTrue(hexagons.contains("89283082803ffff"));
+    assertTrue(hexagons.contains("89283082873ffff"));
+    assertTrue(hexagons.contains("8928308283bffff"));
+  }
+
+  @Test
+  void hexRing2Unsafe() {
+    List<String> hexagons = h3.gridRingUnsafe("8928308280fffff", 2);
+
+    assertEquals(12, hexagons.size());
+
+    assertTrue(hexagons.contains("89283082813ffff"));
+    assertTrue(hexagons.contains("89283082817ffff"));
+    assertTrue(hexagons.contains("8928308281bffff"));
+    assertTrue(hexagons.contains("89283082863ffff"));
+    assertTrue(hexagons.contains("89283082823ffff"));
+    assertTrue(hexagons.contains("8928308287bffff"));
+    assertTrue(hexagons.contains("89283082833ffff"));
+    assertTrue(hexagons.contains("8928308282bffff"));
+    assertTrue(hexagons.contains("89283082857ffff"));
+    assertTrue(hexagons.contains("892830828abffff"));
+    assertTrue(hexagons.contains("89283082847ffff"));
+    assertTrue(hexagons.contains("89283082867ffff"));
+  }
+
+  @Test
+  void hexRingLargeUnsafe() {
+    int k = 50;
+    List<String> hexagons = h3.gridRingUnsafe("8928308280fffff", k);
+
+    int expectedCount = 50 * 6;
+
+    assertEquals(expectedCount, hexagons.size());
+  }
+
+  @Test
+  void hexRingPentagonUnsafe() {
+    assertThrows(H3Exception.class, () -> h3.gridRingUnsafe("821c07fffffffff", 1));
+  }
+
+  @Test
+  void hexRingAroundPentagonUnsafe() {
+    assertThrows(H3Exception.class, () -> h3.gridRingUnsafe("821c37fffffffff", 2));
+  }
+
+  @Test
+  void hexRingSingleUnsafe() {
     String origin = "8928308280fffff";
     List<String> hexagons = h3.gridRingUnsafe(origin, 0);