rbtree-ruby 0.3.3 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2145d91a96cc64b7e65c65460716b678301f74d6decdffa2dbd077a914273c21
-  data.tar.gz: 66503c542ce07672a493830afbfcb66ebfea14d8563e67b1b2dd1d5ecd1d9c48
+  metadata.gz: d89cd253c189b3342f30e2a4df3a293561e2353af6592d86f25fcea5eeb76433
+  data.tar.gz: 9af04bff3851e7806fc637c2fc0ad583decf8e7c020edf841220a2b90fe8aaf4
 SHA512:
-  metadata.gz: 7befca8277d78b75242a443c2ec155bded73f899222b32330c6416e6ffeaad8ec6bca01e11ce23c6047208871cf71cfb8c6a742732b4ae0b531f54e51a8e424e
-  data.tar.gz: eb77127897b535277717575afe27c47cd087ba15685f59b0df67516c55d393a8d7412cf08d667cea5494978746967c098294bb73e8e9771c2aee363762afcca9
+  metadata.gz: a9708ffb8b421f883953c68582c607b9333e671542e21c0f3e0927838d2bb68202142150c11dd11541ea79fa1fcafc6c3195456c38d4b0db6b3897272d205835
+  data.tar.gz: 601190e616b7b478cc6ceabe682e9d43ef169871753667fe61e326f65daceaa60441122a550f8458f1d4a7a794a032ac0add88f326956db903854ee96e34b613

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.5] - 2026-01-26
+
+### Optimized
+- **O(1) Max Access**: Added cached `@max_node` to ensure `max` and `pop` operations run in constant time.
+- **Traversal Engine Rewrite**: Optimized all range queries (`lt`, `gt`, `between`, `each`) with a unified traversal engine featuring $O(1)$ range rejection and bound optimization.
+- **Fast-path Startup**: Range queries now leverage the hybrid Hash index to jump directly to target nodes (even for exclusive bounds), eliminating $O(\log N)$ tree descents when keys exist.
+
+### Changed
+- **Defensive Assertion**: Added an explicit check to `find_nearest_node` to ensure only `Numeric` keys are accepted, formalizing a pre-existing design constraint.
+- **Internal Refactoring**: Unified the insertion logic between `RBTree` and `MultiRBTree` into a single internal method to improve maintainability and ensure consistent optimization.
+
+## [0.3.4] - 2026-01-25
+
+### Added
+- **Range-based Lookup**: Support for passing `Range` objects to the bracket operator `[]`.
+  - `tree[2..4]` -> `between(2, 4)`
+  - `tree[2...4]` -> `between(2, 4, include_max: false)`
+  - `tree[5..]` -> `gte(5)`
+  - `tree[..10]` -> `lte(10)`
+  - `tree[...10]` -> `lt(10)`
+  - Returns an `Enumerator` of `[key, value]` pairs.
+  - *Note: `gt` (greater than exclusive) is not covered by standard Ruby Range syntax and remains available via the `gt` method.*
+
 ## [0.3.3] - 2026-01-23
 
 ### Optimized
@@ -207,6 +230,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - ASCII diagrams for tree rotation operations
 - MIT License (Copyright © 2026 Masahito Suzuki)
 
+[0.3.5]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.5
+[0.3.4]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.4
+[0.3.3]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.3
 [0.3.2]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.2
 [0.3.1]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.1
 [0.3.0]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.0

data/README.ja.md

@@ -80,9 +80,16 @@ tree.max  # => [20, "twenty"]
 
 # 範囲クエリ（Enumeratorを返す、配列には.to_aを使用）
 tree.lt(10).to_a   # => [[1, "one"], [2, "two"], [3, "three"]]
-tree.gte(10).to_a  # => [[10, "ten"], [20, "twenty"]]
+tree.gte(10).each { |k, v| puts k } # ブロック渡しでのループ
 tree.between(2, 10).to_a  # => [[2, "two"], [3, "three"], [10, "ten"]]
 
+# []でのRangeオブジェクトの利用 (v0.3.4+)
+tree[..10].to_a    # lte(10)相当
+tree[2..10].each { |k, v| ... } # Rangeでのループ
+tree[2...10].to_a  # between(2, 10, include_max: false)相当
+tree[10..].to_a    # gte(10)相当
+tree[2..10, reverse: true].to_a # オプション指定可能
+
 # shiftとpop
 tree.shift  # => [1, "one"] (最小値を削除)
 tree.pop    # => [20, "twenty"] (最大値を削除)
@@ -232,10 +239,9 @@ tree.max(last: true)      # => [2, "b"]      (最大キーの最後の値)
 - `delete(key)` - O(log n)
 - `value(key)` / `[]` - **O(1)** (内部ハッシュインデックスによる超高速アクセス)
 - `has_key?` - **O(1)** (内部ハッシュインデックスによる超高速チェック)
-- `min` - **O(1)**
-- `max` - O(log n)
+- `min` / `max` - **O(1)**
 - `shift` / `pop` - O(log n)
-- `prev` / `succ` - O(log n)、O(1)ハッシュチェック付き
+- `prev` / `succ` - O(log n)、O(1)ハッシュチェックと高速な走査開始により改善
 
 全要素のイテレーションはO(n)時間。
 

data/README.md

@@ -80,9 +80,16 @@ tree.max  # => [20, "twenty"]
 
 # Range queries (return Enumerator, use .to_a for Array)
 tree.lt(10).to_a   # => [[1, "one"], [2, "two"], [3, "three"]]
-tree.gte(10).to_a  # => [[10, "ten"], [20, "twenty"]]
+tree.gte(10).each { |k, v| puts k } # Block iteration
 tree.between(2, 10).to_a  # => [[2, "two"], [3, "three"], [10, "ten"]]
 
+# Range objects in [] (v0.3.4+)
+tree[..10].to_a    # lte(10)
+tree[2..10].each { |k, v| ... } # Block iteration on Range
+tree[2...10].to_a  # between(2, 10, include_max: false)
+tree[10..].to_a    # gte(10)
+tree[2..10, reverse: true].to_a # with options
+
 # Shift and pop
 tree.shift  # => [1, "one"] (removes minimum)
 tree.pop    # => [20, "twenty"] (removes maximum)
@@ -232,10 +239,9 @@ All major operations run in **O(log n)** time:
 - `delete(key)` - O(log n)
 - `value(key)` / `[]` - **O(1)** (hybrid hash index)
 - `has_key?` - **O(1)** (hybrid hash index)
-- `min` - **O(1)**
-- `max` - O(log n)
+- `min` / `max` - **O(1)**
 - `shift` / `pop` - O(log n)
-- `prev` / `succ` - O(log n) with O(1) hash check
+- `prev` / `succ` - O(log n) with O(1) hash check and faster startup
 
 Iteration over all elements takes O(n) time.
 

data/lib/rbtree/version.rb

@@ -2,5 +2,5 @@
 
 class RBTree
   # The version of the rbtree-ruby gem
-  VERSION = "0.3.3"
+  VERSION = "0.3.5"
 end

data/lib/rbtree.rb

@@ -99,6 +99,7 @@ class RBTree
     @nil_node.right = @nil_node
     @root = @nil_node
     @min_node = @nil_node
+    @max_node = @nil_node
     @hash_index = {}  # Hash index for O(1) key lookup
     @node_allocator = node_allocator
     @key_count = 0
@@ -191,11 +192,35 @@ class RBTree
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two'})
   #   tree.get(1)  # => "one"
-  #   tree[2]      # => "two"
-  #   tree[3]      # => nil
   def value(key) = @hash_index[key]&.value
   alias :get :value
-  alias :[] :value
+
+  # Retrieves a value associated with the given key, or a range of entries if a Range is provided.
+  #
+  # @param key_or_range [Object, Range] the key to look up or a Range for query
+  # @param ... [Hash] additional options to pass to the respective lookup method
+  # @return [Object, Enumerator, nil]
+  #   - If a key is provided: the associated value, or nil if not found
+  #   - If a Range is provided: an Enumerator yielding [key, value] pairs
+  # @example Single key lookup
+  #   tree[2]      # => "two"
+  # @example Range lookup
+  #   tree[2..4].to_a  # => [[2, "two"], [3, "three"], [4, "four"]]
+  #   tree[...3].to_a  # => [[1, "one"], [2, "two"]]
+  def [](key_or_range, **)
+    return value(key_or_range, **) if !key_or_range.is_a?(Range)
+
+    r = key_or_range
+    r.begin ? (
+      r.end ?
+        between(r.begin, r.end, include_max: !r.exclude_end?, **) :
+        gte(r.begin, **)
+    ) : (
+      r.end ?
+        (r.exclude_end? ? lt(r.end, **) : lte(r.end, **)) :
+        each(**)
+    )
+  end
 
   # Returns the key with the key closest to the given key.
   #
@@ -394,7 +419,7 @@ class RBTree
   #   tree.pop  # => [3, "three"]
   #   tree.pop  # => [2, "two"]
   def pop
-    return nil unless (n = rightmost(@root)) != @nil_node
+    return nil unless (n = @max_node) != @nil_node
     pair = n.pair
     delete(n.key)
     pair
@@ -404,7 +429,7 @@ class RBTree
   #
   # @return [RBTree] self
   def clear
-    @root = @min_node = @nil_node
+    @root = @min_node = @max_node = @nil_node
     @hash_index.clear
     @key_count = 0
     self
@@ -460,11 +485,7 @@ class RBTree
   #   end
   def each(reverse: false, safe: false, &block)
     return enum_for(__method__, reverse: reverse, safe: safe) { size } unless block_given?
-    if reverse
-      traverse_all_desc(@root, safe: safe, &block)
-    else
-      traverse_all_asc(@root, safe: safe, &block)
-    end
+    traverse_range(reverse, nil, nil, false, false, safe: safe, &block)
     self
   end
 
@@ -506,11 +527,7 @@ class RBTree
   #   tree.lt(3, safe: true) { |k, _| tree.delete(k) if k.even? }  # safe to delete
   def lt(key, reverse: false, safe: false, &block)
     return enum_for(__method__, key, reverse: reverse, safe: safe) unless block_given?
-    if reverse
-      traverse_lt_desc(@root, key, safe: safe, &block)
-    else
-      traverse_lt_asc(@root, key, safe: safe, &block)
-    end
+    traverse_range(reverse, nil, key, false, false, safe: safe, &block)
     self
   end
 
@@ -527,11 +544,7 @@ class RBTree
   #   tree.lte(3, reverse: true).first  # => [3, "three"]
   def lte(key, reverse: false, safe: false, &block)
     return enum_for(__method__, key, reverse: reverse, safe: safe) unless block_given?
-    if reverse
-      traverse_lte_desc(@root, key, safe: safe, &block)
-    else
-      traverse_lte_asc(@root, key, safe: safe, &block)
-    end
+    traverse_range(reverse, nil, key, false, true, safe: safe, &block)
     self
   end
 
@@ -548,11 +561,7 @@ class RBTree
   #   tree.gt(2, reverse: true).first  # => [4, "four"]
   def gt(key, reverse: false, safe: false, &block)
     return enum_for(__method__, key, reverse: reverse, safe: safe) unless block_given?
-    if reverse
-      traverse_gt_desc(@root, key, safe: safe, &block)
-    else
-      traverse_gt_asc(@root, key, safe: safe, &block)
-    end
+    traverse_range(reverse, key, nil, false, false, safe: safe, &block)
     self
   end
 
@@ -569,11 +578,7 @@ class RBTree
   #   tree.gte(2, reverse: true).first  # => [4, "four"]
   def gte(key, reverse: false, safe: false, &block)
     return enum_for(__method__, key, reverse: reverse, safe: safe) unless block_given?
-    if reverse
-      traverse_gte_desc(@root, key, safe: safe, &block)
-    else
-      traverse_gte_asc(@root, key, safe: safe, &block)
-    end
+    traverse_range(reverse, key, nil, true, false, safe: safe, &block)
     self
   end
 
@@ -593,11 +598,7 @@ class RBTree
   #   tree.between(2, 4, reverse: true).first  # => [4, "four"]
   def between(min, max, include_min: true, include_max: true, reverse: false, safe: false, &block)
     return enum_for(__method__, min, max, include_min: include_min, include_max: include_max, reverse: reverse, safe: safe) unless block_given?
-    if reverse
-      traverse_between_desc(@root, min, max, include_min, include_max, safe: safe, &block)
-    else
-      traverse_between_asc(@root, min, max, include_min, include_max, safe: safe, &block)
-    end
+    traverse_range(reverse, min, max, include_min, include_max, safe: safe, &block)
     self
   end
 
@@ -631,9 +632,8 @@ class RBTree
   # @!visibility private
   private
 
-  def min_node = ((n = @min_node) == @nil_node) ? nil : n
-
-  def max_node = ((n = rightmost(@root)) == @nil_node) ? nil : n
+  def min_node = (@min_node == @nil_node) ? nil : @min_node
+  def max_node = (@max_node == @nil_node) ? nil : @max_node
 
   # Inserts a single key-value pair.
   #
@@ -642,27 +642,51 @@ class RBTree
   # @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
   def insert_entry(key, value, overwrite: true)
+    insert_entry_generic(key) do |node, is_new|
+      if is_new
+        value
+      else
+        if overwrite
+          node.value = value
+          true
+        else
+          nil
+        end
+      end
+    end
+  end
+
+  # Generic entry insertion logic shared between RBTree and MultiRBTree.
+  #
+  # @param key [Object] the key to insert
+  # @yield [node, is_new] yields the existing node (if any) and whether it's a new insertion
+  # @yieldparam node [Node, nil] the existing node or nil
+  # @yieldparam is_new [Boolean] true if no node with the key exists
+  # @yieldreturn [Object]
+  #   - if is_new: the initial value for the new node
+  #   - if !is_new: the value to return from insert_entry
+  def insert_entry_generic(key)
     if (node = @hash_index[key])
-      return nil unless overwrite
-      node.value = value
-      return true
+      return yield(node, false)
     end
+
     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
+        return yield(x, false)
       elsif cmp < 0
         x = x.left
       else
         x = x.right
       end
     end
-    z = allocate_node(key, value, Node::RED, @nil_node, @nil_node, @nil_node)
+
+    initial_value = yield(nil, true)
+
+    z = allocate_node(key, initial_value, Node::RED, @nil_node, @nil_node, @nil_node)
     z.parent = y
     if y == @nil_node
       @root = z
@@ -679,14 +703,34 @@ class RBTree
     if @min_node == @nil_node || (key <=> @min_node.key) < 0
       @min_node = z
     end
+    if @max_node == @nil_node || (key <=> @max_node.key) > 0
+      @max_node = z
+    end
     
-    @hash_index[key] = z  # Add to hash index
+    @hash_index[key] = z
     true
   end
 
+  # Traverses the tree in a specified direction (ascending or descending).
+  #
+  # @param direction [Boolean] true for descending, false for ascending
+  # @param min [Object] the lower bound (inclusive)
+  # @param max [Object] the upper bound (inclusive)
+  # @param include_min [Boolean] whether to include the lower bound
+  # @param include_max [Boolean] whether to include the upper bound
+  # @param safe [Boolean] whether to use safe traversal
+  # @yield [key, value] each key-value pair in the specified direction
+  # @return [void]
+  def traverse_range(direction, min, max, include_min, include_max, safe: false, &block)
+    if direction
+      traverse_range_desc(min, max, include_min, include_max, safe: safe, &block)
+    else
+      traverse_range_asc(min, max, include_min, include_max, safe: safe, &block)
+    end
+  end
+
   # Traverses the tree in ascending order (in-order traversal).
   #
-  # @param node [Node] the current node
   # @param min [Object] the lower bound (inclusive)
   # @param max [Object] the upper bound (inclusive)
   # @param include_min [Boolean] whether to include the lower bound
@@ -694,56 +738,31 @@ class RBTree
   # @param safe [Boolean] whether to use safe traversal
   # @yield [key, value] each key-value pair in ascending order
   # @return [void]
-  def traverse_range_asc(node, min, max, include_min, include_max, safe: false, &block)
+  def traverse_range_asc(min, max, include_min, include_max, safe: false, &block)
+    # O(1) Range Rejection
+    return if min && @max_node != @nil_node && (min <=> @max_node.key) > 0
+    return if min && @max_node != @nil_node && !include_min && (min <=> @max_node.key) == 0
+
+    # O(1) Bound Optimization
+    max = nil if max && @max_node != @nil_node && (cmp = max <=> @max_node.key) >= 0 && (cmp > 0 || include_max)
+
     if safe
       pair = !min ? find_min :
         include_min && @hash_index[min]&.pair || find_successor(min)
-      if !max
-        while pair
-          current_key = pair[0]
-          yield pair
-          pair = find_successor(current_key)
-        end
-      else
-        while pair && pair[0] < max
-          current_key = pair[0]
-          yield pair
-          pair = find_successor(current_key)
-        end
+      while pair && (!max || pair[0] < max)
+        current_key = pair[0]
+        yield pair
+        pair = find_successor(current_key)
       end
       yield pair if pair && max && include_max && pair[0] == max
     else
-      stack = []
-      current = node
-      while current != @nil_node || !stack.empty?
-        while current != @nil_node
-          if min && ((current.key <=> min) < 0 ||
-              (!include_min && (current.key <=> min) == 0))
-            current = current.right
-          else
-            stack << current
-            current = current.left
-          end
-        end
-        
-        if !stack.empty?
-          current = stack.pop
-          
-          if max && ((current.key <=> max) > 0 ||
-              (!include_max && (current.key <=> max) == 0))
-            return
-          else
-            yield current.pair
-            current = current.right
-          end
-        end
-      end
+      start_node, stack = resolve_startup_asc(min, include_min)
+      traverse_from_asc(start_node, stack, max, include_max, &block)
     end
   end
 
   # Traverses the tree in descending order (reverse in-order traversal).
   #
-  # @param node [Node] the current node
   # @param min [Object] the lower bound (inclusive)
   # @param max [Object] the upper bound (inclusive)
   # @param include_min [Boolean] whether to include the lower bound
@@ -751,164 +770,218 @@ class RBTree
   # @param safe [Boolean] whether to use safe traversal
   # @yield [key, value] each key-value pair in descending order
   # @return [void]
-  def traverse_range_desc(node, min, max, include_min, include_max, safe: false, &block)
+  def traverse_range_desc(min, max, include_min, include_max, safe: false, &block)
+    # O(1) Range Rejection
+    return if max && @min_node != @nil_node && (max <=> @min_node.key) < 0
+    return if max && @min_node != @nil_node && !include_max && (max <=> @min_node.key) == 0
+
+    # O(1) Bound Optimization
+    min = nil if min && @min_node != @nil_node && (cmp = min <=> @min_node.key) <= 0 && (cmp < 0 || include_min)
+
     if safe
       pair = !max ? find_max :
         include_max && @hash_index[max]&.pair || find_predecessor(max)
-      if !min
-        while pair
-          current_key = pair[0]
-          yield pair
-          pair = find_predecessor(current_key)
-        end
-      else
-        while pair && pair[0] > min
-          current_key = pair[0]
-          yield pair
-          pair = find_predecessor(current_key)
-        end
+      while pair && (!min || pair[0] > min)
+        current_key = pair[0]
+        yield pair
+        pair = find_predecessor(current_key)
       end
       yield pair if pair && min && include_min && pair[0] == min
     else
-      stack = []
-      current = node
-      while current != @nil_node || !stack.empty?
-        while current != @nil_node
-          if max && ((current.key <=> max) > 0 ||
-              (!include_max && (current.key <=> max) == 0))
-            current = current.left
-          else
-            stack << current
-            current = current.right
-          end
-        end
-        
-        if !stack.empty?
-          current = stack.pop
-          
-          if min && ((current.key <=> min) < 0 ||
-              (!include_min && (current.key <=> min) == 0))
-            return
-          else
-            yield current.pair
-            current = current.left
-          end
-        end
-      end
+      start_node, stack = resolve_startup_desc(max, include_max)
+      traverse_from_desc(start_node, stack, min, include_min, &block)
     end
   end
 
-  # 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_all_asc(node, safe: false, &block) =
-    traverse_range_asc(node, nil, nil, false, false, safe: safe, &block)
-
-  # 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_all_desc(node, safe: false, &block) =
-    traverse_range_desc(node, nil, nil, false, false, safe: safe, &block)
-
-  # Traverses nodes with keys less than the specified key.
+  private
+  
+  # Returns the predecessor of the given node.
   #
-  # @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_asc(node, key, safe: false, &block) =
-    traverse_range_asc(node, nil, key, false, false, safe: safe, &block)
+  # @param node [Node] the node to find the predecessor of
+  # @return [Node] the predecessor node
+  def predecessor_node_of(node)
+    if node.left != @nil_node
+      return rightmost(node.left)
+    end
+    y = node.parent
+    while y != @nil_node && node == y.left
+      node = y
+      y = y.parent
+    end
+    y
+  end
 
-  # Traverses nodes with keys less than or equal to the specified key.
+  # Returns the successor of the given node.
   #
-  # @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_asc(node, key, safe: false, &block) =
-    traverse_range_asc(node, nil, key, false, true, safe: safe, &block)
+  # @param node [Node] the node to find the successor of
+  # @return [Node] the successor node
+  def successor_node_of(node)
+    if node.right != @nil_node
+      return leftmost(node.right)
+    end
+    y = node.parent
+    while y != @nil_node && node == y.right
+      node = y
+      y = y.parent
+    end
+    y
+  end
 
-  # Traverses nodes with keys greater than the specified key.
+  # Resolves the startup node for ascending traversal.
   #
-  # @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_asc(node, key, safe: false, &block) =
-    traverse_range_asc(node, key, nil, false, false, safe: safe, &block)
+  # @param min [Object] the minimum key to traverse from
+  # @param include_min [Boolean] whether to include the minimum key
+  # @return [Array(Node, Array)] the starting node and stack
+  def resolve_startup_asc(min, include_min)
+    # 1. Use cached min if no lower bound or if min is less than tree min
+    if @min_node != @nil_node && (!min || (min <=> @min_node.key) < 0)
+      return [@min_node, reconstruct_stack_asc(@min_node)]
+    end
+    
+    # 2. Use Hash index if key exists
+    if min && (node = @hash_index[min])
+      start_node = include_min ? node : successor_node_of(node)
+      return [start_node, reconstruct_stack_asc(start_node)]
+    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_asc(node, key, safe: false, &block) =
-    traverse_range_asc(node, key, nil, true, false, safe: safe, &block)
+    # 3. Fallback to tree search from root
+    stack = []
+    current = @root
+    while current != @nil_node
+      if min && ((current.key <=> min) < 0 || (!include_min && (current.key <=> min) == 0))
+        current = current.right
+      else
+        stack << current
+        current = current.left
+      end
+    end
+    [@nil_node, stack]
+  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_asc(node, min, max, include_min, include_max, safe: false, &block) =
-    traverse_range_asc(node, min, max, include_min, include_max, safe: safe, &block)
+  # Reconstructs the stack for ascending traversal.
+  #
+  # @param node [Node] the node to reconstruct the stack from
+  # @return [Array] the reconstructed stack
+  def reconstruct_stack_asc(node)
+    return [] if node == @nil_node
+    stack = []
+    curr = node
+    while (p = curr.parent) != @nil_node
+      stack << p if curr == p.left
+      curr = p
+    end
+    stack.reverse!
+    stack
+  end
 
-  # Traverses nodes with keys less than the specified key in descending order.
+  # Traverses the tree in ascending order.
   #
-  # @param node [Node] the current node
-  # @param key [Object] the upper bound (exclusive)
-  # @yield [key, value] each matching key-value pair in descending order
-  # @return [void]
-  def traverse_lt_desc(node, key, safe: false, &block) =
-    traverse_range_desc(node, nil, key, false, false, safe: safe, &block)
+  # @param current [Node] the current node
+  # @param stack [Array] the stack of nodes to traverse
+  # @param max [Object] the maximum key to traverse to
+  # @param include_max [Boolean] whether to include the maximum key
+  # @yield [Array(Object, Object)] each key-value pair
+  # @yieldparam key [Object] the key
+  # @yieldparam val [Object] the value
+  def traverse_from_asc(current, stack, max, include_max, &block)
+    while current != @nil_node || !stack.empty?
+      if current != @nil_node
+        if max
+          cmp = current.key <=> max
+          if cmp >= 0
+            yield current.pair if include_max && cmp == 0
+            return
+          end
+        end
+        yield current.pair
+        current = current.right
+        while current != @nil_node
+          stack << current
+          current = current.left
+        end
+      else
+        current = stack.pop
+      end
+    end
+  end
 
-  # Traverses nodes with keys less than or equal to the specified key in descending order.
+  # Resolves the startup node for descending traversal.
   #
-  # @param node [Node] the current node
-  # @param key [Object] the upper bound (inclusive)
-  # @yield [key, value] each matching key-value pair in descending order
-  # @return [void]
-  def traverse_lte_desc(node, key, safe: false, &block) =
-    traverse_range_desc(node, nil, key, false, true, safe: safe, &block)
+  # @param max [Object] the maximum key to traverse from
+  # @param include_max [Boolean] whether to include the maximum key
+  # @return [Array(Node, Array)] the starting node and stack
+  def resolve_startup_desc(max, include_max)
+    # 1. Use cached max if no upper bound or if max is greater than tree max
+    if @max_node != @nil_node && (!max || (max <=> @max_node.key) > 0)
+      return [@max_node, reconstruct_stack_desc(@max_node)]
+    end
+  
+    # 2. Use Hash index if key exists
+    if max && (node = @hash_index[max])
+      start_node = include_max ? node : predecessor_node_of(node)
+      return [start_node, reconstruct_stack_desc(start_node)]
+    end
 
-  # Traverses nodes with keys greater than the specified key in descending order.
-  #
-  # @param node [Node] the current node
-  # @param key [Object] the lower bound (exclusive)
-  # @yield [key, value] each matching key-value pair in descending order
-  # @return [void]
-  def traverse_gt_desc(node, key, safe: false, &block) =
-    traverse_range_desc(node, key, nil, false, false, safe: safe, &block)
+    # 3. Fallback to tree search from root
+    stack = []
+    current = @root
+    while current != @nil_node
+      if max && ((current.key <=> max) > 0 || (!include_max && (current.key <=> max) == 0))
+        current = current.left
+      else
+        stack << current
+        current = current.right
+      end
+    end
+    [@nil_node, stack]
+  end
 
-  # Traverses nodes with keys greater than or equal to the specified key in descending order.
-  #
-  # @param node [Node] the current node
-  # @param key [Object] the lower bound (inclusive)
-  # @yield [key, value] each matching key-value pair in descending order
-  # @return [void]
-  def traverse_gte_desc(node, key, safe: false, &block) =
-    traverse_range_desc(node, key, nil, true, false, safe: safe, &block)
+  # Reconstructs the stack for descending traversal.
+  #
+  # @param node [Node] the node to reconstruct the stack from
+  # @return [Array] the reconstructed stack
+  def reconstruct_stack_desc(node)
+    return [] if node == @nil_node
+    stack = []
+    curr = node
+    while (p = curr.parent) != @nil_node
+      stack << p if curr == p.right
+      curr = p
+    end
+    stack.reverse!
+    stack
+  end
 
-  # Traverses nodes with keys within the specified range in descending order.
+  # Traverses the tree in descending order.
   #
-  # @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 in descending order
-  # @return [void]
-  def traverse_between_desc(node, min, max, include_min, include_max, safe: false, &block) =
-    traverse_range_desc(node, min, max, include_min, include_max, safe: safe, &block)
+  # @param current [Node] the current node
+  # @param stack [Array] the stack of nodes to traverse
+  # @param min [Object] the minimum key to traverse to
+  # @param include_min [Boolean] whether to include the minimum key
+  # @yield [Array(Object, Object)] each key-value pair
+  # @yieldparam key [Object] the key
+  # @yieldparam val [Object] the value
+  def traverse_from_desc(current, stack, min, include_min, &block)
+    while current != @nil_node || !stack.empty?
+      if current != @nil_node
+        if min
+          cmp = current.key <=> min
+          if cmp <= 0
+            yield current.pair if include_min && cmp == 0
+            return
+          end
+        end
+        yield current.pair
+        current = current.left
+        while current != @nil_node
+          stack << current
+          current = current.right
+        end
+      else
+        current = stack.pop
+      end
+    end
+  end
 
   # Restores red-black tree properties after insertion.
   #
@@ -1012,6 +1085,10 @@ class RBTree
     if next_min_node
       @min_node = next_min_node
     end
+    if z == @max_node
+       next_max_node = predecessor_node_of(z)
+       @max_node = next_max_node
+    end
 
     value = z.value
     release_node(z)
@@ -1104,6 +1181,13 @@ class RBTree
   # @param key [Numeric] the target key
   # @return [Node] the nearest node, or @nil_node if tree is empty
   def find_nearest_node(key)
+    raise ArgumentError, "key must be Numeric" unless key.is_a?(Numeric)
+
+    # If key is larger than max_key, return max_node
+    return @max_node if @max_node != @nil_node && key >= @max_node.key
+    # If key is smaller than min_key, return min_node
+    return @min_node if @min_node != @nil_node && key <= @min_node.key
+
     current = @root
     closest = @nil_node
     min_dist = nil
@@ -1144,21 +1228,11 @@ class RBTree
   # @param key [Object] the reference key
   # @return [Node] the predecessor node, or @nil_node if none exists
   def find_predecessor_node(key)
-    # Check if key exists using O(1) hash lookup
+    # If key is larger than max_key, return max_node
+    return @max_node if max_key && (key <=> max_key) > 0
+    # If key exists using O(1) hash lookup, return predecessor node
     if (node = @hash_index[key])
-      # Key exists: find predecessor in subtree or ancestors
-      if node.left != @nil_node
-        return rightmost(node.left)
-      else
-        # Walk up to find first ancestor where we came from the right
-        current = node
-        parent = current.parent
-        while parent != @nil_node && current == parent.left
-          current = parent
-          parent = parent.parent
-        end
-        return parent
-      end
+      return predecessor_node_of(node)
     end
 
     # Key doesn't exist: descend tree tracking the best candidate
@@ -1194,25 +1268,14 @@ class RBTree
   # @param key [Object] the reference key
   # @return [Node] the successor node, or @nil_node if none exists
   def find_successor_node(key)
+    # If key is larger than or equal to max_key, return nil
+    return @nil_node if max_key && (key <=> max_key) >= 0
     # If key is smaller than min_key, return min_node
-    return @min_node if min_key && key < min_key
-    # Check if key exists using O(1) hash lookup
+    return @min_node if min_key && (key <=> min_key) < 0
+    # If key exists using O(1) hash lookup, return successor node
     if (node = @hash_index[key])
-      # Key exists: find successor in subtree or ancestors
-      if node.right != @nil_node
-        return leftmost(node.right)
-      else
-        # Walk up to find first ancestor where we came from the left
-        current = node
-        parent = current.parent
-        while parent != @nil_node && current == parent.right
-          current = parent
-          parent = parent.parent
-        end
-        return parent
-      end
+      return successor_node_of(node)
     end
-
     # Key doesn't exist: descend tree tracking the best candidate
     current = @root
     successor = @nil_node
@@ -1268,7 +1331,7 @@ class RBTree
   # Returns the maximum key-value pair.
   #
   # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
-  def find_max = ((n = rightmost(@root)) != @nil_node) && n.pair
+  def find_max = ((n = @max_node) != @nil_node) && n.pair
 
   # Performs a left rotation on the given node.
   #
@@ -1499,7 +1562,6 @@ class MultiRBTree < RBTree
   #   tree.get(1, last: true)  # => "second"
   def value(key, last: false) = @hash_index[key]&.value&.send(last ? :last : :first)
   alias :get :value
-  alias :[] :value
 
   # Retrieves the first value associated with the given key.
   #
@@ -1673,47 +1735,15 @@ class MultiRBTree < RBTree
   #   tree.insert(1, 'first')
   #   tree.insert(1, 'second')  # adds another value for key 1
   def insert_entry(key, value, **)
-    if (node = @hash_index[key])
-      node.value << value
+    insert_entry_generic(key) do |node, is_new|
       @value_count += 1
-      return true
-    end
-    y = @nil_node
-    x = @root
-    while x != @nil_node
-      y = x
-      cmp = key <=> x.key
-      if cmp == 0
-        x.value << value
-        @value_count += 1
-        return true
-      elsif cmp < 0
-        x = x.left
+      if is_new
+        [value]
       else
-        x = x.right
+        node.value << value
+        true
       end
     end
-    z = allocate_node(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)
-    @value_count += 1
-    
-    if @min_node == @nil_node || (key <=> @min_node.key) < 0
-      @min_node = z
-    end
-    
-    @hash_index[key] = z  # Add to hash index
-    true
   end
 
   # Traverses the tree in ascending order, yielding each key-value pair.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbtree-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.5
 platform: ruby
 authors:
 - Masahito Suzuki