rbtree-ruby 0.1.0 → 0.1.2

data/lib/rbtree.rb

@@ -0,0 +1,1260 @@
+# frozen_string_literal: true
+
+require_relative "rbtree/version"
+
+# A Red-Black Tree implementation providing efficient ordered key-value storage.
+#
+# RBTree is a self-balancing binary search tree that maintains sorted order of keys
+# and provides O(log n) time complexity for insertion, deletion, and lookup operations.
+# The tree enforces the following red-black properties to maintain balance:
+#
+# 1. Every node is either red or black
+# 2. The root is always black
+# 3. All leaves (nil nodes) are black
+# 4. Red nodes cannot have red children
+# 5. All paths from root to leaves contain the same number of black nodes
+#
+# == Features
+#
+# * Ordered iteration over key-value pairs
+# * Range queries (less than, greater than, between)
+# * Efficient min/max retrieval
+# * Nearest key search for numeric keys
+# * Tree integrity validation
+#
+# == Usage
+#
+#   # Create an empty tree
+#   tree = RBTree.new
+#
+#   # Create from a hash
+#   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+#
+#   # Create from an array of key-value pairs
+#   tree = RBTree.new([[3, 'three'], [1, 'one'], [2, 'two']])
+#
+#   # Create using bracket notation
+#   tree = RBTree[3 => 'three', 1 => 'one', 2 => 'two']
+#
+#   # Insert and retrieve values
+#   tree.insert(5, 'five')
+#   tree[4] = 'four'
+#   puts tree[4]  # => "four"
+#
+#   # Iterate in sorted order
+#   tree.each { |key, value| puts "#{key}: #{value}" }
+#
+# == Performance
+#
+# All major operations (insert, delete, search) run in O(log n) time.
+# Iteration over all elements takes O(n) time.
+#
+# @author Masahito Suzuki
+# @since 0.1.0
+class RBTree
+  include Enumerable
+
+  # Returns the number of key-value pairs stored in the tree.
+  # @return [Integer] the number of entries in the tree
+  attr_reader :size
+
+  # Creates a new RBTree from the given arguments.
+  #
+  # This is a convenience method equivalent to RBTree.new(*args).
+  #
+  # @param args [Hash, Array] optional initial data
+  # @return [RBTree] a new RBTree instance
+  # @example
+  #   tree = RBTree[1 => 'one', 2 => 'two', 3 => 'three']
+  def self.[](*args)
+    new(*args)
+  end
+
+  # Initializes a new RBTree.
+  #
+  # The tree can be initialized empty or populated with initial data from a Hash or Array.
+  #
+  # @param args [Hash, Array, nil] optional initial data
+  #   - If a Hash is provided, each key-value pair is inserted into the tree
+  #   - If an Array is provided, it should contain [key, value] pairs
+  #   - If no arguments are provided, an empty tree is created
+  # @raise [ArgumentError] if arguments are invalid
+  # @example Create an empty tree
+  #   tree = RBTree.new
+  # @example Create from a hash
+  #   tree = RBTree.new({1 => 'one', 2 => 'two'})
+  # @example Create from an array
+  #   tree = RBTree.new([[1, 'one'], [2, 'two']])
+  def initialize(*args)
+    @nil_node = Node.new
+    @nil_node.color = Node::BLACK
+    @nil_node.left = @nil_node
+    @nil_node.right = @nil_node
+    @root = @nil_node
+    @min_node = @nil_node
+    @size = 0
+
+    if args.any?
+      source = args.size == 1 ? args.first : args
+      case source
+      when Hash
+        source.each { |k, v| insert(k, v) }
+      when Array
+        source.each do |arg| 
+          key, value = arg
+          insert(key, value)
+        end
+      else
+        raise ArgumentError, "Invalid arguments"
+      end
+    end
+  end
+
+  # Returns a string representation of the tree.
+  #
+  # Shows the first 5 entries and total size. Useful for debugging.
+  #
+  # @return [String] a human-readable representation of the tree
+  def inspect
+    if @size > 0
+      content = first(5).map { |k, v| "#{k.inspect}=>#{v.inspect}" }.join(", ")
+      suffix = @size > 5 ? ", ..." : ""
+      "#<#{self.class}:0x#{object_id.to_s(16)} size=#{@size} {#{content}#{suffix}}>"
+    else
+      super
+    end
+  end
+
+  # Checks if the tree is empty.
+  #
+  # @return [Boolean] true if the tree contains no elements, false otherwise
+  def empty? = @root == @nil_node
+
+  # Checks if the tree contains the given key.
+  #
+  # @param key [Object] the key to search for
+  # @return [Boolean] true if the key exists in the tree, false otherwise
+  # @example
+  #   tree = RBTree.new({1 => 'one', 2 => 'two'})
+  #   tree.has_key?(1)  # => true
+  #   tree.has_key?(3)  # => false
+  def has_key?(key)
+    find_node(key) != @nil_node
+  end
+
+  # Retrieves the value associated with the given key.
+  #
+  # @param key [Object] the key to look up
+  # @return [Object, nil] the associated value, or nil if the key is not found
+  # @example
+  #   tree = RBTree.new({1 => 'one', 2 => 'two'})
+  #   tree.get(1)  # => "one"
+  #   tree[2]      # => "two"
+  #   tree[3]      # => nil
+  def get(key)
+    n = find_node(key)
+    n == @nil_node ? nil : n.value
+  end
+  alias_method :[], :get
+
+  # Inserts or updates a key-value pair in the tree.
+  #
+  # If the key already exists and overwrite is true (default), the value is updated.
+  # If overwrite is false and the key exists, the operation returns nil without modification.
+  #
+  # @param key [Object] the key to insert (must implement <=>)
+  # @param value [Object] the value to associate with the key
+  # @param overwrite [Boolean] whether to overwrite existing keys (default: true)
+  # @return [Boolean, nil] true if inserted/updated, nil if key exists and overwrite is false
+  # @example
+  #   tree = RBTree.new
+  #   tree.insert(1, 'one')        # => true
+  #   tree.insert(1, 'ONE')        # => true (overwrites)
+  #   tree.insert(1, 'uno', overwrite: false)  # => nil (no change)
+  #   tree[2] = 'two'              # using alias
+  def insert(key, value, overwrite: true)
+    y = @nil_node
+    x = @root
+    while x != @nil_node
+      y = x
+      cmp = key <=> x.key
+      if cmp == 0
+        return nil unless overwrite
+        x.value = value
+        return true
+      elsif cmp < 0
+        x = x.left
+      else
+        x = x.right
+      end
+    end
+    z = Node.new(key, value, Node::RED, @nil_node, @nil_node, @nil_node)
+    z.parent = y
+    if y == @nil_node
+      @root = z
+    elsif (key <=> y.key) < 0
+      y.left = z
+    else
+      y.right = z
+    end
+    z.left = @nil_node
+    z.right = @nil_node
+    z.color = Node::RED
+    insert_fixup(z)
+    @size += 1
+    
+    if @min_node == @nil_node || (key <=> @min_node.key) < 0
+      @min_node = z
+    end
+    
+    true
+  end
+  alias_method :[]=, :insert
+
+  # Deletes the key-value pair with the specified key.
+  #
+  # @param key [Object] the key to delete
+  # @return [Object, nil] the value associated with the deleted key, or nil if not found
+  # @example
+  #   tree = RBTree.new({1 => 'one', 2 => 'two'})
+  #   tree.delete(1)  # => "one"
+  #   tree.delete(3)  # => nil
+  def delete(key)
+    value = delete_node(key)
+    return nil unless value
+    @size -= 1
+    value
+  end
+
+  # Removes all key-value pairs from the tree.
+  #
+  # @return [RBTree] self
+  def clear
+    @root = @nil_node
+    @min_node = @nil_node
+    @size = 0
+    self
+  end
+
+  # Removes and returns the minimum key-value pair.
+  #
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  # @example
+  #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+  #   tree.shift  # => [1, "one"]
+  #   tree.shift  # => [2, "two"]
+  def shift
+    return nil if @min_node == @nil_node
+    result = [@min_node.key, @min_node.value]
+    delete(@min_node.key)
+    result
+  end
+
+  # Removes and returns the maximum key-value pair.
+  #
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  # @example
+  #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+  #   tree.pop  # => [3, "three"]
+  #   tree.pop  # => [2, "two"]
+  def pop
+    n = rightmost(@root)
+    return nil if n == @nil_node
+    result = [n.key, n.value]
+    delete(n.key)
+    result
+  end
+
+  # Iterates over all key-value pairs in ascending order of keys.
+  #
+  # @yield [key, value] each key-value pair in the tree
+  # @return [Enumerator, RBTree] an Enumerator if no block is given, self otherwise
+  # @example
+  #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+  #   tree.each { |k, v| puts "#{k}: #{v}" }
+  #   # Output:
+  #   # 1: one
+  #   # 2: two
+  #   # 3: three
+  def each(&block)
+    return enum_for(:each) unless block_given?
+    traverse_asc(@root, &block)
+  end
+
+  # Iterates over all key-value pairs in descending order of keys.
+  #
+  # @yield [key, value] each key-value pair in the tree
+  # @return [Enumerator, RBTree] an Enumerator if no block is given, self otherwise
+  # @example
+  #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+  #   tree.reverse_each { |k, v| puts "#{k}: #{v}" }
+  #   # Output:
+  #   # 3: three
+  #   # 2: two
+  #   # 1: one
+  def reverse_each(&block)
+    return enum_for(:reverse_each) unless block_given?
+    traverse_desc(@root, &block)
+  end
+
+  # Returns the minimum key-value pair without removing it.
+  #
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  # @example
+  #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+  #   tree.min  # => [1, "one"]
+  def min
+    @min_node == @nil_node ? nil : [@min_node.key, @min_node.value]
+  end
+
+  # Returns the maximum key-value pair without removing it.
+  #
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  # @example
+  #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+  #   tree.max  # => [3, "three"]
+  def max
+    n = rightmost(@root)
+    n == @nil_node ? nil : [n.key, n.value]
+  end
+
+  # Retrieves all key-value pairs with keys less than the specified key.
+  #
+  # @param key [Object] the upper bound (exclusive)
+  # @yield [key, value] each matching key-value pair (if block given)
+  # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
+  # @example
+  #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
+  #   tree.lt(3)  # => [[1, "one"], [2, "two"]]
+  #   tree.lt(3) { |k, v| puts "#{k}: #{v}" }  # prints pairs and returns tree
+  def lt(key, &block)
+    if block_given?
+      traverse_lt(@root, key, &block)
+      self
+    else
+      res = []
+      traverse_lt(@root, key) { |k, v| res << [k, v] }
+      res
+    end
+  end
+
+  # Retrieves all key-value pairs with keys less than or equal to the specified key.
+  #
+  # @param key [Object] the upper bound (inclusive)
+  # @yield [key, value] each matching key-value pair (if block given)
+  # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
+  # @example
+  #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
+  #   tree.lte(3)  # => [[1, "one"], [2, "two"], [3, "three"]]
+  def lte(key, &block)
+    if block_given?
+      traverse_lte(@root, key, &block)
+      self
+    else
+      res = []
+      traverse_lte(@root, key) { |k, v| res << [k, v] }
+      res
+    end
+  end
+
+  # Retrieves all key-value pairs with keys greater than the specified key.
+  #
+  # @param key [Object] the lower bound (exclusive)
+  # @yield [key, value] each matching key-value pair (if block given)
+  # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
+  # @example
+  #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
+  #   tree.gt(2)  # => [[3, "three"], [4, "four"]]
+  def gt(key, &block)
+    if block_given?
+      traverse_gt(@root, key, &block)
+      self
+    else
+      res = []
+      traverse_gt(@root, key) { |k, v| res << [k, v] }
+      res
+    end
+  end
+
+  # Retrieves all key-value pairs with keys greater than or equal to the specified key.
+  #
+  # @param key [Object] the lower bound (inclusive)
+  # @yield [key, value] each matching key-value pair (if block given)
+  # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
+  # @example
+  #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
+  #   tree.gte(2)  # => [[2, "two"], [3, "three"], [4, "four"]]
+  def gte(key, &block)
+    if block_given?
+      traverse_gte(@root, key, &block)
+      self
+    else
+      res = []
+      traverse_gte(@root, key) { |k, v| res << [k, v] }
+      res
+    end
+  end
+
+  # Retrieves all key-value pairs with keys within the specified range.
+  #
+  # @param min [Object] the lower bound
+  # @param max [Object] the upper bound
+  # @param include_min [Boolean] whether to include the lower bound (default: true)
+  # @param include_max [Boolean] whether to include the upper bound (default: true)
+  # @yield [key, value] each matching key-value pair (if block given)
+  # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
+  # @example
+  #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four', 5 => 'five'})
+  #   tree.between(2, 4)  # => [[2, "two"], [3, "three"], [4, "four"]]
+  #   tree.between(2, 4, include_min: false)  # => [[3, "three"], [4, "four"]]
+  #   tree.between(2, 4, include_max: false)  # => [[2, "two"], [3, "three"]]
+  def between(min, max, include_min: true, include_max: true, &block)
+    if block_given?
+      traverse_between(@root, min, max, include_min, include_max, &block)
+      self
+    else
+      res = []
+      traverse_between(@root, min, max, include_min, include_max) { |k, v| res << [k, v] }
+      res
+    end
+  end
+
+  # Returns the key-value pair with the key closest to the given key.
+  #
+  # This method requires keys to be numeric or support subtraction and abs methods.
+  # If multiple keys have the same distance, the one with the smaller key is returned.
+  #
+  # @param key [Numeric] the target key
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  # @example
+  #   tree = RBTree.new({1 => 'one', 5 => 'five', 10 => 'ten'})
+  #   tree.nearest(4)   # => [5, "five"]
+  #   tree.nearest(7)   # => [5, "five"]
+  #   tree.nearest(8)   # => [10, "ten"]
+  def nearest(key)
+    return nil unless key.respond_to?(:-)
+    n = find_nearest_node(key)
+    n == @nil_node ? nil : [n.key, n.value]
+  end
+
+  # Validates the red-black tree properties.
+  #
+  # Checks that:
+  # 1. Root is black
+  # 2. All paths from root to leaves have the same number of black nodes
+  # 3. No red node has a red child
+  # 4. Keys are properly ordered
+  #
+  # @return [Boolean] true if all properties are satisfied, false otherwise
+  def valid?
+    return false if @root.color == Node::RED
+    return false if check_black_height(@root) == -1
+    return false unless check_order(@root)
+    true
+  end
+
+  # @!visibility private
+  private
+
+  # Traverses the tree in ascending order (in-order traversal).
+  #
+  # @param node [Node] the current node
+  # @yield [key, value] each key-value pair in ascending order
+  # @return [void]
+  def traverse_asc(node, &block)
+    return if node == @nil_node
+    traverse_asc(node.left, &block)
+    yield node.key, node.value
+    traverse_asc(node.right, &block)
+  end
+
+  # Traverses the tree in descending order (reverse in-order traversal).
+  #
+  # @param node [Node] the current node
+  # @yield [key, value] each key-value pair in descending order
+  # @return [void]
+  def traverse_desc(node, &block)
+    return if node == @nil_node
+    traverse_desc(node.right, &block)
+    yield node.key, node.value
+    traverse_desc(node.left, &block)
+  end
+
+  # Traverses nodes with keys less than the specified key.
+  #
+  # @param node [Node] the current node
+  # @param key [Object] the upper bound (exclusive)
+  # @yield [key, value] each matching key-value pair
+  # @return [void]
+  def traverse_lt(node, key, &block)
+    return if node == @nil_node
+    
+    traverse_lt(node.left, key, &block)
+    if (node.key <=> key) < 0
+      yield node.key, node.value
+      traverse_lt(node.right, key, &block)
+    end
+  end
+
+  # Traverses nodes with keys less than or equal to the specified key.
+  #
+  # @param node [Node] the current node
+  # @param key [Object] the upper bound (inclusive)
+  # @yield [key, value] each matching key-value pair
+  # @return [void]
+  def traverse_lte(node, key, &block)
+    return if node == @nil_node
+    
+    traverse_lte(node.left, key, &block)
+    if (node.key <=> key) <= 0
+      yield node.key, node.value
+      traverse_lte(node.right, key, &block)
+    end
+  end
+
+  # Traverses nodes with keys greater than the specified key.
+  #
+  # @param node [Node] the current node
+  # @param key [Object] the lower bound (exclusive)
+  # @yield [key, value] each matching key-value pair
+  # @return [void]
+  def traverse_gt(node, key, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> key) > 0
+      traverse_gt(node.left, key, &block)
+      yield node.key, node.value
+    end
+    traverse_gt(node.right, key, &block)
+  end
+
+  # Traverses nodes with keys greater than or equal to the specified key.
+  #
+  # @param node [Node] the current node
+  # @param key [Object] the lower bound (inclusive)
+  # @yield [key, value] each matching key-value pair
+  # @return [void]
+  def traverse_gte(node, key, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> key) >= 0
+      traverse_gte(node.left, key, &block)
+      yield node.key, node.value
+    end
+    traverse_gte(node.right, key, &block)
+  end
+
+  # Traverses nodes with keys within the specified range.
+  #
+  # @param node [Node] the current node
+  # @param min [Object] the lower bound
+  # @param max [Object] the upper bound
+  # @param include_min [Boolean] whether to include the lower bound
+  # @param include_max [Boolean] whether to include the upper bound
+  # @yield [key, value] each matching key-value pair
+  # @return [void]
+  def traverse_between(node, min, max, include_min, include_max, &block)
+    return if node == @nil_node
+    if (node.key <=> min) > 0
+      traverse_between(node.left, min, max, include_min, include_max, &block)
+    end
+    
+    greater = include_min ? (node.key <=> min) >= 0 : (node.key <=> min) > 0
+    less = include_max ? (node.key <=> max) <= 0 : (node.key <=> max) < 0
+    
+    if greater && less
+      yield node.key, node.value
+    end
+    
+    if (node.key <=> max) < 0
+      traverse_between(node.right, min, max, include_min, include_max, &block)
+    end
+  end
+
+  # Restores red-black tree properties after insertion.
+  #
+  # This method fixes any violations of red-black properties that may occur
+  # after inserting a new node (which is always colored red).
+  #
+  # @param z [Node] the newly inserted node
+  # @return [void]
+  def insert_fixup(z)
+    while z.parent.color == Node::RED
+      if z.parent == z.parent.parent.left
+        y = z.parent.parent.right
+        if y.color == Node::RED
+          z.parent.color = Node::BLACK
+          y.color = Node::BLACK
+          z.parent.parent.color = Node::RED
+          z = z.parent.parent
+        else
+          if z == z.parent.right
+            z = z.parent
+            left_rotate(z)
+          end
+          z.parent.color = Node::BLACK
+          z.parent.parent.color = Node::RED
+          right_rotate(z.parent.parent)
+        end
+      else
+        y = z.parent.parent.left
+        if y.color == Node::RED
+          z.parent.color = Node::BLACK
+          y.color = Node::BLACK
+          z.parent.parent.color = Node::RED
+          z = z.parent.parent
+        else
+          if z == z.parent.left
+            z = z.parent
+            right_rotate(z)
+          end
+          z.parent.color = Node::BLACK
+          z.parent.parent.color = Node::RED
+          left_rotate(z.parent.parent)
+        end
+      end
+    end
+    @root.color = Node::BLACK
+  end
+
+  # Finds and removes a node by key, returning its value.
+  #
+  # @param key [Object] the key to delete
+  # @return [Object, nil] the value of the deleted node, or nil if not found
+  def delete_node(key)
+    z = find_node(key)
+    return nil if z == @nil_node
+    remove_node(z)
+  end
+
+  # Removes a node from the tree and restores red-black properties.
+  #
+  # Handles three cases:
+  # 1. Node has no left child
+  # 2. Node has no right child
+  # 3. Node has both children (replace with inorder successor)
+  #
+  # @param z [Node] the node to remove
+  # @return [Object] the value of the removed node
+  def remove_node(z)
+    next_min_node = nil
+    if z == @min_node
+      if z.right != @nil_node
+        next_min_node = leftmost(z.right)
+      else
+        next_min_node = z.parent
+      end
+    end
+
+    y = z
+    y_original_color = y.color
+    if z.left == @nil_node
+      x = z.right
+      transplant(z, z.right)
+    elsif z.right == @nil_node
+      x = z.left
+      transplant(z, z.left)
+    else
+      y = leftmost(z.right)
+      y_original_color = y.color
+      x = y.right
+      if y.parent == z
+        x.parent = y
+      else
+        transplant(y, y.right)
+        y.right = z.right
+        y.right.parent = y
+      end
+      transplant(z, y)
+      y.left = z.left
+      y.left.parent = y
+      y.color = z.color
+    end
+    if y_original_color == Node::BLACK
+      delete_fixup(x)
+    end
+    
+    if next_min_node
+      @min_node = next_min_node
+    end
+
+    z.value
+  end
+
+  # Restores red-black tree properties after deletion.
+  #
+  # This method fixes any violations of red-black properties that may occur
+  # after removing a black node from the tree.
+  #
+  # @param x [Node] the node that needs rebalancing
+  # @return [void]
+  def delete_fixup(x)
+    while x != @root && x.color == Node::BLACK
+      if x == x.parent.left
+        w = x.parent.right
+        if w.color == Node::RED
+          w.color = Node::BLACK
+          x.parent.color = Node::RED
+          left_rotate(x.parent)
+          w = x.parent.right
+        end
+        if w.left.color == Node::BLACK && w.right.color == Node::BLACK
+          w.color = Node::RED
+          x = x.parent
+        else
+          if w.right.color == Node::BLACK
+            w.left.color = Node::BLACK
+            w.color = Node::RED
+            right_rotate(w)
+            w = x.parent.right
+          end
+          w.color = x.parent.color
+          x.parent.color = Node::BLACK
+          w.right.color = Node::BLACK
+          left_rotate(x.parent)
+          x = @root
+        end
+      else
+        w = x.parent.left
+        if w.color == Node::RED
+          w.color = Node::BLACK
+          x.parent.color = Node::RED
+          right_rotate(x.parent)
+          w = x.parent.left
+        end
+        if w.right.color == Node::BLACK && w.left.color == Node::BLACK
+          w.color = Node::RED
+          x = x.parent
+        else
+          if w.left.color == Node::BLACK
+            w.right.color = Node::BLACK
+            w.color = Node::RED
+            left_rotate(w)
+            w = x.parent.left
+          end
+          w.color = x.parent.color
+          x.parent.color = Node::BLACK
+          w.left.color = Node::BLACK
+          right_rotate(x.parent)
+          x = @root
+        end
+      end
+    end
+    x.color = Node::BLACK
+  end
+
+  # Replaces subtree rooted at node u with subtree rooted at node v.
+  #
+  # @param u [Node] the node to be replaced
+  # @param v [Node] the replacement node
+  # @return [void]
+  def transplant(u, v)
+    if u.parent == @nil_node
+      @root = v
+    elsif u == u.parent.left
+      u.parent.left = v
+    else
+      u.parent.right = v
+    end
+    v.parent = u.parent
+  end
+
+  # Searches for a node with the given key.
+  #
+  # @param key [Object] the key to search for
+  # @return [Node] the found node, or @nil_node if not found
+  def find_node(key)
+    current = @root
+    while current != @nil_node
+      cmp = key <=> current.key
+      if cmp == 0
+        return current
+      elsif cmp < 0
+        current = current.left
+      else
+        current = current.right
+      end
+    end
+    @nil_node
+  end
+
+  # Finds the node with the closest key to the given key.
+  #
+  # Uses numeric distance (absolute difference) to determine proximity.
+  # If multiple nodes have the same distance, returns the one with the smaller key.
+  #
+  # @param key [Numeric] the target key
+  # @return [Node] the nearest node, or @nil_node if tree is empty
+  def find_nearest_node(key)
+    current = @root
+    closest = @nil_node
+    min_dist = nil
+
+    while current != @nil_node
+      cmp = key <=> current.key
+      if cmp == 0
+        return current
+      end
+
+      # For nearest, we still typically rely on numeric distance.
+      # If keys are strings, this part will fail unless they support -.
+      dist = (current.key - key).abs
+
+      if closest == @nil_node || dist < min_dist
+        min_dist = dist
+        closest = current
+      elsif dist == min_dist
+        if (current.key <=> closest.key) < 0
+          closest = current
+        end
+      end
+
+      if cmp < 0
+        current = current.left
+      else
+        current = current.right
+      end
+    end
+    closest
+  end
+
+  # Finds the leftmost (minimum) node in a subtree.
+  #
+  # @param node [Node] the root of the subtree
+  # @return [Node] the leftmost node
+  def leftmost(node)
+    while node.left != @nil_node
+      node = node.left
+    end
+    node
+  end
+
+  # Finds the rightmost (maximum) node in a subtree.
+  #
+  # @param node [Node] the root of the subtree
+  # @return [Node] the rightmost node
+  def rightmost(node)
+    while node.right != @nil_node
+      node = node.right
+    end
+    node
+  end
+
+  # Performs a left rotation on the given node.
+  #
+  # Transforms the tree structure:
+  #     x                y
+  #    / \              / \
+  #   a   y     =>     x   c
+  #      / \          / \
+  #     b   c        a   b
+  #
+  # @param x [Node] the node to rotate
+  # @return [void]
+  def left_rotate(x)
+    y = x.right
+    x.right = y.left
+    if y.left != @nil_node
+      y.left.parent = x
+    end
+    y.parent = x.parent
+    if x.parent == @nil_node
+      @root = y
+    elsif x == x.parent.left
+      x.parent.left = y
+    else
+      x.parent.right = y
+    end
+    y.left = x
+    x.parent = y
+  end
+
+  # Performs a right rotation on the given node.
+  #
+  # Transforms the tree structure:
+  #       y            x
+  #      / \          / \
+  #     x   c   =>   a   y
+  #    / \              / \
+  #   a   b            b   c
+  #
+  # @param y [Node] the node to rotate
+  # @return [void]
+  def right_rotate(y)
+    x = y.left
+    y.left = x.right
+    if x.right != @nil_node
+      x.right.parent = y
+    end
+    x.parent = y.parent
+    if y.parent == @nil_node
+      @root = x
+    elsif y == y.parent.right
+      y.parent.right = x
+    else
+      y.parent.left = x
+    end
+    x.right = y
+    y.parent = x
+  end
+
+  # Recursively checks black height consistency.
+  #
+  # Verifies that:
+  # - No red node has a red child
+  # - All paths have the same black height
+  #
+  # @param node [Node] the current node
+  # @return [Integer] the black height, or -1 if invalid
+  def check_black_height(node)
+    return 0 if node == @nil_node
+
+    if node.color == Node::RED
+      return -1 if node.left.color == Node::RED || node.right.color == Node::RED
+    end
+
+    left_h = check_black_height(node.left)
+    right_h = check_black_height(node.right)
+
+    return -1 if left_h == -1 || right_h == -1 || left_h != right_h
+
+    left_h + (node.color == Node::BLACK ? 1 : 0)
+  end
+
+  def check_order(node)
+    return true if node == @nil_node
+    if node.left != @nil_node && (node.left.key <=> node.key) >= 0
+      return false
+    end
+    if node.right != @nil_node && (node.right.key <=> node.key) <= 0
+      return false
+    end
+    check_order(node.left) && check_order(node.right)
+  end
+end
+
+# A Multi Red-Black Tree that allows duplicate keys.
+#
+# MultiRBTree extends RBTree to support multiple values per key. Each key maps to
+# a linked list of values rather than a single value. The size reflects the total
+# number of key-value pairs (not unique keys).
+#
+# == Features
+#
+# * Multiple values per key using linked lists
+# * Separate methods for single deletion (`delete_one`) vs. all deletions (`delete`)
+# * Values for each key maintain insertion order
+# * min/max return first/last values respectively
+#
+# == Usage
+#
+#   tree = MultiRBTree.new
+#   tree.insert(1, 'first one')
+#   tree.insert(1, 'second one')
+#   tree.insert(2, 'two')
+#
+#   tree.size           # => 3 (total key-value pairs)
+#   tree.get(1)         # => "first one" (first value)
+#   tree.get_all(1)     # => ["first one", "second one"] (all values)
+#
+#   tree.delete_one(1)  # removes only "first one"
+#   tree.get(1)         # => "second one"
+#
+#   tree.delete(1)      # removes all remaining values for key 1
+#
+# @author Masahito Suzuki
+# @since 0.1.2
+class MultiRBTree < RBTree
+  # Retrieves the first value associated with the given key.
+  #
+  # @param key [Object] the key to look up
+  # @return [Object, nil] the first value for the key, or nil if not found
+  # @example
+  #   tree = MultiRBTree.new
+  #   tree.insert(1, 'first')
+  #   tree.insert(1, 'second')
+  #   tree.get(1)  # => "first"
+  def get(key)
+    n = find_node(key)
+    n == @nil_node || n.value.empty? ? nil : n.value.first
+  end
+  alias_method :[], :get
+
+  # Retrieves all values associated with the given key.
+  #
+  # @param key [Object] the key to look up
+  # @return [Array, nil] an Array containing all values, or nil if not found
+  # @example
+  #   tree = MultiRBTree.new
+  #   tree.insert(1, 'first')
+  #   tree.insert(1, 'second')
+  #   tree.get_all(1).to_a  # => ["first", "second"]
+  def get_all(key)
+    n = find_node(key)
+    n == @nil_node || n.value.empty? ? nil : n.value
+  end
+
+  # Inserts a value for the given key.
+  #
+  # If the key already exists, the value is appended to its list.
+  # If the key doesn't exist, a new node is created.
+  #
+  # @param key [Object] the key (must implement <=>)
+  # @param value [Object] the value to insert
+  # @return [Boolean] always returns true
+  # @example
+  #   tree = MultiRBTree.new
+  #   tree.insert(1, 'first')
+  #   tree.insert(1, 'second')  # adds another value for key 1
+  def insert(key, value)
+    y = @nil_node
+    x = @root
+    while x != @nil_node
+      y = x
+      cmp = key <=> x.key
+      if cmp == 0
+        x.value << value
+        @size += 1
+        return true
+      elsif cmp < 0
+        x = x.left
+      else
+        x = x.right
+      end
+    end
+    z = Node.new(key, [value], Node::RED, @nil_node, @nil_node, @nil_node)
+    z.parent = y
+    if y == @nil_node
+      @root = z
+    elsif (key <=> y.key) < 0
+      y.left = z
+    else
+      y.right = z
+    end
+    z.left = @nil_node
+    z.right = @nil_node
+    z.color = Node::RED
+    insert_fixup(z)
+    @size += 1
+    
+    if @min_node == @nil_node || (key <=> @min_node.key) < 0
+      @min_node = z
+    end
+    
+    true
+  end
+
+  # Deletes only the first value for the specified key.
+  #
+  # If the key has multiple values, removes only the first one.
+  # If this was the last value for the key, the node is removed from the tree.
+  #
+  # @param key [Object] the key to delete from
+  # @return [Object, nil] the deleted value, or nil if key not found
+  # @example
+  #   tree = MultiRBTree.new
+  #   tree.insert(1, 'first')
+  #   tree.insert(1, 'second')
+  #   tree.delete_one(1)  # => "first"
+  #   tree.get(1)         # => "second"
+  def delete_one(key)
+    z = find_node(key)
+    return nil if z == @nil_node
+
+    value = z.value.shift
+    @size -= 1
+    if z.value.empty?
+      remove_node(z)
+    end
+    value
+  end
+
+  # Deletes all values for the specified key.
+  #
+  # Removes the node and all associated values.
+  #
+  # @param key [Object] the key to delete
+  # @return [Array, nil] the array of all deleted values, or nil if not found
+  # @example
+  #   tree = MultiRBTree.new
+  #   tree.insert(1, 'first')
+  #   tree.insert(1, 'second')
+  #   vals = tree.delete(1)  # removes both values
+  #   vals.size  # => 2
+  def delete(key)
+    z = find_node(key)
+    return nil if z == @nil_node
+    
+    count = z.value.size
+    remove_node(z)
+    @size -= count
+    z.value
+  end
+
+  def shift
+    return nil if @min_node == @nil_node
+    node = @min_node
+    key = node.key
+    val = node.value.first
+    node.value.shift
+    @size -= 1
+    if node.value.empty?
+      remove_node(node)
+    end
+    [key, val]
+  end
+
+  def pop
+    n = rightmost(@root)
+    return nil if n == @nil_node
+    val = n.value.last
+    n.value.pop
+    @size -= 1
+    if n.value.empty?
+      remove_node(n)
+    end
+    [n.key, val]
+  end
+
+  def min
+    return nil if @min_node == @nil_node || @min_node.value.empty?
+    [@min_node.key, @min_node.value.first]
+  end
+
+  def max
+    n = rightmost(@root)
+    n == @nil_node || n.value.empty? ? nil : [n.key, n.value.first]
+  end
+
+  def nearest(key)
+    (n = super(key)) ? [n[0], n[1].first] : nil
+  end
+
+  private
+
+  def traverse_asc(node, &block)
+    return if node == @nil_node
+    traverse_asc(node.left, &block)
+    node.value.each { |v| yield node.key, v }
+    traverse_asc(node.right, &block)
+  end
+
+  def traverse_desc(node, &block)
+    return if node == @nil_node
+    traverse_desc(node.right, &block)
+    node.value.reverse_each { |v| yield node.key, v }
+    traverse_desc(node.left, &block)
+  end
+
+  def traverse_lt(node, key, &block)
+    return if node == @nil_node
+    
+    traverse_lt(node.left, key, &block)
+    if (node.key <=> key) < 0
+      node.value.each { |v| yield node.key, v }
+      traverse_lt(node.right, key, &block)
+    end
+  end
+
+  def traverse_lte(node, key, &block)
+    return if node == @nil_node
+    
+    traverse_lte(node.left, key, &block)
+    if (node.key <=> key) <= 0
+      node.value.each { |v| yield node.key, v }
+      traverse_lte(node.right, key, &block)
+    end
+  end
+
+  def traverse_gt(node, key, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> key) > 0
+      traverse_gt(node.left, key, &block)
+      node.value.each { |v| yield node.key, v }
+    end
+    traverse_gt(node.right, key, &block)
+  end
+
+  def traverse_gte(node, key, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> key) >= 0
+      traverse_gte(node.left, key, &block)
+      node.value.each { |v| yield node.key, v }
+    end
+    traverse_gte(node.right, key, &block)
+  end
+
+  def traverse_between(node, min, max, include_min, include_max, &block)
+    return if node == @nil_node
+    if (node.key <=> min) > 0
+      traverse_between(node.left, min, max, include_min, include_max, &block)
+    end
+    
+    greater = include_min ? (node.key <=> min) >= 0 : (node.key <=> min) > 0
+    less = include_max ? (node.key <=> max) <= 0 : (node.key <=> max) < 0
+    
+    if greater && less
+      node.value.each { |v| yield node.key, v }
+    end
+    
+    if (node.key <=> max) < 0
+      traverse_between(node.right, min, max, include_min, include_max, &block)
+    end
+  end
+end
+
+# Internal node structure for RBTree.
+#
+# Each node stores a key-value pair, color (red or black), and references
+# to parent, left child, and right child nodes.
+#
+# @!attribute [rw] key
+#   @return [Object] the key stored in this node
+# @!attribute [rw] value
+#   @return [Object] the value stored in this node
+# @!attribute [rw] color
+#   @return [Symbol] the color of the node (:red or :black)
+# @!attribute [rw] left
+#   @return [Node] the left child node
+# @!attribute [rw] right
+#   @return [Node] the right child node
+# @!attribute [rw] parent
+#   @return [Node] the parent node
+#
+# @api private
+class RBTree::Node
+  attr_accessor :key, :value, :color, :left, :right, :parent
+
+  # Red color constant
+  RED = :red
+  # Black color constant
+  BLACK = :black
+
+  # Creates a new Node.
+  #
+  # @param key [Object] the key
+  # @param value [Object] the value
+  # @param color [Symbol] the color (:red or :black)
+  # @param left [Node] the left child
+  # @param right [Node] the right child
+  # @param parent [Node] the parent node
+  def initialize(key = nil, value = nil, color = BLACK, left = nil, right = nil, parent = nil)
+    @key = key
+    @value = value
+    @color = color
+    @left = left
+    @right = right
+    @parent = parent
+  end
+
+  # Checks if the node is red.
+  # @return [Boolean] true if red, false otherwise
+  def red? = @color == RED
+  
+  # Checks if the node is black.
+  # @return [Boolean] true if black, false otherwise
+  def black? = @color == BLACK
+end
+