Update bindings for H3 v4.0.0

- Update function names to match H3 v4 API
- Implement error handling for all functions to use new error code system
- Fix edge functions to use directed edge nomenclature
- Fix memory handling for C parameters
- Re-enable commented functions with proper v4 equivalents

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: seanhandley

lib/h3/bindings/private.rb

@@ -15,63 +15,54 @@ def self.safe_call(out_type, method, *in_args)
         out.send("read_#{out_type}".to_sym)
       end
 
+      # Hierarchy functions
       attach_function :cellToParent, [:h3_index, Resolution, H3Index], :h3_error_code
       attach_function :compactCells, [H3IndexesIn, H3IndexesOut, :int64], :h3_error_code
-      # attach_function :destroy_linked_polygon, :destroyLinkedPolygon, [LinkedGeoPolygon], :void
-      attach_function :edge_length_km, :getHexagonEdgeLengthAvgKm, [Resolution, :pointer], :h3_error_code
+      attach_function :h3_to_children, :cellToChildren, [:h3_index, Resolution, H3IndexesOut], :h3_error_code
+      attach_function :max_children, :cellToChildrenSize, [:h3_index, Resolution, :pointer], :h3_error_code
+      attach_function :max_uncompact_size, :uncompactCellsSize, [H3IndexesIn, :int64, Resolution, :pointer], :h3_error_code
+      attach_function :uncompactCells, [H3IndexesIn, :size_t, H3IndexesOut, :size_t, Resolution], :h3_error_code
+
+      # Indexing functions
       attach_function :from_string, :stringToH3, %i[string pointer], :h3_error_code
       attach_function :geo_to_h3, :latLngToCell, [LatLng, Resolution, :pointer], :h3_error_code
-      # attach_function :get_pentagon_indexes, :getPentagonIndexes, [:int, H3IndexesOut], :void
-      attach_function :hexagon_count, :getNumCells, [Resolution, :pointer], :h3_error_code
-      attach_function :h3_faces, :getIcosahedronFaces, %i[h3_index buffer_out], :h3_error_code
-      # attach_function :h3_indexes_from_unidirectional_edge,
-      #                 :getH3IndexesFromUnidirectionalEdge,
-      #                 [:h3_index, H3IndexesOut], :void
-      # attach_function :h3_line, :h3Line, [:h3_index, :h3_index, H3IndexesOut], :int
-      # attach_function :h3_unidirectional_edges_from_hexagon,
-      #                 :getH3UnidirectionalEdgesFromHexagon,
-      #                 [:h3_index, H3IndexesOut], :void
-      # attach_function :h3_set_to_linked_geo,
-      #                 :h3SetToLinkedGeo,
-      #                 [H3IndexesIn, :size_t, LinkedGeoPolygon],
-      #                 :void
-      attach_function :h3_to_children, :cellToChildren, [:h3_index, Resolution, H3IndexesOut], :h3_error_code
       attach_function :h3_to_geo, :cellToLatLng, [:h3_index, LatLng], :h3_error_code
       attach_function :h3_to_string, :h3ToString, %i[h3_index buffer_out size_t], :h3_error_code
-      attach_function :h3_to_geo_boundary,
-                      :cellToBoundary,
-                      [:h3_index, CellBoundary],
-                      :h3_error_code
-      # attach_function :h3_unidirectional_edge_boundary,
-      #                 :getH3UnidirectionalEdgeBoundary,
-      #                 [:h3_index, CellBoundary], :void
-      # attach_function :hex_range, :hexRange, [:h3_index, :k_distance, H3IndexesOut], :bool
-      # attach_function :hex_range_distances,
-      #                 :hexRangeDistances,
-      #                 [:h3_index, :k_distance, H3IndexesOut, :buffer_out], :bool
-      # attach_function :hex_ranges,
-      #                 :hexRanges,
-      #                 [H3IndexesIn, :size_t, :k_distance, H3IndexesOut],
-      #                 :bool
-      # attach_function :hex_ring, :hexRing, [:h3_index, :k_distance, H3IndexesOut], :bool
+      attach_function :h3_to_geo_boundary, :cellToBoundary, [:h3_index, CellBoundary], :h3_error_code
+
+      # Traversal functions
       attach_function :k_ring, :gridDisk, [:h3_index, :k_distance, H3IndexesOut], :h3_error_code
-      # attach_function :k_ring_distances,
-      #                 :kRingDistances,
-      #                 [:h3_index, :k_distance, H3IndexesOut, :buffer_out],
-      #                 :bool
-      attach_function :max_children, :cellToChildrenSize, [:h3_index, Resolution, :pointer], :h3_error_code
+      attach_function :k_ring_distances, :gridDiskDistances, [:h3_index, :k_distance, H3IndexesOut, :pointer], :h3_error_code
+      attach_function :hex_range, :gridDiskUnsafe, [:h3_index, :k_distance, H3IndexesOut], :h3_error_code
+      attach_function :hex_range_distances, :gridDiskDistancesUnsafe, [:h3_index, :k_distance, H3IndexesOut, :pointer], :h3_error_code
+      attach_function :hex_ranges, :gridDisksUnsafe, [H3IndexesIn, :size_t, :k_distance, H3IndexesOut], :h3_error_code
+      attach_function :hex_ring, :gridRingUnsafe, [:h3_index, :k_distance, H3IndexesOut], :h3_error_code
+      attach_function :h3_line, :gridPathCells, [:h3_index, :h3_index, H3IndexesOut], :h3_error_code
+
+      # Directed edge functions (formerly unidirectional_edge)
+      attach_function :h3_indexes_from_unidirectional_edge, :directedEdgeToCells, [:h3_index, H3IndexesOut], :h3_error_code
+      attach_function :h3_unidirectional_edges_from_hexagon, :originToDirectedEdges, [:h3_index, H3IndexesOut], :h3_error_code
+      attach_function :h3_unidirectional_edge_boundary, :directedEdgeToBoundary, [:h3_index, CellBoundary], :h3_error_code
+
+      # Miscellaneous functions
+      attach_function :hexagon_count, :getNumCells, [Resolution, :pointer], :h3_error_code
+      attach_function :edge_length_km, :getHexagonEdgeLengthAvgKm, [Resolution, :pointer], :h3_error_code
+      attach_function :edge_length_m, :getHexagonEdgeLengthAvgM, [Resolution, :pointer], :h3_error_code
+      attach_function :h3_faces, :getIcosahedronFaces, %i[h3_index buffer_out], :h3_error_code
       attach_function :max_face_count, :maxFaceCount, %i[h3_index pointer], :h3_error_code
-      # attach_function :max_polyfill_size,
-      #                 :maxPolyfillSize,
-      #                 [GeoPolygon, Resolution],
-      #                 :int
-      attach_function :max_uncompact_size, :uncompactCellsSize, [H3IndexesIn, :int64, Resolution, :pointer], :h3_error_code
-      # 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 :get_pentagon_indexes, :getPentagonCells, [:int, H3IndexesOut], :h3_error_code
       attach_function :res_0_indexes, :getRes0Cells, [H3IndexesOut], :h3_error_code
-      attach_function :uncompactCells, [H3IndexesIn, :size_t, H3IndexesOut, :size_t, Resolution], :h3_error_code
+
+      # Distance functions
+      attach_function :point_distance_rads, :greatCircleDistanceRads, [LatLng, LatLng], :double
+      attach_function :point_distance_km, :greatCircleDistanceKm, [LatLng, LatLng], :double
+      attach_function :point_distance_m, :greatCircleDistanceM, [LatLng, LatLng], :double
+
+      # Region functions
+      attach_function :destroy_linked_polygon, :destroyLinkedMultiPolygon, [LinkedGeoPolygon], :void
+      attach_function :h3_set_to_linked_geo, :cellsToLinkedMultiPolygon, [H3IndexesIn, :size_t, LinkedGeoPolygon], :h3_error_code
+      attach_function :max_polyfill_size, :maxPolygonToCellsSize, [GeoPolygon, Resolution, :pointer], :h3_error_code
+      attach_function :polyfill, :polygonToCells, [GeoPolygon, Resolution, H3IndexesOut], :h3_error_code
     end
   end
 end

lib/h3/inspection.rb

@@ -103,7 +103,9 @@ def from_string(str)
     # @return [String] H3 index in hexadecimal form.
     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)
+      Bindings::Private.h3_to_string(h3_index, h3_str, H3_TO_STR_BUF_SIZE).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
       h3_str.read_string
     end
 

lib/h3/miscellaneous.rb

@@ -44,7 +44,9 @@ def edge_length_km(resolution)
     #   3229.482772
     #
     # @return [Float] Length of edge in metres
-    # attach_function :edge_length_m, :distanceM, [Resolution], :double
+    def edge_length_m(resolution)
+      Bindings::Private.safe_call(:double, :edge_length_m, resolution)
+    end
 
     # @!method hex_area_km2(resolution)
     #
@@ -169,7 +171,7 @@ def hexagon_count(resolution)
     #    3.287684056071637e-05
     #
     # @return [Double] Edge length in rads
-    # attach_function :exact_edge_length_rads, :exactEdgeLengthRads, %i[h3_index], :double
+    attach_function :exact_edge_length_rads, :getDirectedEdgeLengthRads, %i[h3_index], :double
 
     # @!method exact_edge_length_km
     #
@@ -180,7 +182,7 @@ def hexagon_count(resolution)
     #    3.287684056071637e-05
     #
     # @return [Double] Edge length in kilometres
-    # attach_function :exact_edge_length_km, :exactEdgeLengthKm, %i[h3_index], :double
+    attach_function :exact_edge_length_km, :getDirectedEdgeLengthKm, %i[h3_index], :double
 
     # @!method exact_edge_length_m
     #
@@ -191,7 +193,7 @@ def hexagon_count(resolution)
     #    3.287684056071637e-05
     #
     # @return [Double] Edge length in metres
-    # attach_function :exact_edge_length_m, :exactEdgeLengthM, %i[h3_index], :double
+    attach_function :exact_edge_length_m, :getDirectedEdgeLengthM, %i[h3_index], :double
 
     # Returns the radians distance between two points.
     #
@@ -235,7 +237,9 @@ def point_distance_m(origin, destination)
     # @return [Array<Integer>] All resolution 0 hexagons (base cells).
     def base_cells
       out = H3Indexes.of_size(base_cell_count)
-      Bindings::Private.res_0_indexes(out)
+      Bindings::Private.res_0_indexes(out).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
       out.read
     end
 
@@ -248,7 +252,9 @@ def base_cells
     # @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)
+      Bindings::Private.get_pentagon_indexes(resolution, out).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
       out.read
     end
 

lib/h3/traversal.rb

@@ -10,13 +10,24 @@ module Traversal
     # Derive the maximum k-ring size for distance k.
     #
     # @param [Integer] k K value.
+    # @param [FFI::MemoryPointer] out Optional memory pointer for storing result (for internal use).
     #
     # @example Derive the maximum k-ring size for k=5
     #   H3.max_kring_size(5)
     #   91
     #
-    # @return [Integer] Maximum k-ring size.
-    attach_function :max_kring_size, :maxGridDiskSize, %i[k_distance pointer], :h3_error_code
+    # @return [Integer] Maximum k-ring size if out is nil, otherwise returns error code.
+    def max_kring_size(k, out = nil)
+      if out
+        return Bindings::Private.max_kring_size(k, out)
+      else
+        out_ptr = FFI::MemoryPointer.new(:int64)
+        Bindings::Private.max_kring_size(k, out_ptr).tap do |code|
+          Bindings::Error::raise_error(code) unless code.zero?
+        end
+        out_ptr.read_int64
+      end
+    end
 
     # @!method distance(origin, h3_index)
     #
@@ -80,10 +91,17 @@ module Traversal
     #
     # @return [Array<Integer>] Array of H3 indexes within the k-range.
     def hex_range(origin, k)
-      max_hexagons = max_kring_size(k)
-      out = H3Indexes.of_size(max_hexagons)
-      pentagonal_distortion = Bindings::Private.hex_range(origin, k, out)
-      raise(ArgumentError, "Specified hexagon range contains a pentagon") if pentagonal_distortion
+      max_size = FFI::MemoryPointer.new(:int64)
+      max_kring_size(k, max_size).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
+      
+      out = H3Indexes.of_size(max_size.read_int64)
+      Bindings::Private.hex_range(origin, k, out).tap do |code|
+        # The 'pentagon distortion' error in H3 v4 is error code 9
+        raise(ArgumentError, "Specified hexagon range contains a pentagon") if code == 9
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
       out.read
     end
 
@@ -141,8 +159,13 @@ def k_ring(origin, k)
     def hex_ring(origin, k)
       max_hexagons = max_hex_ring_size(k)
       out = H3Indexes.of_size(max_hexagons)
-      pentagonal_distortion = Bindings::Private.hex_ring(origin, k, out)
-      raise(ArgumentError, "The hex ring contains a pentagon") if pentagonal_distortion
+      
+      Bindings::Private.hex_ring(origin, k, out).tap do |code|
+        # The 'pentagon distortion' error in H3 v4 is error code 9
+        raise(ArgumentError, "The hex ring contains a pentagon") if code == 9
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
+      
       out.read
     end
 
@@ -236,11 +259,20 @@ def hex_ranges(h3_set, k, grouped: true)
     #
     # @return [Hash] Hex range grouped by distance.
     def hex_range_distances(origin, k)
-      max_out_size = max_kring_size(k)
+      max_size = FFI::MemoryPointer.new(:int64)
+      max_kring_size(k, max_size).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
+      
+      max_out_size = max_size.read_int64
       out = H3Indexes.of_size(max_out_size)
       distances = FFI::MemoryPointer.new(:int, max_out_size)
-      pentagonal_distortion = Bindings::Private.hex_range_distances(origin, k, out, distances)
-      raise(ArgumentError, "Specified hexagon range contains a pentagon") if pentagonal_distortion
+      
+      Bindings::Private.hex_range_distances(origin, k, out, distances).tap do |code|
+        # The 'pentagon distortion' error in H3 v4 is error code 9
+        raise(ArgumentError, "Specified hexagon range contains a pentagon") if code == 9
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
 
       hexagons = out.read
       distances = distances.read_array_of_int(max_out_size)
@@ -273,10 +305,18 @@ def hex_range_distances(origin, k)
     #
     # @return [Hash] Hash of k-ring distances grouped by distance.
     def k_ring_distances(origin, k)
-      max_out_size = max_kring_size(k)
+      max_size = FFI::MemoryPointer.new(:int64)
+      max_kring_size(k, max_size).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
+      
+      max_out_size = max_size.read_int64
       out = H3Indexes.of_size(max_out_size)
       distances = FFI::MemoryPointer.new(:int, max_out_size)
-      Bindings::Private.k_ring_distances(origin, k, out, distances)
+      
+      Bindings::Private.k_ring_distances(origin, k, out, distances).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
 
       hexagons = out.read
       distances = distances.read_array_of_int(max_out_size)
@@ -305,8 +345,12 @@ def k_ring_distances(origin, k)
     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?
+      
+      Bindings::Private.h3_line(origin, destination, hexagons).tap do |code|
+        # In H3 v4, this could be various error codes
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
+      
       hexagons.read
     end
 
@@ -322,10 +366,20 @@ def k_rings_for_hex_range(indexes, k)
 
     def hex_ranges_ungrouped(h3_set, k)
       h3_set = H3Indexes.with_contents(h3_set)
-      max_out_size = h3_set.size * max_kring_size(k)
+      
+      # Calculate max output size
+      max_out_per_cell = FFI::MemoryPointer.new(:int64)
+      Bindings::Private.max_kring_size(k, max_out_per_cell).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
+      max_out_size = h3_set.size * max_out_per_cell.read_int64
+      
       out = H3Indexes.of_size(max_out_size)
-      if Bindings::Private.hex_ranges(h3_set, h3_set.size, k, out)
-        raise(ArgumentError, "One of the specified hexagon ranges contains a pentagon")
+      
+      Bindings::Private.hex_ranges(h3_set, h3_set.size, k, out).tap do |code|
+        # The 'pentagon distortion' error in H3 v4 is error code 9
+        raise(ArgumentError, "One of the specified hexagon ranges contains a pentagon") if code == 9
+        Bindings::Error::raise_error(code) unless code.zero?
       end
 
       out.read

lib/h3/unidirectional_edges.rb

@@ -100,7 +100,9 @@ module UnidirectionalEdges
     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)
+      Bindings::Private.h3_indexes_from_unidirectional_edge(edge, out).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
       out.read
     end
 
@@ -119,7 +121,9 @@ def origin_and_destination_from_unidirectional_edge(edge)
     def unidirectional_edges_from_hexagon(origin)
       max_edges = 6
       out = H3Indexes.of_size(max_edges)
-      Bindings::Private.h3_unidirectional_edges_from_hexagon(origin, out)
+      Bindings::Private.h3_unidirectional_edges_from_hexagon(origin, out).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
       out.read
     end
 
@@ -138,7 +142,9 @@ def unidirectional_edges_from_hexagon(origin)
     # @return [Array<Array<Float>>] Edge boundary coordinates for a hexagon
     def unidirectional_edge_boundary(edge)
       geo_boundary = CellBoundary.new
-      Bindings::Private.h3_unidirectional_edge_boundary(edge, geo_boundary)
+      Bindings::Private.h3_unidirectional_edge_boundary(edge, geo_boundary).tap do |code|
+        Bindings::Error::raise_error(code) unless code.zero?
+      end
       geo_boundary[:verts].take(geo_boundary[:num_verts]).map do |d|
         [rads_to_degs(d[:lat]), rads_to_degs(d[:lon])]
       end