Release v3.6.0

CHANGELOG.md

@@ -6,6 +6,11 @@ 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.6.0] - 2019-8-14
+### Added
+- `center_child` method to find center child at given resolution (#62).
+- `pentagons` (and `pentagon_count`) method to find pentagons at given resolution (#62).
+
 ## [3.5.1] - 2019-8-5
 ### Changed
 - Renamed 26 methods to be more idiomatic with Ruby conventions. The old names are deprecated until 2020 when they will be removed (#59).

Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    h3 (3.5.1)
+    h3 (3.6.0)
       ffi (~> 1.9)
       rgeo-geojson (~> 2.1)
-      zeitwerk (~> 2.1.9)
+      zeitwerk (~> 2.1)
 
 GEM
   remote: https://rubygems.org/
@@ -20,7 +20,7 @@ GEM
     ffi (1.11.1)
     json (2.1.0)
     rake (12.3.2)
-    rgeo (2.0.1)
+    rgeo (2.1.0)
     rgeo-geojson (2.1.1)
       rgeo (>= 1.0.0)
     rspec (3.8.0)

h3.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency "ffi", "~> 1.9"
   spec.add_runtime_dependency "rgeo-geojson", "~> 2.1"
-  spec.add_runtime_dependency "zeitwerk", "~> 2.1.9"
+  spec.add_runtime_dependency "zeitwerk", "~> 2.1"
 
   spec.add_development_dependency "coveralls", "~> 0.8"
   spec.add_development_dependency "rake", "~> 12.3"

lib/h3/bindings/private.rb

@@ -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 :get_pentagon_indexes, :getPentagonIndexes, [:int, H3IndexesOut], :void
       attach_function :h3_faces, :h3GetFaces, %i[h3_index output_buffer], :void
       attach_function :h3_indexes_from_unidirectional_edge,
                       :getH3IndexesFromUnidirectionalEdge,

lib/h3/hierarchy.rb

@@ -39,6 +39,21 @@ def h3_to_parent(h3_index, resolution)
     # @return [Integer] Maximum number of child hexagons possible at given resolution.
     attach_function :max_children, :maxH3ToChildrenSize, [:h3_index, Resolution], :int
 
+    # @!method center_child(h3_index, child_resolution)
+    #
+    # Returns the center child (finer) index contained by the given index
+    # at the given resolution.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    # @param [Integer] child_resoluton The desired resolution of the center child hexagon.
+    #
+    # @example Find center child hexagon.
+    #    H3.center_child(613196570357137407, 10)
+    #    622203769609814015
+    #
+    # @return [Integer] H3 index of center child hexagon.
+    attach_function :center_child, :h3ToCenterChild, [:h3_index, Resolution], :h3_index
+
     # @deprecated Please use {#max_children} instead.
     def max_h3_to_children_size(h3_index, resolution)
       max_children(h3_index, resolution)

lib/h3/miscellaneous.rb

@@ -113,6 +113,18 @@ def num_hexagons(resolution)
     # @return [Integer] The number of resolution 0 hexagons (base cells).
     attach_function :base_cell_count, :res0IndexCount, [], :int
 
+    # @!method pentagon_count
+    #
+    # Number of pentagon H3 indexes per resolution.
+    # This is always 12, but provided as a convenience.
+    #
+    # @example Return the number of pentagons
+    #    H3.pentagon_count
+    #    12
+    #
+    # @return [Integer] The number of pentagons per resolution.
+    attach_function :pentagon_count, :pentagonIndexCount, [], :int
+
     # @deprecated Please use {#base_cell_count} instead.
     def res_0_index_count
       base_cell_count
@@ -132,6 +144,19 @@ def base_cells
       out.read
     end
 
+    # Returns all pentagon indexes at the given resolution.
+    #
+    # @example Return all pentagons at resolution 4.
+    #   H3.pentagons(4)
+    #   [594615896891195391, 594967740612083711, ..., 598591730937233407]
+    #
+    # @return [Array<Integer>] All pentagon indexes at the given resolution.
+    def pentagons(resolution)
+      out = H3Indexes.of_size(pentagon_count)
+      Bindings::Private.get_pentagon_indexes(resolution, out)
+      out.read
+    end
+
     # @deprecated Please use {#base_cells} instead.
     def res_0_indexes
       base_cells

lib/h3/version.rb

@@ -1,3 +1,3 @@
 module H3
-  VERSION = "3.5.1".freeze
+  VERSION = "3.6.0".freeze
 end

spec/hierarchy_spec.rb

@@ -172,4 +172,14 @@
       end
     end
   end
+
+  describe ".center_child" do
+    let(:h3_index) { "8828308299fffff".to_i(16) }
+    let(:resolution) { 10 }
+    let(:result) { "8a2830829807fff".to_i(16) }
+
+    subject(:center_child) { H3.center_child(h3_index, resolution) }
+
+    it { is_expected.to eq result }
+  end
 end

spec/miscellaneous_spec.rb

@@ -81,4 +81,32 @@
       expect(base_cells.count).to eq(count)
     end
   end
+
+  describe ".pentagon_count" do
+    let(:count) { 12 }
+    subject(:pentagon_count) { H3.pentagon_count }
+
+    it "has 12 pentagons per resolution" do
+      expect(pentagon_count).to eq(count)
+    end
+  end
+
+  describe ".pentagons" do
+    let(:resolution) { 4 }
+    let(:expected) do
+      [
+        594615896891195391, 594967740612083711,
+        595319584332972031, 595812165542215679,
+        596199193635192831, 596515852983992319,
+        596691774844436479, 597008434193235967,
+        597395462286213119, 597888043495456767,
+        598239887216345087, 598591730937233407
+      ]
+    end
+    subject(:pentagons) { H3.pentagons(resolution) }
+
+    it "returns pentagons at the given resolution" do
+      expect(pentagons).to eq(expected)
+    end
+  end
 end