rbtree-ruby 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56ddd66545f9e423b96066b12deea8e22fc86b35b7a97be056ebf91f80543e77
-  data.tar.gz: 10a3ec88b0a5f5cb199ac96267d7665bfee99ab4fb9cf89488790fe798120b05
+  metadata.gz: 8aa1d883925f6b7f608108f1f916598aa04be013aee415c06dfc7bda35d6986c
+  data.tar.gz: e935f213100c933b42a3cf0d709809d5ca8d536db56d6e27a6b3de9681847ad9
 SHA512:
-  metadata.gz: 1d521a30299f8c3db327d1b671d84113cf3c9e5adc90a78747e76b7480ef02ceb95d813a90eeebadfd32e4b8360b2d43fffd1ed1ac4d9314d8368cbe137ce7aa
-  data.tar.gz: 445a6cf0a99efdd0b5b4dc41dd86ec219e784cc3a2ecf150b4467e2619bcb08bd9b47d119d1c5310f43fdecdd7dc19941c3bfa4ae9e7b68d2b359819336f0a97
+  metadata.gz: 419f0270137b6a6ae39bd73d5ea0c4cc25ff0769c288619ee795d172e724040c6032c09c952745b9bb871ff082861c00ae879fa6a98a571414bad87c2534cb9a
+  data.tar.gz: e403cc18d16ff9661a341fb326b3aadebc5d1a83b69ed03395b318cf6666d8de9dca24e88da2a9c231395aa7780ce57ed89902717ad1266bd1551e384872719f

data/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.1.7] - 2026-01-14
+
+### Added
+- **Predecessor/Successor Search**: New `prev(key)` and `succ(key)` methods
+  - Returns the key-value pair immediately before/after the given key
+  - Works even if the key doesn't exist in the tree (returns nearest neighbor)
+  - Uses hash index for O(1) existence check, then O(log n) tree traversal
+- **Reverse Range Queries**: All range query methods now support `:reverse` option
+  - `lt(key, reverse: true)`, `lte`, `gt`, `gte`, `between` 
+  - Returns results in descending order instead of ascending
+- **MultiRBTree Enhancements**:
+  - `get(key, last: false)` - Choose first or last value from array
+  - `get_first(key)`, `get_last(key)` - Convenient aliases
+  - `delete_one(key, last: false)` - Choose which end to delete from
+  - `delete_first(key)`, `delete_last(key)` - Convenient aliases
+  - `min(last: false)`, `max(last: false)` - Choose first or last value
+  - `prev(key, last: false)`, `succ(key, last: false)` - Choose first or last value
+
+### Changed
+- **MultiRBTree Iteration**: Reverse iteration (`reverse_each`, `lt(..., reverse: true)`, etc.) now iterates each key's value array in reverse order (last to first), making it a true mirror of forward iteration
+
+### Fixed
+- **MultiRBTree size tracking**: Fixed bug where `insert` did not increment size when key already existed in hash index
+
+## [0.1.6] - 2026-01-13
+
+### Changed
+- **Performance**: Standardized on Boolean colors (`true`/`false`) instead of Symbols (`:red`/`:black`) for faster checks.
+- **Optimization**: `insert` operations now check the internal hash index first, allowing O(1) updates for existing keys (RBTree) and O(1) appends (MultiRBTree).
+
 ## [0.1.5] - 2026-01-13
 
 ### Changed
@@ -77,6 +107,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.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
 [0.1.5]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.5
 [0.1.4]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.4
 [0.1.3]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.3

data/README.md

@@ -1,4 +1,4 @@
-# RBTree
+# 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.
 
@@ -127,6 +127,66 @@ tree.nearest(7)   # => [5, "five"]  (same distance, returns smaller key)
 tree.nearest(8)   # => [10, "ten"]
 ```
 
+### Predecessor/Successor Search
+
+Find the next or previous key in the tree:
+
+```ruby
+tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
+
+tree.prev(5)   # => [3, "three"]  (largest key < 5)
+tree.succ(5)   # => [7, "seven"]  (smallest key > 5)
+
+# Works even if the key doesn't exist
+tree.prev(4)   # => [3, "three"]  (4 doesn't exist, returns largest key < 4)
+tree.succ(4)   # => [5, "five"]   (4 doesn't exist, returns smallest key > 4)
+
+# Returns nil at boundaries
+tree.prev(1)   # => nil (no key smaller than 1)
+tree.succ(7)   # => nil (no key larger than 7)
+```
+
+### Reverse Range Queries
+
+All range queries support a `:reverse` option to iterate in descending order:
+
+```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.between(1, 4, reverse: true)  # => [[4, "four"], [3, "three"], [2, "two"], [1, "one"]]
+```
+
+### MultiRBTree Value Array Access
+
+For keys with multiple values, choose which value to access:
+
+```ruby
+tree = MultiRBTree.new
+tree.insert(1, 'first')
+tree.insert(1, 'second')
+tree.insert(1, 'third')
+
+# Access first or last value
+tree.get(1)               # => "first"
+tree.get(1, last: true)   # => "third"
+tree.get_first(1)         # => "first"
+tree.get_last(1)          # => "third"
+
+# Delete from either end
+tree.delete_first(1)      # => "first"
+tree.delete_last(1)       # => "third"  
+tree.get(1)               # => "second"
+
+# min/max with :last option
+tree.insert(2, 'a')
+tree.insert(2, 'b')
+tree.min                  # => [1, "second"] (first value of min key)
+tree.max(last: true)      # => [2, "b"]      (last value of max key)
+```
+
 ## Performance
 
 All major operations run in **O(log n)** time:
@@ -138,6 +198,7 @@ All major operations run in **O(log n)** time:
 - `min` - **O(1)**
 - `max` - O(log n)
 - `shift` / `pop` - O(log n)
+- `prev` / `succ` - O(log n) with O(1) hash check
 
 Iteration over all elements takes O(n) time.
 
@@ -147,17 +208,17 @@ RBTree uses an internal **Memory Pool** to recycle node objects.
 - Significantly reduces Garbage Collection (GC) pressure during frequent insertions and deletions (e.g., in high-throughput queues).
 - In benchmarks with 100,000 cyclic operations, **GC time was 0.0s** compared to significant pauses without pooling.
 
-### RBTree vs Hash vs Array
+### RBTree vs Hash vs Array (Overwhelming Power)
 
-RBTree provides significant advantages for ordered operations:
+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**:
 
-| Operation | RBTree | Hash | Speedup |
-|-----------|--------|------|---------|
-| `min` / `max` | O(1) / O(log n) | O(n) | **~1000x faster** |
-| Range queries (`between`, `lt`, `gt`) | O(log n + k) | O(n) | **10-100x faster** |
-| Nearest key search | O(log n) | O(n) | **100x+ faster** |
-| Ordered iteration | O(n), always sorted | Requires `sort` O(n log n) | **Free sorting** |
-| Key lookup | O(1) | O(1) | Equal |
+| Operation | RBTree | Hash/Array | Speedup | Why? |
+|-----------|--------|------------|---------|------|
+| **Nearest Key Search** | **O(log n)** | O(n) scan | **~8,600x faster** | Spatial binary search vs full scan |
+| **Range Queries** | **O(log n + k)** | O(n) filter | **~540x faster** | Direct subtree jump vs full scan |
+| **Min Extraction** | **O(log n)** | O(n) search | **~160x faster** | Continuous rebalancing vs full scan |
+| **Sorted Iteration** | **O(n)** | O(n log n) | **FREE** | Always sorted vs explicit `sort` |
+| **Key Lookup** | **O(1)** | O(1) | **Equal** | Optimized Hybrid Hash Index |
 
 ### When to Use RBTree
 

data/lib/rbtree/version.rb

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

data/lib/rbtree.rb

@@ -174,6 +174,11 @@ class RBTree
   #   tree.insert(1, 'uno', overwrite: false)  # => nil (no change)
   #   tree[2] = 'two'              # using alias
   def insert(key, value, overwrite: true)
+    if (node = @hash_index[key])
+      return nil unless overwrite
+      node.value = value
+      return true
+    end
     y = @nil_node
     x = @root
     while x != @nil_node
@@ -324,19 +329,28 @@ class RBTree
   # 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)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
   #   tree.lt(3)  # => [[1, "one"], [2, "two"]]
-  #   tree.lt(3) { |k, v| puts "#{k}: #{v}" }  # prints pairs and returns tree
-  def lt(key, &block)
+  #   tree.lt(3, reverse: true)  # => [[2, "two"], [1, "one"]]
+  def lt(key, reverse: false, &block)
     if block_given?
-      traverse_lt(@root, key, &block)
+      if reverse
+        traverse_lt_desc(@root, key, &block)
+      else
+        traverse_lt(@root, key, &block)
+      end
       self
     else
       res = []
-      traverse_lt(@root, key) { |k, v| res << [k, v] }
+      if reverse
+        traverse_lt_desc(@root, key) { |k, v| res << [k, v] }
+      else
+        traverse_lt(@root, key) { |k, v| res << [k, v] }
+      end
       res
     end
   end
@@ -344,18 +358,28 @@ class RBTree
   # Retrieves all key-value pairs with keys less than or equal to the specified key.
   #
   # @param key [Object] the upper bound (inclusive)
+  # @param reverse [Boolean] if true, iterate in descending order (default: false)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
   #   tree.lte(3)  # => [[1, "one"], [2, "two"], [3, "three"]]
-  def lte(key, &block)
+  #   tree.lte(3, reverse: true)  # => [[3, "three"], [2, "two"], [1, "one"]]
+  def lte(key, reverse: false, &block)
     if block_given?
-      traverse_lte(@root, key, &block)
+      if reverse
+        traverse_lte_desc(@root, key, &block)
+      else
+        traverse_lte(@root, key, &block)
+      end
       self
     else
       res = []
-      traverse_lte(@root, key) { |k, v| res << [k, v] }
+      if reverse
+        traverse_lte_desc(@root, key) { |k, v| res << [k, v] }
+      else
+        traverse_lte(@root, key) { |k, v| res << [k, v] }
+      end
       res
     end
   end
@@ -363,18 +387,28 @@ class RBTree
   # Retrieves all key-value pairs with keys greater than the specified key.
   #
   # @param key [Object] the lower bound (exclusive)
+  # @param reverse [Boolean] if true, iterate in descending order (default: false)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
   #   tree.gt(2)  # => [[3, "three"], [4, "four"]]
-  def gt(key, &block)
+  #   tree.gt(2, reverse: true)  # => [[4, "four"], [3, "three"]]
+  def gt(key, reverse: false, &block)
     if block_given?
-      traverse_gt(@root, key, &block)
+      if reverse
+        traverse_gt_desc(@root, key, &block)
+      else
+        traverse_gt(@root, key, &block)
+      end
       self
     else
       res = []
-      traverse_gt(@root, key) { |k, v| res << [k, v] }
+      if reverse
+        traverse_gt_desc(@root, key) { |k, v| res << [k, v] }
+      else
+        traverse_gt(@root, key) { |k, v| res << [k, v] }
+      end
       res
     end
   end
@@ -382,18 +416,28 @@ class RBTree
   # Retrieves all key-value pairs with keys greater than or equal to the specified key.
   #
   # @param key [Object] the lower bound (inclusive)
+  # @param reverse [Boolean] if true, iterate in descending order (default: false)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
   #   tree.gte(2)  # => [[2, "two"], [3, "three"], [4, "four"]]
-  def gte(key, &block)
+  #   tree.gte(2, reverse: true)  # => [[4, "four"], [3, "three"], [2, "two"]]
+  def gte(key, reverse: false, &block)
     if block_given?
-      traverse_gte(@root, key, &block)
+      if reverse
+        traverse_gte_desc(@root, key, &block)
+      else
+        traverse_gte(@root, key, &block)
+      end
       self
     else
       res = []
-      traverse_gte(@root, key) { |k, v| res << [k, v] }
+      if reverse
+        traverse_gte_desc(@root, key) { |k, v| res << [k, v] }
+      else
+        traverse_gte(@root, key) { |k, v| res << [k, v] }
+      end
       res
     end
   end
@@ -404,20 +448,29 @@ class RBTree
   # @param max [Object] the upper bound
   # @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)
   # @yield [key, value] each matching key-value pair (if block given)
   # @return [Array<Array(Object, Object)>, RBTree] array of [key, value] pairs if no block, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four', 5 => 'five'})
   #   tree.between(2, 4)  # => [[2, "two"], [3, "three"], [4, "four"]]
   #   tree.between(2, 4, include_min: false)  # => [[3, "three"], [4, "four"]]
-  #   tree.between(2, 4, include_max: false)  # => [[2, "two"], [3, "three"]]
-  def between(min, max, include_min: true, include_max: true, &block)
+  #   tree.between(2, 4, reverse: true)  # => [[4, "four"], [3, "three"], [2, "two"]]
+  def between(min, max, include_min: true, include_max: true, reverse: false, &block)
     if block_given?
-      traverse_between(@root, min, max, include_min, include_max, &block)
+      if reverse
+        traverse_between_desc(@root, min, max, include_min, include_max, &block)
+      else
+        traverse_between(@root, min, max, include_min, include_max, &block)
+      end
       self
     else
       res = []
-      traverse_between(@root, min, max, include_min, include_max) { |k, v| res << [k, v] }
+      if reverse
+        traverse_between_desc(@root, min, max, include_min, include_max) { |k, v| res << [k, v] }
+      else
+        traverse_between(@root, min, max, include_min, include_max) { |k, v| res << [k, v] }
+      end
       res
     end
   end
@@ -440,6 +493,40 @@ class RBTree
     n == @nil_node ? nil : [n.key, n.value]
   end
 
+  # Returns the key-value pair with the largest key that is smaller than the given key.
+  #
+  # If the key exists in the tree, returns the predecessor (previous element).
+  # If the key does not exist, returns the largest key-value pair with key < given key.
+  #
+  # @param key [Object] the reference key
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if no predecessor exists
+  # @example
+  #   tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
+  #   tree.prev(5)   # => [3, "three"]
+  #   tree.prev(4)   # => [3, "three"] (4 does not exist)
+  #   tree.prev(1)   # => nil (no predecessor)
+  def prev(key)
+    n = find_predecessor_node(key)
+    n == @nil_node ? nil : [n.key, n.value]
+  end
+
+  # Returns the key-value pair with the smallest key that is larger than the given key.
+  #
+  # If the key exists in the tree, returns the successor (next element).
+  # If the key does not exist, returns the smallest key-value pair with key > given key.
+  #
+  # @param key [Object] the reference key
+  # @return [Array(Object, Object), nil] a two-element array [key, value], or nil if no successor exists
+  # @example
+  #   tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
+  #   tree.succ(5)   # => [7, "seven"]
+  #   tree.succ(4)   # => [5, "five"] (4 does not exist)
+  #   tree.succ(7)   # => nil (no successor)
+  def succ(key)
+    n = find_successor_node(key)
+    n == @nil_node ? nil : [n.key, n.value]
+  end
+
   # Validates the red-black tree properties.
   #
   # Checks that:
@@ -588,6 +675,98 @@ class RBTree
     end
   end
 
+  # Traverses nodes with keys less than the specified key in descending order.
+  #
+  # @param node [Node] the current node
+  # @param key [Object] the upper bound (exclusive)
+  # @yield [key, value] each matching key-value pair in descending order
+  # @return [void]
+  def traverse_lt_desc(node, key, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> key) < 0
+      traverse_lt_desc(node.right, key, &block)
+      yield node.key, node.value
+    end
+    traverse_lt_desc(node.left, key, &block)
+  end
+
+  # Traverses nodes with keys less than or equal to the specified key in descending order.
+  #
+  # @param node [Node] the current node
+  # @param key [Object] the upper bound (inclusive)
+  # @yield [key, value] each matching key-value pair in descending order
+  # @return [void]
+  def traverse_lte_desc(node, key, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> key) <= 0
+      traverse_lte_desc(node.right, key, &block)
+      yield node.key, node.value
+    end
+    traverse_lte_desc(node.left, key, &block)
+  end
+
+  # Traverses nodes with keys greater than the specified key in descending order.
+  #
+  # @param node [Node] the current node
+  # @param key [Object] the lower bound (exclusive)
+  # @yield [key, value] each matching key-value pair in descending order
+  # @return [void]
+  def traverse_gt_desc(node, key, &block)
+    return if node == @nil_node
+    
+    traverse_gt_desc(node.right, key, &block)
+    if (node.key <=> key) > 0
+      yield node.key, node.value
+      traverse_gt_desc(node.left, key, &block)
+    end
+  end
+
+  # Traverses nodes with keys greater than or equal to the specified key in descending order.
+  #
+  # @param node [Node] the current node
+  # @param key [Object] the lower bound (inclusive)
+  # @yield [key, value] each matching key-value pair in descending order
+  # @return [void]
+  def traverse_gte_desc(node, key, &block)
+    return if node == @nil_node
+    
+    traverse_gte_desc(node.right, key, &block)
+    if (node.key <=> key) >= 0
+      yield node.key, node.value
+      traverse_gte_desc(node.left, key, &block)
+    end
+  end
+
+  # Traverses nodes with keys within the specified range in descending order.
+  #
+  # @param node [Node] the current node
+  # @param min [Object] the lower bound
+  # @param max [Object] the upper bound
+  # @param include_min [Boolean] whether to include the lower bound
+  # @param include_max [Boolean] whether to include the upper bound
+  # @yield [key, value] each matching key-value pair in descending order
+  # @return [void]
+  def traverse_between_desc(node, min, max, include_min, include_max, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> max) < 0
+      traverse_between_desc(node.right, min, max, include_min, include_max, &block)
+    end
+    
+    greater = include_min ? (node.key <=> min) >= 0 : (node.key <=> min) > 0
+    less = include_max ? (node.key <=> max) <= 0 : (node.key <=> max) < 0
+    
+    if greater && less
+      yield node.key, node.value
+    end
+    
+    if (node.key <=> min) > 0
+      traverse_between_desc(node.left, min, max, include_min, include_max, &block)
+    end
+  end
+
   # Restores red-black tree properties after insertion.
   #
   # This method fixes any violations of red-black properties that may occur
@@ -837,6 +1016,86 @@ class RBTree
     closest
   end
 
+  # Finds the node with the largest key that is smaller than the given key.
+  #
+  # If the key exists in the tree, returns its predecessor node.
+  # If the key does not exist, returns the largest node with key < given key.
+  #
+  # @param key [Object] the reference key
+  # @return [Node] the predecessor node, or @nil_node if none exists
+  def find_predecessor_node(key)
+    # Check if key exists using O(1) hash lookup
+    if (node = @hash_index[key])
+      # Key exists: find predecessor in subtree or ancestors
+      if node.left != @nil_node
+        return rightmost(node.left)
+      else
+        # Walk up to find first ancestor where we came from the right
+        current = node
+        parent = current.parent
+        while parent != @nil_node && current == parent.left
+          current = parent
+          parent = parent.parent
+        end
+        return parent
+      end
+    end
+
+    # Key doesn't exist: descend tree tracking the best candidate
+    current = @root
+    predecessor = @nil_node
+    while current != @nil_node
+      cmp = key <=> current.key
+      if cmp > 0
+        predecessor = current  # This node's key < given key
+        current = current.right
+      else
+        current = current.left
+      end
+    end
+    predecessor
+  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.
+  # If the key does not exist, returns the smallest node with key > given key.
+  #
+  # @param key [Object] the reference key
+  # @return [Node] the successor node, or @nil_node if none exists
+  def find_successor_node(key)
+    # Check if key exists using O(1) hash lookup
+    if (node = @hash_index[key])
+      # Key exists: find successor in subtree or ancestors
+      if node.right != @nil_node
+        return leftmost(node.right)
+      else
+        # Walk up to find first ancestor where we came from the left
+        current = node
+        parent = current.parent
+        while parent != @nil_node && current == parent.right
+          current = parent
+          parent = parent.parent
+        end
+        return parent
+      end
+    end
+
+    # Key doesn't exist: descend tree tracking the best candidate
+    current = @root
+    successor = @nil_node
+    while current != @nil_node
+      cmp = key <=> current.key
+      if cmp < 0
+        successor = current  # This node's key > given key
+        current = current.left
+      else
+        current = current.right
+      end
+    end
+    successor
+  end
+
   # Finds the leftmost (minimum) node in a subtree.
   #
   # @param node [Node] the root of the subtree
@@ -989,7 +1248,39 @@ end
 # * Multiple values per key using arrays
 # * Separate methods for single deletion (`delete_one`) vs. all deletions (`delete`)
 # * Values for each key maintain insertion order
-# * min/max return first/last values respectively
+# * Configurable access to first or last value via `:last` option
+#
+# == Value Array Access
+#
+# For each key, values are stored in insertion order. Methods that access
+# a single value support a `:last` option to choose which end of the array:
+#
+# * +get(key)+, +get_first(key)+ - returns first value (oldest)
+# * +get(key, last: true)+, +get_last(key)+ - returns last value (newest)
+# * +delete_one(key)+, +delete_first(key)+ - removes first value
+# * +delete_one(key, last: true)+, +delete_last(key)+ - removes last value
+# * +prev(key)+, +succ(key)+ - returns first value of adjacent key
+# * +prev(key, last: true)+, +succ(key, last: true)+ - returns last value
+#
+# == Boundary Operations
+#
+# * +min+, +max+ - return [key, first_value] by default
+# * +min(last: true)+, +max(last: true)+ - return [key, last_value]
+# * +shift+ - removes and returns [smallest_key, first_value]
+# * +pop+ - removes and returns [largest_key, last_value]
+#
+# == Iteration Order
+#
+# When iterating over values, the order depends on the direction:
+#
+# * Forward iteration (+each+, +lt+, +gt+, etc.): Each key's values are
+#   yielded in insertion order (first to last).
+#
+# * Reverse iteration (+reverse_each+, +lt(key, reverse: true)+, etc.):
+#   Each key's values are yielded in reverse insertion order (last to first).
+#
+# This ensures consistent behavior where reverse iteration is truly the
+# mirror image of forward iteration.
 #
 # == Usage
 #
@@ -998,32 +1289,55 @@ end
 #   tree.insert(1, 'second one')
 #   tree.insert(2, 'two')
 #
-#   tree.size           # => 3 (total key-value pairs)
-#   tree.get(1)         # => "first one" (first value)
-#   tree.get_all(1)     # => ["first one", "second one"] (all values)
+#   tree.size             # => 3 (total key-value pairs)
+#   tree.get(1)           # => "first one" (first value)
+#   tree.get(1, last: true)  # => "second one" (last value)
+#   tree.get_all(1)       # => ["first one", "second one"] (all values)
 #
-#   tree.delete_one(1)  # removes only "first one"
-#   tree.get(1)         # => "second one"
+#   tree.delete_one(1)    # removes only "first one"
+#   tree.get(1)           # => "second one"
 #
-#   tree.delete(1)      # removes all remaining values for key 1
+#   tree.delete(1)        # removes all remaining values for key 1
 #
 # @author Masahito Suzuki
 # @since 0.1.2
 class MultiRBTree < RBTree
-  # Retrieves the first value associated with the given key.
+  # Retrieves a value associated with the given key.
   #
   # @param key [Object] the key to look up
-  # @return [Object, nil] the first value for the key, or nil if not found
+  # @param last [Boolean] if true, return the last value; otherwise return the first (default: false)
+  # @return [Object, nil] the value for the key, or nil if not found
   # @example
   #   tree = MultiRBTree.new
   #   tree.insert(1, 'first')
   #   tree.insert(1, 'second')
-  #   tree.get(1)  # => "first"
-  def get(key)
+  #   tree.get(1)              # => "first"
+  #   tree.get(1, last: true)  # => "second"
+  def get(key, last: false)
     n = find_node(key)
-    n == @nil_node || n.value.empty? ? nil : n.value.first
+    return nil if n == @nil_node || n.value.empty?
+    last ? n.value.last : n.value.first
   end
-  alias_method :[], :get
+
+  # Retrieves the first value associated with the given key.
+  #
+  # @param key [Object] the key to look up
+  # @return [Object, nil] the first value for the key, or nil if not found
+  def get_first(key) = get(key, last: false)
+
+  # Retrieves the last value associated with the given key.
+  #
+  # @param key [Object] the key to look up
+  # @return [Object, nil] the last value for the key, or nil if not found
+  def get_last(key) = get(key, last: true)
+
+  # Returns the first value for the given key (for Hash-like access).
+  #
+  # Note: Unlike get(), this method does not accept options.
+  #
+  # @param key [Object] the key to look up
+  # @return [Object, nil] the first value for the key, or nil if not found
+  def [](key) = get(key)
 
   # Retrieves all values associated with the given key.
   #
@@ -1052,6 +1366,11 @@ class MultiRBTree < RBTree
   #   tree.insert(1, 'first')
   #   tree.insert(1, 'second')  # adds another value for key 1
   def insert(key, value)
+    if (node = @hash_index[key])
+      node.value << value
+      @size += 1
+      return true
+    end
     y = @nil_node
     x = @root
     while x != @nil_node
@@ -1090,24 +1409,25 @@ class MultiRBTree < RBTree
     true
   end
 
-  # Deletes only the first value for the specified key.
+  # Deletes a single value for the specified key.
   #
-  # If the key has multiple values, removes only the first one.
+  # If the key has multiple values, removes only one value.
   # If this was the last value for the key, the node is removed from the tree.
   #
   # @param key [Object] the key to delete from
+  # @param last [Boolean] if true, remove the last value; otherwise remove the first (default: false)
   # @return [Object, nil] the deleted value, or nil if key not found
   # @example
   #   tree = MultiRBTree.new
   #   tree.insert(1, 'first')
   #   tree.insert(1, 'second')
-  #   tree.delete_one(1)  # => "first"
-  #   tree.get(1)         # => "second"
-  def delete_one(key)
+  #   tree.delete_one(1)              # => "first"
+  #   tree.delete_one(1, last: true)  # => "second" (if more values existed)
+  def delete_one(key, last: false)
     z = @hash_index[key]  # O(1) lookup
     return nil unless z
 
-    value = z.value.shift
+    value = last ? z.value.pop : z.value.shift
     @size -= 1
     if z.value.empty?
       @hash_index.delete(key)  # Remove from index when node removed
@@ -1116,6 +1436,18 @@ class MultiRBTree < RBTree
     value
   end
 
+  # Deletes the first value for the specified key.
+  #
+  # @param key [Object] the key to delete from
+  # @return [Object, nil] the deleted value, or nil if key not found
+  def delete_first(key) = delete_one(key, last: false)
+
+  # Deletes the last value for the specified key.
+  #
+  # @param key [Object] the key to delete from
+  # @return [Object, nil] the deleted value, or nil if key not found
+  def delete_last(key) = delete_one(key, last: true)
+
   # Deletes all values for the specified key.
   #
   # Removes the node and all associated values.
@@ -1163,18 +1495,32 @@ class MultiRBTree < RBTree
     [n.key, val]
   end
 
-  def min
+  def min(last: false)
     return nil if @min_node == @nil_node || @min_node.value.empty?
-    [@min_node.key, @min_node.value.first]
+    [@min_node.key, last ? @min_node.value.last : @min_node.value.first]
   end
 
-  def max
+  def max(last: false)
     n = rightmost(@root)
-    n == @nil_node || n.value.empty? ? nil : [n.key, n.value.first]
+    return nil if n == @nil_node || n.value.empty?
+    [n.key, last ? n.value.last : n.value.first]
   end
 
   def nearest(key)
-    (n = super(key)) ? [n[0], n[1].first] : nil
+    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]
   end
 
   private
@@ -1264,6 +1610,65 @@ class MultiRBTree < RBTree
       traverse_between(node.right, min, max, include_min, include_max, &block)
     end
   end
+
+  def traverse_lt_desc(node, key, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> key) < 0
+      traverse_lt_desc(node.right, key, &block)
+      node.value.reverse_each { |v| yield node.key, v }
+    end
+    traverse_lt_desc(node.left, key, &block)
+  end
+
+  def traverse_lte_desc(node, key, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> key) <= 0
+      traverse_lte_desc(node.right, key, &block)
+      node.value.reverse_each { |v| yield node.key, v }
+    end
+    traverse_lte_desc(node.left, key, &block)
+  end
+
+  def traverse_gt_desc(node, key, &block)
+    return if node == @nil_node
+    
+    traverse_gt_desc(node.right, key, &block)
+    if (node.key <=> key) > 0
+      node.value.reverse_each { |v| yield node.key, v }
+      traverse_gt_desc(node.left, key, &block)
+    end
+  end
+
+  def traverse_gte_desc(node, key, &block)
+    return if node == @nil_node
+    
+    traverse_gte_desc(node.right, key, &block)
+    if (node.key <=> key) >= 0
+      node.value.reverse_each { |v| yield node.key, v }
+      traverse_gte_desc(node.left, key, &block)
+    end
+  end
+
+  def traverse_between_desc(node, min, max, include_min, include_max, &block)
+    return if node == @nil_node
+    
+    if (node.key <=> max) < 0
+      traverse_between_desc(node.right, min, max, include_min, include_max, &block)
+    end
+    
+    greater = include_min ? (node.key <=> min) >= 0 : (node.key <=> min) > 0
+    less = include_max ? (node.key <=> max) <= 0 : (node.key <=> max) < 0
+    
+    if greater && less
+      node.value.reverse_each { |v| yield node.key, v }
+    end
+    
+    if (node.key <=> min) > 0
+      traverse_between_desc(node.left, min, max, include_min, include_max, &block)
+    end
+  end
 end
 
 # Internal node structure for RBTree.
@@ -1288,16 +1693,16 @@ end
 class RBTree::Node
   attr_accessor :key, :value, :color, :left, :right, :parent
 
-  # Red color constant
-  RED = :red
-  # Black color constant
-  BLACK = :black
+  # Red color constant (true)
+  RED = true
+  # Black color constant (false)
+  BLACK = false
 
   # Creates a new Node.
   #
   # @param key [Object] the key
   # @param value [Object] the value
-  # @param color [Symbol] the color (:red or :black)
+  # @param color [Boolean] the color (true=red, false=black)
   # @param left [Node] the left child
   # @param right [Node] the right child
   # @param parent [Node] the parent node

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbtree-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Masahito Suzuki
@@ -47,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A pure Ruby implementation of Red-Black Tree with multi-value support
 test_files: []