rbtree-ruby 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea4c407bb808b5f0ce61e05d95bdb1b9a7efce1a6db4ef6c5688016d39eb66a1
-  data.tar.gz: 1dec0818d2844494de2daf36cca3b018d28589316b580d71879756e34ca3adb0
+  metadata.gz: 13b088e9f0f8ab5cf80a77b8f9b8e1af73b94b33bdff90115fe575def2c54b11
+  data.tar.gz: 51636a7c22c4ccc70d2ac14bafc58a39bbccac7599a704506c280d8d39345117
 SHA512:
-  metadata.gz: 654691a199723dd0b7426fea9165b372f4c71bcdadc8a58a90b76352b8eaade41145270ff6f88ffb37a4a22732a46b636d21515a07d4ae18b061c5d6fb154d53
-  data.tar.gz: 8e619ef4f92f440e92350748bfaadc80dc65f8a1daed06d6df1b73e20c4228ee943677496f56e9a8e413cb7081b8d98e6c7711a0b6ffe50fcbf8ab00bb65ed5a
+  metadata.gz: e543801d0b22de4ee8654f7b8164121c2107ccda64bc16f47d034e98526703e4aa444e03cecd225bddb9aa9fc5547813bcd1bc73cd4a4048df98eee5d41a2fc6
+  data.tar.gz: 6d6986550fe2293e971558e65119f230c3eb26e8f43f8af77fe8bf666d5df337c6bf23e36a4e4fd7e8aee86287b6f58579e48a637e66d27a6e80ab66b0010ed4

data/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.2.2] - 2026-01-14
+
+### Changed
+- **Iterative Traversal (Complete)**: All traversal methods (`lt`, `lte`, `gt`, `gte`, `between` and their `_desc` variants) now use an iterative stack-based approach instead of recursion.
+  - Ensures deep trees can be traversed without `SystemStackError`.
+  - Applies to both `RBTree` and `MultiRBTree`.
+- **Code Deduplication**: Unified traversal logic between `RBTree` and `MultiRBTree` for better maintainability.
+- **Documentation**: Minor typo fixes.
+
+### Fixed
+- **MultiRBTree#prev / #succ**: Fixed incorrect use of bare `super` which forwarded keyword arguments to parent methods that don't accept them. Also fixed incorrect access to parent return value (was treating `[key, value]` pair as a node object).
+- **MultiRBTree#shift / #pop hash index leak**: When `shift` or `pop` removed the last value for a key, the key remained in the internal hash index (`@hash_index`). Now correctly uses `delete_node(key)` instead of `remove_node(node)` to ensure hash index consistency.
+
+## [0.2.1] - 2026-01-14
+
+### Added
+- **Enhanced iteration**: `each` now accepts `reverse:` and `safe:` options
+  - `tree.each(reverse: true) { ... }` (same as `reverse_each`)
+  - `tree.each(safe: true) { ... }` (modification-safe)
+  - `tree.each(reverse: true, safe: true) { ... }` (reverse modification-safe)
+  - In `MultiRBTree`, `reverse: true` also iterates over values in reverse insertion order.
+- **Range query safe mode**: `safe:` option for `lt`, `lte`, `gt`, `gte`, `between`
+  - `tree.lt(10, safe: true) { |k, _| tree.delete(k) if k.even? }`
+  - Works with `:reverse` option: `tree.gt(5, reverse: true, safe: true)`
+  - Returns Enumerator: `tree.between(1, 100, safe: true).select { ... }`
+
+### Changed
+- **MultiRBTree#get_all**: Now returns an `Enumerator` instead of an `Array` when no block is given.
+  - Improves consistency with other iteration methods.
+  - Safe handling for non-existent keys (returns empty Enumerator/nil logic handled safely).
+  - Use `.to_a` to get an Array: `tree.get_all(key).to_a`
+
 ## [0.2.0] - 2026-01-14
 
 ### Added

data/README.ja.md

@@ -2,7 +2,8 @@
 
 🌍 *[English](README.md) | [日本語](README.ja.md)*
 
-Red-Black Tree（赤黒木）データ構造のピュアRuby実装です。挿入、削除、検索操作がO(log n)の時間計算量で実行できる、効率的な順序付きキーバリューストレージを提供します。
+Red-Black Tree（赤黒木）データ構造のピュアRuby実装です。挿入、削除、検索操作がO(log n)の時間計算量で実行できる、
+効率的な順序付きキーバリューストレージを提供します。
 
 ## 特徴
 
@@ -60,6 +61,12 @@ tree.each { |key, value| puts "#{key}: #{value}" }
 # 10: ten
 # 20: twenty
 
+# イテレーション中の変更
+# 標準のHashやArrayとは異なり、`safe: true`オプションを指定することで
+# イテレーション中に安全にキーの削除や挿入を行うことができます。
+tree.each(safe: true) { |k, v| tree.delete(k) if k.even? }
+tree.each(reverse: true) { |k, v| puts k }  # reverse_eachと同じ
+
 # 最小値と最大値
 tree.min  # => [1, "one"]
 tree.max  # => [20, "twenty"]
@@ -100,8 +107,8 @@ tree.size  # => 4 (キーバリューペアの総数)
 tree.get(1)      # => "first one"
 tree[1]          # => "first one"
 
-# キーの全ての値を取得
-tree.get_all(1)  # => ["first one", "second one", "third one"]
+# キーの全ての値を取得（Enumeratorを返す）
+tree.get_all(1).to_a  # => ["first one", "second one", "third one"]
 
 # 全キーバリューペアをイテレーション
 tree.each { |k, v| puts "#{k}: #{v}" }

data/README.md

@@ -2,7 +2,8 @@
 
 🌍 *[English](README.md) | [日本語](README.ja.md)*
 
-A pure Ruby implementation of the Red-Black Tree data structure, providing efficient ordered key-value storage with O(log n) time complexity for insertion, deletion, and lookup operations.
+A pure Ruby implementation of the Red-Black Tree data structure, providing efficient ordered
+key-value storage with O(log n) time complexity for insertion, deletion, and lookup operations.
 
 ## Features
 
@@ -60,6 +61,12 @@ tree.each { |key, value| puts "#{key}: #{value}" }
 # 10: ten
 # 20: twenty
 
+# Modification during iteration
+# Unlike standard Ruby Hash/Array, modification during iteration is fully supported
+# with the `safe: true` option. This allows you to delete or insert keys safely while iterating.
+tree.each(safe: true) { |k, v| tree.delete(k) if k.even? }
+tree.each(reverse: true) { |k, v| puts k }  # Same as reverse_each
+
 # Min and max
 tree.min  # => [1, "one"]
 tree.max  # => [20, "twenty"]
@@ -100,8 +107,8 @@ tree.size  # => 4 (total number of key-value pairs)
 tree.get(1)      # => "first one"
 tree[1]          # => "first one"
 
-# Get all values for a key
-tree.get_all(1)  # => ["first one", "second one", "third one"]
+# Get all values for a key (returns Enumerator)
+tree.get_all(1).to_a  # => ["first one", "second one", "third one"]
 
 # Iterate over all key-value pairs
 tree.each { |k, v| puts "#{k}: #{v}" }

data/lib/rbtree/version.rb

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

data/lib/rbtree.rb

@@ -112,26 +112,27 @@ class RBTree
     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
 
+  # 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 = find_min
+
+  # 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 = find_max
+
   # Checks if the tree contains the given key.
   #
   # @param key [Object] the key to search for
@@ -158,6 +159,58 @@ class RBTree
   end
   alias_method :[], :get
 
+  # 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.pair
+  end
+
+  # Returns the key-value pair with the largest key that is smaller than the given key.
+  #
+  # If the key exists in the tree, returns the predecessor (previous element).
+  # If the key does not exist, returns the largest key-value pair with key < given key.
+  #
+  # @param key [Object] the reference key
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if no predecessor exists
+  # @example
+  #   tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
+  #   tree.prev(5)   # => [3, "three"]
+  #   tree.prev(4)   # => [3, "three"] (4 does not exist)
+  #   tree.prev(1)   # => nil (no predecessor)
+  def prev(key)
+    n = find_predecessor_node(key)
+    n == @nil_node ? nil : n.pair
+  end
+
+  # Returns the key-value pair with the smallest key that is larger than the given key.
+  #
+  # If the key exists in the tree, returns the successor (next element).
+  # If the key does not exist, returns the smallest key-value pair with key > given key.
+  #
+  # @param key [Object] the reference key
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if no successor exists
+  # @example
+  #   tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
+  #   tree.succ(5)   # => [7, "seven"]
+  #   tree.succ(4)   # => [5, "five"] (4 does not exist)
+  #   tree.succ(7)   # => nil (no successor)
+  def succ(key)
+    n = find_successor_node(key)
+    n == @nil_node ? nil : n.pair
+  end
+
   # Inserts or updates a key-value pair in the tree.
   #
   # If the key already exists and overwrite is true (default), the value is updated.
@@ -233,17 +286,6 @@ class RBTree
     value
   end
 
-  # Removes all key-value pairs from the tree.
-  #
-  # @return [RBTree] self
-  def clear
-    @root = @nil_node
-    @min_node = @nil_node
-    @hash_index.clear
-    @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
@@ -268,13 +310,26 @@ class RBTree
   def pop
     n = rightmost(@root)
     return nil if n == @nil_node
-    result = [n.key, n.value]
+    result = n.pair
     delete(n.key)
     result
   end
 
-  # Iterates over all key-value pairs in ascending order of keys.
+  # Removes all key-value pairs from the tree.
+  #
+  # @return [RBTree] self
+  def clear
+    @root = @nil_node
+    @min_node = @nil_node
+    @hash_index.clear
+    @size = 0
+    self
+  end
+
+  # Iterates over all key-value pairs in ascending (or descending) order.
   #
+  # @param reverse [Boolean] if true, iterate in descending order (default: false)
+  # @param safe [Boolean] if true, safe for modifications during iteration (default: false)
   # @yield [key, value] each key-value pair in the tree
   # @return [Enumerator, RBTree] an Enumerator if no block is given, self otherwise
   # @example
@@ -284,9 +339,22 @@ class RBTree
   #   # 1: one
   #   # 2: two
   #   # 3: three
-  def each(&block)
-    return enum_for(:each) unless block_given?
-    traverse_asc(@root, &block)
+  #
+  #   # Reverse iteration
+  #   tree.each(reverse: true) { |k, v| ... }
+  #
+  #   # Safe iteration for modifications
+  #   tree.each(safe: true) do |k, v|
+  #     tree.delete(k) if k.even?
+  #   end
+  def each(reverse: false, safe: false, &block)
+    return enum_for(:each, reverse: reverse, safe: safe) unless block_given?
+    if reverse
+      traverse_all_desc(@root, safe: safe, &block)
+    else
+      traverse_all_asc(@root, safe: safe, &block)
+    end
+    self
   end
 
   # Iterates over all key-value pairs in descending order of keys.
@@ -300,49 +368,34 @@ class RBTree
   #   # 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.
+  # Iterates over all key-value pairs in descending order of keys.
   #
-  # @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.
+  # This is an alias for `each(reverse: true)`.
   #
-  # @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
+  # @param safe [Boolean] if true, safe for modifications during iteration (default: false)
+  # @yield [key, value] each key-value pair in the tree
+  # @return [Enumerator, RBTree] an Enumerator if no block is given, self otherwise
+  # @see #each
+  def reverse_each(safe: false, &block) = each(reverse: true, safe: safe, &block)
 
   # Retrieves all key-value pairs with keys less than the specified key.
   #
   # @param key [Object] the upper bound (exclusive)
   # @param reverse [Boolean] if true, iterate in descending order (default: false)
+  # @param safe [Boolean] if true, safe for modifications during iteration (default: false)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
   #   tree.lt(3).to_a  # => [[1, "one"], [2, "two"]]
   #   tree.lt(3, reverse: true).first  # => [2, "two"]
-  #   tree.lt(3) { |k, v| puts k }  # prints keys, returns self
-  def lt(key, reverse: false, &block)
-    return enum_for(:lt, key, reverse: reverse) unless block_given?
+  #   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(:lt, key, reverse: reverse, safe: safe) unless block_given?
     if reverse
-      traverse_lt_desc(@root, key, &block)
+      traverse_lt_desc(@root, key, safe: safe, &block)
     else
-      traverse_lt(@root, key, &block)
+      traverse_lt_asc(@root, key, safe: safe, &block)
     end
     self
   end
@@ -351,18 +404,19 @@ class RBTree
   #
   # @param key [Object] the upper bound (inclusive)
   # @param reverse [Boolean] if true, iterate in descending order (default: false)
+  # @param safe [Boolean] if true, safe for modifications during iteration (default: false)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
   #   tree.lte(3).to_a  # => [[1, "one"], [2, "two"], [3, "three"]]
   #   tree.lte(3, reverse: true).first  # => [3, "three"]
-  def lte(key, reverse: false, &block)
-    return enum_for(:lte, key, reverse: reverse) unless block_given?
+  def lte(key, reverse: false, safe: false, &block)
+    return enum_for(:lte, key, reverse: reverse, safe: safe) unless block_given?
     if reverse
-      traverse_lte_desc(@root, key, &block)
+      traverse_lte_desc(@root, key, safe: safe, &block)
     else
-      traverse_lte(@root, key, &block)
+      traverse_lte_asc(@root, key, safe: safe, &block)
     end
     self
   end
@@ -371,18 +425,19 @@ class RBTree
   #
   # @param key [Object] the lower bound (exclusive)
   # @param reverse [Boolean] if true, iterate in descending order (default: false)
+  # @param safe [Boolean] if true, safe for modifications during iteration (default: false)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
   #   tree.gt(2).to_a  # => [[3, "three"], [4, "four"]]
   #   tree.gt(2, reverse: true).first  # => [4, "four"]
-  def gt(key, reverse: false, &block)
-    return enum_for(:gt, key, reverse: reverse) unless block_given?
+  def gt(key, reverse: false, safe: false, &block)
+    return enum_for(:gt, key, reverse: reverse, safe: safe) unless block_given?
     if reverse
-      traverse_gt_desc(@root, key, &block)
+      traverse_gt_desc(@root, key, safe: safe, &block)
     else
-      traverse_gt(@root, key, &block)
+      traverse_gt_asc(@root, key, safe: safe, &block)
     end
     self
   end
@@ -391,18 +446,19 @@ class RBTree
   #
   # @param key [Object] the lower bound (inclusive)
   # @param reverse [Boolean] if true, iterate in descending order (default: false)
+  # @param safe [Boolean] if true, safe for modifications during iteration (default: false)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
   #   tree.gte(2).to_a  # => [[2, "two"], [3, "three"], [4, "four"]]
   #   tree.gte(2, reverse: true).first  # => [4, "four"]
-  def gte(key, reverse: false, &block)
-    return enum_for(:gte, key, reverse: reverse) unless block_given?
+  def gte(key, reverse: false, safe: false, &block)
+    return enum_for(:gte, key, reverse: reverse, safe: safe) unless block_given?
     if reverse
-      traverse_gte_desc(@root, key, &block)
+      traverse_gte_desc(@root, key, safe: safe, &block)
     else
-      traverse_gte(@root, key, &block)
+      traverse_gte_asc(@root, key, safe: safe, &block)
     end
     self
   end
@@ -414,72 +470,36 @@ class RBTree
   # @param include_min [Boolean] whether to include the lower bound (default: true)
   # @param include_max [Boolean] whether to include the upper bound (default: true)
   # @param reverse [Boolean] if true, iterate in descending order (default: false)
+  # @param safe [Boolean] if true, safe for modifications during iteration (default: false)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four', 5 => 'five'})
   #   tree.between(2, 4).to_a  # => [[2, "two"], [3, "three"], [4, "four"]]
   #   tree.between(2, 4, reverse: true).first  # => [4, "four"]
-  def between(min, max, include_min: true, include_max: true, reverse: false, &block)
-    return enum_for(:between, min, max, include_min: include_min, include_max: include_max, reverse: reverse) unless block_given?
+  def between(min, max, include_min: true, include_max: true, reverse: false, safe: false, &block)
+    return enum_for(:between, 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, &block)
+      traverse_between_desc(@root, min, max, include_min, include_max, safe: safe, &block)
     else
-      traverse_between(@root, min, max, include_min, include_max, &block)
+      traverse_between_asc(@root, min, max, include_min, include_max, safe: safe, &block)
     end
     self
   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
-
-  # Returns the key-value pair with the largest key that is smaller than the given key.
-  #
-  # If the key exists in the tree, returns the predecessor (previous element).
-  # If the key does not exist, returns the largest key-value pair with key < given key.
-  #
-  # @param key [Object] the reference key
-  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if no predecessor exists
-  # @example
-  #   tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
-  #   tree.prev(5)   # => [3, "three"]
-  #   tree.prev(4)   # => [3, "three"] (4 does not exist)
-  #   tree.prev(1)   # => nil (no predecessor)
-  def prev(key)
-    n = find_predecessor_node(key)
-    n == @nil_node ? nil : [n.key, n.value]
-  end
-
-  # Returns the key-value pair with the smallest key that is larger than the given key.
+  # Returns a string representation of the tree.
   #
-  # If the key exists in the tree, returns the successor (next element).
-  # If the key does not exist, returns the smallest key-value pair with key > given key.
+  # Shows the first 5 entries and total size. Useful for debugging.
   #
-  # @param key [Object] the reference key
-  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if no successor exists
-  # @example
-  #   tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
-  #   tree.succ(5)   # => [7, "seven"]
-  #   tree.succ(4)   # => [5, "five"] (4 does not exist)
-  #   tree.succ(7)   # => nil (no successor)
-  def succ(key)
-    n = find_successor_node(key)
-    n == @nil_node ? nil : [n.key, n.value]
+  # @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
 
   # Validates the red-black tree properties.
@@ -504,56 +524,141 @@ class RBTree
   # 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
+  # @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 ascending order
   # @return [void]
-  def traverse_asc(node, &block)
-    stack = []
-    current = node
-    while current != @nil_node || !stack.empty?
-      while current != @nil_node
-        stack << current
-        current = current.left
+  def traverse_range_asc(node, min, max, include_min, include_max, safe: false, &block)
+    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
+      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
-      current = stack.pop
-      yield current.key, current.value
-      current = current.right
     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
+  # @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 descending order
   # @return [void]
-  def traverse_desc(node, &block)
-    stack = []
-    current = node
-    while current != @nil_node || !stack.empty?
-      while current != @nil_node
-        stack << current
-        current = current.right
+  def traverse_range_desc(node, min, max, include_min, include_max, safe: false, &block)
+    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
+      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
-      current = stack.pop
-      yield current.key, current.value
-      current = current.left
     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.
   #
   # @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
+  def traverse_lt_asc(node, key, safe: false, &block) =
+    traverse_range_asc(node, nil, key, false, false, safe: safe, &block)
 
   # Traverses nodes with keys less than or equal to the specified key.
   #
@@ -561,15 +666,8 @@ class RBTree
   # @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
+  def traverse_lte_asc(node, key, safe: false, &block) =
+    traverse_range_asc(node, nil, key, false, true, safe: safe, &block)
 
   # Traverses nodes with keys greater than the specified key.
   #
@@ -577,15 +675,8 @@ class RBTree
   # @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
+  def traverse_gt_asc(node, key, safe: false, &block) =
+    traverse_range_asc(node, key, nil, false, false, safe: safe, &block)
 
   # Traverses nodes with keys greater than or equal to the specified key.
   #
@@ -593,15 +684,8 @@ class RBTree
   # @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
+  def traverse_gte_asc(node, key, safe: false, &block) =
+    traverse_range_asc(node, key, nil, true, false, safe: safe, &block)
 
   # Traverses nodes with keys within the specified range.
   #
@@ -612,23 +696,8 @@ class RBTree
   # @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
+  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)
 
   # Traverses nodes with keys less than the specified key in descending order.
   #
@@ -636,15 +705,8 @@ class RBTree
   # @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, &block)
-    return if node == @nil_node
-    
-    if (node.key <=> key) < 0
-      traverse_lt_desc(node.right, key, &block)
-      yield node.key, node.value
-    end
-    traverse_lt_desc(node.left, key, &block)
-  end
+  def traverse_lt_desc(node, key, safe: false, &block) =
+    traverse_range_desc(node, nil, key, false, false, safe: safe, &block)
 
   # Traverses nodes with keys less than or equal to the specified key in descending order.
   #
@@ -652,15 +714,8 @@ class RBTree
   # @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, &block)
-    return if node == @nil_node
-    
-    if (node.key <=> key) <= 0
-      traverse_lte_desc(node.right, key, &block)
-      yield node.key, node.value
-    end
-    traverse_lte_desc(node.left, key, &block)
-  end
+  def traverse_lte_desc(node, key, safe: false, &block) =
+    traverse_range_desc(node, nil, key, false, true, safe: safe, &block)
 
   # Traverses nodes with keys greater than the specified key in descending order.
   #
@@ -668,15 +723,8 @@ class RBTree
   # @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, &block)
-    return if node == @nil_node
-    
-    traverse_gt_desc(node.right, key, &block)
-    if (node.key <=> key) > 0
-      yield node.key, node.value
-      traverse_gt_desc(node.left, key, &block)
-    end
-  end
+  def traverse_gt_desc(node, key, safe: false, &block) =
+    traverse_range_desc(node, key, nil, false, false, safe: safe, &block)
 
   # Traverses nodes with keys greater than or equal to the specified key in descending order.
   #
@@ -684,15 +732,8 @@ class RBTree
   # @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, &block)
-    return if node == @nil_node
-    
-    traverse_gte_desc(node.right, key, &block)
-    if (node.key <=> key) >= 0
-      yield node.key, node.value
-      traverse_gte_desc(node.left, key, &block)
-    end
-  end
+  def traverse_gte_desc(node, key, safe: false, &block) =
+    traverse_range_desc(node, key, nil, true, false, safe: safe, &block)
 
   # Traverses nodes with keys within the specified range in descending order.
   #
@@ -703,24 +744,8 @@ class RBTree
   # @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, &block)
-    return if node == @nil_node
-    
-    if (node.key <=> max) < 0
-      traverse_between_desc(node.right, 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 <=> min) > 0
-      traverse_between_desc(node.left, min, max, include_min, include_max, &block)
-    end
-  end
+  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)
 
   # Restores red-black tree properties after insertion.
   #
@@ -1011,6 +1036,16 @@ class RBTree
     predecessor
   end
 
+  # Finds the node with the largest key that is smaller than the given key.
+  # Returns the key-value pair if found, or nil if the tree is empty.
+  #
+  # @param key [Object] the reference key
+  # @return [Array(Object, Object), nil] the key-value pair, or nil if tree is empty
+  def find_predecessor(key)
+    n = find_predecessor_node(key)
+    n == @nil_node ? nil : n.pair
+  end
+
   # Finds the node with the smallest key that is larger than the given key.
   #
   # If the key exists in the tree, returns its successor node.
@@ -1051,6 +1086,16 @@ class RBTree
     successor
   end
 
+  # Finds the node with the smallest key that is larger than the given key.
+  # Returns the key-value pair if found, or nil if the tree is empty.
+  #
+  # @param key [Object] the reference key
+  # @return [Array(Object, Object), nil] the key-value pair, or nil if tree is empty
+  def find_successor(key)
+    n = find_successor_node(key)
+    n == @nil_node ? nil : n.pair
+  end
+
   # Finds the leftmost (minimum) node in a subtree.
   #
   # @param node [Node] the root of the subtree
@@ -1062,6 +1107,11 @@ class RBTree
     node
   end
 
+  # Returns the minimum key-value pair.
+  #
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  def find_min = @min_node == @nil_node ? nil : @min_node.pair
+
   # Finds the rightmost (maximum) node in a subtree.
   #
   # @param node [Node] the root of the subtree
@@ -1073,6 +1123,11 @@ class RBTree
     node
   end
 
+  # 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 ? nil : n.pair
+
   # Performs a left rotation on the given node.
   #
   # Transforms the tree structure:
@@ -1257,6 +1312,17 @@ end
 # @author Masahito Suzuki
 # @since 0.1.2
 class MultiRBTree < RBTree
+  def min(last: false)
+    return nil if @min_node == @nil_node || @min_node.value.empty?
+    [@min_node.key, last ? @min_node.value.last : @min_node.value.first]
+  end
+
+  def max(last: false)
+    n = rightmost(@root)
+    return nil if n == @nil_node || n.value.empty?
+    [n.key, last ? n.value.last : n.value.first]
+  end
+
   # Retrieves a value associated with the given key.
   #
   # @param key [Object] the key to look up
@@ -1286,26 +1352,22 @@ class MultiRBTree < RBTree
   # @return [Object, nil] the last value for the key, or nil if not found
   def get_last(key) = get(key, last: true)
 
-  # Returns the first value for the given key (for Hash-like access).
-  #
-  # Note: Unlike get(), this method does not accept options.
-  #
-  # @param key [Object] the key to look up
-  # @return [Object, nil] the first value for the key, or nil if not found
-  def [](key) = get(key)
+  def nearest(key, last: false)
+    n = find_nearest_node(key)
+    return nil if n == @nil_node || n.value.empty?
+    [n.key, last ? n.value.last : n.value.first]
+  end
 
-  # 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
+  def prev(key, last: false)
+    pair = super(key)
+    return nil unless pair
+    [pair[0], last ? pair[1].last : pair[1].first]
+  end
+  
+  def succ(key, last: false)
+    pair = super(key)
+    return nil unless pair
+    [pair[0], last ? pair[1].last : pair[1].first]
   end
 
   # Inserts a value for the given key.
@@ -1433,7 +1495,7 @@ class MultiRBTree < RBTree
     node.value.shift
     @size -= 1
     if node.value.empty?
-      remove_node(node)
+      delete_node(key)
     end
     [key, val]
   end
@@ -1441,189 +1503,38 @@ class MultiRBTree < RBTree
   def pop
     n = rightmost(@root)
     return nil if n == @nil_node
+    key = n.key
     val = n.value.last
     n.value.pop
     @size -= 1
     if n.value.empty?
-      remove_node(n)
+      delete_node(key)
     end
-    [n.key, val]
-  end
-
-  def min(last: false)
-    return nil if @min_node == @nil_node || @min_node.value.empty?
-    [@min_node.key, last ? @min_node.value.last : @min_node.value.first]
-  end
-
-  def max(last: false)
-    n = rightmost(@root)
-    return nil if n == @nil_node || n.value.empty?
-    [n.key, last ? n.value.last : n.value.first]
-  end
-
-  def nearest(key, last: false)
-    n = find_nearest_node(key)
-    return nil if n == @nil_node || n.value.empty?
-    [n.key, last ? n.value.last : n.value.first]
-  end
-
-  def prev(key, last: false)
-    n = find_predecessor_node(key)
-    return nil if n == @nil_node || n.value.empty?
-    [n.key, last ? n.value.last : n.value.first]
+    [key, val]
   end
 
-  def succ(key, last: false)
-    n = find_successor_node(key)
-    return nil if n == @nil_node || n.value.empty?
-    [n.key, last ? n.value.last : n.value.first]
+  # 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)
+    return enum_for(:get_all, key) unless block_given?
+    @hash_index[key]&.value&.each { |v| yield v }
   end
 
   private
 
-  def traverse_asc(node, &block)
-    stack = []
-    current = node
-    while current != @nil_node || !stack.empty?
-      while current != @nil_node
-        stack << current
-        current = current.left
-      end
-      current = stack.pop
-      current.value.each { |v| yield current.key, v }
-      current = current.right
-    end
+  def traverse_range_asc(...)
+    super { |k, vals| vals.each { |v| yield k, v } }
   end
 
-  def traverse_desc(node, &block)
-    stack = []
-    current = node
-    while current != @nil_node || !stack.empty?
-      while current != @nil_node
-        stack << current
-        current = current.right
-      end
-      current = stack.pop
-      current.value.reverse_each { |v| yield current.key, v }
-      current = current.left
-    end
-  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
-
-  def traverse_lt_desc(node, key, &block)
-    return if node == @nil_node
-    
-    if (node.key <=> key) < 0
-      traverse_lt_desc(node.right, key, &block)
-      node.value.reverse_each { |v| yield node.key, v }
-    end
-    traverse_lt_desc(node.left, key, &block)
-  end
-
-  def traverse_lte_desc(node, key, &block)
-    return if node == @nil_node
-    
-    if (node.key <=> key) <= 0
-      traverse_lte_desc(node.right, key, &block)
-      node.value.reverse_each { |v| yield node.key, v }
-    end
-    traverse_lte_desc(node.left, key, &block)
-  end
-
-  def traverse_gt_desc(node, key, &block)
-    return if node == @nil_node
-    
-    traverse_gt_desc(node.right, key, &block)
-    if (node.key <=> key) > 0
-      node.value.reverse_each { |v| yield node.key, v }
-      traverse_gt_desc(node.left, key, &block)
-    end
-  end
-
-  def traverse_gte_desc(node, key, &block)
-    return if node == @nil_node
-    
-    traverse_gte_desc(node.right, key, &block)
-    if (node.key <=> key) >= 0
-      node.value.reverse_each { |v| yield node.key, v }
-      traverse_gte_desc(node.left, key, &block)
-    end
-  end
-
-  def traverse_between_desc(node, min, max, include_min, include_max, &block)
-    return if node == @nil_node
-    
-    if (node.key <=> max) < 0
-      traverse_between_desc(node.right, 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.reverse_each { |v| yield node.key, v }
-    end
-    
-    if (node.key <=> min) > 0
-      traverse_between_desc(node.left, min, max, include_min, include_max, &block)
-    end
+  def traverse_range_desc(...)
+    super { |k, vals| vals.reverse_each { |v| yield k, v } }
   end
 end
 
@@ -1671,11 +1582,7 @@ class RBTree::Node
     @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
+  # Returns the key-value pair.
+  # @return [Array(Object, Object)] the key-value pair
+  def pair = [key, value]
 end

metadata

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