rbtree-ruby 0.1.8 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad4ff4e15079d2034a111e0180f1abbf5f433283de5c125f45569f9b69f558fc
-  data.tar.gz: 7355e1ae3964e79aa8d110c52e38672641c8d67ac1cb4cfbbd974fe6298f07f7
+  metadata.gz: 89348dfde7177409ecdca6a4184ebee7f83f3a57eebb84b3f4925ad4460a7a92
+  data.tar.gz: bd46b055e05a121787b67ecf20836181800abe0a230800703872c1412826ccfa
 SHA512:
-  metadata.gz: e62ddc40bfc16d4afaf9430b679b03cfb50e89d3a02d7ab43a190b168015d4c6605baf579cc55abc0d42db207465538f99e81618beca873a1b4c654d1ab0c72f
-  data.tar.gz: d11f0258d1ea5ea2686cc8bb581eb3b5c524554bf2182d68d54759e592d58d57e463bfa87b13dbabb67e68becfa8648108b267751791a1877e49bc7c6e2f6a06
+  metadata.gz: 908a2d3d58bfac4c7d092e745ebe7f3f2c391551ea5fa7822871d1d0334c64985169df7433342e0e77cad9cf85f8a6b1a265ee427d96445095b3aa27da73d8ef
+  data.tar.gz: c7b5afe4a5189deee48c6abc5cbca6340c14ebfc65d581f2788117bfb84aabca7757582ab5b6bbcf7cc5866e6350be4f85f87fda78ea49af8c394dd0884de6b3

data/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.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
+- **MultiRBTree**: `nearest(key, last: false)` option to choose first or last value
+
 ## [0.1.8] - 2026-01-14
 
 ### Changed
@@ -116,6 +140,7 @@ 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.2.0]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.2.0
 [0.1.8]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.8
 [0.1.7]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.7
 [0.1.6]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.6

data/README.ja.md

@@ -0,0 +1,282 @@
+# rbtree-ruby
+
+🌍 *[English](README.md) | [日本語](README.ja.md)*
+
+Red-Black Tree（赤黒木）データ構造のピュアRuby実装です。挿入、削除、検索操作がO(log n)の時間計算量で実行できる、
+効率的な順序付きキーバリューストレージを提供します。
+
+## 特徴
+
+- **自己平衡二分探索木**: 赤黒木の性質により最適なパフォーマンスを維持
+- **順序付き操作**: 効率的な範囲クエリ、最小/最大値の取得、ソート済みイテレーション
+- **複数値サポート**: `MultiRBTree`クラスで同一キーに複数の値を格納可能
+- **ピュアRuby**: C拡張不要、あらゆるRuby実装で動作
+- **充実したドキュメント**: 使用例付きの包括的なRDocドキュメント
+
+## インストール
+
+Gemfileに以下を追加:
+
+```ruby
+gem 'rbtree-ruby'
+```
+
+実行:
+
+```bash
+bundle install
+```
+
+または直接インストール:
+
+```bash
+gem install rbtree-ruby
+```
+
+## 使い方
+
+### 基本的なRBTree
+
+```ruby
+require 'rbtree'
+
+# 空のツリーを作成
+tree = RBTree.new
+
+# データで初期化
+tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+tree = RBTree[[5, 'five'], [4, 'four']]
+
+# 値の挿入と取得
+tree.insert(10, 'ten')
+tree[20] = 'twenty'
+puts tree[10]  # => "ten"
+
+# ソート順でイテレーション
+tree.each { |key, value| puts "#{key}: #{value}" }
+# 出力:
+# 1: one
+# 2: two
+# 3: three
+# 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"]
+
+# 範囲クエリ（Enumeratorを返す、配列には.to_aを使用）
+tree.lt(10).to_a   # => [[1, "one"], [2, "two"], [3, "three"]]
+tree.gte(10).to_a  # => [[10, "ten"], [20, "twenty"]]
+tree.between(2, 10).to_a  # => [[2, "two"], [3, "three"], [10, "ten"]]
+
+# shiftとpop
+tree.shift  # => [1, "one"] (最小値を削除)
+tree.pop    # => [20, "twenty"] (最大値を削除)
+
+# 削除
+tree.delete(3)  # => "three"
+
+# キーの存在確認
+tree.has_key?(2)  # => true
+tree.size         # => 2
+```
+
+### MultiRBTree（重複キー対応）
+
+```ruby
+require 'rbtree'
+
+tree = MultiRBTree.new
+
+# 同じキーに複数の値を挿入
+tree.insert(1, 'first one')
+tree.insert(1, 'second one')
+tree.insert(1, 'third one')
+tree.insert(2, 'two')
+
+tree.size  # => 4 (キーバリューペアの総数)
+
+# 最初の値を取得
+tree.get(1)      # => "first one"
+tree[1]          # => "first one"
+
+# キーの全ての値を取得（Enumeratorを返す）
+tree.get_all(1).to_a  # => ["first one", "second one", "third one"]
+
+# 全キーバリューペアをイテレーション
+tree.each { |k, v| puts "#{k}: #{v}" }
+# 出力:
+# 1: first one
+# 1: second one
+# 1: third one
+# 2: two
+
+# 最初の値のみ削除
+tree.delete_one(1)  # => "first one"
+tree.get(1)         # => "second one"
+
+# キーの全ての値を削除
+tree.delete(1)      # 残りの値を全て削除
+```
+
+### 最近傍キー検索
+
+```ruby
+tree = RBTree.new({1 => 'one', 5 => 'five', 10 => 'ten'})
+
+tree.nearest(4)   # => [5, "five"]  (4に最も近いキー)
+tree.nearest(7)   # => [5, "five"]  (同距離の場合は小さいキー)
+tree.nearest(8)   # => [10, "ten"]
+```
+
+### 前後キー検索
+
+```ruby
+tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
+
+tree.prev(5)   # => [3, "three"]  (5より小さい最大のキー)
+tree.succ(5)   # => [7, "seven"]  (5より大きい最小のキー)
+
+# キーが存在しなくても動作
+tree.prev(4)   # => [3, "three"]  (4は存在しない、4未満の最大キーを返す)
+tree.succ(4)   # => [5, "five"]   (4は存在しない、4より大きい最小キーを返す)
+
+# 境界ではnilを返す
+tree.prev(1)   # => nil (1より小さいキーなし)
+tree.succ(7)   # => nil (7より大きいキーなし)
+```
+
+### 逆順範囲クエリ
+
+範囲クエリは`Enumerator`を返し（配列には`.to_a`を使用）、`:reverse`オプションをサポート:
+
+```ruby
+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).to_a     # => [[2, "two"], [1, "one"]]
+tree.lt(3).first                   # => [1, "one"] (遅延評価、配列は作成されない)
+
+# 遅延評価
+tree.gt(0).lazy.take(2).to_a  # => [[1, "one"], [2, "two"]] (最初の2件のみ計算)
+```
+
+### MultiRBTree 値配列アクセス
+
+複数の値を持つキーで、どの値にアクセスするか選択:
+
+```ruby
+tree = MultiRBTree.new
+tree.insert(1, 'first')
+tree.insert(1, 'second')
+tree.insert(1, 'third')
+
+# 最初または最後の値にアクセス
+tree.get(1)               # => "first"
+tree.get(1, last: true)   # => "third"
+tree.get_first(1)         # => "first"
+tree.get_last(1)          # => "third"
+
+# どちらの端からも削除可能
+tree.delete_first(1)      # => "first"
+tree.delete_last(1)       # => "third"  
+tree.get(1)               # => "second"
+
+# min/maxの:lastオプション
+tree.insert(2, 'a')
+tree.insert(2, 'b')
+tree.min                  # => [1, "second"] (最小キーの最初の値)
+tree.max(last: true)      # => [2, "b"]      (最大キーの最後の値)
+```
+
+## パフォーマンス
+
+主要な操作は**O(log n)**時間で実行:
+
+- `insert(key, value)` - O(log n)
+- `delete(key)` - O(log n)
+- `get(key)` / `[]` - **O(1)** (ハイブリッドハッシュインデックス)
+- `has_key?` - **O(1)** (ハイブリッドハッシュインデックス)
+- `min` - **O(1)**
+- `max` - O(log n)
+- `shift` / `pop` - O(log n)
+- `prev` / `succ` - O(log n)、O(1)ハッシュチェック付き
+
+全要素のイテレーションはO(n)時間。
+
+### メモリ効率
+
+RBTreeは内部的な**メモリプール**を使用してノードオブジェクトを再利用:
+- 頻繁な挿入・削除時のGC負荷を大幅に削減
+- 100,000回の循環操作ベンチマークで**GC時間0.0秒**を達成
+
+### RBTree vs Hash vs Array
+
+順序付き操作と空間的操作において、RBTreeは単に速いだけでなく、全く異なるクラスの性能を発揮。**50万件**でのベンチマーク:
+
+| 操作 | RBTree | Hash/Array | 高速化 | 理由 |
+|-----|--------|------------|-------|-----|
+| **最近傍検索** | **O(log n)** | O(n) スキャン | **〜8,600倍高速** | 二分探索 vs 全件スキャン |
+| **範囲クエリ** | **O(log n + k)** | O(n) フィルター | **〜540倍高速** | 部分木へ直接ジャンプ vs 全件スキャン |
+| **最小値抽出** | **O(log n)** | O(n) 検索 | **〜160倍高速** | 連続的なリバランス vs 全件スキャン |
+| **ソート済みイテレーション** | **O(n)** | O(n log n) | **無料** | 常にソート済み vs 明示的な`sort` |
+| **キー検索** | **O(1)** | O(1) | **同等** | ハイブリッドハッシュインデックス |
+
+### RBTreeを使うべき場面
+
+✅ **RBTreeが適している場合:**
+- キー順でのイテレーション
+- 高速なmin/max取得
+- 範囲クエリ（`between`, `lt`, `gt`, `lte`, `gte`）
+- 最近傍キー検索
+- 優先度キュー的な動作（キー順でshift/pop）
+
+✅ **Hashが適している場合:**
+- 高速なキーバリュー検索のみ（RBTreeも同等に高速！）
+- 順序付けが不要
+
+## APIドキュメント
+
+完全なRDocドキュメントを生成:
+
+```bash
+rdoc lib/rbtree.rb
+```
+
+`doc/index.html`をブラウザで開いてください。
+
+## 開発
+
+リポジトリをチェックアウト後、`bundle install`で依存関係をインストール:
+
+```bash
+# RDocドキュメント生成
+rake rdoc
+
+# gemのビルド
+rake build
+
+# ローカルインストール
+rake install
+```
+
+## コントリビューション
+
+バグ報告やプルリクエストはGitHubで受け付けています: https://github.com/firelzrd/rbtree-ruby
+
+## ライセンス
+
+[MIT License](https://opensource.org/licenses/MIT)でオープンソースとして公開。
+
+## 作者
+
+Masahito Suzuki (firelzrd@gmail.com)
+
+Copyright © 2026 Masahito Suzuki

data/README.md

@@ -1,6 +1,9 @@
 # rbtree-ruby
 
-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.
+🌍 *[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.
 
 ## Features
 
@@ -58,14 +61,20 @@ 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"]
 
-# Range queries
-tree.lt(10)   # => [[1, "one"], [2, "two"], [3, "three"]]
-tree.gte(10)  # => [[10, "ten"], [20, "twenty"]]
-tree.between(2, 10)  # => [[2, "two"], [3, "three"], [10, "ten"]]
+# 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.between(2, 10).to_a  # => [[2, "two"], [3, "three"], [10, "ten"]]
 
 # Shift and pop
 tree.shift  # => [1, "one"] (removes minimum)
@@ -98,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}" }
@@ -148,15 +157,17 @@ tree.succ(7)   # => nil (no key larger than 7)
 
 ### Reverse Range Queries
 
-All range queries support a `:reverse` option to iterate in descending order:
+All range queries return an `Enumerator` (use `.to_a` for Array) and support a `:reverse` option:
 
 ```ruby
 tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
 
-tree.lt(3)                    # => [[1, "one"], [2, "two"]]
-tree.lt(3, reverse: true)     # => [[2, "two"], [1, "one"]]
+tree.lt(3).to_a                    # => [[1, "one"], [2, "two"]]
+tree.lt(3, reverse: true).to_a     # => [[2, "two"], [1, "one"]]
+tree.lt(3).first                   # => [1, "one"] (lazy, no array created)
 
-tree.between(1, 4, reverse: true)  # => [[4, "four"], [3, "three"], [2, "two"], [1, "one"]]
+# Lazy evaluation
+tree.gt(0).lazy.take(2).to_a  # => [[1, "one"], [2, "two"]] (only computes first 2)
 ```
 
 ### MultiRBTree Value Array Access

data/lib/rbtree/version.rb

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

data/lib/rbtree.rb

@@ -268,13 +268,15 @@ 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.
+  # 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 +286,40 @@ 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 safe
+      if reverse
+        pair = find_max
+        while pair
+          current_key = pair[0]
+          yield pair[0], pair[1]
+          pair = find_predecessor(current_key)
+        end
+      else
+        pair = find_min
+        while pair
+          current_key = pair[0]
+          yield pair[0], pair[1]
+          pair = find_successor(current_key)
+        end
+      end
+    else
+      if reverse
+        traverse_desc(@root, &block)
+      else
+        traverse_asc(@root, &block)
+      end
+    end
+    self
   end
 
   # Iterates over all key-value pairs in descending order of keys.
@@ -300,10 +333,15 @@ 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
+  # Iterates over all key-value pairs in descending order of keys.
+  #
+  # This is an alias for `each(reverse: true)`.
+  #
+  # @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)
 
   # Returns the minimum key-value pair without removing it.
   #
@@ -311,9 +349,7 @@ class RBTree
   # @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
+  def min = find_min
 
   # Returns the maximum key-value pair without removing it.
   #
@@ -321,25 +357,39 @@ class RBTree
   # @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
+  def max = find_max
 
   # 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?
-    if reverse
+  #   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 safe
+      if reverse
+        pair = find_predecessor(key)
+        while pair
+          current_key = pair[0]
+          yield pair
+          pair = find_predecessor(current_key)
+        end
+      else
+        pair = find_min
+        while pair && pair[0] < key
+          current_key = pair[0]
+          yield pair
+          pair = find_successor(current_key)
+        end
+      end
+    elsif reverse
       traverse_lt_desc(@root, key, &block)
     else
       traverse_lt(@root, key, &block)
@@ -351,15 +401,32 @@ 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?
-    if reverse
+  def lte(key, reverse: false, safe: false, &block)
+    return enum_for(:lte, key, reverse: reverse, safe: safe) unless block_given?
+    if safe
+      if reverse
+        pair = @hash_index[key]&.pair || find_predecessor(key)
+        while pair
+          current_key = pair[0]
+          yield pair
+          pair = find_predecessor(current_key)
+        end
+      else
+        pair = find_min
+        while pair && pair[0] <= key
+          current_key = pair[0]
+          yield pair
+          pair = succ(current_key)
+        end
+      end
+    elsif reverse
       traverse_lte_desc(@root, key, &block)
     else
       traverse_lte(@root, key, &block)
@@ -371,15 +438,32 @@ 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?
-    if reverse
+  def gt(key, reverse: false, safe: false, &block)
+    return enum_for(:gt, key, reverse: reverse, safe: safe) unless block_given?
+    if safe
+      if reverse
+        pair = find_max
+        while pair && pair[0] > key
+          current_key = pair[0]
+          yield pair
+          pair = find_predecessor(current_key)
+        end
+      else
+        pair = find_successor(key)
+        while pair
+          current_key = pair[0]
+          yield pair
+          pair = find_successor(current_key)
+        end
+      end
+    elsif reverse
       traverse_gt_desc(@root, key, &block)
     else
       traverse_gt(@root, key, &block)
@@ -391,15 +475,32 @@ 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?
-    if reverse
+  def gte(key, reverse: false, safe: false, &block)
+    return enum_for(:gte, key, reverse: reverse, safe: safe) unless block_given?
+    if safe
+      if reverse
+        pair = find_max
+        while pair && pair[0] >= key
+          current_key = pair[0]
+          yield pair
+          pair = find_predecessor(current_key)
+        end
+      else
+        pair = @hash_index[key]&.pair || find_successor(key)
+        while pair
+          current_key = pair[0]
+          yield pair
+          pair = find_successor(current_key)
+        end
+      end
+    elsif reverse
       traverse_gte_desc(@root, key, &block)
     else
       traverse_gte(@root, key, &block)
@@ -414,15 +515,34 @@ 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?
-    if reverse
+  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 safe
+      if reverse
+        pair = include_max && @hash_index[max]&.pair || find_predecessor(max)
+        while pair && pair[0] > min
+          current_key = pair[0]
+          yield pair
+          pair = find_predecessor(current_key)
+        end
+        yield pair if pair && include_min && pair[0] == min
+      else
+        pair = include_min && @hash_index[min]&.pair || find_successor(min)
+        while pair && pair[0] < max
+          current_key = pair[0]
+          yield pair
+          pair = find_successor(current_key)
+        end
+        yield pair if pair && include_max && pair[0] == max
+      end
+    elsif reverse
       traverse_between_desc(@root, min, max, include_min, include_max, &block)
     else
       traverse_between(@root, min, max, include_min, include_max, &block)
@@ -445,7 +565,7 @@ class RBTree
   def nearest(key)
     return nil unless key.respond_to?(:-)
     n = find_nearest_node(key)
-    n == @nil_node ? nil : [n.key, n.value]
+    n == @nil_node ? nil : n.pair
   end
 
   # Returns the key-value pair with the largest key that is smaller than the given key.
@@ -462,7 +582,7 @@ class RBTree
   #   tree.prev(1)   # => nil (no predecessor)
   def prev(key)
     n = find_predecessor_node(key)
-    n == @nil_node ? nil : [n.key, n.value]
+    n == @nil_node ? nil : n.pair
   end
 
   # Returns the key-value pair with the smallest key that is larger than the given key.
@@ -479,7 +599,7 @@ class RBTree
   #   tree.succ(7)   # => nil (no successor)
   def succ(key)
     n = find_successor_node(key)
-    n == @nil_node ? nil : [n.key, n.value]
+    n == @nil_node ? nil : n.pair
   end
 
   # Validates the red-black tree properties.
@@ -515,7 +635,7 @@ class RBTree
         current = current.left
       end
       current = stack.pop
-      yield current.key, current.value
+      yield current.pair
       current = current.right
     end
   end
@@ -534,7 +654,7 @@ class RBTree
         current = current.right
       end
       current = stack.pop
-      yield current.key, current.value
+      yield current.pair
       current = current.left
     end
   end
@@ -550,7 +670,7 @@ class RBTree
     
     traverse_lt(node.left, key, &block)
     if (node.key <=> key) < 0
-      yield node.key, node.value
+      yield node.pair
       traverse_lt(node.right, key, &block)
     end
   end
@@ -566,7 +686,7 @@ class RBTree
     
     traverse_lte(node.left, key, &block)
     if (node.key <=> key) <= 0
-      yield node.key, node.value
+      yield node.pair
       traverse_lte(node.right, key, &block)
     end
   end
@@ -582,7 +702,7 @@ class RBTree
     
     if (node.key <=> key) > 0
       traverse_gt(node.left, key, &block)
-      yield node.key, node.value
+      yield node.pair
     end
     traverse_gt(node.right, key, &block)
   end
@@ -598,7 +718,7 @@ class RBTree
     
     if (node.key <=> key) >= 0
       traverse_gte(node.left, key, &block)
-      yield node.key, node.value
+      yield node.pair
     end
     traverse_gte(node.right, key, &block)
   end
@@ -622,7 +742,7 @@ class RBTree
     less = include_max ? (node.key <=> max) <= 0 : (node.key <=> max) < 0
     
     if greater && less
-      yield node.key, node.value
+      yield node.pair
     end
     
     if (node.key <=> max) < 0
@@ -641,7 +761,7 @@ class RBTree
     
     if (node.key <=> key) < 0
       traverse_lt_desc(node.right, key, &block)
-      yield node.key, node.value
+      yield node.pair
     end
     traverse_lt_desc(node.left, key, &block)
   end
@@ -657,7 +777,7 @@ class RBTree
     
     if (node.key <=> key) <= 0
       traverse_lte_desc(node.right, key, &block)
-      yield node.key, node.value
+      yield node.pair
     end
     traverse_lte_desc(node.left, key, &block)
   end
@@ -673,7 +793,7 @@ class RBTree
     
     traverse_gt_desc(node.right, key, &block)
     if (node.key <=> key) > 0
-      yield node.key, node.value
+      yield node.pair
       traverse_gt_desc(node.left, key, &block)
     end
   end
@@ -689,7 +809,7 @@ class RBTree
     
     traverse_gte_desc(node.right, key, &block)
     if (node.key <=> key) >= 0
-      yield node.key, node.value
+      yield node.pair
       traverse_gte_desc(node.left, key, &block)
     end
   end
@@ -714,7 +834,7 @@ class RBTree
     less = include_max ? (node.key <=> max) <= 0 : (node.key <=> max) < 0
     
     if greater && less
-      yield node.key, node.value
+      yield node.pair
     end
     
     if (node.key <=> min) > 0
@@ -1011,6 +1131,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 +1181,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 +1202,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 +1218,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:
@@ -1304,8 +1454,8 @@ class MultiRBTree < RBTree
   #   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
+    return enum_for(:get_all, key) unless block_given?
+    @hash_index[key]&.value&.each { |v| yield v }
   end
 
   # Inserts a value for the given key.
@@ -1461,23 +1611,81 @@ class MultiRBTree < RBTree
     [n.key, last ? n.value.last : n.value.first]
   end
 
-  def nearest(key)
+  def nearest(key, last: false)
     n = find_nearest_node(key)
-    n == @nil_node || n.value.empty? ? nil : [n.key, 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]
   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]
+  def each(reverse: false, safe: false, &block)
+    return enum_for(:each, reverse: reverse, safe: safe) unless block_given?
+    if safe
+      super do |k, vals|
+        vals.send(reverse ? :reverse_each : :each) { |v| yield k, v }
+      end
+    else
+      super
+    end
   end
 
+  def lt(key, reverse: false, safe: false, &block)
+    return enum_for(:lt, key, reverse: reverse, safe: safe) unless block_given?
+    if safe
+      super do |k, vals|
+        vals.send(reverse ? :reverse_each : :each) { |v| yield k, v }
+      end
+    else
+      super
+    end
+  end
+
+  def lte(key, reverse: false, safe: false, &block)
+    return enum_for(:lte, key, reverse: reverse, safe: safe) unless block_given?
+    if safe
+      super do |k, vals|
+        vals.send(reverse ? :reverse_each : :each) { |v| yield k, v }
+      end
+    else
+      super
+    end
+  end
+
+  def gt(key, reverse: false, safe: false, &block)
+    return enum_for(:gt, key, reverse: reverse, safe: safe) unless block_given?
+    if safe
+      super do |k, vals|
+        vals.send(reverse ? :reverse_each : :each) { |v| yield k, v }
+      end
+    else
+      super
+    end
+  end
+
+  def gte(key, reverse: false, safe: false, &block)
+    return enum_for(:gte, key, reverse: reverse, safe: safe) unless block_given?
+    if safe
+      super do |k, vals|
+        vals.send(reverse ? :reverse_each : :each) { |v| yield k, v }
+      end
+    else
+      super
+    end
+  end
+
+  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 safe
+      super do |k, vals|
+        vals.send(reverse ? :reverse_each : :each) { |v| yield k, v }
+      end
+    else
+      super
+    end
+  end
+
+  def prev(key, last: false) = (n = super) && [n.key, last ? n.value.last : n.value.first]
+  def succ(key, last: false) = (n = super) && [n.key, last ? n.value.last : n.value.first]
+
   private
 
   def traverse_asc(node, &block)
@@ -1677,4 +1885,8 @@ class RBTree::Node
   # 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

data/rbtree-ruby.gemspec

@@ -8,11 +8,12 @@ Gem::Specification.new do |spec|
   spec.authors = ["Masahito Suzuki"]
   spec.email   = ["firelzrd@gmail.com"]
 
-  spec.summary     = "A pure Ruby implementation of Red-Black Tree with multi-value support"
+  spec.summary     = "A pure Ruby Red-Black Tree with O(1) lookup, range queries, and multi-value support"
   spec.description = <<~DESC
-    RBTree is a pure Ruby implementation of the Red-Black Tree data structure,
-    providing efficient ordered key-value storage with O(log n) operations.
-    Includes MultiRBTree for handling duplicate keys with linked lists.
+    A high-performance pure Ruby Red-Black Tree implementation. Features: O(1) key
+    lookup via hybrid hash index, O(log n) insert/delete, lazy Enumerator-based
+    range queries (lt/gt/between), nearest/prev/succ search, memory-efficient node
+    pooling, and MultiRBTree for duplicate keys with first/last value access.
   DESC
   spec.homepage = "https://github.com/firelzrd/rbtree-ruby"
   spec.license  = "MIT"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbtree-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.1
 platform: ruby
 authors:
 - Masahito Suzuki
@@ -10,9 +10,10 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  RBTree is a pure Ruby implementation of the Red-Black Tree data structure,
-  providing efficient ordered key-value storage with O(log n) operations.
-  Includes MultiRBTree for handling duplicate keys with linked lists.
+  A high-performance pure Ruby Red-Black Tree implementation. Features: O(1) key
+  lookup via hybrid hash index, O(log n) insert/delete, lazy Enumerator-based
+  range queries (lt/gt/between), nearest/prev/succ search, memory-efficient node
+  pooling, and MultiRBTree for duplicate keys with first/last value access.
 email:
 - firelzrd@gmail.com
 executables: []
@@ -21,6 +22,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
+- README.ja.md
 - README.md
 - Rakefile
 - lib/rbtree.rb
@@ -49,5 +51,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: A pure Ruby implementation of Red-Black Tree with multi-value support
+summary: A pure Ruby Red-Black Tree with O(1) lookup, range queries, and multi-value
+  support
 test_files: []