Refactor shared binary heap internals into a utility module

Extract identical helper methods from BinaryHeapNode and BinaryMaxHeapNode into Tree::Utils::HeapSharedMethods to reduce duplication while preserving public behavior.

Author: evolve75

CHANGELOG.md

@@ -14,6 +14,9 @@ Changes section to scan for breaking or behavioral changes.
   `Tree::BinaryHeapNode#pop`, `Tree::BinaryMaxHeapNode#pop`,
   and `Tree::TrieNode#search`.
 * Add alias-focused regression tests to lock these compatibility contracts.
+* Refactor shared binary heap internals into
+  `Tree::Utils::HeapSharedMethods` to reduce duplication between min-heap and
+  max-heap implementations without changing public behavior.
 * Make `Tree::TrieNode#<<` use trie word-insert semantics (`insert(word)`)
   instead of generic child-node attachment semantics.
 * Add `<<` insertion shorthand to `Tree::AATree` and `Tree::BTree` for

lib/tree/binaryheap.rb

@@ -38,6 +38,7 @@
 # frozen_string_literal: true
 
 require_relative 'binarytree'
+require_relative 'utils/heap_shared_methods'
 
 module Tree
   # Provides a Binary Heap (min-heap) implementation. This node allows only two
@@ -56,6 +57,8 @@ module Tree
   # This inherits from the {Tree::BinaryTreeNode} class.
   #
   class BinaryHeapNode < BinaryTreeNode
+    include Tree::Utils::HeapSharedMethods
+
     # Inserts the specified node into the heap, based on the node content.
     #
     # @param [Tree::BinaryHeapNode, String, Symbol] node_or_name The node
@@ -222,24 +225,6 @@ def validate_key!(key)
       raise ArgumentError, 'Binary heap key (content) must not be nil.' if key.nil?
     end
 
-    # +true+ if the root represents an empty heap.
-    #
-    # @param [Tree::BinaryHeapNode] node The node to check.
-    # @return [Boolean] +true+ if empty.
-    def empty_root?(node)
-      node.root? && node.content.nil? && !node.children?
-    end
-
-    # Returns the heap size treating an empty root as size 0.
-    #
-    # @param [Tree::BinaryHeapNode] node The root node.
-    # @return [Integer] The heap size.
-    def heap_size(node)
-      return 0 if empty_root?(node)
-
-      node.size
-    end
-
     # Insert a node at the next available index to keep the heap complete.
     #
     # @param [Tree::BinaryHeapNode] tree_root The root node.
@@ -258,31 +243,6 @@ def insert_at_index(tree_root, node)
       end
     end
 
-    # Return the node at the given heap index.
-    #
-    # @param [Tree::BinaryHeapNode] tree_root The root node.
-    # @param [Integer] index The heap index (1-based).
-    # @return [Tree::BinaryHeapNode, nil] The node at the index.
-    def node_for_index(tree_root, index)
-      return tree_root if index == 1
-
-      current = tree_root
-      path_bits = index.to_s(2).chars.drop(1)
-      path_bits.each do |bit|
-        current = bit == '0' ? current.left_child : current.right_child
-        return nil unless current
-      end
-      current
-    end
-
-    # Return the last node in the heap (right-most node at the deepest level).
-    #
-    # @param [Tree::BinaryHeapNode] tree_root The root node.
-    # @return [Tree::BinaryHeapNode] The last node.
-    def last_node(tree_root)
-      node_for_index(tree_root, heap_size(tree_root))
-    end
-
     # Restore heap ordering by bubbling the node upward.
     #
     # @param [Tree::BinaryHeapNode] node The node to lift.
@@ -317,56 +277,6 @@ def heapify_down(node)
       end
     end
 
-    # Swap the content values of two nodes.
-    #
-    # @param [Tree::BinaryHeapNode] left The first node.
-    # @param [Tree::BinaryHeapNode] right The second node.
-    # @return [void]
-    def swap_contents(left, right)
-      left.content, right.content = right.content, left.content
-    end
-
-    # Remove the last node from the heap.
-    #
-    # @param [Tree::BinaryHeapNode] node The last node.
-    # @return [void]
-    def remove_last_node(node)
-      if node.root?
-        node.instance_variable_set(:@content, nil)
-        return
-      end
-
-      if node.left_child?
-        node.parent.left_child = nil
-      else
-        node.parent.right_child = nil
-      end
-    end
-
-    # Remove an arbitrary node from the heap.
-    #
-    # @param [Tree::BinaryHeapNode] node The node to remove.
-    # @return [void]
-    def remove_node(node)
-      tree_root = root
-      return if empty_root?(tree_root)
-
-      if heap_size(tree_root) == 1
-        tree_root.instance_variable_set(:@content, nil)
-        return
-      end
-
-      last = last_node(tree_root)
-      if node.equal?(last)
-        remove_last_node(last)
-        return
-      end
-
-      swap_contents(node, last)
-      remove_last_node(last)
-      rebalance_after_swap(node)
-    end
-
     # Rebalance heap ordering after swapping in a replacement node.
     #
     # @param [Tree::BinaryHeapNode] node The node to rebalance from.

lib/tree/binarymaxheap.rb

@@ -38,6 +38,7 @@
 # frozen_string_literal: true
 
 require_relative 'binarytree'
+require_relative 'utils/heap_shared_methods'
 
 module Tree
   # Provides a Binary Max-Heap implementation. This node allows only two child
@@ -56,6 +57,8 @@ module Tree
   # This inherits from the {Tree::BinaryTreeNode} class.
   #
   class BinaryMaxHeapNode < BinaryTreeNode
+    include Tree::Utils::HeapSharedMethods
+
     # Inserts the specified node into the heap, based on the node content.
     #
     # @param [Tree::BinaryMaxHeapNode, String, Symbol] node_or_name The node
@@ -224,24 +227,6 @@ def validate_key!(key)
       raise ArgumentError, 'Binary max-heap key (content) must not be nil.' if key.nil?
     end
 
-    # +true+ if the root represents an empty heap.
-    #
-    # @param [Tree::BinaryMaxHeapNode] node The node to check.
-    # @return [Boolean] +true+ if empty.
-    def empty_root?(node)
-      node.root? && node.content.nil? && !node.children?
-    end
-
-    # Returns the heap size treating an empty root as size 0.
-    #
-    # @param [Tree::BinaryMaxHeapNode] node The root node.
-    # @return [Integer] The heap size.
-    def heap_size(node)
-      return 0 if empty_root?(node)
-
-      node.size
-    end
-
     # Insert a node at the next available index to keep the heap complete.
     #
     # @param [Tree::BinaryMaxHeapNode] tree_root The root node.
@@ -260,31 +245,6 @@ def insert_at_index(tree_root, node)
       end
     end
 
-    # Return the node at the given heap index.
-    #
-    # @param [Tree::BinaryMaxHeapNode] tree_root The root node.
-    # @param [Integer] index The heap index (1-based).
-    # @return [Tree::BinaryMaxHeapNode, nil] The node at the index.
-    def node_for_index(tree_root, index)
-      return tree_root if index == 1
-
-      current = tree_root
-      path_bits = index.to_s(2).chars.drop(1)
-      path_bits.each do |bit|
-        current = bit == '0' ? current.left_child : current.right_child
-        return nil unless current
-      end
-      current
-    end
-
-    # Return the last node in the heap (right-most node at the deepest level).
-    #
-    # @param [Tree::BinaryMaxHeapNode] tree_root The root node.
-    # @return [Tree::BinaryMaxHeapNode] The last node.
-    def last_node(tree_root)
-      node_for_index(tree_root, heap_size(tree_root))
-    end
-
     # Restore heap ordering by bubbling the node upward.
     #
     # @param [Tree::BinaryMaxHeapNode] node The node to lift.
@@ -319,56 +279,6 @@ def heapify_down(node)
       end
     end
 
-    # Swap the content values of two nodes.
-    #
-    # @param [Tree::BinaryMaxHeapNode] left The first node.
-    # @param [Tree::BinaryMaxHeapNode] right The second node.
-    # @return [void]
-    def swap_contents(left, right)
-      left.content, right.content = right.content, left.content
-    end
-
-    # Remove the last node from the heap.
-    #
-    # @param [Tree::BinaryMaxHeapNode] node The last node.
-    # @return [void]
-    def remove_last_node(node)
-      if node.root?
-        node.instance_variable_set(:@content, nil)
-        return
-      end
-
-      if node.left_child?
-        node.parent.left_child = nil
-      else
-        node.parent.right_child = nil
-      end
-    end
-
-    # Remove an arbitrary node from the heap.
-    #
-    # @param [Tree::BinaryMaxHeapNode] node The node to remove.
-    # @return [void]
-    def remove_node(node)
-      tree_root = root
-      return if empty_root?(tree_root)
-
-      if heap_size(tree_root) == 1
-        tree_root.instance_variable_set(:@content, nil)
-        return
-      end
-
-      last = last_node(tree_root)
-      if node.equal?(last)
-        remove_last_node(last)
-        return
-      end
-
-      swap_contents(node, last)
-      remove_last_node(last)
-      rebalance_after_swap(node)
-    end
-
     # Rebalance heap ordering after swapping in a replacement node.
     #
     # @param [Tree::BinaryMaxHeapNode] node The node to rebalance from.