philiprehberger-queue_stack 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f720c2ee97526d57826cb37fba4be96e6e1143879b7627a2792cef97ffaa1dc
-  data.tar.gz: 311fdae1a3eb9f31d27f4ef77006eae1f224050418ac97721540d761ac081ac0
+  metadata.gz: dba395bc3ee76baae4cdbbbb100fc91103049635c386e02fe5ac3ae118e9997a
+  data.tar.gz: 921a8e4241383d570d951e154b19e7abcce5cdb682d93b42888d36c9804871a2
 SHA512:
-  metadata.gz: fd4c5bc553fde4d2278b2efa422ed0c4c67aaf63d9c5bc049bce395066ab544533bf2b11696a564769cbd6dbdd900a4c802a12abec032d888d17c0d0d5d0dc36
-  data.tar.gz: aa1cc6ea3d889cde7c372943df2bb9b5c46d0f87f3e628659e01ebbbf3697a8ce548f41c36508a3f82af14818ca0bd852da74aa577e13abf29899f1b60e6a162
+  metadata.gz: 30320f35b2ae5d2e01221091e203c31cc799ec5d6a1ff279a0201a04dd9c038f254ad8319d1e4f8cf3a50e1e292e2522a813e8330383f2f49ce99b86d5704b1c
+  data.tar.gz: 2ddd79499fa0b97b99fcb45c5c941984c1f8b3ddeee25cc4edeed317b9317509d9ade981940ca685266770db6dc3d472b11e3fdb8610b45731abd44f7f3a284e

data/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

data/README.md

@@ -70,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
@@ -150,6 +169,7 @@ 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 |
@@ -171,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

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.4.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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 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