philiprehberger-queue_stack 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61b9b755594ffadcc05a80b942c0424a29043da9e01c81bc41045c5d440156e1
-  data.tar.gz: 823d4982ec931ecf197a42e37ceb7439939a4e6e06070d22ceb437eb1985f2e4
+  metadata.gz: dba395bc3ee76baae4cdbbbb100fc91103049635c386e02fe5ac3ae118e9997a
+  data.tar.gz: 921a8e4241383d570d951e154b19e7abcce5cdb682d93b42888d36c9804871a2
 SHA512:
-  metadata.gz: 0c2f235cd8a6f31bafd5d94af63806e3caabc0fff8743b82815ff90df255f74dbf6d924edccb57e5d73f0fef65958b1c7231e60e96bc9dde9aee3e94718ce0fd
-  data.tar.gz: 35d25847836f39bbd80fd7aa8ff07005c126cec030be1d1e9908a4d428d8f96cf2b662167cce8428314aefd7a1ce2384179dd8489e132f1635333e2ffd1dec48
+  metadata.gz: 30320f35b2ae5d2e01221091e203c31cc799ec5d6a1ff279a0201a04dd9c038f254ad8319d1e4f8cf3a50e1e292e2522a813e8330383f2f49ce99b86d5704b1c
+  data.tar.gz: 2ddd79499fa0b97b99fcb45c5c941984c1f8b3ddeee25cc4edeed317b9317509d9ade981940ca685266770db6dc3d472b11e3fdb8610b45731abd44f7f3a284e

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-16
+
+### Added
+- `Queue#dequeue_if { |item| ... }` conditionally removes and returns the front item only when the block returns truthy; returns `nil` when empty or the block returns false (non-blocking)
+- `Stack#pop_if { |item| ... }` conditionally removes and returns the top item only when the block returns truthy; returns `nil` when empty or the block returns false (non-blocking)
+
+## [0.4.0] - 2026-04-15
+
+### Added
+- `Queue#peek_at(index)` returns the item at the given position without removing it, supporting negative indices like `Array#[]` and returning `nil` when out of range
+
 ## [0.3.0] - 2026-04-09
 
 ### Added

data/README.md

@@ -40,9 +40,13 @@ item = q.dequeue  # => 'task'
 q = Philiprehberger::QueueStack::Queue.new(capacity: 10)
 q.enqueue('first')
 q.enqueue('second')
-q.dequeue   # => 'first'
-q.peek      # => 'second'
-q.size      # => 1
+q.enqueue('third')
+q.peek         # => 'first'
+q.peek_at(1)   # => 'second'
+q.peek_at(-1)  # => 'third'
+q.peek_at(99)  # => nil (out of range)
+q.dequeue      # => 'first'
+q.size         # => 2
 ```
 
 ### Stack (LIFO)
@@ -66,6 +70,25 @@ s = Philiprehberger::QueueStack::Stack.new
 item = s.try_pop(timeout: 5)  # waits up to 5 seconds
 ```
 
+### Conditional Removal
+
+Remove the front/top item only when a predicate holds. Non-blocking; returns `nil` if the collection is empty or the block returns false (the item stays put).
+
+```ruby
+q = Philiprehberger::QueueStack::Queue.new
+q.enqueue({ priority: 10 })
+q.enqueue({ priority: 2 })
+
+# Only take high-priority work
+q.dequeue_if { |job| job[:priority] >= 5 }  # => { priority: 10 }
+q.dequeue_if { |job| job[:priority] >= 5 }  # => nil (head priority 2 left intact)
+
+s = Philiprehberger::QueueStack::Stack.new
+s.push(:ready)
+s.pop_if { |item| item == :ready }   # => :ready
+s.pop_if { |item| item == :ready }   # => nil (empty)
+```
+
 ### Drain
 
 ```ruby
@@ -146,9 +169,11 @@ q.full?   # => true
 | `#enqueue(item)` | Add item to back (blocks if full) |
 | `#try_enqueue(item, timeout: nil)` | Non-blocking enqueue, returns true/false (waits up to timeout if given) |
 | `#dequeue` | Remove and return front item (blocks if empty) |
+| `#dequeue_if { \|item\| ... }` | Remove and return the front item only if the block is truthy (non-blocking) |
 | `#try_dequeue(timeout:)` | Dequeue with timeout, returns nil on timeout |
 | `#clear` | Remove all items without returning them |
 | `#peek` | View front item without removing |
+| `#peek_at(index)` | View item at the given position (supports negative indices, returns nil if out of range) |
 | `#drain` | Remove and return all items as array (FIFO order) |
 | `#each` | Iterate items without removing (returns Enumerator if no block) |
 | `#to_a` | Snapshot as array (FIFO order) |
@@ -166,6 +191,7 @@ q.full?   # => true
 | `#push(item)` | Push item on top (blocks if full) |
 | `#try_push(item, timeout: nil)` | Non-blocking push, returns true/false (waits up to timeout if given) |
 | `#pop` | Remove and return top item (blocks if empty) |
+| `#pop_if { \|item\| ... }` | Remove and return the top item only if the block is truthy (non-blocking) |
 | `#try_pop(timeout:)` | Pop with timeout, returns nil on timeout |
 | `#clear` | Remove all items without returning them |
 | `#peek` | View top item without removing |

data/lib/philiprehberger/queue_stack/queue.rb

@@ -96,6 +96,24 @@ module Philiprehberger
         end
       end
 
+      # Conditionally dequeue the front item. The block is called with the item
+      # that would be dequeued next. If the block returns truthy, the item is
+      # removed and returned. Otherwise the item is left in place and +nil+ is
+      # returned. Returns +nil+ immediately if the queue is empty (non-blocking).
+      #
+      # @yield [item] the front item
+      # @return [Object, nil] the removed item, or nil if empty or block returned false
+      def dequeue_if
+        @mutex.synchronize do
+          return nil if @items.empty?
+          return nil unless yield(@items.first)
+
+          item = @items.shift
+          @not_full.signal
+          item
+        end
+      end
+
       # Try to dequeue an item with a timeout.
       #
       # @param timeout [Numeric] seconds to wait
@@ -175,6 +193,18 @@ module Philiprehberger
         @mutex.synchronize { @items.first }
       end
 
+      # Peek at the item at the given position without removing it.
+      #
+      # Indexing follows +Array#[]+ semantics: +0+ is the front of the queue,
+      # +size - 1+ is the back, and negative indices count from the back
+      # (+-1+ is the last item). Returns +nil+ when the index is out of range.
+      #
+      # @param index [Integer] position in the queue (supports negative indices)
+      # @return [Object, nil] the item at the position or nil if out of range
+      def peek_at(index)
+        @mutex.synchronize { @items[index] }
+      end
+
       # Return the number of items in the queue.
       #
       # @return [Integer]

data/lib/philiprehberger/queue_stack/stack.rb

@@ -96,6 +96,24 @@ module Philiprehberger
         end
       end
 
+      # Conditionally pop the top item. The block is called with the item that
+      # would be popped next. If the block returns truthy, the item is removed
+      # and returned. Otherwise the item is left in place and +nil+ is returned.
+      # Returns +nil+ immediately if the stack is empty (non-blocking).
+      #
+      # @yield [item] the top item
+      # @return [Object, nil] the removed item, or nil if empty or block returned false
+      def pop_if
+        @mutex.synchronize do
+          return nil if @items.empty?
+          return nil unless yield(@items.last)
+
+          item = @items.pop
+          @not_full.signal
+          item
+        end
+      end
+
       # Try to pop an item with a timeout.
       #
       # @param timeout [Numeric] seconds to wait

data/lib/philiprehberger/queue_stack/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module QueueStack
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-queue_stack
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies: []
 description: Thread-safe queue and stack data structures with configurable capacity
   limits, blocking enqueue/dequeue with timeouts, and peek operations. Uses Mutex