rbtree-ruby 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf6eb0a695ef93f89f9af8ceea5928c549785ea0110992f061b00ecdc76e3d64
-  data.tar.gz: 458cbee1ded3e8e0686ec495392bffbaf881ac0bc798d68790240abb0a3011b7
+  metadata.gz: ad4ff4e15079d2034a111e0180f1abbf5f433283de5c125f45569f9b69f558fc
+  data.tar.gz: 7355e1ae3964e79aa8d110c52e38672641c8d67ac1cb4cfbbd974fe6298f07f7
 SHA512:
-  metadata.gz: 48ee9755aad89802b6cb1b6af19a7919151e14531f2c6e2f2dfbb07062c5e1060490e8d5244d0fd960f44d4eb8b00e84ee9f24e5b3be6319c808f212dde848c2
-  data.tar.gz: aeadf12c689069742c8cc05c569a84bbb6a87b3736f2f7e6351b68fb2aae5dbc24eca80e65a97455b50dae82b47c3ade7b8b70a171d86f879a179865eab9182d
+  metadata.gz: e62ddc40bfc16d4afaf9430b679b03cfb50e89d3a02d7ab43a190b168015d4c6605baf579cc55abc0d42db207465538f99e81618beca873a1b4c654d1ab0c72f
+  data.tar.gz: d11f0258d1ea5ea2686cc8bb581eb3b5c524554bf2182d68d54759e592d58d57e463bfa87b13dbabb67e68becfa8648108b267751791a1877e49bc7c6e2f6a06

data/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.8] - 2026-01-14
+
+### Changed
+- **Range Query Returns Enumerator**: `lt`, `lte`, `gt`, `gte`, `between` now return an `Enumerator` instead of an `Array` when no block is given
+  - Enables lazy evaluation: `tree.gt(100).lazy.take(5).to_a`
+  - Enables chaining: `tree.lt(50).map { |k, v| k }`
+  - Use `.to_a` to get an Array: `tree.lt(50).to_a`
+  - **Breaking**: Code using direct array access like `tree.lt(50)[0]` must change to `tree.lt(50).first`
+
+## [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
@@ -83,8 +116,6 @@ 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.8]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.8
+[0.1.7]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.7
 [0.1.6]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.6
-[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
-[0.1.2]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.2

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.6"
+  VERSION = "0.1.8"
 end

data/lib/rbtree.rb

@@ -329,78 +329,82 @@ 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
+  # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
-  #   tree.lt(3)  # => [[1, "one"], [2, "two"]]
-  #   tree.lt(3) { |k, v| puts "#{k}: #{v}" }  # prints pairs and returns tree
-  def lt(key, &block)
-    if block_given?
-      traverse_lt(@root, key, &block)
-      self
+  #   tree.lt(3).to_a  # => [[1, "one"], [2, "two"]]
+  #   tree.lt(3, reverse: true).first  # => [2, "two"]
+  #   tree.lt(3) { |k, v| puts k }  # prints keys, returns self
+  def lt(key, reverse: false, &block)
+    return enum_for(:lt, key, reverse: reverse) unless block_given?
+    if reverse
+      traverse_lt_desc(@root, key, &block)
     else
-      res = []
-      traverse_lt(@root, key) { |k, v| res << [k, v] }
-      res
+      traverse_lt(@root, key, &block)
     end
+    self
   end
 
   # 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
+  # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
-  #   tree.lte(3)  # => [[1, "one"], [2, "two"], [3, "three"]]
-  def lte(key, &block)
-    if block_given?
-      traverse_lte(@root, key, &block)
-      self
+  #   tree.lte(3).to_a  # => [[1, "one"], [2, "two"], [3, "three"]]
+  #   tree.lte(3, reverse: true).first  # => [3, "three"]
+  def lte(key, reverse: false, &block)
+    return enum_for(:lte, key, reverse: reverse) unless block_given?
+    if reverse
+      traverse_lte_desc(@root, key, &block)
     else
-      res = []
-      traverse_lte(@root, key) { |k, v| res << [k, v] }
-      res
+      traverse_lte(@root, key, &block)
     end
+    self
   end
 
   # 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
+  # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
-  #   tree.gt(2)  # => [[3, "three"], [4, "four"]]
-  def gt(key, &block)
-    if block_given?
-      traverse_gt(@root, key, &block)
-      self
+  #   tree.gt(2).to_a  # => [[3, "three"], [4, "four"]]
+  #   tree.gt(2, reverse: true).first  # => [4, "four"]
+  def gt(key, reverse: false, &block)
+    return enum_for(:gt, key, reverse: reverse) unless block_given?
+    if reverse
+      traverse_gt_desc(@root, key, &block)
     else
-      res = []
-      traverse_gt(@root, key) { |k, v| res << [k, v] }
-      res
+      traverse_gt(@root, key, &block)
     end
+    self
   end
 
   # 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
+  # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'})
-  #   tree.gte(2)  # => [[2, "two"], [3, "three"], [4, "four"]]
-  def gte(key, &block)
-    if block_given?
-      traverse_gte(@root, key, &block)
-      self
+  #   tree.gte(2).to_a  # => [[2, "two"], [3, "three"], [4, "four"]]
+  #   tree.gte(2, reverse: true).first  # => [4, "four"]
+  def gte(key, reverse: false, &block)
+    return enum_for(:gte, key, reverse: reverse) unless block_given?
+    if reverse
+      traverse_gte_desc(@root, key, &block)
     else
-      res = []
-      traverse_gte(@root, key) { |k, v| res << [k, v] }
-      res
+      traverse_gte(@root, key, &block)
     end
+    self
   end
 
   # Retrieves all key-value pairs with keys within the specified range.
@@ -409,22 +413,21 @@ 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
+  # @return [Enumerator, RBTree] Enumerator if no block given, self otherwise
   # @example
   #   tree = RBTree.new({1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four', 5 => 'five'})
-  #   tree.between(2, 4)  # => [[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)
-    if block_given?
-      traverse_between(@root, min, max, include_min, include_max, &block)
-      self
+  #   tree.between(2, 4).to_a  # => [[2, "two"], [3, "three"], [4, "four"]]
+  #   tree.between(2, 4, reverse: true).first  # => [4, "four"]
+  def between(min, max, include_min: true, include_max: true, reverse: false, &block)
+    return enum_for(:between, min, max, include_min: include_min, include_max: include_max, reverse: reverse) unless block_given?
+    if reverse
+      traverse_between_desc(@root, min, max, include_min, include_max, &block)
     else
-      res = []
-      traverse_between(@root, min, max, include_min, include_max) { |k, v| res << [k, v] }
-      res
+      traverse_between(@root, min, max, include_min, include_max, &block)
     end
+    self
   end
 
   # Returns the key-value pair with the key closest to the given key.
@@ -445,6 +448,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:
@@ -593,6 +630,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
@@ -842,6 +971,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
@@ -994,7 +1203,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
 #
@@ -1003,32 +1244,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.
   #
@@ -1059,6 +1323,7 @@ class MultiRBTree < RBTree
   def insert(key, value)
     if (node = @hash_index[key])
       node.value << value
+      @size += 1
       return true
     end
     y = @nil_node
@@ -1099,24 +1364,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
@@ -1125,6 +1391,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.
@@ -1172,18 +1450,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
@@ -1273,6 +1565,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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbtree-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 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: []