Upgrade to v4.0.0-rc2 (#91)

Upgrades H3-Java to H3 core library v4.0.0 release candidate. Since this is not the final v4 release, H3-Java with v4 is also considered pre-release.

A new class, `H3CoreV3`, is added to act as a compatibility layer during upgrades. Because it is implemented using the v4 library underneath, care was not taken to make exceptions the same across both interfaces - only the function names are the same. I think this makes H3CoreV3 of limited use, so I expect to remove it in an update before or soon after releasing h3-java v4.0.0.

Author: Isaac Brodsky

CHANGELOG.md

@@ -7,6 +7,15 @@ file [H3Core.java](./src/main/java/com/uber/h3core/H3Core.java), and support
 for the Linux x64 and Darwin x64 platforms.
 
 ## [Unreleased]
+### Breaking Changes
+- Changed the API of `H3Core` to align it with the core library, and introduced `H3CoreV3` for users who wish to use the old names. (#91)
+
+### Added
+- Vertex mode API. (#91)
+
+### Changed
+- Upgraded the core library to v4.0.0. (#91)
+
 ### Removed
 - Removed support for Linux MIPSEL (#92)
 

README.md

@@ -37,13 +37,13 @@ double lat = 37.775938728915946;
 double lng = -122.41795063018799;
 int res = 9;
 
-String hexAddr = h3.geoToH3Address(lat, lng, res);
+String hexAddr = h3.latLngToCellAddress(lat, lng, res);
 ```
 
 Decode a hexagon address into coordinates:
 
 ```java
-List<GeoCoord> geoCoords = h3.h3ToGeoBoundary(hexAddr);
+List<LatLng> LatLngs = h3.cellToGeoBoundary(hexAddr);
 ```
 
 ## Supported Operating Systems

docs/migrating-from-v3.md

@@ -0,0 +1,21 @@
+# Migrating from h3-java version 3
+
+The H3 library introduced breaking [changes](https://h3geo.org/docs/next/library/migrating-3.x) in 4.0.0 which are reflected in H3-Java 4.0.0.
+
+Cell indexes generated in 3.x and 4.x are the same and can be used in either library version interchangably.
+
+## Renaming
+
+Functions and classes were renamed in H3 version 4.0.0 to have a more consistent and predictable naming scheme. The corresponding H3-Java names were changed to match.
+
+### Legacy API
+
+If you do not wish to use the new names, the H3-Java library provides `H3CoreV3` as a temporary compatability layer for applications. Your application can use `H3CoreV3` where it previously used `H3Core` and continue using the same function names. Because `H3CoreV3` uses the core library version 4.0.0 internally, exceptions and error codes are not backwards compatible.
+
+## Exceptions
+
+Specialized exceptions in H3-Java have been replaced with `H3Exception`, which is a `RuntimeException`. This exception wraps the error codes now returned by the H3 core library. The library may also throw standard Java exceptions like `IllegalArgumentException`.
+
+## Removed
+
+* `kRings`: This function is no longer exposed in the H3 library as it existed only for FFI performance reasons.

h3version.properties

@@ -1 +1 @@
-h3.git.reference=v3.7.2
+h3.git.reference=v4.0.0-rc2