philiprehberger-priority_queue 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6c6189abf62a5cd7a03eec4626b908cfb8fbfd954e8183dbb5ebe43f421105f
-  data.tar.gz: 8af43691f143f9c673f56fed46d90486d9e0616ca938939bd99e5e62262b0bb9
+  metadata.gz: a631e281cd30a3bd485b87972243ee8f53420dd1fb86e16a2cf8b5d32493dbb5
+  data.tar.gz: 91ae0621673e00deef9dc027e2645468d0070d1d8bb38d453197a7c3326790e8
 SHA512:
-  metadata.gz: fbb8db631237032ac270c43fe2c5a1f9e9c33a906a4e2c60def195451ade5d930196ffdaf44cd3342d21228a870c98d493ff31764fe0f7587e488b74a82003e7
-  data.tar.gz: 12603ff8ef9d42bbac4fb3f364dab1b6edda0904962752e5ada257a022ec060f801d27175a7954c0849a2bd7499d78d9899d2a578bd6b1019ad26a32761a95cc
+  metadata.gz: 32f67845be0fa02863266bf26fde40d6a425cff68e8b7b0271a69c21ad05842c68e6db0a587ed0ef7a65455070021d7308459bac122a6870159910129ca97c76
+  data.tar.gz: da04d30b1cdc936aa4b1a6f15c99feb1110b5dae3a456d8d9fa30ae8fa41a4d0a93bdd420ea83fdf03572bb1004c1483dcc54a5928c5cc611ff998aeec76feb7

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.1.8] - 2026-03-24
+
+### Changed
+- Add Usage subsections and expand API table in README
+
 ## [0.1.7] - 2026-03-24
 
 ### Fixed

data/README.md

@@ -31,45 +31,78 @@ require "philiprehberger/priority_queue"
 
 # Min-heap (default) - lowest priority first
 queue = Philiprehberger::PriorityQueue::Queue.new
-queue.push('low', priority: 1)
-queue.push('high', priority: 10)
-queue.push('mid', priority: 5)
+queue.push("low", priority: 1)
+queue.push("high", priority: 10)
+queue.push("mid", priority: 5)
 
 queue.pop   # => "low"
 queue.pop   # => "mid"
 queue.pop   # => "high"
 
-# Max-heap - highest priority first
+# Peek without removing
+queue.push("item", priority: 1)
+queue.peek   # => "item"
+queue.size   # => 1
+queue.empty? # => false
+
+# Shovel operator for hash-based push
+queue << { item: "task", priority: 3 }
+```
+
+### Max-Heap Mode
+
+Pass `mode: :max` to pop the highest priority first.
+
+```ruby
 queue = Philiprehberger::PriorityQueue::Queue.new(mode: :max)
-queue.push('task_a', priority: 3)
-queue.push('task_b', priority: 7)
-queue.pop   # => "task_b"
+queue.push("task_a", priority: 3)
+queue.push("task_b", priority: 7)
+queue.push("task_c", priority: 1)
+
+queue.pop # => "task_b"
+queue.pop # => "task_a"
+queue.pop # => "task_c"
+```
 
-# Custom comparator
+### Custom Comparator
+
+Supply a block to define your own ordering. The block receives two priorities and must return `-1`, `0`, or `1`.
+
+```ruby
 queue = Philiprehberger::PriorityQueue::Queue.new { |a, b| a.length <=> b.length }
-queue.push('short', priority: 'short')
-queue.push('very long', priority: 'very long')
-queue.pop   # => "short"
+queue.push("short", priority: "short")
+queue.push("very long", priority: "very long")
+queue.pop # => "short"
+```
 
-# Peek without removing
-queue = Philiprehberger::PriorityQueue::Queue.new
-queue.push('item', priority: 1)
-queue.peek  # => "item"
-queue.size  # => 1
+### Priority Updates
 
-# Change priority
+Change the priority of an item already in the queue. The heap re-balances automatically.
+
+```ruby
 queue = Philiprehberger::PriorityQueue::Queue.new
-queue.push('task', priority: 10)
-queue.change_priority('task', 1)  # now highest priority in min-heap
+queue.push("task_a", priority: 10)
+queue.push("task_b", priority: 5)
+
+queue.change_priority("task_a", 1) # task_a is now highest priority
+queue.pop # => "task_a"
+```
+
+### Merging Queues
+
+Combine two queues into a new queue. The originals are unchanged.
+
+```ruby
+q1 = Philiprehberger::PriorityQueue::Queue.new
+q1.push("a", priority: 1)
+q1.push("b", priority: 3)
 
-# Merge queues
-merged = queue1.merge(queue2)
+q2 = Philiprehberger::PriorityQueue::Queue.new
+q2.push("c", priority: 2)
 
-# Other operations
-queue.include?('task')  # => true
-queue.to_a              # => items sorted by priority
-queue.empty?            # => false
-queue.clear             # removes all items
+merged = q1.merge(q2)
+merged.to_a # => ["a", "c", "b"]
+merged.size # => 3
 ```
 
 ## API
@@ -77,15 +110,16 @@ queue.clear             # removes all items
 | Method | Description |
 |--------|-------------|
 | `Queue.new(mode: :min, &comparator)` | Create a priority queue; mode can be `:min` or `:max`; optional custom comparator block |
-| `#push(item, priority:)` | Add an item with the given priority |
-| `#pop` | Remove and return the highest-priority item |
-| `#peek` | Return the highest-priority item without removing it |
+| `#push(item, priority:)` | Add an item with the given priority; returns `self` for chaining |
+| `#<<(item:, priority:)` | Shovel operator; push via a hash with `:item` and `:priority` keys |
+| `#pop` | Remove and return the highest-priority item; returns `nil` when empty |
+| `#peek` | Return the highest-priority item without removing it; returns `nil` when empty |
 | `#size` | Return the number of items in the queue |
 | `#empty?` | Return `true` if the queue has no items |
-| `#change_priority(item, new_priority)` | Update the priority of an existing item and re-heapify |
-| `#to_a` | Return all items sorted by priority |
+| `#change_priority(item, new_priority)` | Update the priority of an existing item and re-heapify; raises `ArgumentError` if item not found |
+| `#to_a` | Return all items sorted by priority with FIFO tie-breaking |
 | `#include?(item)` | Return `true` if the item is in the queue |
-| `#clear` | Remove all items from the queue |
+| `#clear` | Remove all items from the queue; returns `self` |
 | `#merge(other)` | Return a new queue containing items from both queues |
 
 ## Development

data/lib/philiprehberger/priority_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module PriorityQueue
-    VERSION = '0.1.7'
+    VERSION = '0.1.8'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-priority_queue
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - philiprehberger