Deprecate longwinded method names (#59)

* Rename methods.

* Fix deprecation warnings in specs.

Author: seanhandley

README.md

@@ -11,15 +11,15 @@ Please consult [the H3 documentation](https://uber.github.io/h3/#/documentation/
 
 ## Supported H3 Versions
 
-The semantic versioning of this gem matches the versioning of the H3 C library. E.g. version `3.2.x` of this gem is targeted for version `3.2.y` of H3 C lib where `x` and `y` are independent patch levels.
+The semantic versioning of this gem matches the versioning of the H3 C library. E.g. version `3.5.x` of this gem is targeted for version `3.5.y` of H3 C lib where `x` and `y` are independent patch levels.
 
 ## Naming Conventions
 
 We have changed camel-case method names to snake-case, as per the Ruby convention.
 
-In addition, some methods using the `get` verb have been renamed i.e. `getH3UnidirectionalEdgesFromHexagon` becomes `h3_unidirectional_edges_from_hexagon`.
+In addition, some methods using the `get` verb have been renamed i.e. `getH3UnidirectionalEdgesFromHexagon` becomes `unidirectional_edges_from_hexagon`.
 
-We have also suffixed predicate methods with a question mark, as per the Ruby convention, and removed `is` from the name i.e. `h3IsPentagon` becomes `h3_pentagon?`
+We have also suffixed predicate methods with a question mark, as per the Ruby convention, and removed `h3Is` from the name i.e. `h3IsPentagon` becomes `pentagon?`
 
 ## Getting Started
 
@@ -53,13 +53,13 @@ require "h3"
 Call H3 functions via the `H3` namespace
 
 ```ruby
-H3.geo_to_h3([53.959130, -1.079230], 8).to_s(16)
+H3.from_geo_coordinates([53.959130, -1.079230], 8).to_s(16)
 => "8819429a9dfffff"
-H3.h3_valid?("8819429a9dfffff".to_i(16))
+H3.valid?("8819429a9dfffff".to_i(16))
 => true
-H3.h3_pentagon?("8819429a9dfffff".to_i(16))
+H3.pentagon?("8819429a9dfffff".to_i(16))
 => false
-H3.h3_to_geo_boundary("8819429a9dfffff".to_i(16))
+H3.to_boundary("8819429a9dfffff".to_i(16))
 => [[53.962987505331384, -1.079984346847996], [53.9618315234061, -1.0870313428985856], [53.95744798515881, -1.0882421079017874], [53.95422067486053, -1.082406760751464], [53.955376670617454, -1.0753609232787642], [53.95975996282198, -1.074149274503605]]
 ```
 

lib/h3.rb

@@ -19,20 +19,6 @@ 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

lib/h3/bindings/base.rb

@@ -7,6 +7,7 @@ module Base
       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"]

lib/h3/hierarchy.rb

@@ -5,54 +5,72 @@ 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.
     #
     # @param [Integer] h3_index A valid H3 index.
     # @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)
+    # @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.
     #
     # @param [Integer] h3_index A valid H3 index.
     # @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
+
+    # @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.
     # @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
     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.

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
@@ -35,23 +35,35 @@ def geo_to_h3(coords, resolution)
       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.
     #
     # @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])]
     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
@@ -62,20 +74,26 @@ def h3_to_geo(h3_index)
     # @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],
     #     [52.24477956752282, -1.7336997597088104], [52.246521439109415, -1.7341950448552204]
     #   ]
     #
     # @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|
         [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