h3 3.5.0 → 3.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95994576b5df069470128bda24d6768b3c8d5fe9ee61ebf0b5f4f16126f64208
-  data.tar.gz: a439783870113f4101d00a3fb94c8f4fec978ddabc55410531aa3e0f3c787fdd
+  metadata.gz: fcd6c37e501f228912e6a851ff799d38cefd458b424e9c19ed5fc8a635feda9f
+  data.tar.gz: 9e969c1a07735bed4b498ecdb066f9dde27b5f1d27843f2c48636a8ee6f6fb46
 SHA512:
-  metadata.gz: 6315cd5682f58cf7384b67fbf8dd4cba4eaa59ccbede04386a94d526b26d593dd0a92df2c4446dc5ff3a662622acbede640d63bae7345c64be0225b92c81d244
-  data.tar.gz: 9b543348c2c66cc8a441ba42e27503d8ace2b83b6714b577e5531a1cb29cb28810a5e816b90adda4a344a2082ed6e4623a25f10b7126a648498fe200787b930e
+  metadata.gz: 33281c3298ba50a851674f6f1523a55c5683bddcfe32772cd7d95a6bf529db6690d20f47c1e9f9b4ff473f5f42283801b403b2620c14241a4e5d005b248dae86
+  data.tar.gz: cb3677482d3cd5f6cfb0bc63f2d9ebe7bc1c0a9409a354f6917f21fed6044e6b42e2ee2694208873fccef7be498d4034d992bc38d5a339f2691c5af99273f763

data/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.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).
+- Added Zeitwerk as the code loader.
+
 ## [3.5.0] - 2019-7-25
 ### Added
 - `h3_faces` and `max_face_count` support (#56)

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    h3 (3.5.0)
+    h3 (3.5.1)
       ffi (~> 1.9)
       rgeo-geojson (~> 2.1)
+      zeitwerk (~> 2.1.9)
 
 GEM
   remote: https://rubygems.org/
@@ -16,10 +17,10 @@ GEM
       tins (~> 1.6)
     diff-lcs (1.3)
     docile (1.3.1)
-    ffi (1.10.0)
+    ffi (1.11.1)
     json (2.1.0)
     rake (12.3.2)
-    rgeo (2.0.0)
+    rgeo (2.0.1)
     rgeo-geojson (2.1.1)
       rgeo (>= 1.0.0)
     rspec (3.8.0)
@@ -44,7 +45,8 @@ GEM
       tins (~> 1.0)
     thor (0.19.4)
     tins (1.20.2)
-    yard (0.9.16)
+    yard (0.9.20)
+    zeitwerk (2.1.9)
 
 PLATFORMS
   ruby

data/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]]
 ```
 

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.9"
 
   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,6 +7,7 @@ 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"]

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,19 @@ 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)
+    # @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.
     #
@@ -27,11 +33,17 @@ 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
+
+    # @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.
     #
@@ -39,20 +51,26 @@ 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
     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

@@ -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,6 +35,12 @@ 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.
@@ -42,16 +48,22 @@ 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])]
     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,7 +74,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,12 +82,18 @@ 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|
         [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

@@ -8,59 +8,85 @@ 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)
+    # @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
     #
     # @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
+
+    # @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 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
+
+    # @deprecated Please use {#from_string} instead.
+    def string_to_h3(string)
+      from_string(string)
+    end
+    deprecate :string_to_h3, :from_string, 2020, 1
 
-    # @!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_function :pentagon, :h3IsPentagon, %i[h3_index], :bool
+    alias_method :pentagon?, :pentagon
+    undef_method :pentagon
 
-    # @!method h3_res_class_3?(h3_index)
+    # @deprecated Please use {#pentagon?} instead.
+    def h3_pentagon?(h3_index)
+      pentagon?(h3_index)
+    end
+    deprecate :h3_pentagon?, :pentagon?, 2020, 1
+
+    # @!method class_3_resolution?(h3_index)
     #
     # Determine whether the given H3 index has a resolution with
     # Class III orientation.
@@ -68,40 +94,62 @@ 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_function :class_3_resolution, :h3IsResClassIII, %i[h3_index], :bool
+    alias_method :class_3_resolution?, :class_3_resolution
+    undef_method :class_3_resolution
 
-    # @!method h3_valid?(h3_index)
+    # @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
+
+    # @!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_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
 
     # 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
     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.
@@ -115,25 +163,29 @@ 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)
+    # @!method 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)
       # 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