h3 3.6.0 → 3.7.2

data/h3.gemspec

@@ -9,14 +9,14 @@ Gem::Specification.new do |spec|
   spec.authors  = ["Lachlan Laycock", "Sean Handley"]
   spec.email    = "l.laycock@stuart.com"
 
-  spec.required_ruby_version = "> 2.3"
+  spec.required_ruby_version = ">= 2.5"
   spec.files = `git ls-files --recurse-submodules`.split("\n")
 
   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 "coveralls", "~> 0.8"
   spec.add_development_dependency "rake", "~> 12.3"
   spec.add_development_dependency "rspec", "~> 3.8"
   spec.add_development_dependency "yard", "~> 0.9"

data/lib/h3/bindings/base.rb

@@ -12,11 +12,21 @@ module H3
         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,11 +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 :get_pentagon_indexes, :getPentagonIndexes, [:int, H3IndexesOut], :void
-      attach_function :h3_faces, :h3GetFaces, %i[h3_index output_buffer], :void
+      attach_function :h3_faces, :h3GetFaces, %i[h3_index buffer_out], :void
       attach_function :h3_indexes_from_unidirectional_edge,
                       :getH3IndexesFromUnidirectionalEdge,
                       [:h3_index, H3IndexesOut], :void
@@ -21,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],
@@ -36,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/hierarchy.rb

@@ -19,12 +19,6 @@ module H3
     # @return [Integer] H3 index of parent hexagon.
     attach_function :parent, :h3ToParent, [:h3_index, Resolution], :h3_index
 
-    # @deprecated Please use {#parent} instead.
-    def h3_to_parent(h3_index, resolution)
-      parent(h3_index, resolution)
-    end
-    deprecate :h3_to_parent, :parent, 2020, 1
-
     # @!method max_children(h3_index, child_resolution)
     #
     # Derive maximum number of child hexagons possible at given resolution.
@@ -54,12 +48,6 @@ module H3
     # @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)
-    end
-    deprecate :max_h3_to_children_size, :max_children, 2020, 1
-
     # Derive child hexagons contained within the hexagon at the given H3 index.
     #
     # @param [Integer] h3_index A valid H3 index.
@@ -80,12 +68,6 @@ module H3
       out.read
     end
 
-    # @deprecated Please use {#children} instead.
-    def h3_to_children(h3_index, resolution)
-      children(h3_index, resolution)
-    end
-    deprecate :h3_to_children, :children, 2020, 1
-
     # Find the maximum uncompacted size of the given set of H3 indexes.
     #
     # @param [Array<Integer>] compacted_set An array of valid H3 indexes.

data/lib/h3/indexing.rb

@@ -35,12 +35,6 @@ module H3
       Bindings::Private.geo_to_h3(coords, resolution)
     end
 
-    # @deprecated Please use {#from_geo_coordinates} instead.
-    def geo_to_h3(coords, resolution)
-      from_geo_coordinates(coords, resolution)
-    end
-    deprecate :geo_to_h3, :from_geo_coordinates, 2020, 1
-
     # Derive coordinates for a given H3 index.
     #
     # The coordinates map to the centre of the hexagon at the given index.
@@ -58,12 +52,6 @@ module H3
       [rads_to_degs(coords[:lat]), rads_to_degs(coords[:lon])]
     end
 
-    # @deprecated Please use {#to_geo_coordinates} instead.
-    def h3_to_geo(h3_index)
-      to_geo_coordinates(h3_index)
-    end
-    deprecate :h3_to_geo, :to_geo_coordinates, 2020, 1
-
     # Derive the geographical boundary as coordinates for a given H3 index.
     #
     # This will be a set of 6 coordinate pairs matching the vertexes of the
@@ -89,11 +77,5 @@ module H3
         [rads_to_degs(d[:lat]), rads_to_degs(d[:lon])]
       end
     end
-
-    # @deprecated Please use {#to_boundary} instead.
-    def h3_to_geo_boundary(h3_index)
-      to_boundary(h3_index)
-    end
-    deprecate :h3_to_geo_boundary, :to_boundary, 2020, 1
   end
 end

data/lib/h3/inspection.rb

@@ -21,12 +21,6 @@ module H3
     # @return [Integer] Resolution of H3 index
     attach_function :resolution, :h3GetResolution, %i[h3_index], Resolution
 
-    # @deprecated Please use {#resolution} instead.
-    def h3_resolution(h3_index)
-      resolution(h3_index)
-    end
-    deprecate :h3_resolution, :resolution, 2020, 1
-
     # @!method base_cell(h3_index)
     #
     # Derives the base cell number of the given H3 index
@@ -40,12 +34,6 @@ module H3
     # @return [Integer] Base cell number
     attach_function :base_cell, :h3GetBaseCell, %i[h3_index], :int
 
-    # @deprecated Please use {#base_cell} instead.
-    def h3_base_cell(h3_index)
-      base_cell(h3_index)
-    end
-    deprecate :h3_base_cell, :base_cell, 2020, 1
-
     # @!method from_string(h3_string)
     #
     # Derives the H3 index for a given hexadecimal string representation.
@@ -59,12 +47,6 @@ module H3
     # @return [Integer] H3 index
     attach_function :from_string, :stringToH3, %i[string], :h3_index
 
-    # @deprecated Please use {#from_string} instead.
-    def string_to_h3(string)
-      from_string(string)
-    end
-    deprecate :string_to_h3, :from_string, 2020, 1
-
     # @!method pentagon?(h3_index)
     #
     # Determine whether the given H3 index is a pentagon.
@@ -76,15 +58,7 @@ module H3
     #   true
     #
     # @return [Boolean] True if the H3 index is a pentagon.
-    attach_function :pentagon, :h3IsPentagon, %i[h3_index], :bool
-    alias_method :pentagon?, :pentagon
-    undef_method :pentagon
-
-    # @deprecated Please use {#pentagon?} instead.
-    def h3_pentagon?(h3_index)
-      pentagon?(h3_index)
-    end
-    deprecate :h3_pentagon?, :pentagon?, 2020, 1
+    attach_predicate_function :pentagon?, :h3IsPentagon, %i[h3_index], :bool
 
     # @!method class_3_resolution?(h3_index)
     #
@@ -98,15 +72,7 @@ module H3
     #   true
     #
     # @return [Boolean] True if the H3 index has a class III resolution.
-    attach_function :class_3_resolution, :h3IsResClassIII, %i[h3_index], :bool
-    alias_method :class_3_resolution?, :class_3_resolution
-    undef_method :class_3_resolution
-
-    # @deprecated Please use {#class_3_resolution?} instead.
-    def h3_res_class_3?(h3_index)
-      class_3_resolution?(h3_index)
-    end
-    deprecate :h3_res_class_3?, :class_3_resolution?, 2020, 1
+    attach_predicate_function :class_3_resolution?, :h3IsResClassIII, %i[h3_index], :bool
 
     # @!method valid?(h3_index)
     #
@@ -119,15 +85,7 @@ module H3
     #   true
     #
     # @return [Boolean] True if the H3 index is valid.
-    attach_function :valid, :h3IsValid, %i[h3_index], :bool
-    alias_method :valid?, :valid
-    undef_method :valid
-
-    # @deprecated Please use {#valid?} instead.
-    def h3_valid?(h3_index)
-      valid?(h3_index)
-    end
-    deprecate :h3_valid?, :valid?, 2020, 1
+    attach_predicate_function :valid?, :h3IsValid, %i[h3_index], :bool
 
     # Derives the hexadecimal string representation for a given H3 index.
     #
@@ -144,12 +102,6 @@ module H3
       h3_str.read_string
     end
 
-    # @deprecated Please use {#to_string} instead.
-    def h3_to_string(h3_index)
-      to_string(h3_index)
-    end
-    deprecate :h3_to_string, :to_strings, 2020, 1
-
     # @!method max_face_count(h3_index)
     #
     # Returns the maximum number of icosahedron faces the given H3 index may intersect.
@@ -163,8 +115,6 @@ module H3
     # @return [Integer] Maximum possible number of faces
     attach_function :max_face_count, :maxFaceCount, %i[h3_index], :int
 
-    # @!method faces(h3_index)
-    #
     # Find all icosahedron faces intersected by a given H3 index.
     #
     # @param [Integer] h3_index A H3 index.
@@ -181,11 +131,5 @@ module H3
       # The C function returns a sparse array whose holes are represented by -1.
       out.read_array_of_int(max_faces).reject(&:negative?).sort
     end
-
-    # @deprecated Please use {#faces} instead.
-    def h3_faces(h3_index)
-      faces(h3_index)
-    end
-    deprecate :h3_faces, :faces, 2020, 1
   end
 end

data/lib/h3/miscellaneous.rb

@@ -83,12 +83,6 @@ module H3
     # @return [Integer] Number of unique hexagons
     attach_function :hexagon_count, :numHexagons, [Resolution], :ulong_long
 
-    # @deprecated Please use {#hexagon_count} instead.
-    def num_hexagons(resolution)
-      hexagon_count(resolution)
-    end
-    deprecate :num_hexagons, :hexagon_count, 2020, 1
-
     # @!method rads_to_degs(rads)
     #
     # Convert a number expressed in radians to its equivalent in degrees.
@@ -125,11 +119,104 @@ module H3
     # @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
+    # @!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
-    deprecate :res_0_index_count, :base_cell_count, 2020, 1
 
     # Returns all resolution 0 hexagons (base cells).
     #
@@ -157,10 +244,28 @@ module H3
       out.read
     end
 
-    # @deprecated Please use {#base_cells} instead.
-    def res_0_indexes
-      base_cells
+    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
-    deprecate :res_0_indexes, :base_cells, 2020, 1
   end
 end