Support for h3 3.5.0 (#56)

* Update h3 to 3.5.0

Includes new `h3_faces` and `h3_max_count` methods.

Behind the scenes, `cmake` is given a couple of extra build options
to prevent it from building unnecessary filter binaries and benchmarks.

* Update CHANGELOG.md

Co-Authored-By: Xavier Noria <[email protected]>

* Update lib/h3/inspection.rb

Co-Authored-By: Xavier Noria <[email protected]>

Author: seanhandley

CHANGELOG.md

@@ -6,6 +6,12 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 We track the MAJOR and MINOR version levels of Uber's H3 project (https://github.com/uber/h3) but maintain independent patch levels so we can make small fixes and non breaking changes.
 
+## [3.5.0] - 2019-7-25
+### Added
+- `h3_faces` and `max_face_count` support (#56)
+### Changed
+- New CMake options to prevent unnecessary building of filter apps and benchmarks.
+
 ## [3.4.4] - 2019-6-4
 ### Changed
 - Internal h3 bugfixes.

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    h3 (3.4.0)
+    h3 (3.5.0)
       ffi (~> 1.9)
       rgeo-geojson (~> 2.1)
 

ext/h3/Makefile

@@ -1,5 +1,5 @@
 make:
-	cd src; cmake . -DBUILD_SHARED_LIBS=true; make
+	cd src; cmake . -DBUILD_SHARED_LIBS=true -DBUILD_FILTERS=OFF -DBUILD_BENCHMARKS=OFF; make
 install:
 	: # do nothing, we'll load the lib directly
 clean:

ext/h3/src

@@ -10,6 +10,7 @@ module Private
       attach_function :compact, [H3IndexesIn, H3IndexesOut, :size], :bool
       attach_function :destroy_linked_polygon, :destroyLinkedPolygon, [LinkedGeoPolygon], :void
       attach_function :geo_to_h3, :geoToH3, [GeoCoord, Resolution], :h3_index
+      attach_function :h3_faces, :h3GetFaces, %i[h3_index output_buffer], :void
       attach_function :h3_indexes_from_unidirectional_edge,
                       :getH3IndexesFromUnidirectionalEdge,
                       [:h3_index, H3IndexesOut], :void

lib/h3/bindings/private.rb

@@ -101,5 +101,39 @@ def h3_to_string(h3_index)
       Bindings::Private.h3_to_string(h3_index, h3_str, H3_TO_STR_BUF_SIZE)
       h3_str.read_string
     end
+
+    # @!method max_face_count(h3_index)
+    #
+    # Returns the maximum number of icosahedron faces the given H3 index may intersect.
+    #
+    # @param [Integer] h3_index A H3 index.
+    #
+    # @example Check maximum faces
+    #   H3.max_face_count(585961082523222015)
+    #   5
+    #
+    # @return [Integer] Maximum possible number of faces
+    attach_function :max_face_count, :maxFaceCount, %i[h3_index], :int
+
+    # void h3GetFaces(H3Index h, int* out);
+
+    # @!method h3_faces(h3_index)
+    #
+    # Find all icosahedron faces intersected by a given H3 index.
+    #
+    # @param [Integer] h3_index A H3 index.
+    #
+    # @example Find icosahedron faces for given index
+    #   H3.h3_faces(585961082523222015)
+    #   [1, 2, 6, 7, 11]
+    #
+    # @return [Array<Integer>] Faces. Faces are represented as integers from 0-19, inclusive.
+    def h3_faces(h3_index)
+      max_faces = max_face_count(h3_index)
+      out = FFI::MemoryPointer.new(:int, max_faces)
+      Bindings::Private.h3_faces(h3_index, out)
+      # The C function returns a sparse array whose holes are represented by -1.
+      out.read_array_of_int(max_faces).reject(&:negative?).sort
+    end
   end
 end

lib/h3/inspection.rb

@@ -1,3 +1,3 @@
 module H3
-  VERSION = "3.4.4".freeze
+  VERSION = "3.5.0".freeze
 end

lib/h3/version.rb

@@ -87,4 +87,36 @@
       it { is_expected.to eq(result) } 
     end
   end
-end
+
+  describe ".max_face_count" do
+    let(:h3_index) { "8928308280fffff".to_i(16) }
+    let(:result) { 2 }
+
+    subject(:max_face_count) { H3.max_face_count(h3_index) }
+
+    it { is_expected.to eq(result) }
+
+    context "when the h3 index is a pentagon" do
+      let(:h3_index) { "821c07fffffffff".to_i(16) }
+      let(:result) { 5 }
+
+      it { is_expected.to eq(result) } 
+    end
+  end
+
+  describe ".h3_faces" do
+    let(:h3_index) { "8928308280fffff".to_i(16) }
+    let(:result) { [7] }
+
+    subject(:max_face_count) { H3.h3_faces(h3_index) }
+
+    it { is_expected.to eq(result) }
+
+    context "when the h3 index is a pentagon" do
+      let(:h3_index) { "821c07fffffffff".to_i(16) }
+      let(:result) { [1, 2, 6, 7, 11] }
+
+      it { is_expected.to eq(result) } 
+    end
+  end
+end