philiprehberger-priority_queue 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fca90d36f6f8f63c1b89c458854eb61af26682c7dcf66aaa1da9023f8cba5ab
-  data.tar.gz: a91b25347569be4e586c4c0ec1ce8c6d77b77d652df16ba39bce020c4560458c
+  metadata.gz: 5f4b5e7596b5e647e5e21d266d6532e93e045e36eb4373fb4588150220798f7b
+  data.tar.gz: 18dfd8320614129f2fef3980afdaa69e65052f081471252b35d6b1b70ee70f3a
 SHA512:
-  metadata.gz: b280a1927ced0e7ac6706af14e03a319111c962d8d67cfe7d93ceab3ce05761a187698ec0b8d8d175c3fdb12f52fecf35640de99410242dee37a583e5bdf1322
-  data.tar.gz: c52cb6190358eab1880f423df857c8165cadca1b98255c1c062a2c6bdfe54c027d0c29a492f9baf1481d78078f354c1190a7f48dbdf0d570ee5ae38d2fa7f57b
+  metadata.gz: 8f1818babf9c4a3b4f052c8a5fe7b7168f93dd8072933049209e6ecf87485e0769c7fe5dbea5fb166fb45543653a8acf77a53ef3699dd063e5cbf185c4a32629
+  data.tar.gz: 30d6bda5afc831cb70e0f8d5beb4ae4b5b37cb4e7512e4b236ad396b00811aec6c8233040e512910855338d0a088a7a538a64650c6f460faeb8f1d293a2ab9dd

data/CHANGELOG.md

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

data/README.md

@@ -154,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.
@@ -230,6 +245,7 @@ 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) |

data/lib/philiprehberger/priority_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module PriorityQueue
-    VERSION = '0.4.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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-priority_queue
 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-21 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,