philiprehberger-priority_queue 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 550864e1c3c7c28c4d978059acd56e73d64fd084e9263f46afd5fbf52a86671e
-  data.tar.gz: 766b98241695a100ba12122f06c6a7d4cada3c28685643f08fae483b667da0ce
+  metadata.gz: 4fca90d36f6f8f63c1b89c458854eb61af26682c7dcf66aaa1da9023f8cba5ab
+  data.tar.gz: a91b25347569be4e586c4c0ec1ce8c6d77b77d652df16ba39bce020c4560458c
 SHA512:
-  metadata.gz: a76b48855cd5782999ec79ae730efc4ebeaad9a02f78b4b1d981979d3cdf7b9543108d53bf710163d526b09273f655a9dc0bcf716c42c870c6678994d2a4b29d
-  data.tar.gz: d31237580572959f8cbf0943504b96205df6b97678a4385dcf5963bf069b52f8eac8cbd45d644be6779c7cca1d98ec039e6e507844888f4d83ad9e61e0d00c59
+  metadata.gz: b280a1927ced0e7ac6706af14e03a319111c962d8d67cfe7d93ceab3ce05761a187698ec0b8d8d175c3fdb12f52fecf35640de99410242dee37a583e5bdf1322
+  data.tar.gz: c52cb6190358eab1880f423df857c8165cadca1b98255c1c062a2c6bdfe54c027d0c29a492f9baf1481d78078f354c1190a7f48dbdf0d570ee5ae38d2fa7f57b

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-21
+
+### Added
+- `Queue#bulk_push` — insert multiple items from a hash
+- `Queue#priority_of` — lookup priority by item
+- `Queue#find` — priority-ordered search
+
+### Fixed
+- `bug_report.yml` — require Ruby version; add Gem version input per guide
+
+## [0.3.0] - 2026-04-15
+
+### Added
+- `Queue#pop_n(n)` to pop up to `n` items in priority order and return them as an array; returns `[]` for empty queues or `n == 0`; raises `ArgumentError` for negative `n`
+
 ## [0.2.1] - 2026-04-15
 
 ### Fixed

data/README.md

@@ -103,6 +103,18 @@ queue.push_many([
 queue.pop # => "alert"
 ```
 
+### Bulk Insertion
+
+Insert multiple items from a hash, look up the priority of an item, and search in priority order.
+
+```ruby
+queue = Philiprehberger::PriorityQueue::Queue.new
+queue.bulk_push("email" => 2, "backup" => 5, "alert" => 1)
+
+queue.priority_of("backup")            # => 5
+queue.find { |_item, priority| priority > 1 } # => ["email", 2]
+```
+
 ### Peek Priority
 
 Return just the top priority value without the item.
@@ -127,6 +139,21 @@ queue.drain # => ["a", "b", "c"]
 queue.empty? # => true
 ```
 
+### Pop N
+
+Pop up to `n` items in priority order. Returns fewer than `n` items when the queue is exhausted.
+
+```ruby
+queue = Philiprehberger::PriorityQueue::Queue.new
+queue.push("a", priority: 1)
+queue.push("b", priority: 2)
+queue.push("c", priority: 3)
+
+queue.pop_n(2) # => ["a", "b"]
+queue.pop_n(5) # => ["c"]
+queue.pop_n(0) # => []
+```
+
 ### Delete
 
 Remove a specific item by value.
@@ -202,9 +229,13 @@ merged.size # => 3
 | `#push_many(items)` | Batch push from array of hashes `[{ item: x, priority: n }, ...]`; returns `self` |
 | `#peek_priority` | Return just the top priority value; returns `nil` when empty |
 | `#drain` | Pop all items and return as array in priority order; empties the queue |
+| `#pop_n(n)` | Pop up to `n` items in priority order and return as array; returns `[]` for empty queue or `n == 0`; raises `ArgumentError` for negative `n` |
 | `#delete(item)` | Remove a specific item by value; returns the item or `nil` |
 | `#priorities` | Return sorted array of unique priority values in the queue |
 | `#each` | Yield `[item, priority]` pairs in priority order (Enumerable) |
+| `#bulk_push(items_hash)` | Insert multiple items from a hash `{ item => priority, ... }`; returns `self`; raises `ArgumentError` for non-Hash input |
+| `#priority_of(item)` | Return the priority of the first matching item (O(n) linear scan); returns `nil` if not present |
+| `#find(&block)` | Yield `[item, priority]` pairs in priority order and return the first pair for which the block is truthy; returns `nil` if none match, or an `Enumerator` when no block is given |
 
 ## Development
 

data/lib/philiprehberger/priority_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module PriorityQueue
-    VERSION = '0.2.1'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/priority_queue.rb

@@ -57,6 +57,18 @@ module Philiprehberger
         @heap[0][2]
       end
 
+      def pop_n(n)
+        raise ArgumentError, "n must be non-negative, got #{n}" if n.negative?
+
+        result = []
+        n.times do
+          break if empty?
+
+          result << pop
+        end
+        result
+      end
+
       def empty?
         @size.zero?
       end
@@ -141,6 +153,48 @@ module Philiprehberger
         @heap.map { |entry| entry[0] }.uniq.sort
       end
 
+      # Insert multiple items from a hash in one call.
+      #
+      # @param items_hash [Hash] a mapping of item to priority
+      # @return [self] the queue, for chaining
+      # @raise [ArgumentError] if +items_hash+ is not a Hash
+      def bulk_push(items_hash)
+        raise ArgumentError, "Expected a Hash, got #{items_hash.class}" unless items_hash.is_a?(Hash)
+
+        items_hash.each { |item, priority| push(item, priority: priority) }
+        self
+      end
+
+      # Look up the priority of the first matching item.
+      #
+      # Uses a linear scan (O(n)) over internal storage and returns
+      # the priority associated with the first entry whose item is
+      # +==+ to the argument.
+      #
+      # @param item [Object] the item to look up
+      # @return [Object, nil] the priority of the first match, or +nil+ when not present
+      def priority_of(item)
+        entry = @heap.find { |e| e[2] == item }
+        entry.nil? ? nil : entry[0]
+      end
+
+      # Find the first [item, priority] pair in priority order for which
+      # the block returns a truthy value.
+      #
+      # @yield [item, priority] pairs in priority order
+      # @yieldparam item [Object] the item
+      # @yieldparam priority [Object] the priority
+      # @return [Array, nil] the first matching +[item, priority]+ pair, or +nil+ when none match
+      # @return [Enumerator] if no block is given
+      def find(&block)
+        return enum_for(:find) unless block
+
+        each do |item, priority|
+          return [item, priority] if block.call(item, priority)
+        end
+        nil
+      end
+
       def merge(other)
         merged = self.class.new(&@comparator)
         @heap.each { |entry| merged.push(entry[2], priority: entry[0]) }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-priority_queue
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-04-21 00:00:00.000000000 Z
 dependencies: []
 description: A binary heap-based priority queue supporting min-heap, max-heap, and
   custom comparator modes. Features O(log n) push/pop, priority changes, merge operations,