philiprehberger-priority_queue 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81ecb740f0ef3871c9662a0bf53f627784e039ad638c3e772fae8cbf9664ec52
-  data.tar.gz: 8233105bc0db893faa7a53696c2283165d4bc6b5f10f86c02771a1101ddb1a76
+  metadata.gz: 5f4b5e7596b5e647e5e21d266d6532e93e045e36eb4373fb4588150220798f7b
+  data.tar.gz: 18dfd8320614129f2fef3980afdaa69e65052f081471252b35d6b1b70ee70f3a
 SHA512:
-  metadata.gz: 47adacec5e5bd08c5cd6dd2a45500f5e5901372df0171b1aaceb6aefe0e162fc4504e67b345a067ee818685333ca158eb3440a7fe9173c4716e2ed18f1586537
-  data.tar.gz: 53380b7734ed65fcbf26b80644caef0268b2c187182a8168792aba4fa855433a4dcca840060a9f673972cb4250fc3e1cc996e75474bfcb8a07ac35168d03da59
+  metadata.gz: 8f1818babf9c4a3b4f052c8a5fe7b7168f93dd8072933049209e6ecf87485e0769c7fe5dbea5fb166fb45543653a8acf77a53ef3699dd063e5cbf185c4a32629
+  data.tar.gz: 30d6bda5afc831cb70e0f8d5beb4ae4b5b37cb4e7512e4b236ad396b00811aec6c8233040e512910855338d0a088a7a538a64650c6f460faeb8f1d293a2ab9dd

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-26
+
+### Added
+- `Queue#peek_n(n)` — return the top `n` items in priority order without removing them; symmetric to `#pop_n`
+
+## [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

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.
@@ -142,6 +154,21 @@ queue.pop_n(5) # => ["c"]
 queue.pop_n(0) # => []
 ```
 
+### Peek N
+
+Return the top `n` items in priority order without removing them. The queue is unchanged.
+
+```ruby
+queue = Philiprehberger::PriorityQueue::Queue.new
+queue.push("a", priority: 1)
+queue.push("b", priority: 2)
+queue.push("c", priority: 3)
+
+queue.peek_n(2) # => ["a", "b"]
+queue.peek_n(5) # => ["a", "b", "c"]
+queue.size      # => 3
+```
+
 ### Delete
 
 Remove a specific item by value.
@@ -218,9 +245,13 @@ merged.size # => 3
 | `#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` |
+| `#peek_n(n)` | Return up to `n` items in priority order without removing them; 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.3.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/priority_queue.rb

@@ -69,6 +69,21 @@ module Philiprehberger
         result
       end
 
+      # Return the top +n+ items in priority order without removing them.
+      #
+      # When the queue is empty or +n+ is zero, returns +[]+. When +n+ is
+      # greater than or equal to the size, returns all items in priority order.
+      # The queue is not modified.
+      #
+      # @param n [Integer] the maximum number of items to return; must be non-negative
+      # @return [Array] the top +n+ items in priority order, or fewer when the queue is smaller
+      # @raise [ArgumentError] if +n+ is negative
+      def peek_n(n)
+        raise ArgumentError, "n must be non-negative, got #{n}" if n.negative?
+
+        to_a.first(n)
+      end
+
       def empty?
         @size.zero?
       end
@@ -153,6 +168,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.3.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-27 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,