rbtree-ruby 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d89cd253c189b3342f30e2a4df3a293561e2353af6592d86f25fcea5eeb76433
-  data.tar.gz: 9af04bff3851e7806fc637c2fc0ad583decf8e7c020edf841220a2b90fe8aaf4
+  metadata.gz: d1b75c1ac61280ad120b20c9e945e8ac0890e8732905d0699229c57606ae01c3
+  data.tar.gz: caaa60ee759ade14c62f169d0126a50c38e344259918baba96e3a24dcf1a57f1
 SHA512:
-  metadata.gz: a9708ffb8b421f883953c68582c607b9333e671542e21c0f3e0927838d2bb68202142150c11dd11541ea79fa1fcafc6c3195456c38d4b0db6b3897272d205835
-  data.tar.gz: 601190e616b7b478cc6ceabe682e9d43ef169871753667fe61e326f65daceaa60441122a550f8458f1d4a7a794a032ac0add88f326956db903854ee96e34b613
+  metadata.gz: 8316e96b9f44660dbba226688874629571d48059c728d057476d6dc47704ee97a521fe4850277cd2cacea44cdedbd0b26014f7811b339cb8aa0738306bd3fa12
+  data.tar.gz: 6747969000f0293210656e06c5be5068cb2db668f8dffc4c6a23b87202081e98b46ce84d9369bc57b69c2f4e19b2e4c33538b06e83384ce3e25e5e5aea518a8e

data/CHANGELOG.md

@@ -5,6 +5,128 @@ 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.4.0] - 2026-08-15
+
+A correctness release. Every defect fixed here was present in 0.3.6 with a fully
+green test suite, so each one now has a regression test that fails against 0.3.6.
+
+### Fixed
+
+- **Key identity between the tree and the hash index**: the internal index keys on
+  `eql?`/`hash` while the tree orders by `<=>`, so a key that was `<=>`-equal to a
+  stored key but not `eql?` to it (most commonly `1.0` against a stored `1`) could be
+  written but not read back: `tree[1] = 'a'; tree[1.0]` returned `nil`, and
+  `tree.delete(1.0)` was a no-op. Lookups that miss the hash index now fall back to an
+  O(log n) tree search, so ordering and lookup can no longer disagree. Lookups of keys
+  that cannot be compared at all report absence instead of raising. That fallback is
+  skipped when it is provably futile — see `RBTree.coherent_key_class` below — so
+  ordinary key types keep O(1) lookups for hits and misses alike.
+- **`delete` / `delete_key` with `nil` or `false` values**: presence was decided by the
+  truthiness of the value, so entries holding `nil` or `false` could not be removed.
+  `shift` and `pop` returned such a pair without removing it, which made the idiomatic
+  `while (pair = tree.shift)` loop spin forever. `delete_if`, `keep_if` and `reject!`
+  were affected for the same reason.
+- **`to_h` ignored the tree's order**: it was built from the hash index, so it came back
+  in insertion order rather than key order. It is now built by ordered traversal, and
+  `MultiRBTree#to_h` returns copies of the value lists instead of the live arrays.
+- **`MultiRBTree#merge!(self)` and `insert(self)` never terminated**: appending to a
+  key's value list while iterating that same list grew it without bound. Self-insertion
+  now operates on a snapshot, so `tree.merge!(tree)` doubles each entry as expected.
+- **`MultiRBTree#keys` enumerator size**: `keys.to_a` yields one entry per value while
+  `keys.size` reported the number of unique keys. The size now matches what is yielded.
+- **`MultiRBTree#values(key, reverse: true)`** silently ignored `reverse:` when called
+  without a block; the returned Enumerator now honours it.
+- **`MultiRBTree#value_count(key)`** treated a `false` or `nil` key as "no argument" and
+  returned the total count. A sentinel default is used instead, so `nil` and `false` are
+  looked up as ordinary keys.
+- **Safe-mode range queries required `Comparable`**: the safe traversal compared bounds
+  with `<` and `>` while the rest of the code used `<=>`, so keys defining only `<=>`
+  raised `NoMethodError` under `safe: true`, and boundary elements could be dropped.
+- **`clear` corrupted node-pool statistics**: discarded nodes were never accounted for,
+  so `AutoShrinkNodePool`'s live-node count only ever grew, permanently inflating the
+  pool's target capacity in a build/clear cycle. `clear` stays O(1) and now notifies the
+  allocator through the new `NodeAllocator#discard` hook.
+- **`dup`, `select`, `reject`, `invert` and `merge` dropped a custom allocator**, silently
+  reverting the result to a default `AutoShrinkNodePool`. They now carry the allocator over.
+- **Ordering queries raised `NoMethodError` on incomparable keys** (`undefined method '>'
+  for nil`); they raise `ArgumentError` with a useful message instead.
+
+### Added
+
+- **Modification detection during iteration**: mutating the tree inside a non-safe
+  iteration now raises `RuntimeError`, as `Hash` does. This previously produced silent
+  corruption rather than merely skipping elements — because released nodes are recycled
+  by the allocator, an in-flight traversal could be rewired and emit keys **out of
+  order**. The check covers `each`, `reverse_each`, `keys`, every range query, and any
+  `Enumerator` they return. Replacing the value of an existing key is not a structural
+  change and remains allowed; `safe: true` is unaffected.
+- **`Enumerable`-compatible `first`, `last`, `min` and `max`**: `first(n)` and `min(n)`
+  raised `ArgumentError`, and a comparison block passed to `min`/`max` was silently
+  ignored — returning the tree's extreme rather than the block's. With no argument and
+  no block these remain O(1) cached lookups; otherwise `Enumerable` semantics apply.
+  `last(n)` returns the n largest pairs in ascending order.
+- **`RBTree#valid?` now verifies the auxiliary structures**, not just the red-black
+  invariants: hash-index agreement, `min`/`max` caches, `key_count`, parent pointers,
+  and — in `MultiRBTree` — `value_count` and the per-node value lists. Ordering is
+  checked against bounds inherited from ancestors, so a key misplaced across subtrees is
+  detected rather than only one misplaced against its immediate parent.
+- **`RBTree.coherent_key_class(klass)`**: declares that a key class resolves
+  `<=>`-equality and `eql?` identically, letting lookups that miss the hash index skip
+  the fallback tree descent. `Integer`, `Float`, `Rational`, `String`, `Symbol` and
+  `Time` are known coherent and need no declaration; each was verified against its corner
+  cases (`0.0` vs `-0.0`, Strings differing only in encoding, `Time` values in different
+  zones, Integers beyond the fixnum range). Trees whose keys are all of one such class
+  therefore pay essentially nothing for the correctness fix above: 50,000 missing lookups
+  on a 200,000-entry Integer-keyed tree cost 8.1 ms, against 6.3 ms for a bare hash probe
+  and 72 ms with an unconditional descent. Mixed-class trees and undeclared custom key
+  classes keep the descent and stay correct.
+- **`NodeAllocator#discard(count)`** hook for bulk node disposal.
+- **`rake test`** task (the Rakefile previously defined none).
+
+### Changed
+
+- `MultiRBTree#to_h` returns `{key => [values]}` with copied arrays; mutating the result
+  no longer affects the tree.
+- `MultiRBTree` safe iteration snapshots each key's value list, so removing values during
+  the iteration of their own key no longer skips siblings. Values removed during that
+  key's iteration may still be yielded.
+- A key that is `<=>`-equal to a stored key updates the existing entry, and the node keeps
+  the key object it was first created with (its canonical key).
+- `dup` shares the original's allocator instance rather than creating a default one.
+
+### Notes on compatibility
+
+- Code that mutated a tree during a non-safe iteration and appeared to work will now
+  raise; add `safe: true`.
+- `to_h` key order changed from insertion order to ascending key order.
+- `MultiRBTree#value_count(nil)` now looks up the key `nil` instead of returning the
+  total; call `value_count` with no arguments for the total.
+- Lookups of absent keys are O(log n) rather than O(1) *only* on trees that mix key
+  classes or are keyed by an undeclared custom class; on a tree keyed by a single core
+  class every lookup stays O(1). Lookups that hit the hash index are unchanged.
+
+## [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
@@ -230,6 +352,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.6]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.3.6
 [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

data/README.ja.md

@@ -10,10 +10,10 @@ Red-Black Tree（赤黒木）データ構造のピュアRuby実装です。挿
 - **順序付き操作**: ソート済みイテレーション、範囲クエリ（lt, gt, between）、最小/最大値取得が高速に実行可能。
 - **複数値サポート**: `MultiRBTree`クラスで同一キーに複数の値を格納。値は挿入順に保持され、最初または最後の値を個別にアクセス可能。
 - **ピュアRuby**: C拡張不要。MRI, JRuby, TruffleRubyなどあらゆるRuby実装で動作。
-- **ハイブリッドインデックス**: 内部ハッシュインデックスにより、キー検索と存在確認がO(1)の超高速アクセスを実現。
+- **ハイブリッドインデックス**: 内部ハッシュインデックスにより、キー検索と存在確認がO(1)の超高速アクセスを実現。同時にキーの同一性は順序が決めるため、検索結果と順序判定が食い違うことはありません（[キーの要件](#キーの要件)参照）。
 - **メモリ効率**: ノードプールによるオブジェクト再利用と自動縮小機能でGC負荷を大幅に削減。長時間実行アプリにも適応。
 - **最近傍検索**: 数値キーに対して、最も近いキーペアをO(log n)で効率的に探索。
-- **安全なイテレーション**: `safe: true`オプションにより、イテレーション中に他の操作（削除・挿入）を安全に実行可能。
+- **安全なイテレーション**: `safe: true`オプションにより、イテレーション中に他の操作（削除・挿入）を安全に実行可能。指定しない場合、イテレーション中の変更は黙って壊れるのではなく `RuntimeError` になります。
 
 ## インストール
 
@@ -71,12 +71,16 @@ tree.each { |key, value| puts "#{key}: #{value}" }
 # イテレーション中の変更
 # 標準のHashやArrayとは異なり、`safe: true`オプションを指定することで
 # イテレーション中に安全にキーの削除や挿入を行うことができます。
+# 指定しない場合、イテレーション中の変更は RuntimeError になります（「イテレーションの安全性」参照）。
 tree.each(safe: true) { |k, v| tree.delete(k) if k.even? }
 tree.each(reverse: true) { |k, v| puts k }  # reverse_eachと同じ
 
-# 最小値と最大値
+# 最小値と最大値 — O(1)。個数やブロックを渡した場合は Enumerable 互換の動作になります
 tree.min  # => [1, "one"]
 tree.max  # => [20, "twenty"]
+tree.first(2)  # => [[1, "one"], [2, "two"]]
+tree.last(2)   # => [[10, "ten"], [20, "twenty"]]
+tree.min(2)    # => [[1, "one"], [2, "two"]]
 
 # 範囲クエリ（Enumeratorを返す、配列には.to_aを使用）
 tree.lt(10).to_a   # => [[1, "one"], [2, "two"], [3, "three"]]
@@ -194,13 +198,66 @@ tree = RBTree.new({1 => 'one', 2 => 'two'})
 # 配列への変換（Enumerable経由）
 tree.to_a  # => [[1, "one"], [2, "two"]]
 
-# ハッシュへの変換
+# ハッシュへの変換（キーは昇順に挿入されます）
 tree.to_h  # => {1 => "one", 2 => "two"}
 
-# 他のツリー、ハッシュ、またはEnumerableの結合
+# MultiRBTree は各キーに値リストのコピーを対応させます
+multi = MultiRBTree.new
+multi.insert(1, 'a'); multi.insert(1, 'b')
+multi.to_h  # => {1 => ["a", "b"]}
+
+# 結合（破壊的）
 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 値配列アクセス
@@ -231,20 +288,110 @@ tree.min                  # => [1, "second"] (最小キーの最初の値)
 tree.max(last: true)      # => [2, "b"]      (最大キーの最後の値)
 ```
 
+## セマンティクス
+
+### キーの要件
+
+キーは `<=>` で相互に比較可能である必要があります。キーの同一性を決めるのは `eql?`/`hash`
+ではなく**順序**です。つまり `(key <=> stored_key) == 0` となるキーは、すべて同一のエントリを指します。
+
+```ruby
+tree = RBTree.new
+tree[1] = 'int'
+
+tree[1.0]           # => "int"   (1.0 <=> 1 が 0 なので同じキー)
+tree.has_key?(1.0)  # => true
+tree[1.0] = 'float'
+tree.to_a           # => [[1, "float"]]  — 最初に挿入されたキーオブジェクトが保持される
+```
+
+内部のハッシュインデックスは `eql?`/`hash` をキーにしているため、上記の `tree[1.0]` は
+インデックスにヒットせず、木を使って解決されます。ただしこのフォールバックは、**無駄だと
+証明できる場合には省略されます** — 格納済みの全キーと検索キーが同一クラスで、そのクラスにおいて
+`<=>` 等価と `eql?` が一致するなら、該当するキーは既にインデックスで見つかっているはずだからです。
+`Integer` / `Float` / `Rational` / `String` / `Symbol` / `Time` がこれに該当します:
+
+| ツリー | 検索コスト |
+|---|---|
+| 全キーが上記コアクラスのいずれか1種類 | **O(1)**（ヒットもミスも） |
+| クラス混在、または独自キークラス | ハッシュヒット時 O(1)、それ以外 O(log n) |
+
+`<=>` に加えて整合する `eql?`/`hash` を定義した独自クラスは、O(1) 経路に参加できます:
+
+```ruby
+class Version
+  include Comparable
+  attr_reader :parts
+  def initialize(parts) = @parts = parts
+  def <=>(other) = parts <=> other.parts
+  def eql?(other) = other.instance_of?(Version) && parts == other.parts
+  def hash = parts.hash
+end
+
+RBTree.coherent_key_class(Version)
+```
+
+これは純粋な最適化ヒントです。宣言しなくても正しく動作し、インデックスを外れた検索が
+O(log n) の木探索になるだけです。`<=>` だけを定義して `eql?`/`hash` を既定（同一性）の
+ままにしているクラスは、**宣言してはいけません**。
+
+比較不能なキーは、例外ではなく「存在しない」として扱われます:
+
+```ruby
+tree['Integer と <=> できない値']  # => nil
+tree.has_key?('...')              # => false
+tree['...'] = 'x'                 # ArgumentError — 挿入には順序が必要
+```
+
+### イテレーションの安全性
+
+イテレーションは生のノードリンクをたどり、削除されたノードはアロケータによって再利用されます。
+そのためイテレーション中の変更は「要素を取りこぼす」だけでは済まず、**キーが順序を無視して
+yield されうる**という壊れ方をします。これは検出され、明示的なエラーになります:
+
+```ruby
+tree.each { |k, v| tree.delete(k) }
+# => RuntimeError: can't modify RBTree during iteration (pass `safe: true` to iterate safely)
+
+tree.each(safe: true) { |k, v| tree.delete(k) }   # サポートされている
+```
+
+この検出は `each` / `reverse_each` / `keys` / 全ての範囲クエリと、それらが返す `Enumerator`
+（後から変更された場合を含む）に適用されます。既存キーの値の差し替えは構造変更ではないため
+許可されます。`delete_if` / `keep_if` / `reject!` は内部で安全にイテレートします。
+
+`MultiRBTree` の `safe: true` は各キーの値リストのスナップショットを取ります。そのため、
+あるキーのイテレーション中にそのキーの値を削除しても兄弟要素が飛ばされることはありません。
+一方で、自分のキーのイテレーション中に削除された値は yield されることがあります。
+
+### スレッド安全性
+
+いかなる操作も同期されていません。木・ハッシュインデックス・ノードアロケータはすべて共有される
+可変状態であるため、複数スレッドから触る場合は外部でロックしてください。なお、複数の木に渡した
+ノードアロケータ（`dup` 経由を含む）は、それらの木の間で共有される状態になります。
+
 ## パフォーマンス
 
 主要な操作は**O(log n)**時間で実行:
 
 - `insert(key, value)` - O(log n)
 - `delete(key)` - O(log n)
-- `value(key)` / `[]` - **O(1)** (内部ハッシュインデックスによる超高速アクセス)
-- `has_key?` - **O(1)** (内部ハッシュインデックスによる超高速チェック)
+- `value(key)` / `[]` - **O(1)**（クラス混在・独自キーのツリーでミスした場合のみ O(log n)。[キーの要件](#キーの要件)参照）
+- `has_key?` - **O(1)**（同上）
 - `min` / `max` - **O(1)**
 - `shift` / `pop` - O(log n)
 - `prev` / `succ` - O(log n)、O(1)ハッシュチェックと高速な走査開始により改善
+- `clear` - **O(1)**（ノードは再利用されず GC に委ねられます）
 
 全要素のイテレーションはO(n)時間。
 
+> **検索ミスについて:** キーの同一性を `eql?` ではなく順序で決めることの代償は、通常のキー型では
+> ゼロです。20万件の Integer キーのツリーでの実測で、5万回の空振り検索が 8.1 ms（素のハッシュ探査のみの
+> 場合は 6.3 ms）。差はクラス判定1回ぶんであって、木の降下ではありません。木を降りるのはクラス混在・
+> 独自キーのツリーだけです（ミス1回あたり約 1.4 µs）。ヒット時・挿入・削除・イテレーション・範囲クエリには
+> 影響ありません。
+
+
 ### RBTree vs Hash vs Array
 
 順序付き操作と空間的操作において、RBTreeは単に速いだけでなく、全く異なるクラスの性能を発揮。**50万件**でのベンチマーク:

data/README.md

@@ -10,10 +10,10 @@ A pure Ruby implementation of the Red-Black Tree data structure, providing effic
 - **Ordered Operations**: Efficient sorted iteration, range queries (`lt`, `gt`, `between`), min/max retrieval.
 - **Multi-Value Support**: `MultiRBTree` class stores multiple values per key, with access to first or last value individually.
 - **Pure Ruby**: No C extensions required. Works on MRI, JRuby, TruffleRuby, and all Ruby implementations.
-- **Hybrid Indexing**: Internal hash index enables O(1) key lookup and membership checks — matching standard Hash performance.
+- **Hybrid Indexing**: Internal hash index enables O(1) key lookup and membership checks — matching standard Hash performance — while ordering still decides key identity, so lookup and ordering never disagree (see [Key Requirements](#key-requirements)).
 - **Memory Efficiency**: Node recycling with auto-shrinking pool (`AutoShrinkNodePool`) drastically reduces GC pressure in long-running apps.
 - **Nearest Key Search**: Finds the closest numeric key in O(log n) time — ideal for spatial or temporal queries.
-- **Safe Iteration**: Use `safe: true` to safely modify the tree (insert/delete) during iteration.
+- **Safe Iteration**: Use `safe: true` to safely modify the tree (insert/delete) during iteration. Without it, modifying during iteration raises `RuntimeError` rather than silently misbehaving.
 
 ## Installation
 
@@ -71,12 +71,16 @@ tree.each { |key, value| puts "#{key}: #{value}" }
 # 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.
+# Without it, modifying the tree mid-iteration raises RuntimeError (see "Iteration Safety").
 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
+# Min and max — O(1), and Enumerable-compatible when given a count or a block
 tree.min  # => [1, "one"]
 tree.max  # => [20, "twenty"]
+tree.first(2)  # => [[1, "one"], [2, "two"]]
+tree.last(2)   # => [[10, "ten"], [20, "twenty"]]
+tree.min(2)    # => [[1, "one"], [2, "two"]]
 
 # Range queries (return Enumerator, use .to_a for Array)
 tree.lt(10).to_a   # => [[1, "one"], [2, "two"], [3, "three"]]
@@ -194,13 +198,66 @@ tree = RBTree.new({1 => 'one', 2 => 'two'})
 # Convert to Array (via Enumerable)
 tree.to_a  # => [[1, "one"], [2, "two"]]
 
-# Convert to Hash
+# Convert to Hash (keys are inserted in ascending order)
 tree.to_h  # => {1 => "one", 2 => "two"}
 
-# Merge another tree, hash, or enumerable
+# MultiRBTree maps each key to a copy of its value list
+multi = MultiRBTree.new
+multi.insert(1, 'a'); multi.insert(1, 'b')
+multi.to_h  # => {1 => ["a", "b"]}
+
+# 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
@@ -231,20 +288,112 @@ tree.min                  # => [1, "second"] (first value of min key)
 tree.max(last: true)      # => [2, "b"]      (last value of max key)
 ```
 
+## Semantics
+
+### Key Requirements
+
+Keys must be mutually comparable with `<=>`. Ordering — not `eql?`/`hash` — decides key
+identity: any key for which `(key <=> stored_key) == 0` refers to the same entry.
+
+```ruby
+tree = RBTree.new
+tree[1] = 'int'
+
+tree[1.0]           # => "int"   (1.0 <=> 1 is 0, so it is the same key)
+tree.has_key?(1.0)  # => true
+tree[1.0] = 'float'
+tree.to_a           # => [[1, "float"]]  — the first key object inserted is kept
+```
+
+The internal hash index is keyed by `eql?`/`hash`, so a lookup like `tree[1.0]` above
+misses it and resolves through the tree instead. That fallback is skipped whenever it is
+provably futile — when every stored key and the lookup key share one class for which
+`<=>`-equality coincides with `eql?`, any matching key would already have been found in
+the index. `Integer`, `Float`, `Rational`, `String`, `Symbol` and `Time` qualify, so:
+
+| Tree | Lookup cost |
+|---|---|
+| Keys all of one core class above | **O(1)**, hits and misses alike |
+| Mixed key classes, or a custom key class | O(1) on a hash hit, O(log n) otherwise |
+
+A custom key class that defines `<=>` alongside a matching `eql?`/`hash` can opt into the
+O(1) path:
+
+```ruby
+class Version
+  include Comparable
+  attr_reader :parts
+  def initialize(parts) = @parts = parts
+  def <=>(other) = parts <=> other.parts
+  def eql?(other) = other.instance_of?(Version) && parts == other.parts
+  def hash = parts.hash
+end
+
+RBTree.coherent_key_class(Version)
+```
+
+This is purely an optimization hint — without it such trees are still correct, just with
+an O(log n) descent on lookups that miss the index. A class that defines `<=>` but leaves
+`eql?`/`hash` at their default identity semantics must **not** be declared.
+
+Keys that cannot be compared at all are reported as absent by lookups rather than raising:
+
+```ruby
+tree['no <=> with Integer']       # => nil
+tree.has_key?('...')             # => false
+tree['...'] = 'x'                # raises ArgumentError — insertion needs an ordering
+```
+
+### Iteration Safety
+
+Iteration walks live node links, and deleted nodes are recycled by the allocator, so
+mutating the tree during a plain iteration is not merely lossy — it can yield keys out of
+order. This is detected and reported:
+
+```ruby
+tree.each { |k, v| tree.delete(k) }
+# => RuntimeError: can't modify RBTree during iteration (pass `safe: true` to iterate safely)
+
+tree.each(safe: true) { |k, v| tree.delete(k) }   # supported
+```
+
+The guard covers `each`, `reverse_each`, `keys`, all range queries, and any `Enumerator`
+they return — including one held across a later mutation. Replacing the value of an
+existing key is not a structural change and stays allowed. `delete_if`, `keep_if` and
+`reject!` iterate safely on your behalf.
+
+In `MultiRBTree`, `safe: true` snapshots each key's value list, so removing values while
+that key is being iterated will not skip its siblings; values removed during the
+iteration of their own key may still be yielded.
+
+### Thread Safety
+
+No operation is synchronized. The tree, its hash index, and the node allocator are all
+shared mutable state, so concurrent access from multiple threads requires external
+locking. Note that a node allocator passed to several trees (including via `dup`) is
+shared state between them.
+
 ## Performance
 
 All major operations run in **O(log n)** time:
 
 - `insert(key, value)` - O(log n)
 - `delete(key)` - O(log n)
-- `value(key)` / `[]` - **O(1)** (hybrid hash index)
-- `has_key?` - **O(1)** (hybrid hash index)
+- `value(key)` / `[]` - **O(1)** (O(log n) only for a miss on a mixed-class or custom-key tree — see [Key Requirements](#key-requirements))
+- `has_key?` - **O(1)** (same proviso)
 - `min` / `max` - **O(1)**
 - `shift` / `pop` - O(log n)
 - `prev` / `succ` - O(log n) with O(1) hash check and faster startup
+- `clear` - **O(1)** (nodes are left to the GC rather than recycled)
 
 Iteration over all elements takes O(n) time.
 
+> **On lookup misses:** resolving key identity through ordering rather than `eql?` costs
+> nothing for ordinary key types. Measured on a 200,000-entry Integer-keyed tree, 50,000
+> missing lookups take 8.1 ms against 6.3 ms for a bare hash probe — the difference is a
+> class check, not a tree descent. Only a mixed-class or custom-key tree pays the descent
+> (~1.4 µs per miss). Hits, insert, delete, iteration and range queries are unaffected.
+
 ### RBTree vs Hash vs Array (Overwhelming Power)
 
 For ordered and spatial operations, RBTree is not just faster—it is in a completely different class. The following benchmarks were conducted with **500,000 items**:

data/Rakefile

@@ -2,6 +2,13 @@
 
 require "bundler/gem_tasks"
 require "rdoc/task"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib" << "test"
+  t.test_files = FileList["test/**/test_*.rb"]
+  t.warning = false
+end
 
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = "doc"

data/lib/rbtree/version.rb

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