rbtree-ruby 0.3.5 → 0.4.0

data/lib/rbtree.rb

@@ -54,6 +54,29 @@ require_relative "rbtree/version"
 class RBTree
   include Enumerable
 
+  # Key classes where <tt>(a <=> b) == 0</tt> and <tt>a.eql?(b)</tt> agree for any two
+  # instances of that same class, letting {#find_node} skip its fallback descent.
+  COHERENT_KEY_CLASSES = [
+    Integer, Float, Rational, String, Symbol, Time,
+  ].to_h { |klass| [klass, true] }
+  private_constant :COHERENT_KEY_CLASSES
+
+  # Declares that <tt>(a <=> b) == 0</tt> and +a.eql?(b)+ agree for instances of the
+  # given key class, speeding up lookups that miss the internal hash index.
+  #
+  # Optimization hint only: undeclared classes are still handled correctly, at
+  # O(log n) per missed lookup. Declaring a class that does not satisfy this makes
+  # such lookups report a present key as absent.
+  #
+  # @param klass [Class] the key class to declare coherent
+  # @return [Class] the declared class
+  # @example
+  #   RBTree.coherent_key_class(Version)
+  def self.coherent_key_class(klass)
+    COHERENT_KEY_CLASSES[klass] = true
+    klass
+  end
+
   # Returns the number of key-value pairs stored in the tree.
   # @return [Integer] the number of entries in the tree
   attr_reader :key_count
@@ -100,9 +123,12 @@ class RBTree
     @root = @nil_node
     @min_node = @nil_node
     @max_node = @nil_node
-    @hash_index = {}  # Hash index for O(1) key lookup
+    @hash_index = {}  # Hash index for O(1) key lookup, one entry per node
     @node_allocator = node_allocator
     @key_count = 0
+    @mod_count = 0    # bumped by changes a traversal can observe
+    @key_class = nil  # single class of all keys, or false once mixed
+    @coherent_keys = false
 
     @overwrite = overwrite
 
@@ -111,10 +137,28 @@ class RBTree
     end
   end
 
-  # Returns a Hash containing all key-value pairs from the tree.
+  # Creates a deep copy of the tree.
+  # Called automatically by `dup` and `clone`.
+  #
+  # The copy shares the original's node allocator instance.
+  #
+  # @param orig [RBTree] the original tree to copy
+  # @return [void]
+  def initialize_copy(orig)
+    initialize(
+      overwrite: orig.instance_variable_get(:@overwrite),
+      node_allocator: orig.instance_variable_get(:@node_allocator))
+    orig.each { |k, v| insert(k, v) }
+  end
+
+  # Returns a Hash containing all key-value pairs from the tree, in ascending key order.
   #
   # @return [Hash] a new Hash with the tree's contents
-  def to_h = @hash_index.transform_values(&:value)
+  def to_h
+    h = {}
+    each { |k, v| h[k] = v }
+    h
+  end
 
   # Checks if the tree is empty.
   #
@@ -136,11 +180,19 @@ class RBTree
 
   # 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
+  # With no argument and no block this is an O(1) cached lookup; given a count or a
+  # comparison block, `Enumerable#min` semantics apply instead.
+  #
+  # @param args [Integer] optional number of smallest pairs to return
+  # @return [Array, nil] the pair, or the n smallest pairs, or nil if tree is empty
   # @example
   #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
-  #   tree.min  # => [1, "one"]
-  def min = min_node&.pair
+  #   tree.min     # => [1, "one"]
+  #   tree.min(2)  # => [[1, "one"], [2, "two"]]
+  def min(*args, &block)
+    return super if !args.empty? || block
+    min_node&.pair
+  end
 
   # Returns the maximum key without removing it.
   #
@@ -152,37 +204,59 @@ class RBTree
 
   # 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
+  # With no argument and no block this is an O(1) cached lookup; given a count or a
+  # comparison block, `Enumerable#max` semantics apply instead.
+  #
+  # @param args [Integer] optional number of largest pairs to return
+  # @return [Array, nil] the pair, or the n largest pairs, or nil if tree is empty
   # @example
   #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
-  #   tree.max  # => [3, "three"]
-  def max = max_node&.pair
+  #   tree.max     # => [3, "three"]
+  #   tree.max(2)  # => [[3, "three"], [2, "two"]]
+  def max(*args, &block)
+    return super if !args.empty? || block
+    max_node&.pair
+  end
 
-  # Returns the first key-value pair without removing it.
+  # Returns the first key-value pair, or the first +n+ pairs, without removing them.
   #
-  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  # @param n [Integer, nil] number of leading pairs to return
+  # @return [Array, nil] the pair, or the n smallest pairs in ascending order
   # @example
   #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
-  #   tree.first  # => [1, "one"]
-  def first = min
+  #   tree.first     # => [1, "one"]
+  #   tree.first(2)  # => [[1, "one"], [2, "two"]]
+  def first(n = nil) = n.nil? ? min : take(n)
 
-  # Returns the last key-value pair without removing it.
+  # Returns the last key-value pair, or the last +n+ pairs, without removing them.
   #
-  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  # @param n [Integer, nil] number of trailing pairs to return
+  # @return [Array, nil] the pair, or the n largest pairs in ascending order
   # @example
   #   tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
-  #   tree.last  # => [3, "three"]
-  def last = max
+  #   tree.last     # => [3, "three"]
+  #   tree.last(2)  # => [[2, "two"], [3, "three"]]
+  def last(n = nil)
+    return max if n.nil?
+    result = []
+    reverse_each { |pair| break if result.size >= n; result << pair }
+    result.reverse!
+    result
+  end
 
   # Checks if the tree contains the given key.
   #
+  # A key counts as present when <tt>(key <=> stored_key) == 0</tt>, even if the two
+  # objects are not +eql?+ (e.g. +1.0+ finds a stored +1+).
+  #
   # @param key [Object] the key to search for
   # @return [Boolean] true if the key exists in the tree, false otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two'})
-  #   tree.key?(1)  # => true
-  #   tree.key?(3)  # => false
-  def has_key?(key) = @hash_index.key?(key)
+  #   tree.key?(1)    # => true
+  #   tree.key?(1.0)  # => true
+  #   tree.key?(3)    # => false
+  def has_key?(key) = @hash_index.key?(key) || !find_node_by_order(key).nil?
   alias :key? :has_key?
 
   # Retrieves the value associated with the given key.
@@ -192,7 +266,7 @@ class RBTree
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two'})
   #   tree.get(1)  # => "one"
-  def value(key) = @hash_index[key]&.value
+  def value(key) = (@hash_index[key] || find_node_by_order(key))&.value
   alias :get :value
 
   # Retrieves a value associated with the given key, or a range of entries if a Range is provided.
@@ -353,6 +427,9 @@ class RBTree
         raise ArgumentError, "Source must be iterable"
       end
 
+      # Self-insertion (e.g. tree.merge!(tree)) must not mutate what it iterates.
+      source = source.to_a if source.equal?(self)
+
       source.each do |*pair|
         key, value = nil, nil
         if pair.size == 1 && pair[0].is_a?(Array)
@@ -369,21 +446,54 @@ class RBTree
   end
   alias :[]= :insert
   
+  # Returns a new tree containing the merged contents of self and other.
+  #
+  # When a block is given, it is called with (key, old_value, new_value) for
+  # duplicate keys, and the block's return value is used.
+  #
+  # @param other [RBTree, Hash, Enumerable] the source to merge from
+  # @yield [key, old_value, new_value] called for duplicate keys when block given
+  # @return [RBTree] a new tree with merged contents
+  def merge(other, &block)
+    dup.merge!(other, &block)
+  end
+
   # Merges the contents of another tree, hash, or enumerable into this tree.
   #
+  # When a block is given, it is called with (key, old_value, new_value) for
+  # duplicate keys, and the block's return value is used.
+  #
   # @param other [RBTree, Hash, Enumerable] the source to merge from
-  # @param overwrite [Boolean] whether to overwrite existing keys (default: true)
+  # @param overwrite [Boolean] whether to overwrite existing keys (default: true). Ignored if block given.
+  # @yield [key, old_value, new_value] called for duplicate keys when block given
   # @return [RBTree] self
-  def merge!(other, overwrite: true)
+  def merge!(other, overwrite: true, &block)
     if defined?(MultiRBTree) && other.is_a?(MultiRBTree)
       raise ArgumentError, "Cannot merge MultiRBTree into RBTree"
     end
-    insert(other, overwrite: overwrite)
+    if block
+      other_enum = other.is_a?(Hash) || other.is_a?(RBTree) ? other : other.each
+      # Snapshot on self-merge; see RBTree#insert.
+      other_enum = other_enum.to_a if other_enum.equal?(self)
+      other_enum.each do |k, v|
+        if has_key?(k)
+          insert_entry(k, block.call(k, value(k), v), overwrite: true)
+        else
+          insert_entry(k, v)
+        end
+      end
+    else
+      insert(other, overwrite: overwrite)
+    end
     self
   end
 
   # Deletes the key-value pair with the specified key.
   #
+  # Entries whose value is +nil+ or +false+ are deleted correctly, so the return
+  # value alone cannot distinguish them from a missing key; use {#has_key?} first
+  # if that matters.
+  #
   # @param key [Object] the key to delete
   # @return [Object, nil] the value associated with the deleted key, or nil if not found
   # @example
@@ -391,8 +501,9 @@ class RBTree
   #   tree.delete(1)  # => "one"
   #   tree.delete(3)  # => nil
   def delete_key(key)
-    return nil unless (value = (z = @hash_index[key])&.value)
-    delete_indexed_node(key)
+    return nil unless (z = find_node(key))
+    value = z.value
+    delete_found_node(z)
     value
   end
   alias :delete :delete_key
@@ -427,11 +538,18 @@ class RBTree
 
   # Removes all key-value pairs from the tree.
   #
+  # Runs in O(1): the nodes are left to the garbage collector, and the allocator is
+  # told of the bulk discard so that pool statistics stay accurate.
+  #
   # @return [RBTree] self
   def clear
+    @node_allocator.discard(@key_count) if @key_count > 0
     @root = @min_node = @max_node = @nil_node
     @hash_index.clear
     @key_count = 0
+    @key_class = nil
+    @coherent_keys = false
+    @mod_count += 1
     self
   end
 
@@ -457,7 +575,8 @@ class RBTree
   #     tree.delete(k) if k.even?
   #   end
   def keys(reverse: false, safe: false, &block)
-    return enum_for(__method__, reverse: reverse, safe: safe) { @key_count } unless block_given?
+    # `size`, not `key_count`: MultiRBTree yields a key once per value it holds.
+    return enum_for(__method__, reverse: reverse, safe: safe) { size } unless block_given?
     each(reverse: reverse, safe: safe) { |key, _| yield key }
     self
   end
@@ -602,6 +721,72 @@ class RBTree
     self
   end
 
+  # Returns a new tree containing key-value pairs for which the block returns true.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, Enumerator] a new tree with selected pairs, or Enumerator if no block
+  def select(&block)
+    return enum_for(__method__) { size } unless block_given?
+    result = new_derived_tree
+    each { |k, v| result.insert(k, v) if block.call(k, v) }
+    result
+  end
+
+  # Returns a new tree containing key-value pairs for which the block returns false.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, Enumerator] a new tree with non-rejected pairs, or Enumerator if no block
+  def reject(&block)
+    return enum_for(__method__) { size } unless block_given?
+    result = new_derived_tree
+    each { |k, v| result.insert(k, v) unless block.call(k, v) }
+    result
+  end
+
+  # Deletes key-value pairs for which the block returns true. Returns nil if no changes were made.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, nil, Enumerator] self if changed, nil if unchanged, or Enumerator if no block
+  def reject!(&block)
+    return enum_for(__method__) { size } unless block_given?
+    size_before = size
+    delete_if(&block)
+    size == size_before ? nil : self
+  end
+
+  # Keeps key-value pairs for which the block returns true, deleting the rest. Modifies the tree in place.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, Enumerator] self, or Enumerator if no block
+  def keep_if(&block)
+    return enum_for(__method__) { size } unless block_given?
+    each(safe: true) { |k, v| delete(k) unless block.call(k, v) }
+    self
+  end
+
+  # Deletes key-value pairs for which the block returns true. Modifies the tree in place.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [RBTree, Enumerator] self, or Enumerator if no block
+  def delete_if(&block)
+    return enum_for(__method__) { size } unless block_given?
+    each(safe: true) { |k, v| delete(k) if block.call(k, v) }
+    self
+  end
+
+  # Returns a new tree with keys and values swapped.
+  #
+  # For RBTree, duplicate values result in later keys overwriting earlier ones.
+  # For MultiRBTree, all key-value pairs are preserved.
+  # Values must implement <=> to serve as keys in the new tree.
+  #
+  # @return [RBTree, MultiRBTree] a new tree with keys and values inverted
+  def invert
+    result = new_derived_tree
+    each { |k, v| result.insert(v, k) }
+    result
+  end
+
   # Returns a string representation of the tree.
   #
   # Shows the first 5 entries and total size. Useful for debugging.
@@ -613,19 +798,41 @@ class RBTree
     "#<#{self.class}:0x#{object_id.to_s(16)} size=#{size} {#{content}#{suffix}}>"
   end
 
-  # Validates the red-black tree properties.
+  # Validates the red-black tree properties and the auxiliary structures.
   #
   # Checks that:
-  # 1. Root is black
+  # 1. Root is black and has no parent
   # 2. All paths from root to leaves have the same number of black nodes
   # 3. No red node has a red child
-  # 4. Keys are properly ordered
+  # 4. Keys are ordered against bounds inherited from ancestors
+  # 5. Every child's parent pointer points back at its parent
+  # 6. The Hash index holds exactly one entry per node, mapped to that node
+  # 7. `@min_node` / `@max_node` are the actual extremes, and `key_count` is right
   #
   # @return [Boolean] true if all properties are satisfied, false otherwise
   def valid?
     return false if @root.color == Node::RED
+    return false if @root != @nil_node && @root.parent != @nil_node
     return false if check_black_height(@root) == -1
-    return false unless check_order(@root)
+    return false unless check_order(@root, nil, nil)
+    return false unless check_links(@root)
+
+    count = 0
+    first_node = nil
+    last_node = nil
+    indexed = true
+    each_node_asc do |n|
+      count += 1
+      first_node ||= n
+      last_node = n
+      indexed &&= @hash_index[n.key].equal?(n)
+    end
+
+    return false unless indexed
+    return false unless count == @key_count
+    return false unless @hash_index.size == @key_count
+    return false unless (first_node || @nil_node).equal?(@min_node)
+    return false unless (last_node || @nil_node).equal?(@max_node)
     true
   end
 
@@ -635,6 +842,108 @@ class RBTree
   def min_node = (@min_node == @nil_node) ? nil : @min_node
   def max_node = (@max_node == @nil_node) ? nil : @max_node
 
+  # Creates an empty tree of the same class, keeping this tree's allocator.
+  #
+  # @return [RBTree] a new empty tree
+  def new_derived_tree = self.class.new(node_allocator: @node_allocator)
+
+  # Locates the node holding the given key, by O(1) hash index or by ordering.
+  #
+  # The index is keyed by +eql?+ while the tree orders by <tt><=></tt>, so a key
+  # such as +1.0+ misses the index but still matches a stored +1+.
+  #
+  # @param key [Object] the key to locate
+  # @return [Node, nil] the node holding an equal key, or nil if absent
+  def find_node(key) = @hash_index[key] || find_node_by_order(key)
+
+  # Resolves a key the hash index missed, using the tree's <tt><=></tt> ordering.
+  #
+  # Split from {#find_node} so hot callers can inline the hash probe and pay no
+  # method call on a hit. The descent is skipped when every stored key and the
+  # lookup key share a class in {COHERENT_KEY_CLASSES}, since a match would then
+  # have been found in the index already. Incomparable keys report absence rather
+  # than raising, so lookups stay total.
+  #
+  # @param key [Object] the key to locate
+  # @return [Node, nil] the node holding an equal key, or nil if absent
+  def find_node_by_order(key)
+    return nil if @coherent_keys && key.instance_of?(@key_class)
+
+    x = @root
+    while x != @nil_node
+      cmp = key <=> x.key
+      return nil unless cmp
+      return x if cmp == 0
+      x = cmp < 0 ? x.left : x.right
+    end
+    nil
+  end
+
+  # Records the class of a newly inserted key for {#find_node_by_order}.
+  #
+  # Deletion never relaxes the result: a stale pessimistic value costs a descent,
+  # never correctness.
+  #
+  # @param key [Object] the key of the node being created
+  # @return [void]
+  def note_key_class(key)
+    klass = key.class
+    return if @key_class.equal?(klass)
+
+    if @key_class.nil?
+      @key_class = klass
+      @coherent_keys = COHERENT_KEY_CLASSES.include?(klass)
+    else
+      @key_class = false
+      @coherent_keys = false
+    end
+  end
+
+  # Compares two keys, rejecting incomparable ones with a clear error.
+  #
+  # @param a [Object] the left-hand key
+  # @param b [Object] the right-hand key
+  # @return [Integer] the result of <tt>a <=> b</tt>
+  # @raise [ArgumentError] if the keys cannot be compared
+  def compare!(a, b)
+    cmp = a <=> b
+    return cmp if cmp
+    raise ArgumentError, "comparison of #{a.class} with #{b.inspect} failed"
+  end
+
+  # Reports mutation detected during a non-safe traversal.
+  #
+  # Such a traversal walks live node links, and released nodes are recycled by the
+  # allocator, so mutating during one can yield keys out of order rather than
+  # merely skip them. Callers compare `@mod_count` inline and only call this on
+  # mismatch, keeping the per-element cost to an integer comparison.
+  #
+  # @raise [RuntimeError] always
+  # @return [void]
+  def concurrent_modification!
+    raise RuntimeError,
+      "can't modify #{self.class} during iteration (pass `safe: true` to iterate safely)"
+  end
+
+  # Walks every node in ascending key order, following live tree links.
+  #
+  # @yield [node] each node
+  # @return [void]
+  def each_node_asc
+    stack = []
+    current = @root
+    while current != @nil_node || !stack.empty?
+      if current != @nil_node
+        stack << current
+        current = current.left
+      else
+        current = stack.pop
+        yield current
+        current = current.right
+      end
+    end
+  end
+
   # Inserts a single key-value pair.
   #
   # @param key [Object] the key to insert
@@ -658,6 +967,9 @@ class RBTree
 
   # Generic entry insertion logic shared between RBTree and MultiRBTree.
   #
+  # A key that is <tt><=></tt>-equal to a stored key updates that node, which keeps
+  # the key object it was created with, so the index stays at one entry per node.
+  #
   # @param key [Object] the key to insert
   # @yield [node, is_new] yields the existing node (if any) and whether it's a new insertion
   # @yieldparam node [Node, nil] the existing node or nil
@@ -665,6 +977,7 @@ class RBTree
   # @yieldreturn [Object]
   #   - if is_new: the initial value for the new node
   #   - if !is_new: the value to return from insert_entry
+  # @raise [ArgumentError] if the key cannot be compared with the stored keys
   def insert_entry_generic(key)
     if (node = @hash_index[key])
       return yield(node, false)
@@ -675,6 +988,9 @@ class RBTree
     while x != @nil_node
       y = x
       cmp = key <=> x.key
+      unless cmp
+        raise ArgumentError, "comparison of #{key.class} with #{x.key.inspect} failed"
+      end
       if cmp == 0
         return yield(x, false)
       elsif cmp < 0
@@ -708,6 +1024,8 @@ class RBTree
     end
     
     @hash_index[key] = z
+    note_key_class(key)
+    @mod_count += 1
     true
   end
 
@@ -748,13 +1066,13 @@ class RBTree
 
     if safe
       pair = !min ? find_min :
-        include_min && @hash_index[min]&.pair || find_successor(min)
-      while pair && (!max || pair[0] < max)
+        include_min && find_node(min)&.pair || find_successor(min)
+      while pair && (!max || (pair[0] <=> max) < 0)
         current_key = pair[0]
         yield pair
         pair = find_successor(current_key)
       end
-      yield pair if pair && max && include_max && pair[0] == max
+      yield pair if pair && max && include_max && (pair[0] <=> max) == 0
     else
       start_node, stack = resolve_startup_asc(min, include_min)
       traverse_from_asc(start_node, stack, max, include_max, &block)
@@ -780,13 +1098,13 @@ class RBTree
 
     if safe
       pair = !max ? find_max :
-        include_max && @hash_index[max]&.pair || find_predecessor(max)
-      while pair && (!min || pair[0] > min)
+        include_max && find_node(max)&.pair || find_predecessor(max)
+      while pair && (!min || (pair[0] <=> min) > 0)
         current_key = pair[0]
         yield pair
         pair = find_predecessor(current_key)
       end
-      yield pair if pair && min && include_min && pair[0] == min
+      yield pair if pair && min && include_min && (pair[0] <=> min) == 0
     else
       start_node, stack = resolve_startup_desc(max, include_max)
       traverse_from_desc(start_node, stack, min, include_min, &block)
@@ -838,7 +1156,8 @@ class RBTree
       return [@min_node, reconstruct_stack_asc(@min_node)]
     end
     
-    # 2. Use Hash index if key exists
+    # 2. Use Hash index if key exists. A pure O(1) probe, not {#find_node}: on a
+    #    miss, step 3's descent already places a <=>-equal node correctly.
     if min && (node = @hash_index[min])
       start_node = include_min ? node : successor_node_of(node)
       return [start_node, reconstruct_stack_asc(start_node)]
@@ -884,16 +1203,21 @@ class RBTree
   # @yieldparam key [Object] the key
   # @yieldparam val [Object] the value
   def traverse_from_asc(current, stack, max, include_max, &block)
+    mod = @mod_count
     while current != @nil_node || !stack.empty?
       if current != @nil_node
         if max
           cmp = current.key <=> max
           if cmp >= 0
-            yield current.pair if include_max && cmp == 0
+            if include_max && cmp == 0
+              yield current.pair
+              concurrent_modification! unless @mod_count == mod
+            end
             return
           end
         end
         yield current.pair
+        concurrent_modification! unless @mod_count == mod
         current = current.right
         while current != @nil_node
           stack << current
@@ -916,7 +1240,7 @@ class RBTree
       return [@max_node, reconstruct_stack_desc(@max_node)]
     end
   
-    # 2. Use Hash index if key exists
+    # 2. Use Hash index if key exists; see the note in #resolve_startup_asc.
     if max && (node = @hash_index[max])
       start_node = include_max ? node : predecessor_node_of(node)
       return [start_node, reconstruct_stack_desc(start_node)]
@@ -962,16 +1286,21 @@ class RBTree
   # @yieldparam key [Object] the key
   # @yieldparam val [Object] the value
   def traverse_from_desc(current, stack, min, include_min, &block)
+    mod = @mod_count
     while current != @nil_node || !stack.empty?
       if current != @nil_node
         if min
           cmp = current.key <=> min
           if cmp <= 0
-            yield current.pair if include_min && cmp == 0
+            if include_min && cmp == 0
+              yield current.pair
+              concurrent_modification! unless @mod_count == mod
+            end
             return
           end
         end
         yield current.pair
+        concurrent_modification! unless @mod_count == mod
         current = current.left
         while current != @nil_node
           stack << current
@@ -1033,7 +1362,17 @@ class RBTree
   #
   # @param key [Object] the key to delete
   # @return [Object, nil] the value of the deleted node, or nil if not found
-  def delete_indexed_node(key) = (z = @hash_index.delete(key)) && delete_node(z)
+  def delete_indexed_node(key) = (z = find_node(key)) && delete_found_node(z)
+
+  # Removes an already-located node, unindexing it under its own key so that a node
+  # found through a non-+eql?+ but <tt><=></tt>-equal key is still removed correctly.
+  #
+  # @param z [Node] the node to remove
+  # @return [Object] the value of the removed node
+  def delete_found_node(z)
+    @hash_index.delete(z.key)
+    delete_node(z)
+  end
 
   # Removes a node from the tree and restores red-black properties.
   #
@@ -1092,6 +1431,7 @@ class RBTree
 
     value = z.value
     release_node(z)
+    @mod_count += 1
     value
   end
 
@@ -1229,8 +1569,9 @@ class RBTree
   # @return [Node] the predecessor node, or @nil_node if none exists
   def find_predecessor_node(key)
     # If key is larger than max_key, return max_node
-    return @max_node if max_key && (key <=> max_key) > 0
-    # If key exists using O(1) hash lookup, return predecessor node
+    return @max_node if (mk = max_key) && compare!(key, mk) > 0
+    # O(1) hash fast path; on a miss the descent below steps away from a
+    # <=>-equal node in the right direction anyway.
     if (node = @hash_index[key])
       return predecessor_node_of(node)
     end
@@ -1269,10 +1610,10 @@ class RBTree
   # @return [Node] the successor node, or @nil_node if none exists
   def find_successor_node(key)
     # If key is larger than or equal to max_key, return nil
-    return @nil_node if max_key && (key <=> max_key) >= 0
+    return @nil_node if (mk = max_key) && compare!(key, mk) >= 0
     # If key is smaller than min_key, return min_node
-    return @min_node if min_key && (key <=> min_key) < 0
-    # If key exists using O(1) hash lookup, return successor node
+    return @min_node if (nk = min_key) && compare!(key, nk) < 0
+    # O(1) hash fast path; see the note in #find_predecessor_node.
     if (node = @hash_index[key])
       return successor_node_of(node)
     end
@@ -1431,15 +1772,31 @@ class RBTree
     left_h + (node.color == Node::BLACK ? 1 : 0)
   end
 
-  def check_order(node)
+  # Recursively checks the binary-search-tree ordering.
+  #
+  # Bounds are inherited from ancestors, so a key misplaced relative to a higher
+  # ancestor is rejected even when it is ordered correctly against its parent.
+  #
+  # @param node [Node] the current node
+  # @param lo [Object, nil] exclusive lower bound inherited from ancestors
+  # @param hi [Object, nil] exclusive upper bound inherited from ancestors
+  # @return [Boolean] true if the subtree is correctly ordered
+  def check_order(node, lo, hi)
+    return true if node == @nil_node
+    return false if lo && (node.key <=> lo) <= 0
+    return false if hi && (node.key <=> hi) >= 0
+    check_order(node.left, lo, node.key) && check_order(node.right, node.key, hi)
+  end
+
+  # Recursively checks that every child points back at its parent.
+  #
+  # @param node [Node] the current node
+  # @return [Boolean] true if all parent links in the subtree are consistent
+  def check_links(node)
     return true if node == @nil_node
-    if node.left != @nil_node && (node.left.key <=> node.key) >= 0
-      return false
-    end
-    if node.right != @nil_node && (node.right.key <=> node.key) <= 0
-      return false
-    end
-    check_order(node.left) && check_order(node.right)
+    return false if node.left != @nil_node && !node.left.parent.equal?(node)
+    return false if node.right != @nil_node && !node.right.parent.equal?(node)
+    check_links(node.left) && check_links(node.right)
   end
 end
 
@@ -1508,6 +1865,11 @@ end
 # @author Masahito Suzuki
 # @since 0.1.2
 class MultiRBTree < RBTree
+  # Sentinel for "no key given", so +nil+ and +false+ stay usable as keys.
+  # @api private
+  NO_KEY = Object.new
+  private_constant :NO_KEY
+
   def initialize(*args, **kwargs)
     @value_count = 0
     super
@@ -1516,38 +1878,90 @@ class MultiRBTree < RBTree
   # Returns the number of values stored in the tree.
   # @return [Integer] the number of values in the tree
   def size = @value_count
+
+  # Removes all elements from the tree.
+  # @return [MultiRBTree] self
+  def clear
+    @value_count = 0
+    super
+  end
+
+  # Returns a Hash mapping each key to an Array of its values.
+  #
+  # Keys are inserted in ascending order, and each value Array is a fresh copy,
+  # so mutating the result cannot corrupt the tree.
+  #
+  # @return [Hash] a new Hash with the tree's contents
+  # @example
+  #   tree = MultiRBTree.new
+  #   tree.insert(1, 'a'); tree.insert(1, 'b')
+  #   tree.to_h  # => {1 => ["a", "b"]}
+  def to_h
+    h = {}
+    each { |k, v| (h[k] ||= []) << v }
+    h
+  end
+
+  # Validates everything `RBTree#valid?` does, plus that every node holds a
+  # non-empty Array of values and that `size` matches the total value count.
+  #
+  # @return [Boolean] true if all properties are satisfied, false otherwise
+  def valid?
+    return false unless super
+    total = 0
+    ok = true
+    each_node_asc do |n|
+      ok &&= n.value.is_a?(Array) && !n.value.empty?
+      total += n.value.size if n.value.is_a?(Array)
+    end
+    ok && total == @value_count
+  end
   
   # Returns the minimum key-value pair without removing it.
   #
+  # As with `RBTree#min`, a count or comparison block switches to `Enumerable#min`.
+  #
   # @param last [Boolean] whether to return the last value (default: false)
   # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
   # @example
   #   tree = MultiRBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
   #   tree.min  # => [1, "one"]
-  def min(last: false) = (n = min_node) && [n.key, n.value.send(last ? :last : :first)]
+  def min(*args, last: false, &block)
+    return super(*args, &block) if !args.empty? || block
+    (n = min_node) && [n.key, n.value.send(last ? :last : :first)]
+  end
 
   # Returns the maximum key-value pair without removing it.
   #
+  # As with `RBTree#max`, a count or comparison block switches to `Enumerable#max`.
+  #
   # @param last [Boolean] whether to return the last value (default: false)
   # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
   # @example
   #   tree = MultiRBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
   #   tree.max  # => [3, "three"]
-  def max(last: false) = (n = max_node) && [n.key, n.value.send(last ? :last : :first)]
+  def max(*args, last: false, &block)
+    return super(*args, &block) if !args.empty? || block
+    (n = max_node) && [n.key, n.value.send(last ? :last : :first)]
+  end
 
-  # Returns the last key-value pair without removing it.
+  # Returns the last key-value pair, or the last +n+ pairs, without removing them.
   #
-  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if tree is empty
+  # @param n [Integer, nil] number of trailing pairs to return
+  # @return [Array, nil] the pair, or the n last pairs in ascending order
   # @example
   #   tree = MultiRBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
   #   tree.last  # => [3, "three"]
-  def last = max(last: true)
+  def last(n = nil) = n.nil? ? max(last: true) : super(n)
 
-  # Returns the number of values for a given key or the total number of key-value pairs if no key is given.
+  # Returns the number of values for a given key, or the total number of key-value
+  # pairs when called without an argument.
+  #
+  # The default is a sentinel, so +nil+ and +false+ are looked up as ordinary keys.
   #
-  # @param key [Object, nil] the key to look up, or nil for total count
+  # @param key [Object] the key to look up; omit for the total count
   # @return [Integer] the number of values for the key, or total count if no key is given
-  def value_count(key = nil) = !key ? size : (@hash_index[key]&.value&.size || 0)
+  def value_count(key = NO_KEY) = key.equal?(NO_KEY) ? size : (find_node(key)&.value&.size || 0)
 
   # Retrieves a value associated with the given key.
   #
@@ -1560,7 +1974,7 @@ class MultiRBTree < RBTree
   #   tree.insert(1, 'second')
   #   tree.get(1)              # => "first"
   #   tree.get(1, last: true)  # => "second"
-  def value(key, last: false) = @hash_index[key]&.value&.send(last ? :last : :first)
+  def value(key, last: false) = (@hash_index[key] || find_node_by_order(key))&.value&.send(last ? :last : :first)
   alias :get :value
 
   # Retrieves the first value associated with the given key.
@@ -1580,15 +1994,17 @@ class MultiRBTree < RBTree
   # 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
+  # @param reverse [Boolean] if true, yield the values in reverse insertion order (default: false)
+  # @return [Enumerator, nil] an Enumerator over the values, or nil if the key is absent (when a block is given)
   # @example
   #   tree = MultiRBTree.new
   #   tree.insert(1, 'first')
   #   tree.insert(1, 'second')
-  #   tree.values(1).to_a   # => ["first", "second"]
+  #   tree.values(1).to_a                 # => ["first", "second"]
+  #   tree.values(1, reverse: true).to_a  # => ["second", "first"]
   def values(key, reverse: false)
-    return enum_for(__method__, key) { value_count(key) } unless block_given?
-    @hash_index[key]&.value&.send(reverse ? :reverse_each : :each) { |v| yield v }
+    return enum_for(__method__, key, reverse: reverse) { value_count(key) } unless block_given?
+    find_node(key)&.value&.send(reverse ? :reverse_each : :each) { |v| yield v }
   end
   alias :get_all :values
 
@@ -1648,9 +2064,13 @@ class MultiRBTree < RBTree
   #   tree.delete_value(1)            # => "first"
   #   tree.delete_value(1, last: true)  # => "second" (if more values existed)
   def delete_value(key, last: false)
-    (z = @hash_index[key]) or return nil
+    (z = find_node(key)) or return nil
     value = z.value.send(last ? :pop : :shift)
-    z.value.empty? && delete_indexed_node(key)
+    if z.value.empty?
+      delete_found_node(z)
+    else
+      @mod_count += 1
+    end
     @value_count -= 1
     value
   end
@@ -1683,9 +2103,9 @@ class MultiRBTree < RBTree
   #   vals = tree.delete(1)  # removes both values
   #   vals.size  # => 2
   def delete_key(key)
-    return nil unless (z = @hash_index[key])
+    return nil unless (z = find_node(key))
     @value_count -= (value = z.value).size
-    delete_indexed_node(z.key)
+    delete_found_node(z)
     value
   end
   alias :delete :delete_key
@@ -1697,9 +2117,14 @@ class MultiRBTree < RBTree
   #   tree = MultiRBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
   #   tree.shift  # => [1, "one"]
   def shift
-    (key, vals = min_node&.pair) or return nil
+    (n = min_node) or return nil
+    key, vals = n.pair
     val = vals.shift
-    vals.empty? && delete_indexed_node(key)
+    if vals.empty?
+      delete_found_node(n)
+    else
+      @mod_count += 1
+    end
     @value_count -= 1
     [key, val]
   end
@@ -1711,16 +2136,61 @@ class MultiRBTree < RBTree
   #   tree = MultiRBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
   #   tree.pop  # => [3, "three"]
   def pop
-    (key, vals = max_node&.pair) or return nil
+    (n = max_node) or return nil
+    key, vals = n.pair
     val = vals.pop
-    vals.empty? && delete_indexed_node(key)
+    if vals.empty?
+      delete_found_node(n)
+    else
+      @mod_count += 1
+    end
     @value_count -= 1
     [key, val]
   end
 
+  # Keeps key-value pairs for which the block returns true, deleting the rest.
+  # Unlike RBTree, this removes individual values rather than entire keys.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [MultiRBTree, Enumerator] self, or Enumerator if no block
+  def keep_if(&block)
+    return enum_for(__method__) { size } unless block_given?
+    filter_values! { |k, v| block.call(k, v) }
+    self
+  end
+
+  # Deletes key-value pairs for which the block returns true.
+  # Unlike RBTree, this removes individual values rather than entire keys.
+  #
+  # @yield [key, value] each key-value pair
+  # @return [MultiRBTree, Enumerator] self, or Enumerator if no block
+  def delete_if(&block)
+    return enum_for(__method__) { size } unless block_given?
+    filter_values! { |k, v| !block.call(k, v) }
+    self
+  end
+
   # @!visibility private
   private
 
+  # Filters values in-place across all nodes.
+  # Keeps only values for which the block returns true.
+  # Removes nodes whose value arrays become empty.
+  # Updates @value_count accordingly.
+  def filter_values!
+    emptied = []
+    @hash_index.each_value do |node|
+      before = node.value.size
+      node.value.select! { |v| yield node.key, v }
+      removed = before - node.value.size
+      next if removed == 0
+      @value_count -= removed
+      @mod_count += 1
+      emptied << node if node.value.empty?
+    end
+    emptied.each { |node| delete_found_node(node) }
+  end
+
   # Inserts a value for the given key.
   #
   # If the key already exists, the value is appended to its list.
@@ -1741,6 +2211,7 @@ class MultiRBTree < RBTree
         [value]
       else
         node.value << value
+        @mod_count += 1  # observable to a traversal walking this value list
         true
       end
     end
@@ -1748,22 +2219,49 @@ class MultiRBTree < RBTree
 
   # Traverses the tree in ascending order, yielding each key-value pair.
   #
-  # @param range [Range] the range of keys to traverse
+  # Each node's value list is flattened to one [key, value] pair per value. Safe
+  # mode snapshots the list, so removing values of the key being iterated cannot
+  # skip its siblings, though such values may still be yielded.
+  #
+  # @param min [Object] the lower bound
+  # @param max [Object] the upper bound
+  # @param include_min [Boolean] whether to include the lower bound
+  # @param include_max [Boolean] whether to include the upper bound
+  # @param safe [Boolean] whether to use safe traversal
   # @yield [Array(Object, Object)] each key-value pair
-  # @yieldparam key [Object] the key
-  # @yieldparam val [Object] the value
-  def traverse_range_asc(...)
-    super { |k, vals| vals.each { |v| yield [k, v] } }
+  def traverse_range_asc(min, max, include_min, include_max, safe: false, &block)
+    if safe
+      super(min, max, include_min, include_max, safe: true) do |k, vals|
+        vals.dup.each { |v| yield [k, v] }
+      end
+    else
+      mod = @mod_count
+      super(min, max, include_min, include_max, safe: false) do |k, vals|
+        vals.each { |v| yield [k, v]; concurrent_modification! unless @mod_count == mod }
+      end
+    end
   end
 
   # Traverses the tree in descending order, yielding each key-value pair.
   #
-  # @param range [Range] the range of keys to traverse
+  # @param min [Object] the lower bound
+  # @param max [Object] the upper bound
+  # @param include_min [Boolean] whether to include the lower bound
+  # @param include_max [Boolean] whether to include the upper bound
+  # @param safe [Boolean] whether to use safe traversal
   # @yield [Array(Object, Object)] each key-value pair
-  # @yieldparam key [Object] the key
-  # @yieldparam val [Object] the value
-  def traverse_range_desc(...)
-    super { |k, vals| vals.reverse_each { |v| yield [k, v] } }
+  # @see #traverse_range_asc
+  def traverse_range_desc(min, max, include_min, include_max, safe: false, &block)
+    if safe
+      super(min, max, include_min, include_max, safe: true) do |k, vals|
+        vals.dup.reverse_each { |v| yield [k, v] }
+      end
+    else
+      mod = @mod_count
+      super(min, max, include_min, include_max, safe: false) do |k, vals|
+        vals.reverse_each { |v| yield [k, v]; concurrent_modification! unless @mod_count == mod }
+      end
+    end
   end
 end
 
@@ -1834,6 +2332,15 @@ class RBTree::NodeAllocator
   #
   # @param node [Node] the node to release
   def release(node) = nil
+
+  # Notifies the allocator that +count+ nodes were dropped in bulk rather than
+  # released individually, as `RBTree#clear` does.
+  #
+  # The nodes are not reclaimed for reuse; this only keeps live-node statistics right.
+  #
+  # @param count [Integer] the number of nodes discarded
+  # @return [void]
+  def discard(count) = nil
 end
 
 # Internal node pool for RBTree.
@@ -1947,12 +2454,22 @@ class RBTree::AutoShrinkNodePool < RBTree::NodePool
     @min_active_in_interval = @active_nodes if @active_nodes < @min_active_in_interval
 
     @check_count += 1
-    
+
     perform_maintenance if @check_count >= @check_interval
 
     super if @pool.size < @current_target_capacity
   end
 
+  # Accounts for nodes dropped in bulk, so that the live-node count comes back down
+  # after a `clear` instead of inflating the observed fluctuation range.
+  #
+  # @param count [Integer] the number of nodes discarded
+  # @return [void]
+  def discard(count)
+    @active_nodes -= count
+    @min_active_in_interval = @active_nodes if @active_nodes < @min_active_in_interval
+  end
+
   private
 
   def perform_maintenance