h3 3.5.0 → 3.5.1

data/lib/h3/miscellaneous.rb

@@ -70,18 +70,24 @@ 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
+
+    # @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)
     #
@@ -96,28 +102,40 @@ 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
+
+    # @deprecated Please use {#base_cell_count} instead.
+    def res_0_index_count
+      base_cell_count
+    end
+    deprecate :res_0_index_count, :base_cell_count, 2020, 1
 
     # 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
+
+    # @deprecated Please use {#base_cells} instead.
+    def res_0_indexes
+      base_cells
+    end
+    deprecate :res_0_indexes, :base_cells, 2020, 1
   end
 end

data/lib/h3/traversal.rb

@@ -18,7 +18,7 @@ module H3
     # @return [Integer] Maximum k-ring size.
     attach_function :max_kring_size, :maxKringSize, %i[k_distance], :int
 
-    # @!method h3_distance(origin, h3_index)
+    # @!method distance(origin, h3_index)
     #
     # Derive the distance between two H3 indexes.
     #
@@ -26,13 +26,19 @@ module H3
     # @param [Integer] h3_index H3 index
     #
     # @example Derive the distance between two H3 indexes.
-    #   H3.h3_distance(617700169983721471, 617700169959866367)
+    #   H3.distance(617700169983721471, 617700169959866367)
     #   5
     #
     # @return [Integer] Distance between indexes.
-    attach_function :h3_distance, :h3Distance, %i[h3_index h3_index], :k_distance
+    attach_function :distance, :h3Distance, %i[h3_index h3_index], :k_distance
 
-    # @!method h3_line_size(origin, destination)
+    # @deprecated Please use {#distance} instead.
+    def h3_distance(origin, destination)
+      distance(origin, destination)
+    end
+    deprecate :h3_distance, :distance, 2020, 1
+
+    # @!method line_size(origin, destination)
     #
     # Derive the number of hexagons present in a line between two H3 indexes.
     #
@@ -45,11 +51,17 @@ module H3
     # @param [Integer] destination H3 index
     #
     # @example Derive the number of hexagons present in a line between two H3 indexes.
-    #   H3.h3_line_size(617700169983721471, 617700169959866367)
+    #   H3.line_size(617700169983721471, 617700169959866367)
     #   6
     #
     # @return [Integer] Number of hexagons found between indexes.
-    attach_function :h3_line_size, :h3LineSize, %i[h3_index h3_index], :int
+    attach_function :line_size, :h3LineSize, %i[h3_index h3_index], :int
+
+    # @deprecated Please use {#line_size} instead.
+    def h3_line_size(origin, destination)
+      line_size(origin, destination)
+    end
+    deprecate :h3_line_size, :line_size, 2020, 1
 
     # Derives H3 indexes within k distance of the origin H3 index.
     #
@@ -288,7 +300,7 @@ module H3
     # @param [Integer] destination Destination H3 index.
     #
     # @example Derive the indexes found in a line.
-    #   H3.h3_line(617700169983721471, 617700169959866367)
+    #   H3.line(617700169983721471, 617700169959866367)
     #   [
     #     617700169983721471, 617700169984245759, 617700169988177919,
     #     617700169986867199, 617700169987391487, 617700169959866367
@@ -297,14 +309,20 @@ module H3
     # @raise [ArgumentError] Could not compute line
     #
     # @return [Array<Integer>] H3 indexes
-    def h3_line(origin, destination)
-      max_hexagons = h3_line_size(origin, destination)
+    def line(origin, destination)
+      max_hexagons = line_size(origin, destination)
       hexagons = H3Indexes.of_size(max_hexagons)
       res = Bindings::Private.h3_line(origin, destination, hexagons)
       raise(ArgumentError, "Could not compute line") if res.negative?
       hexagons.read
     end
 
+    # @deprecated Please use {#line} instead.
+    def h3_line(origin, destination)
+      line(origin, destination)
+    end
+    deprecate :h3_line, :line, 2020, 1
+
     private
 
     def k_rings_for_hex_range(indexes, k)

data/lib/h3/unidirectional_edges.rb

@@ -5,7 +5,7 @@ module H3
   module UnidirectionalEdges
     extend H3::Bindings::Base
 
-    # @!method h3_indexes_neighbors?(origin, destination)
+    # @!method neighbors?(origin, destination)
     #
     # Determine whether two H3 indexes are neighbors.
     #
@@ -13,29 +13,47 @@ module H3
     # @param [Integer] destination Destination H3 index
     #
     # @example Check two H3 indexes
-    #   H3.h3_indexes_neighbors?(617700169958293503, 617700169958031359)
+    #   H3.neighbors?(617700169958293503, 617700169958031359)
     #   true
     #
     # @return [Boolean] True if indexes are neighbors
-    attach_function :h3_indexes_neighbors, :h3IndexesAreNeighbors, %i[h3_index h3_index], :bool
+    attach_function :neighbors, :h3IndexesAreNeighbors, %i[h3_index h3_index], :bool
+    alias_method :neighbors?, :neighbors
+    undef_method :neighbors
 
-    # @!method h3_unidirectional_edge_valid?(h3_index)
+    # @deprecated Please use {#neighbors?} instead.
+    def h3_indexes_neighbors?(origin, destination)
+      neighbors?(origin, destination)
+    end
+
+    deprecate :h3_indexes_neighbors?, :neighbors?, 2020, 1
+
+    # @!method unidirectional_edge_valid?(h3_index)
     #
     # Determine whether the given H3 index represents an edge.
     #
     # @param [Integer] h3_index H3 index
     #
     # @example Check if H3 index is a valid unidirectional edge.
-    #   H3.h3_unidirectional_edge_valid?(1266218516299644927)
+    #   H3.unidirectional_edge_valid?(1266218516299644927)
     #   true
     #
     # @return [Boolean] True if H3 index is a valid unidirectional edge
-    attach_function :h3_unidirectional_edge_valid,
+    attach_function :unidirectional_edge_valid,
                     :h3UnidirectionalEdgeIsValid,
                     %i[h3_index],
                     :bool
+    alias_method :unidirectional_edge_valid?, :unidirectional_edge_valid
+    undef_method :unidirectional_edge_valid
+
+    # @deprecated Please use {#unidirectional_edge_valid?} instead.
+    def h3_unidirectional_edge_valid?(h3_index)
+      unidirectional_edge_valid?(h3_index)
+    end
+
+    deprecate :h3_unidirectional_edge_valid?, :unidirectional_edge_valid?, 2020, 1
 
-    # @!method h3_unidirectional_edge(origin, destination)
+    # @!method unidirectional_edge(origin, destination)
     #
     # Derives the H3 index of the edge from the given H3 indexes.
     #
@@ -43,15 +61,22 @@ module H3
     # @param [Integer] destination H3 index
     #
     # @example Derive the H3 edge index between two H3 indexes
-    #   H3.h3_unidirectional_edge(617700169958293503, 617700169958031359)
+    #   H3.unidirectional_edge(617700169958293503, 617700169958031359)
     #   1626506486489284607
     #
     # @return [Integer] H3 edge index
-    attach_function :h3_unidirectional_edge,
+    attach_function :unidirectional_edge,
                     :getH3UnidirectionalEdge,
                     %i[h3_index h3_index],
                     :h3_index
 
+    # @deprecated Please use {#unidirectional_edge} instead.
+    def h3_unidirectional_edge(origin, destination)
+      unidirectional_edge(origin, destination)
+    end
+
+    deprecate :h3_unidirectional_edge, :unidirectional_edge, 2020, 1
+
     # @!method destination_from_unidirectional_edge(edge)
     #
     # Derive destination H3 index from edge.
@@ -93,42 +118,62 @@ module H3
     # @param [Integer] edge H3 edge index
     #
     # @example Get origin and destination indexes from edge
-    #   H3.h3_indexes_from_unidirectional_edge(1266218516299644927)
+    #   H3.origin_and_destination_from_unidirectional_edge(1266218516299644927)
     #   [617700169958293503, 617700169961177087]
     #
     # @return [Array<Integer>] H3 index array.
-    def h3_indexes_from_unidirectional_edge(edge)
+    def origin_and_destination_from_unidirectional_edge(edge)
       max_hexagons = 2
       out = H3Indexes.of_size(max_hexagons)
       Bindings::Private.h3_indexes_from_unidirectional_edge(edge, out)
       out.read
     end
 
+    # @deprecated Please use {#origin_and_destination_from_unidirectional_edge} instead.
+    def h3_indexes_from_unidirectional_edge(edge)
+      origin_and_destination_from_unidirectional_edge(edge)
+    end
+
+    deprecate :h3_indexes_from_unidirectional_edge,
+              :origin_and_destination_from_unidirectional_edge,
+              2020,
+              1
+
     # Derive unidirectional edges for a H3 index.
     #
     # @param [Integer] origin H3 index
     #
     # @example Get unidirectional indexes from hexagon
-    #   H3.h3_unidirectional_edges_from_hexagon(612933930963697663)
+    #   H3.unidirectional_edges_from_hexagon(612933930963697663)
     #   [
     #     1261452277305049087, 1333509871342977023, 1405567465380904959,
     #     1477625059418832895, 1549682653456760831, 1621740247494688767
     #   ]
     #
     # @return [Array<Integer>] H3 index array.
-    def h3_unidirectional_edges_from_hexagon(origin)
+    def unidirectional_edges_from_hexagon(origin)
       max_edges = 6
       out = H3Indexes.of_size(max_edges)
       Bindings::Private.h3_unidirectional_edges_from_hexagon(origin, out)
       out.read
     end
 
+    # @deprecated Please use {#unidirectional_edges_from_hexagon} instead.
+    def h3_unidirectional_edges_from_hexagon(origin)
+      unidirectional_edges_from_hexagon(origin)
+    end
+
+    deprecate :h3_unidirectional_edges_from_hexagon,
+              :unidirectional_edges_from_hexagon,
+              2020,
+              1
+
     # Derive coordinates for edge boundary.
     #
     # @param [Integer] edge H3 edge index
     #
     # @example
-    #   H3.h3_unidirectional_edge_boundary(612933930963697663)
+    #   H3.unidirectional_edge_boundary(612933930963697663)
     #   [
     #     [68.92995788193981, 31.831280499087402], [69.39359648991828, 62.345344956509784],
     #     [76.163042830191, 94.14309010184775], [87.36469532319619, 145.5581976913368],
@@ -136,12 +181,22 @@ module H3
     #   ]
     #
     # @return [Array<Array<Float>>] Edge boundary coordinates for a hexagon
-    def h3_unidirectional_edge_boundary(edge)
+    def unidirectional_edge_boundary(edge)
       geo_boundary = GeoBoundary.new
       Bindings::Private.h3_unidirectional_edge_boundary(edge, geo_boundary)
       geo_boundary[:verts].take(geo_boundary[:num_verts]).map do |d|
         [rads_to_degs(d[:lat]), rads_to_degs(d[:lon])]
       end
     end
+
+    # @deprecated Please use {#unidirectional_edge_boundary} instead.
+    def h3_unidirectional_edge_boundary(edge)
+      unidirectional_edge_boundary(edge)
+    end
+
+    deprecate :h3_unidirectional_edge_boundary,
+              :unidirectional_edge_boundary,
+              2020,
+              1
   end
 end

data/lib/h3/version.rb

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

data/spec/hierarchy_spec.rb

@@ -1,27 +1,27 @@
 RSpec.describe H3 do
   include_context "constants"
 
-  describe ".h3_to_parent" do
+  describe ".parent" do
     let(:h3_index) { "89283082993ffff".to_i(16) }
     let(:parent_resolution) { 8 }
     let(:result) { "8828308299fffff".to_i(16) }
 
-    subject(:h3_to_parent) { H3.h3_to_parent(h3_index, parent_resolution) }
+    subject(:parent) { H3.parent(h3_index, parent_resolution) }
 
     it { is_expected.to eq(result) }
   end
 
-  describe ".h3_to_children" do
+  describe ".children" do
     let(:h3_index) { "8928308280fffff".to_i(16) }
 
-    subject(:h3_to_children) { H3.h3_to_children(h3_index, child_resolution) }
+    subject(:children) { H3.children(h3_index, child_resolution) }
 
     context "when resolution is 3" do
       let(:child_resolution) { 3 }
       let(:count) { 0 }
 
       it "has 0 children" do
-        expect(h3_to_children.count).to eq count
+        expect(children.count).to eq count
       end
     end
 
@@ -31,11 +31,11 @@ RSpec.describe H3 do
       let(:expected) { "8928308280fffff".to_i(16) }
 
       it "has 1 child" do
-        expect(h3_to_children.count).to eq count
+        expect(children.count).to eq count
       end
 
       it "is the expected value" do
-        expect(h3_to_children.first).to eq expected
+        expect(children.first).to eq expected
       end
     end
 
@@ -44,7 +44,7 @@ RSpec.describe H3 do
       let(:count) { 7 }
 
       it "has 7 children" do
-        expect(h3_to_children.count).to eq count
+        expect(children.count).to eq count
       end
     end
 
@@ -53,7 +53,7 @@ RSpec.describe H3 do
       let(:count) { 117649 }
 
       it "has 117649 children" do
-        expect(h3_to_children.count).to eq count
+        expect(children.count).to eq count
       end
     end
 
@@ -61,7 +61,7 @@ RSpec.describe H3 do
       let(:child_resolution) { -1 }
 
       it "raises an error" do
-        expect { h3_to_children }.to raise_error(ArgumentError)
+        expect { children }.to raise_error(ArgumentError)
       end
     end
 
@@ -69,15 +69,15 @@ RSpec.describe H3 do
       let(:child_resolution) { 16 }
 
       it "raises an error" do
-        expect { h3_to_children }.to raise_error(ArgumentError)
+        expect { children }.to raise_error(ArgumentError)
       end
     end
   end
 
-  describe ".max_h3_to_children_size" do
+  describe ".max_children" do
     let(:h3_index) { "8928308280fffff".to_i(16) }
 
-    subject(:h3_to_children) { H3.max_h3_to_children_size(h3_index, child_resolution) }
+    subject(:max_children) { H3.max_children(h3_index, child_resolution) }
 
     context "when resolution is 3" do
       let(:child_resolution) { 3 }

data/spec/indexing_spec.rb

@@ -1,12 +1,12 @@
 RSpec.describe H3 do
   include_context "constants"
 
-  describe ".geo_to_h3" do
+  describe ".from_geo_coordinates" do
     let(:resolution) { 8 }
     let(:coords) { [53.959130, -1.079230]}
     let(:result) { valid_h3_index }
 
-    subject(:geo_to_h3) { H3.geo_to_h3(coords, resolution) }
+    subject(:from_geo_coordinates) { H3.from_geo_coordinates(coords, resolution) }
 
     it { is_expected.to eq(result) }
 
@@ -14,7 +14,7 @@ RSpec.describe H3 do
       let(:coords) { [1, 2, 3] }
 
       it "raises an error" do
-        expect { geo_to_h3 }.to raise_error(ArgumentError)
+        expect { from_geo_coordinates }.to raise_error(ArgumentError)
       end
     end
 
@@ -22,7 +22,7 @@ RSpec.describe H3 do
       let(:coords) { "boom" }
 
       it "raises an error" do
-        expect { geo_to_h3 }.to raise_error(ArgumentError)
+        expect { from_geo_coordinates }.to raise_error(ArgumentError)
       end
     end
 
@@ -30,31 +30,31 @@ RSpec.describe H3 do
       let(:coords) { [-1.1323222, 190.1020102] }
 
       it "raises an error" do
-        expect { geo_to_h3 }.to raise_error(ArgumentError)
+        expect { from_geo_coordinates }.to raise_error(ArgumentError)
       end
     end    
   end
 
-  describe ".h3_to_geo" do
+  describe ".to_geo_coordinates" do
     let(:h3_index) { valid_h3_index }
     let(:expected_lat) { 53.95860421941 }
     let(:expected_lon) { -1.08119564709 }
 
-    subject(:h3_to_geo) { H3.h3_to_geo(h3_index) }
+    subject(:to_geo_coordinates) { H3.to_geo_coordinates(h3_index) }
 
     it "should return the expected latitude" do
-      expect(h3_to_geo[0]).to be_within(0.000001).of(expected_lat)
+      expect(to_geo_coordinates[0]).to be_within(0.000001).of(expected_lat)
     end
 
     it "should return the expected longitude" do
-      expect(h3_to_geo[1]).to be_within(0.000001).of(expected_lon)
+      expect(to_geo_coordinates[1]).to be_within(0.000001).of(expected_lon)
     end
 
     context "when given an invalid h3_index" do
       let(:h3_index) { "boom" }
 
       it "raises an error" do
-        expect { h3_to_geo }.to raise_error(TypeError)
+        expect { to_geo_coordinates }.to raise_error(TypeError)
       end
     end
 
@@ -62,12 +62,12 @@ RSpec.describe H3 do
       let(:h3_index) { too_long_number }
 
       it "raises an error" do
-        expect { h3_to_geo }.to raise_error(RangeError)
+        expect { to_geo_coordinates }.to raise_error(RangeError)
       end
     end
   end
 
-  describe ".h3_to_geo_boundary" do
+  describe ".to_boundary" do
     let(:h3_index) { "85283473fffffff".to_i(16) }
     let(:expected) do
       [
@@ -80,13 +80,13 @@ RSpec.describe H3 do
       ]
     end
 
-    subject(:h3_to_geo_boundary) { H3.h3_to_geo_boundary(h3_index) }
+    subject(:to_boundary) { H3.to_boundary(h3_index) }
 
     it "matches expected boundary coordinates" do
-      h3_to_geo_boundary.zip(expected) do |(lat, lon), (exp_lat, exp_lon)|
+      to_boundary.zip(expected) do |(lat, lon), (exp_lat, exp_lon)|
         expect(lat).to be_within(0.000001).of(exp_lat)
         expect(lon).to be_within(0.000001).of(exp_lon)
       end
     end
   end
-end
+end