h3 3.5.0 → 3.7.1

data/h3.gemspec

@@ -14,6 +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"
 
   spec.add_development_dependency "coveralls", "~> 0.8"
   spec.add_development_dependency "rake", "~> 12.3"

data/lib/h3.rb

@@ -1,15 +1,8 @@
 require "ffi"
 require "rgeo/geo_json"
+require "zeitwerk"
 
-require "h3/bindings"
-require "h3/geo_json"
-require "h3/hierarchy"
-require "h3/indexing"
-require "h3/inspection"
-require "h3/miscellaneous"
-require "h3/regions"
-require "h3/traversal"
-require "h3/unidirectional_edges"
+Zeitwerk::Loader.for_gem.setup
 
 # The main H3 namespace.
 #
@@ -17,7 +10,7 @@ require "h3/unidirectional_edges"
 #
 # @see https://uber.github.io/h3/#/documentation/overview/introduction
 module H3
-  extend GeoJSON
+  extend GeoJson
   extend Hierarchy
   extend Miscellaneous
   extend Indexing
@@ -26,17 +19,9 @@ module H3
   extend Traversal
   extend UnidirectionalEdges
 
-  PREDICATES = %i[h3_indexes_neighbors h3_pentagon h3_res_class_3
-                  h3_unidirectional_edge_valid h3_valid].freeze
-  private_constant :PREDICATES
-
-  class << self
-    # FFI's attach_function doesn't allow method names ending with a
-    # question mark. This works around the issue by dynamically
-    # renaming those methods afterwards.
-    PREDICATES.each do |predicate|
-      alias_method "#{predicate}?", predicate
-      undef_method predicate
-    end
-  end
+  # Internal bindings related modules and classes.
+  #
+  # These are intended to be used by the library's public methods
+  # and not to be used directly by client code.
+  module Bindings; end
 end

data/lib/h3/bindings/base.rb

@@ -7,15 +7,26 @@ module H3
       def self.extended(base)
         lib_path = File.expand_path(__dir__ + "/../../../ext/h3/src/lib")
         base.extend FFI::Library
+        base.extend Gem::Deprecate
         base.include Structs
         base.include Types
         base.ffi_lib ["#{lib_path}/libh3.dylib", "#{lib_path}/libh3.so"]
         base.typedef :ulong_long, :h3_index
-        base.typedef :int, :size
         base.typedef :int, :k_distance
-        base.typedef :pointer, :h3_set
-        base.typedef :pointer, :output_buffer
-        base.const_set("H3_INDEX", :ulong_long)
+      end
+
+      def attach_predicate_function(name, *args)
+        stripped_name = name.to_s.gsub("?", "")
+        attach_function(stripped_name, *args).tap do
+          rename_function stripped_name, name
+        end
+      end
+
+      private
+
+      def rename_function(from, to)
+        alias_method to, from
+        undef_method from
       end
     end
   end

data/lib/h3/bindings/private.rb

@@ -7,10 +7,11 @@ module H3
     module Private
       extend H3::Bindings::Base
 
-      attach_function :compact, [H3IndexesIn, H3IndexesOut, :size], :bool
+      attach_function :compact, [H3IndexesIn, H3IndexesOut, :size_t], :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 :get_pentagon_indexes, :getPentagonIndexes, [:int, H3IndexesOut], :void
+      attach_function :h3_faces, :h3GetFaces, %i[h3_index buffer_out], :void
       attach_function :h3_indexes_from_unidirectional_edge,
                       :getH3IndexesFromUnidirectionalEdge,
                       [:h3_index, H3IndexesOut], :void
@@ -20,11 +21,11 @@ module H3
                       [:h3_index, H3IndexesOut], :void
       attach_function :h3_set_to_linked_geo,
                       :h3SetToLinkedGeo,
-                      [H3IndexesIn, :size, LinkedGeoPolygon],
+                      [H3IndexesIn, :size_t, LinkedGeoPolygon],
                       :void
       attach_function :h3_to_children, :h3ToChildren, [:h3_index, Resolution, H3IndexesOut], :void
       attach_function :h3_to_geo, :h3ToGeo, [:h3_index, GeoCoord], :void
-      attach_function :h3_to_string, :h3ToString, %i[h3_index output_buffer size], :void
+      attach_function :h3_to_string, :h3ToString, %i[h3_index buffer_out size_t], :void
       attach_function :h3_to_geo_boundary,
                       :h3ToGeoBoundary,
                       [:h3_index, GeoBoundary],
@@ -35,25 +36,28 @@ module H3
       attach_function :hex_range, :hexRange, [:h3_index, :k_distance, H3IndexesOut], :bool
       attach_function :hex_range_distances,
                       :hexRangeDistances,
-                      [:h3_index, :k_distance, H3IndexesOut, :output_buffer], :bool
+                      [:h3_index, :k_distance, H3IndexesOut, :buffer_out], :bool
       attach_function :hex_ranges,
                       :hexRanges,
-                      [H3IndexesIn, :size, :k_distance, H3IndexesOut],
+                      [H3IndexesIn, :size_t, :k_distance, H3IndexesOut],
                       :bool
       attach_function :hex_ring, :hexRing, [:h3_index, :k_distance, H3IndexesOut], :bool
       attach_function :k_ring, :kRing, [:h3_index, :k_distance, H3IndexesOut], :void
       attach_function :k_ring_distances,
                       :kRingDistances,
-                      [:h3_index, :k_distance, H3IndexesOut, :output_buffer],
+                      [:h3_index, :k_distance, H3IndexesOut, :buffer_out],
                       :bool
       attach_function :max_polyfill_size,
                       :maxPolyfillSize,
                       [GeoPolygon, Resolution],
                       :int
-      attach_function :max_uncompact_size, :maxUncompactSize, [H3IndexesIn, :size, Resolution], :int
+      attach_function :max_uncompact_size, :maxUncompactSize, [H3IndexesIn, :size_t, Resolution], :int
+      attach_function :point_distance_rads, :pointDistRads, [GeoCoord, GeoCoord], :double
+      attach_function :point_distance_km, :pointDistKm, [GeoCoord, GeoCoord], :double
+      attach_function :point_distance_m, :pointDistM, [GeoCoord, GeoCoord], :double
       attach_function :polyfill, [GeoPolygon, Resolution, H3IndexesOut], :void
       attach_function :res_0_indexes, :getRes0Indexes, [H3IndexesOut], :void
-      attach_function :uncompact, [H3IndexesIn, :size, H3IndexesOut, :size, Resolution], :bool
+      attach_function :uncompact, [H3IndexesIn, :size_t, H3IndexesOut, :size_t, Resolution], :bool
     end
   end
 end

data/lib/h3/geo_json.rb

@@ -27,7 +27,7 @@ module H3
   #
   # @see http://geojson.io geojson.io - A tool to see GeoJSON data rendered on a world map.
   # @see https://tools.ietf.org/html/rfc7946 The GeoJSON RFC standard.
-  module GeoJSON
+  module GeoJson
     # Convert a GeoJSON document to a nested array of coordinates.
     #
     # @param [String] input The GeoJSON document. This can be a feature collection, feature,

data/lib/h3/hierarchy.rb

@@ -5,7 +5,7 @@ module H3
   module Hierarchy
     extend H3::Bindings::Base
 
-    # @!method h3_to_parent(h3_index, parent_resolution)
+    # @!method parent(h3_index, parent_resolution)
     #
     # Derive the parent hexagon which contains the hexagon at the given H3 index.
     #
@@ -13,13 +13,13 @@ module H3
     # @param [Integer] parent_resoluton The desired resolution of the parent hexagon.
     #
     # @example Find the parent hexagon for a H3 index.
-    #   H3.h3_to_parent(613196570357137407, 6)
+    #   H3.parent(613196570357137407, 6)
     #   604189371209351167
     #
     # @return [Integer] H3 index of parent hexagon.
-    attach_function :h3_to_parent, :h3ToParent, [:h3_index, Resolution], :h3_index
+    attach_function :parent, :h3ToParent, [:h3_index, Resolution], :h3_index
 
-    # @!method max_h3_to_children_size(h3_index, child_resolution)
+    # @!method max_children(h3_index, child_resolution)
     #
     # Derive maximum number of child hexagons possible at given resolution.
     #
@@ -27,11 +27,26 @@ module H3
     # @param [Integer] child_resoluton The desired resolution of the child hexagons.
     #
     # @example Derive maximum number of child hexagons.
-    #    H3.max_h3_to_children_size(613196570357137407, 10)
+    #    H3.max_children(613196570357137407, 10)
     #    49
     #
     # @return [Integer] Maximum number of child hexagons possible at given resolution.
-    attach_function :max_h3_to_children_size, :maxH3ToChildrenSize, [:h3_index, Resolution], :int
+    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
 
     # Derive child hexagons contained within the hexagon at the given H3 index.
     #
@@ -39,15 +54,15 @@ module H3
     # @param [Integer] child_resolution The desired resolution of hexagons returned.
     #
     # @example Find the child hexagons for a H3 index.
-    #   H3.h3_to_children(613196570357137407, 9)
+    #   H3.children(613196570357137407, 9)
     #   [
     #     617700169982672895, 617700169982935039, 617700169983197183, 617700169983459327,
     #     617700169983721471, 617700169983983615, 617700169984245759
     #   ]
     #
     # @return [Array<Integer>] H3 indexes of child hexagons.
-    def h3_to_children(h3_index, child_resolution)
-      max_children = max_h3_to_children_size(h3_index, child_resolution)
+    def children(h3_index, child_resolution)
+      max_children = max_children(h3_index, child_resolution)
       out = H3Indexes.of_size(max_children)
       Bindings::Private.h3_to_children(h3_index, child_resolution, out)
       out.read

data/lib/h3/indexing.rb

@@ -7,20 +7,20 @@ module H3
   #
   # @see https://uber.github.io/h3/#/documentation/api-reference/indexing
   module Indexing
-    include Bindings::Structs
+    extend H3::Bindings::Base
     # Derive H3 index for the given set of coordinates.
     #
     # @param [Array<Integer>] coords A coordinate pair.
     # @param [Integer] resolution The desired resolution of the H3 index.
     #
     # @example Derive the H3 index for the given coordinates.
-    #   H3.geo_to_h3([52.24630137198303, -1.7358398437499998], 9)
+    #   H3.from_geo_coordinates([52.24630137198303, -1.7358398437499998], 9)
     #   617439284584775679
     #
     # @raise [ArgumentError] If coordinates are invalid.
     #
     # @return [Integer] H3 index.
-    def geo_to_h3(coords, resolution)
+    def from_geo_coordinates(coords, resolution)
       raise ArgumentError unless coords.is_a?(Array) && coords.count == 2
 
       lat, lon = coords
@@ -42,11 +42,11 @@ module H3
     # @param [Integer] h3_index A valid H3 index.
     #
     # @example Derive the central coordinates for the given H3 index.
-    #   H3.h3_to_geo(617439284584775679)
+    #   H3.to_geo_coordinates(617439284584775679)
     #   [52.245519061399506, -1.7363137757391423]
     #
     # @return [Array<Integer>] A coordinate pair.
-    def h3_to_geo(h3_index)
+    def to_geo_coordinates(h3_index)
       coords = GeoCoord.new
       Bindings::Private.h3_to_geo(h3_index, coords)
       [rads_to_degs(coords[:lat]), rads_to_degs(coords[:lon])]
@@ -62,7 +62,7 @@ module H3
     # @param [Integer] h3_index A valid H3 index.
     #
     # @example Derive the geographical boundary for the given H3 index.
-    #   H3.h3_to_geo_boundary(617439284584775679)
+    #   H3.to_boundary(617439284584775679)
     #   [
     #     [52.247260929171055, -1.736809158397472], [52.24625850761068, -1.7389279144996015],
     #     [52.244516619273476, -1.7384324668792375], [52.243777169245725, -1.7358184256304658],
@@ -70,7 +70,7 @@ module H3
     #   ]
     #
     # @return [Array<Array<Integer>>] An array of six coordinate pairs.
-    def h3_to_geo_boundary(h3_index)
+    def to_boundary(h3_index)
       geo_boundary = GeoBoundary.new
       Bindings::Private.h3_to_geo_boundary(h3_index, geo_boundary)
       geo_boundary[:verts].take(geo_boundary[:num_verts]).map do |d|

data/lib/h3/inspection.rb

@@ -8,59 +8,59 @@ module H3
     H3_TO_STR_BUF_SIZE = 17
     private_constant :H3_TO_STR_BUF_SIZE
 
-    # @!method h3_resolution(h3_index)
+    # @!method resolution(h3_index)
     #
     # Derive the resolution of a given H3 index
     #
     # @param [Integer] h3_index A valid H3 index
     #
     # @example Derive the resolution of a H3 index
-    #   H3.h3_resolution(617700440100569087)
+    #   H3.resolution(617700440100569087)
     #   9
     #
     # @return [Integer] Resolution of H3 index
-    attach_function :h3_resolution, :h3GetResolution, %i[h3_index], Resolution
+    attach_function :resolution, :h3GetResolution, %i[h3_index], Resolution
 
-    # @!method h3_base_cell(h3_index)
+    # @!method base_cell(h3_index)
     #
     # Derives the base cell number of the given H3 index
     #
     # @param [Integer] h3_index A valid H3 index
     #
     # @example Derive the base cell number of a H3 index
-    #   H3.h3_base_cell(617700440100569087)
+    #   H3.base_cell(617700440100569087)
     #   20
     #
     # @return [Integer] Base cell number
-    attach_function :h3_base_cell, :h3GetBaseCell, %i[h3_index], :int
+    attach_function :base_cell, :h3GetBaseCell, %i[h3_index], :int
 
-    # @!method string_to_h3(h3_string)
+    # @!method from_string(h3_string)
     #
     # Derives the H3 index for a given hexadecimal string representation.
     #
     # @param [String] h3_string A H3 index in hexadecimal form.
     #
     # @example Derive the H3 index from the given hexadecimal form.
-    #   H3.string_to_h3("8928308280fffff")
+    #   H3.from_string("8928308280fffff")
     #   617700169958293503
     #
     # @return [Integer] H3 index
-    attach_function :string_to_h3, :stringToH3, %i[string], :h3_index
+    attach_function :from_string, :stringToH3, %i[string], :h3_index
 
-    # @!method h3_pentagon?(h3_index)
+    # @!method pentagon?(h3_index)
     #
     # Determine whether the given H3 index is a pentagon.
     #
     # @param [Integer] h3_index A valid H3 index.
     #
     # @example Check if H3 index is a pentagon
-    #   H3.h3_pentagon?(585961082523222015)
+    #   H3.pentagon?(585961082523222015)
     #   true
     #
     # @return [Boolean] True if the H3 index is a pentagon.
-    attach_function :h3_pentagon, :h3IsPentagon, %i[h3_index], :bool
+    attach_predicate_function :pentagon?, :h3IsPentagon, %i[h3_index], :bool
 
-    # @!method h3_res_class_3?(h3_index)
+    # @!method class_3_resolution?(h3_index)
     #
     # Determine whether the given H3 index has a resolution with
     # Class III orientation.
@@ -68,35 +68,35 @@ module H3
     # @param [Integer] h3_index A valid H3 index.
     #
     # @example Check if H3 index has a class III resolution.
-    #   H3.h3_res_class_3?(599686042433355775)
+    #   H3.class_3_resolution?(599686042433355775)
     #   true
     #
     # @return [Boolean] True if the H3 index has a class III resolution.
-    attach_function :h3_res_class_3, :h3IsResClassIII, %i[h3_index], :bool
+    attach_predicate_function :class_3_resolution?, :h3IsResClassIII, %i[h3_index], :bool
 
-    # @!method h3_valid?(h3_index)
+    # @!method valid?(h3_index)
     #
     # Determine whether the given H3 index is valid.
     #
     # @param [Integer] h3_index A H3 index.
     #
     # @example Check if H3 index is valid
-    #   H3.h3_valid?(599686042433355775)
+    #   H3.valid?(599686042433355775)
     #   true
     #
     # @return [Boolean] True if the H3 index is valid.
-    attach_function :h3_valid, :h3IsValid, %i[h3_index], :bool
+    attach_predicate_function :valid?, :h3IsValid, %i[h3_index], :bool
 
     # Derives the hexadecimal string representation for a given H3 index.
     #
     # @param [Integer] h3_index A valid H3 index.
     #
     # @example Derive the given hexadecimal form for the H3 index
-    #   H3.h3_to_string(617700169958293503)
+    #   H3.to_string(617700169958293503)
     #   "89283470dcbffff"
     #
     # @return [String] H3 index in hexadecimal form.
-    def h3_to_string(h3_index)
+    def to_string(h3_index)
       h3_str = FFI::MemoryPointer.new(:char, H3_TO_STR_BUF_SIZE)
       Bindings::Private.h3_to_string(h3_index, h3_str, H3_TO_STR_BUF_SIZE)
       h3_str.read_string
@@ -115,20 +115,16 @@ module H3
     # @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)
+    #   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)
+    def faces(h3_index)
       max_faces = max_face_count(h3_index)
       out = FFI::MemoryPointer.new(:int, max_faces)
       Bindings::Private.h3_faces(h3_index, out)

data/lib/h3/miscellaneous.rb

@@ -70,18 +70,18 @@ module H3
     # @return [Float] Average hexagon area in square metres.
     attach_function :hex_area_m2, :hexAreaM2, [Resolution], :double
 
-    # @!method num_hexagons(resolution)
+    # @!method hexagon_count(resolution)
     #
     # Number of unique H3 indexes at the given resolution.
     #
     # @param [Integer] resolution Resolution.
     #
     # @example Find number of hexagons at resolution 6
-    #   H3.num_hexagons(6)
+    #   H3.hexagon_count(6)
     #   14117882
     #
     # @return [Integer] Number of unique hexagons
-    attach_function :num_hexagons, :numHexagons, [Resolution], :ulong_long
+    attach_function :hexagon_count, :numHexagons, [Resolution], :ulong_long
 
     # @!method rads_to_degs(rads)
     #
@@ -96,28 +96,176 @@ module H3
     # @return [Float] Value expressed in degrees.
     attach_function :rads_to_degs, :radsToDegs, %i[double], :double
 
-    # @!method res_0_index_count
+    # @!method base_cell_count
     #
     # Returns the number of resolution 0 hexagons (base cells).
     #
     # @example Return the number of base cells
-    #    H3.res_0_index_count
+    #    H3.base_cell_count
     #    122
     #
     # @return [Integer] The number of resolution 0 hexagons (base cells).
-    attach_function :res_0_index_count, :res0IndexCount, [], :int
+    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
+
+    # @!method cell_area_rads2
+    #
+    # Area of a given cell expressed in radians squared
+    #
+    # @example Return the area of the cell
+    #    H3.cell_area_rads2(617700169958293503)
+    #    2.6952182709835757e-09
+    #
+    # @return [Double] Area of cell in rads2
+    attach_function :cell_area_rads2, :cellAreaRads2, %i[h3_index], :double
+
+    # @!method cell_area_km2
+    #
+    # Area of a given cell expressed in km squared
+    #
+    # @example Return the area of the cell
+    #    H3.cell_area_km2(617700169958293503)
+    #    0.10939818864648902
+    #
+    # @return [Double] Area of cell in km2
+    attach_function :cell_area_km2, :cellAreaKm2, %i[h3_index], :double
+
+    # @!method cell_area_m2
+    #
+    # Area of a given cell expressed in metres squared
+    #
+    # @example Return the area of the cell
+    #    H3.cell_area_m2(617700169958293503)
+    #    109398.18864648901
+    #
+    # @return [Double] Area of cell in metres squared
+    attach_function :cell_area_m2, :cellAreaM2, %i[h3_index], :double
+
+    # @!method exact_edge_length_rads
+    #
+    # Exact length of edge in rads
+    #
+    # @example Return the edge length
+    #    H3.exact_edge_length_rads(1266218516299644927)
+    #    3.287684056071637e-05
+    #
+    # @return [Double] Edge length in rads
+    attach_function :exact_edge_length_rads, :exactEdgeLengthRads, %i[h3_index], :double
+
+    # @!method exact_edge_length_km
+    #
+    # Exact length of edge in kilometres
+    #
+    # @example Return the edge length
+    #    H3.exact_edge_length_km(1266218516299644927)
+    #    3.287684056071637e-05
+    #
+    # @return [Double] Edge length in kilometres
+    attach_function :exact_edge_length_km, :exactEdgeLengthKm, %i[h3_index], :double
+
+    # @!method exact_edge_length_m
+    #
+    # Exact length of edge in metres
+    #
+    # @example Return the edge length
+    #    H3.exact_edge_length_m(1266218516299644927)
+    #    3.287684056071637e-05
+    #
+    # @return [Double] Edge length in metres
+    attach_function :exact_edge_length_m, :exactEdgeLengthM, %i[h3_index], :double
+
+    # Returns the radians distance between two points.
+    #
+    # @example Return radians distance.
+    #   H3.point_distance_rads([41.3964809, 2.160444], [41.3870609, 2.164917])
+    #   0.00017453024784008713
+    #
+    # @return [Double] Radians distance between two points.
+    def point_distance_rads(origin, destination)
+      Bindings::Private.point_distance_rads(*build_geocoords(origin, destination))
+    end
+
+    # Returns the kilometres distance between two points.
+    #
+    # @example Return km distance.
+    #   H3.point_distance_km([41.3964809, 2.160444], [41.3870609, 2.164917])
+    #   1.1119334622766763
+    #
+    # @return [Double] KM distance between two points.
+    def point_distance_km(origin, destination)
+      Bindings::Private.point_distance_km(*build_geocoords(origin, destination))
+    end
+
+    # Returns the metre distance between two points.
+    #
+    # @example Return metre distance.
+    #   H3.point_distance_m([41.3964809, 2.160444], [41.3870609, 2.164917])
+    #   1111.9334622766764
+    #
+    # @return [Double] Metre distance between two points.
+    def point_distance_m(origin, destination)
+      Bindings::Private.point_distance_m(*build_geocoords(origin, destination))
+    end
 
     # Returns all resolution 0 hexagons (base cells).
     #
     # @example Return all base cells.
-    #   H3.res_0_indexes
+    #   H3.base_cells
     #   [576495936675512319, 576531121047601151, ..., 580753245698260991]
     #
     # @return [Array<Integer>] All resolution 0 hexagons (base cells).
-    def res_0_indexes
-      out = H3Indexes.of_size(res_0_index_count)
+    def base_cells
+      out = H3Indexes.of_size(base_cell_count)
       Bindings::Private.res_0_indexes(out)
       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
+
+    private
+
+    def build_geocoords(origin, destination)
+      [origin, destination].inject([]) do |acc, coords|
+        validate_coordinate(coords)
+
+        geo_coord = GeoCoord.new
+        lat, lon = coords
+        geo_coord[:lat] = degs_to_rads(lat)
+        geo_coord[:lon] = degs_to_rads(lon)
+        acc << geo_coord
+      end
+    end
+
+    def validate_coordinate(coords)
+      raise ArgumentError unless coords.is_a?(Array) && coords.count == 2
+
+      lat, lon = coords
+
+      if lat > 90 || lat < -90 || lon > 180 || lon < -180
+        raise(ArgumentError, "Invalid coordinates")
+      end
+    end
   end
 end