rbtree-ruby 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 911e435d0a205afc1a62791f857ac66d6d6300d2aa332566aa916e65e16148d2
-  data.tar.gz: d1a2b2aec3404901985cfec8a54c5b3df87d12bd4c8872833ba111dd3641033b
+  metadata.gz: 18d0cdfd5f115b61096c266d9de0a482e263574aad1dfce425efaabd3dad67b7
+  data.tar.gz: 639a4f4f85c14cab4acf93f5b9b5280fb6225c96c575cac1a47b2b4f934dca8e
 SHA512:
-  metadata.gz: 6b1a96900494faa73b223e5905897299799c9a5432aa6cbdd95c6881c48c8666fe82f1653907231918fd027413eed3036da64a21087bfded6307a434c3de63b2
-  data.tar.gz: 6456acef3636bf7f857611a22407c4f4a053c632a973b2dfc05913d99b55a338c3a4dbce41d03074c7589354cc4bad2765c5e4be683d2a080248ea30b6a22b04
+  metadata.gz: e40c1a174c7f2dd1c6df7f94e316070178457e0baa41322baa0f622157eb548245bfd334435488d3a49cfe8396e8d587ae80f886a17dadbf93cd9f03fcd701d7
+  data.tar.gz: 20f49f91135a98e4b46ccb4b0981dafab6bb35a9375bfb06024b7b42f5c71ad04b23613ad5a1f372ac6456d9edf03ef9698b68ca2228e0cf5cb85d6c2ae2b5f4

data/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.6] - 2026-01-28
+
+### Added
+
+> **Note:** All methods added in this release are **convenience methods** composed from existing public API primitives (`each`, `insert`, `delete`, `dup`, `merge!`, `safe: true`). They provide no speed advantage over manual composition — their value is purely in readability and API completeness.
+
+- **`dup` (Deep Copy)**: `RBTree` and `MultiRBTree` now support `dup` and `clone` via `initialize_copy`. Creates an independent deep copy of the tree — modifications to the copy do not affect the original and vice versa.
+- **`select`**: Returns a new tree containing only key-value pairs for which the block returns true. Returns an `Enumerator` if no block is given.
+- **`reject`**: Returns a new tree excluding key-value pairs for which the block returns true. Returns an `Enumerator` if no block is given.
+- **`delete_if`**: Deletes key-value pairs in place for which the block returns true. Returns self. In `MultiRBTree`, operates at individual value granularity (can remove specific values without deleting the entire key).
+- **`reject!`**: Same as `delete_if`, but returns `nil` if no changes were made.
+- **`keep_if`**: Keeps only key-value pairs for which the block returns true, deleting the rest in place. Returns self. In `MultiRBTree`, operates at individual value granularity.
+- **`invert`**: Returns a new tree with keys and values swapped. For `RBTree`, duplicate values result in the last key winning (same as `Hash#invert`). For `MultiRBTree`, all pairs are preserved.
+- **`merge`** (non-destructive): Returns a new tree with merged contents. Supports block for duplicate key resolution: `tree.merge(other) { |key, v1, v2| v1 }`.
+- **`merge!` block support**: `merge!` now accepts a block for duplicate key resolution, matching `Hash#merge!` behavior.
+
+### Optimized
+- **`MultiRBTree#delete_if` / `#keep_if`**: Replaced clear-and-rebuild approach with in-place value array filtering via internal `filter_values!`. Avoids O(n log n) tree reconstruction; now runs in O(n) by directly mutating each node's value array and removing only emptied nodes.
+
+### Fixed
+- **`MultiRBTree#clear`**: Fixed `@value_count` not being reset when `clear` was called, which caused `size` to return incorrect values after clearing and re-inserting.
+
+## [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
@@ -219,6 +252,8 @@ 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.4.0]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.4.0
+[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

data/README.ja.md

@@ -197,10 +197,58 @@ tree.to_a  # => [[1, "one"], [2, "two"]]
 # ハッシュへの変換
 tree.to_h  # => {1 => "one", 2 => "two"}
 
-# 他のツリー、ハッシュ、またはEnumerableの結合
+# 結合（破壊的）
 other = {3 => 'three'}
 tree.merge!(other)
 tree.size  # => 3
+
+# 結合（非破壊） — 新しいツリーを返す
+merged = tree.merge({4 => 'four'})
+
+# ブロックで重複キーの解決
+merged = tree.merge({1 => 'ONE'}) { |key, old_val, new_val| old_val }
+
+# キーと値を入れ替え
+tree = RBTree.new({1 => 'a', 2 => 'b', 3 => 'c'})
+tree.invert.to_a  # => [["a", 1], ["b", 2], ["c", 3]]
+```
+
+### フィルタリングとコピー
+
+> **注記:** `dup`、`select`、`reject`、`delete_if`、`reject!`、`keep_if`、`invert`、`merge` は既存のプリミティブを組み合わせた利便性メソッドです。手動で同等の処理を書いた場合と比べて速度上の利点はありません。可読性とAPI互換性のために提供されています。
+
+Rubyの慣習的なメソッドでツリーのコピーやフィルタリングが可能です:
+
+```ruby
+tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
+
+# ディープコピー — 元のツリーと独立
+copy = tree.dup
+copy.delete(1)
+tree.size  # => 4 (変更なし)
+
+# select / reject — 新しいツリーを返す
+evens = tree.select { |k, _| k.even? }   # => {2=>"two", 4=>"four"}
+odds  = tree.reject { |k, _| k.even? }   # => {1=>"one", 3=>"three"}
+
+# delete_if / keep_if — 破壊的に変更
+tree.delete_if { |k, _| k > 2 }
+tree.to_a  # => [[1, "one"], [2, "two"]]
+
+# reject! — delete_ifと同様だが、変更がなければnilを返す
+tree.reject! { |_, _| false }  # => nil
+```
+
+`MultiRBTree`では、`delete_if`と`keep_if`は個々の値単位で操作します:
+
+```ruby
+tree = MultiRBTree.new
+tree.insert(1, 'a')
+tree.insert(1, 'b')
+tree.insert(2, 'c')
+
+tree.delete_if { |k, v| k == 1 && v == 'a' }
+tree.to_a  # => [[1, "b"], [2, "c"]]  — 'a'のみ削除された
 ```
 
 ### MultiRBTree 値配列アクセス
@@ -239,10 +287,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

@@ -197,10 +197,58 @@ tree.to_a  # => [[1, "one"], [2, "two"]]
 # Convert to Hash
 tree.to_h  # => {1 => "one", 2 => "two"}
 
-# Merge another tree, hash, or enumerable
+# Merge (destructive)
 other = {3 => 'three'}
 tree.merge!(other)
 tree.size  # => 3
+
+# Merge (non-destructive) — returns a new tree
+merged = tree.merge({4 => 'four'})
+
+# Merge with block for duplicate key resolution
+merged = tree.merge({1 => 'ONE'}) { |key, old_val, new_val| old_val }
+
+# Invert keys and values
+tree = RBTree.new({1 => 'a', 2 => 'b', 3 => 'c'})
+tree.invert.to_a  # => [["a", 1], ["b", 2], ["c", 3]]
+```
+
+### Filtering and Copying
+
+> **Note:** `dup`, `select`, `reject`, `delete_if`, `reject!`, `keep_if`, `invert`, and `merge` are convenience methods composed from existing primitives. They provide no speed advantage over manual composition — their value is in readability and API completeness.
+
+Create copies or filter trees using familiar Ruby idioms:
+
+```ruby
+tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
+
+# Deep copy — independent of original
+copy = tree.dup
+copy.delete(1)
+tree.size  # => 4 (unchanged)
+
+# select / reject — return a new tree
+evens = tree.select { |k, _| k.even? }   # => {2=>"two", 4=>"four"}
+odds  = tree.reject { |k, _| k.even? }   # => {1=>"one", 3=>"three"}
+
+# delete_if / keep_if — modify in place
+tree.delete_if { |k, _| k > 2 }
+tree.to_a  # => [[1, "one"], [2, "two"]]
+
+# reject! — like delete_if, but returns nil if nothing changed
+tree.reject! { |_, _| false }  # => nil
+```
+
+For `MultiRBTree`, `delete_if` and `keep_if` operate at individual value granularity:
+
+```ruby
+tree = MultiRBTree.new
+tree.insert(1, 'a')
+tree.insert(1, 'b')
+tree.insert(2, 'c')
+
+tree.delete_if { |k, v| k == 1 && v == 'a' }
+tree.to_a  # => [[1, "b"], [2, "c"]]  — only 'a' was removed
 ```
 
 ### MultiRBTree Value Array Access
@@ -239,10 +287,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.4"
+  VERSION = "0.3.6"
 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
@@ -110,6 +111,16 @@ class RBTree
     end
   end
 
+  # Creates a deep copy of the tree.
+  # Called automatically by `dup` and `clone`.
+  #
+  # @param orig [RBTree] the original tree to copy
+  # @return [void]
+  def initialize_copy(orig)
+    initialize(overwrite: orig.instance_variable_get(:@overwrite))
+    orig.each { |k, v| insert(k, v) }
+  end
+
   # Returns a Hash containing all key-value pairs from the tree.
   #
   # @return [Hash] a new Hash with the tree's contents
@@ -368,16 +379,43 @@ class RBTree
   end
   alias :[]= :insert
   
+  # Returns a new tree containing the merged contents of self and other.
+  #
+  # When a block is given, it is called with (key, old_value, new_value) for
+  # duplicate keys, and the block's return value is used.
+  #
+  # @param other [RBTree, Hash, Enumerable] the source to merge from
+  # @yield [key, old_value, new_value] called for duplicate keys when block given
+  # @return [RBTree] a new tree with merged contents
+  def merge(other, &block)
+    dup.merge!(other, &block)
+  end
+
   # Merges the contents of another tree, hash, or enumerable into this tree.
   #
+  # When a block is given, it is called with (key, old_value, new_value) for
+  # duplicate keys, and the block's return value is used.
+  #
   # @param other [RBTree, Hash, Enumerable] the source to merge from
-  # @param overwrite [Boolean] whether to overwrite existing keys (default: true)
+  # @param overwrite [Boolean] whether to overwrite existing keys (default: true). Ignored if block given.
+  # @yield [key, old_value, new_value] called for duplicate keys when block given
   # @return [RBTree] self
-  def merge!(other, overwrite: true)
+  def merge!(other, overwrite: true, &block)
     if defined?(MultiRBTree) && other.is_a?(MultiRBTree)
       raise ArgumentError, "Cannot merge MultiRBTree into RBTree"
     end
-    insert(other, overwrite: overwrite)
+    if block
+      other_enum = other.is_a?(Hash) || other.is_a?(RBTree) ? other : other.each
+      other_enum.each do |k, v|
+        if has_key?(k)
+          insert_entry(k, block.call(k, value(k), v), overwrite: true)
+        else
+          insert_entry(k, v)
+        end
+      end
+    else
+      insert(other, overwrite: overwrite)
+    end
     self
   end
 
@@ -418,7 +456,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
@@ -428,7 +466,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
@@ -484,11 +522,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
 
@@ -530,11 +564,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
 
@@ -551,11 +581,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
 
@@ -572,11 +598,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
 
@@ -593,11 +615,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
 
@@ -617,14 +635,76 @@ 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
+
+  # Returns a new tree containing key-value pairs for which the block returns true.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, Enumerator] a new tree with selected pairs, or Enumerator if no block
+  def select(&block)
+    return enum_for(__method__) { size } unless block_given?
+    result = self.class.new
+    each { |k, v| result.insert(k, v) if block.call(k, v) }
+    result
+  end
+
+  # Returns a new tree containing key-value pairs for which the block returns false.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, Enumerator] a new tree with non-rejected pairs, or Enumerator if no block
+  def reject(&block)
+    return enum_for(__method__) { size } unless block_given?
+    result = self.class.new
+    each { |k, v| result.insert(k, v) unless block.call(k, v) }
+    result
+  end
+
+  # Deletes key-value pairs for which the block returns true. Returns nil if no changes were made.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, nil, Enumerator] self if changed, nil if unchanged, or Enumerator if no block
+  def reject!(&block)
+    return enum_for(__method__) { size } unless block_given?
+    size_before = size
+    delete_if(&block)
+    size == size_before ? nil : self
+  end
+
+  # Keeps key-value pairs for which the block returns true, deleting the rest. Modifies the tree in place.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, Enumerator] self, or Enumerator if no block
+  def keep_if(&block)
+    return enum_for(__method__) { size } unless block_given?
+    each(safe: true) { |k, v| delete(k) unless block.call(k, v) }
     self
   end
 
+  # Deletes key-value pairs for which the block returns true. Modifies the tree in place.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, Enumerator] self, or Enumerator if no block
+  def delete_if(&block)
+    return enum_for(__method__) { size } unless block_given?
+    each(safe: true) { |k, v| delete(k) if block.call(k, v) }
+    self
+  end
+
+  # Returns a new tree with keys and values swapped.
+  #
+  # For RBTree, duplicate values result in later keys overwriting earlier ones.
+  # For MultiRBTree, all key-value pairs are preserved.
+  # Values must implement <=> to serve as keys in the new tree.
+  #
+  # @return [RBTree, MultiRBTree] a new tree with keys and values inverted
+  def invert
+    result = self.class.new
+    each { |k, v| result.insert(v, k) }
+    result
+  end
+
   # Returns a string representation of the tree.
   #
   # Shows the first 5 entries and total size. Useful for debugging.
@@ -655,9 +735,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.
   #
@@ -666,27 +745,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
@@ -703,14 +806,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
@@ -718,56 +841,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
@@ -775,164 +873,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.
   #
@@ -1036,6 +1188,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)
@@ -1128,6 +1284,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
@@ -1168,21 +1331,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
@@ -1218,25 +1371,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
@@ -1292,7 +1434,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.
   #
@@ -1477,6 +1619,13 @@ class MultiRBTree < RBTree
   # Returns the number of values stored in the tree.
   # @return [Integer] the number of values in the tree
   def size = @value_count
+
+  # Removes all elements from the tree.
+  # @return [MultiRBTree] self
+  def clear
+    @value_count = 0
+    super
+  end
   
   # Returns the minimum key-value pair without removing it.
   #
@@ -1679,9 +1828,46 @@ class MultiRBTree < RBTree
     [key, val]
   end
 
+  # Keeps key-value pairs for which the block returns true, deleting the rest.
+  # Unlike RBTree, this removes individual values rather than entire keys.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [MultiRBTree, Enumerator] self, or Enumerator if no block
+  def keep_if(&block)
+    return enum_for(__method__) { size } unless block_given?
+    filter_values! { |k, v| block.call(k, v) }
+    self
+  end
+
+  # Deletes key-value pairs for which the block returns true.
+  # Unlike RBTree, this removes individual values rather than entire keys.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [MultiRBTree, Enumerator] self, or Enumerator if no block
+  def delete_if(&block)
+    return enum_for(__method__) { size } unless block_given?
+    filter_values! { |k, v| !block.call(k, v) }
+    self
+  end
+
   # @!visibility private
   private
 
+  # Filters values in-place across all nodes.
+  # Keeps only values for which the block returns true.
+  # Removes nodes whose value arrays become empty.
+  # Updates @value_count accordingly.
+  def filter_values!
+    keys_to_delete = []
+    @hash_index.each do |key, node|
+      before = node.value.size
+      node.value.select! { |v| yield key, v }
+      @value_count -= before - node.value.size
+      keys_to_delete << key if node.value.empty?
+    end
+    keys_to_delete.each { |k| delete_indexed_node(k) }
+  end
+
   # Inserts a value for the given key.
   #
   # If the key already exists, the value is appended to its list.
@@ -1696,47 +1882,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.4
+  version: 0.3.6
 platform: ruby
 authors:
 - Masahito Suzuki