philiprehberger-priority_queue 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96eac91320e11af568cae20213fb6ea3bc6a16562ec2f8359539f69ce8d551f1
-  data.tar.gz: 9757f9de2dae44612d2fbc90abe916dbfa21b74657b8e19ca708ba43f5b90e39
+  metadata.gz: effc38578d3d02aa350f639420123b99a26e99de790207eb8babb13668540f92
+  data.tar.gz: a303a127bd33cae057fd6c20d5198e55d2dc104f5d22ae4c693ad3515b52b1b0
 SHA512:
-  metadata.gz: b8043b9740dacab51fe67334cc21d06614eb7c0351181fd0ff8558f4cc10cda92cbfe74b68db3c40bdc104916cb2f9df26151065e7d022e684a389d1f608365b
-  data.tar.gz: 00a4ebadb39f16879e25b81fae93f307a00337791271a5ca9b393726a24c32d5d41cb12181a16e5a84fd08d1c2a11e54980de39322162d23d5f14b2c57c5060c
+  metadata.gz: 5d41bad688a95b632280e32d3352034ab2b14fb8ce8a75653a0632d0a0db090dd7b7afee08602bd0a12f9e24c7f6018e83c56a4eb6903453b66890b5b02ce3a2
+  data.tar.gz: 2a1e8ea6ad147e6070a12d503d0543b95776a156152f50c67b2732ac0c63e1226c606eaa9f5abba785ae4c3eb15a94d9a79a89e1e00f6023e9aaaa9bce0d8407

data/CHANGELOG.md

@@ -1,20 +1,20 @@
 # Changelog
 
-All notable changes to this gem will be documented in this file.
+All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
-## [0.1.0] - 2026-03-21
+## [0.1.0] - 2026-03-22
 
 ### Added
-- Initial release
-- Binary heap `Queue` with min-heap (default) and max-heap modes
-- `push(item, priority:)` and `pop` with O(log n) performance
-- `peek` to view the highest-priority item without removal
-- `change_priority(item, new_priority)` to update priorities in-place
-- `to_a` for sorted array extraction
-- `merge(other)` to combine two priority queues
+
+- Binary heap priority queue with min-heap and max-heap modes
 - Custom comparator support via block
+- `push`, `pop`, `peek` operations with O(log n) performance
+- `<<` operator for hash-based push syntax
+- `change_priority` to update item priority with re-heapification
+- `merge` to combine two queues into a new queue
+- `to_a` to return items sorted by priority
+- `include?`, `clear`, `size`, `empty?` utility methods
+- FIFO tie-breaking for equal priorities

data/README.md

@@ -1,10 +1,9 @@
 # philiprehberger-priority_queue
 
-[![Tests](https://github.com/philiprehberger/rb-priority-queue/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-priority-queue/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/philiprehberger-priority_queue.svg)](https://rubygems.org/gems/philiprehberger-priority_queue)
-[![License](https://img.shields.io/github/license/philiprehberger/rb-priority-queue)](LICENSE)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-priority_queue.svg)](https://badge.fury.io/rb/philiprehberger-priority_queue)
+[![CI](https://github.com/philiprehberger/rb-priority-queue/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-priority-queue/actions/workflows/ci.yml)
 
-Binary heap priority queue with min/max modes and custom comparators
+Binary heap priority queue with min/max modes and custom comparators. Features O(log n) push/pop, priority updates, merge operations, and FIFO tie-breaking for equal priorities.
 
 ## Requirements
 
@@ -12,16 +11,14 @@ Binary heap priority queue with min/max modes and custom comparators
 
 ## Installation
 
-Add to your Gemfile:
-
-```ruby
-gem 'philiprehberger-priority_queue'
+```sh
+gem install philiprehberger-priority_queue
 ```
 
-Or install directly:
+Or add to your Gemfile:
 
-```bash
-gem install philiprehberger-priority_queue
+```ruby
+gem 'philiprehberger-priority_queue'
 ```
 
 ## Usage
@@ -29,80 +26,99 @@ gem install philiprehberger-priority_queue
 ```ruby
 require 'philiprehberger/priority_queue'
 
-pq = Philiprehberger::PriorityQueue::Queue.new
-pq.push('low', priority: 1)
-pq.push('high', priority: 10)
-pq.push('mid', priority: 5)
-
-pq.pop   # => "low"
-pq.pop   # => "mid"
-pq.pop   # => "high"
+# 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.pop   # => "low"
+queue.pop   # => "mid"
+queue.pop   # => "high"
+
+# Max-heap - highest priority first
+queue = Philiprehberger::PriorityQueue::Queue.new(mode: :max)
+queue.push('task_a', priority: 3)
+queue.push('task_b', priority: 7)
+queue.pop   # => "task_b"
+
+# Custom comparator
+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"
+
+# Peek without removing
+queue = Philiprehberger::PriorityQueue::Queue.new
+queue.push('item', priority: 1)
+queue.peek  # => "item"
+queue.size  # => 1
+
+# Change priority
+queue = Philiprehberger::PriorityQueue::Queue.new
+queue.push('task', priority: 10)
+queue.change_priority('task', 1)  # now highest priority in min-heap
+
+# Merge queues
+merged = queue1.merge(queue2)
+
+# Other operations
+queue.include?('task')  # => true
+queue.to_a              # => items sorted by priority
+queue.empty?            # => false
+queue.clear             # removes all items
 ```
 
-### Max-Heap
+## API
 
-```ruby
-pq = Philiprehberger::PriorityQueue::Queue.new(mode: :max)
-pq.push('low', priority: 1)
-pq.push('high', priority: 10)
-pq.pop   # => "high"
-```
+### `Queue.new(mode: :min, &comparator)`
 
-### Custom Comparator
+Creates a new priority queue. Mode can be `:min` (default) or `:max`. An optional block provides a custom comparator.
 
-```ruby
-pq = Philiprehberger::PriorityQueue::Queue.new { |a, b| a[:priority] <=> b[:priority] }
-pq.push('task', priority: 5)
-```
+### `#push(item, priority:)` / `#<<`
 
-### Updating Priorities
+Adds an item with the given priority. Returns self. The `<<` operator accepts a hash: `queue << { item: 'x', priority: 1 }`.
 
-```ruby
-pq = Philiprehberger::PriorityQueue::Queue.new
-pq.push('task_a', priority: 10)
-pq.push('task_b', priority: 5)
-pq.change_priority('task_a', 1)
-pq.pop  # => "task_a" (now has lowest priority)
-```
+### `#pop`
 
-### Merging Queues
+Removes and returns the highest-priority item. Returns `nil` if empty.
 
-```ruby
-pq1 = Philiprehberger::PriorityQueue::Queue.new
-pq1.push('a', priority: 1)
+### `#peek`
 
-pq2 = Philiprehberger::PriorityQueue::Queue.new
-pq2.push('b', priority: 2)
+Returns the highest-priority item without removing it. Returns `nil` if empty.
 
-pq1.merge(pq2)
-pq1.size  # => 2
-```
+### `#size` / `#empty?`
 
-## API
+Returns the number of items or whether the queue is empty.
+
+### `#change_priority(item, new_priority)`
+
+Updates the priority of an existing item and re-heapifies. Raises `ArgumentError` if the item is not found.
+
+### `#to_a`
+
+Returns all items sorted by priority.
+
+### `#include?(item)`
+
+Returns `true` if the item is in the queue.
+
+### `#clear`
+
+Removes all items from the queue.
+
+### `#merge(other)`
 
-### `Philiprehberger::PriorityQueue::Queue`
-
-| Method | Description |
-|--------|-------------|
-| `.new(mode: :min)` | Create a min-heap (default) or max-heap |
-| `.new { \|a, b\| ... }` | Create with a custom comparator block |
-| `#push(item, priority:)` | Add an item with a priority |
-| `#pop` | Remove and return the highest-priority item |
-| `#peek` | View the highest-priority item without removing it |
-| `#size` | Number of items in the queue |
-| `#empty?` | Whether the queue is empty |
-| `#change_priority(item, new_priority)` | Update an item's priority |
-| `#to_a` | Return all items in priority order |
-| `#merge(other)` | Merge another queue into this one |
+Returns a new queue containing items from both queues. Does not modify the originals.
 
 ## Development
 
-```bash
+```sh
 bundle install
-bundle exec rspec      # Run tests
-bundle exec rubocop    # Check code style
+bundle exec rspec
+bundle exec rubocop
 ```
 
 ## License
 
-MIT
+MIT License. See [LICENSE](LICENSE) for details.

data/lib/philiprehberger/priority_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module PriorityQueue
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end
 end

data/lib/philiprehberger/priority_queue.rb

@@ -4,164 +4,142 @@ require_relative 'priority_queue/version'
 
 module Philiprehberger
   module PriorityQueue
-    class Error < StandardError; end
-
-    # A binary heap priority queue supporting min-heap, max-heap, and custom comparators
-    #
-    # @example Min-heap (default)
-    #   pq = Queue.new
-    #   pq.push('low', priority: 1)
-    #   pq.push('high', priority: 10)
-    #   pq.pop  # => "low"
-    #
-    # @example Max-heap
-    #   pq = Queue.new(mode: :max)
-    #   pq.push('low', priority: 1)
-    #   pq.push('high', priority: 10)
-    #   pq.pop  # => "high"
     class Queue
-      # Create a new priority queue
-      #
-      # @param mode [Symbol] :min (default) or :max
-      # @yield [a, b] optional custom comparator block
-      # @raise [Error] if mode is invalid
-      def initialize(mode: :min, &comparator)
-        unless %i[min max].include?(mode)
-          raise Error, "Invalid mode: #{mode}. Use :min or :max"
-        end
+      attr_reader :size
 
+      def initialize(mode: :min, &comparator)
         @heap = []
-        @comparator = comparator || default_comparator(mode)
+        @size = 0
+        @insertion_counter = 0
+        @item_index = {}
+
+        @comparator = if comparator
+                        comparator
+                      elsif mode == :max
+                        ->(a, b) { b <=> a }
+                      else
+                        ->(a, b) { a <=> b }
+                      end
       end
 
-      # Push an item onto the queue with a given priority
-      #
-      # @param item [Object] the item to enqueue
-      # @param priority [Numeric] the priority value
-      # @return [self]
-      def push(item, priority: 0)
-        entry = { item: item, priority: priority }
+      def push(item, priority:)
+        entry = [priority, @insertion_counter, item]
+        @insertion_counter += 1
         @heap << entry
-        bubble_up(@heap.length - 1)
+        @item_index[item] = @size
+        @size += 1
+        bubble_up(@size - 1)
         self
       end
 
-      # Remove and return the highest-priority item
-      #
-      # @return [Object, nil] the item, or nil if empty
+      def <<(item_with_priority)
+        raise ArgumentError, 'Expected a hash with :item and :priority keys' unless item_with_priority.is_a?(Hash)
+
+        push(item_with_priority[:item], priority: item_with_priority[:priority])
+      end
+
       def pop
-        return nil if @heap.empty?
+        return nil if empty?
 
-        swap(0, @heap.length - 1)
+        swap(0, @size - 1)
         entry = @heap.pop
-        bubble_down(0) unless @heap.empty?
-        entry[:item]
+        @size -= 1
+        @item_index.delete(entry[2])
+        bubble_down(0) unless empty?
+        entry[2]
       end
 
-      # Return the highest-priority item without removing it
-      #
-      # @return [Object, nil] the item, or nil if empty
       def peek
-        return nil if @heap.empty?
-
-        @heap[0][:item]
-      end
+        return nil if empty?
 
-      # Return the number of items in the queue
-      #
-      # @return [Integer]
-      def size
-        @heap.length
+        @heap[0][2]
       end
 
-      # Check if the queue is empty
-      #
-      # @return [Boolean]
       def empty?
-        @heap.empty?
+        @size.zero?
       end
 
-      # Update the priority of an existing item
-      #
-      # @param item [Object] the item to update
-      # @param new_priority [Numeric] the new priority
-      # @return [self]
-      # @raise [Error] if the item is not found
       def change_priority(item, new_priority)
-        index = @heap.index { |e| e[:item] == item }
-        raise Error, 'Item not found in queue' if index.nil?
+        idx = @item_index[item]
+        raise ArgumentError, "Item not found in queue: #{item.inspect}" if idx.nil?
+
+        old_priority = @heap[idx][0]
+        @heap[idx] = [new_priority, @heap[idx][1], item]
 
-        @heap[index][:priority] = new_priority
-        bubble_up(index)
-        bubble_down(index)
+        cmp = @comparator.call(new_priority, old_priority)
+        if cmp.negative?
+          bubble_up(idx)
+        elsif cmp.positive?
+          bubble_down(idx)
+        end
         self
       end
 
-      # Return all items as a sorted array
-      #
-      # @return [Array] items in priority order
       def to_a
-        clone = Queue.new(&@comparator)
-        @heap.each { |entry| clone.push(entry[:item], priority: entry[:priority]) }
+        @heap.sort { |a, b| compare_entries(a, b) }.map { |entry| entry[2] }
+      end
 
-        result = []
-        result << clone.pop until clone.empty?
-        result
+      def include?(item)
+        @item_index.key?(item)
       end
 
-      # Merge another priority queue into this one
-      #
-      # @param other [Queue] the queue to merge
-      # @return [self]
-      def merge(other)
-        other.each_entry { |item, priority| push(item, priority: priority) }
+      def clear
+        @heap.clear
+        @item_index.clear
+        @size = 0
         self
       end
 
-      # @api private
-      def each_entry
-        @heap.each { |entry| yield entry[:item], entry[:priority] }
+      def merge(other)
+        merged = self.class.new(&@comparator)
+        @heap.each { |entry| merged.push(entry[2], priority: entry[0]) }
+        other.each_entry { |entry| merged.push(entry[2], priority: entry[0]) }
+        merged
+      end
+
+      protected
+
+      def each_entry(&)
+        @heap.each(&)
       end
 
       private
 
-      def default_comparator(mode)
-        case mode
-        when :min then ->(a, b) { a[:priority] <=> b[:priority] }
-        when :max then ->(a, b) { b[:priority] <=> a[:priority] }
-        end
+      def compare_entries(a, b)
+        cmp = @comparator.call(a[0], b[0])
+        cmp.zero? ? a[1] <=> b[1] : cmp
       end
 
-      def bubble_up(index)
-        while index.positive?
-          parent = (index - 1) / 2
-          break unless @comparator.call(@heap[index], @heap[parent]).negative?
+      def bubble_up(idx)
+        while idx.positive?
+          parent = (idx - 1) / 2
+          break unless compare_entries(@heap[idx], @heap[parent]).negative?
 
-          swap(index, parent)
-          index = parent
+          swap(idx, parent)
+          idx = parent
         end
       end
 
-      def bubble_down(index)
-        size = @heap.length
-
+      def bubble_down(idx)
         loop do
-          smallest = index
-          left = 2 * index + 1
-          right = 2 * index + 2
+          smallest = idx
+          left = (2 * idx) + 1
+          right = (2 * idx) + 2
 
-          smallest = left if left < size && @comparator.call(@heap[left], @heap[smallest]).negative?
-          smallest = right if right < size && @comparator.call(@heap[right], @heap[smallest]).negative?
+          smallest = left if left < @size && compare_entries(@heap[left], @heap[smallest]).negative?
+          smallest = right if right < @size && compare_entries(@heap[right], @heap[smallest]).negative?
 
-          break if smallest == index
+          break if smallest == idx
 
-          swap(index, smallest)
-          index = smallest
+          swap(idx, smallest)
+          idx = smallest
         end
       end
 
       def swap(i, j)
         @heap[i], @heap[j] = @heap[j], @heap[i]
+        @item_index[@heap[i][2]] = i
+        @item_index[@heap[j][2]] = j
       end
     end
   end

metadata

@@ -1,19 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-priority_queue
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
-- Philip Rehberger
+- philiprehberger
 autorequire:
 bindir: bin
 cert_chain: []
 date: 2026-03-22 00:00:00.000000000 Z
 dependencies: []
-description: An efficient priority queue using a binary heap. Supports min-heap and
-  max-heap modes, custom comparators, priority updates, and merge operations.
+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,
+  and FIFO tie-breaking.
 email:
-- me@philiprehberger.com
+- philiprehberger@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -30,7 +31,6 @@ metadata:
   homepage_uri: https://github.com/philiprehberger/rb-priority-queue
   source_code_uri: https://github.com/philiprehberger/rb-priority-queue
   changelog_uri: https://github.com/philiprehberger/rb-priority-queue/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/philiprehberger/rb-priority-queue/issues
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -40,7 +40,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="