philiprehberger-priority_queue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 96eac91320e11af568cae20213fb6ea3bc6a16562ec2f8359539f69ce8d551f1
+  data.tar.gz: 9757f9de2dae44612d2fbc90abe916dbfa21b74657b8e19ca708ba43f5b90e39
+SHA512:
+  metadata.gz: b8043b9740dacab51fe67334cc21d06614eb7c0351181fd0ff8558f4cc10cda92cbfe74b68db3c40bdc104916cb2f9df26151065e7d022e684a389d1f608365b
+  data.tar.gz: 00a4ebadb39f16879e25b81fae93f307a00337791271a5ca9b393726a24c32d5d41cb12181a16e5a84fd08d1c2a11e54980de39322162d23d5f14b2c57c5060c

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this gem 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-21
+
+### 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
+- Custom comparator support via block

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# 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)
+
+Binary heap priority queue with min/max modes and custom comparators
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'philiprehberger-priority_queue'
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-priority_queue
+```
+
+## Usage
+
+```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"
+```
+
+### Max-Heap
+
+```ruby
+pq = Philiprehberger::PriorityQueue::Queue.new(mode: :max)
+pq.push('low', priority: 1)
+pq.push('high', priority: 10)
+pq.pop   # => "high"
+```
+
+### Custom Comparator
+
+```ruby
+pq = Philiprehberger::PriorityQueue::Queue.new { |a, b| a[:priority] <=> b[:priority] }
+pq.push('task', priority: 5)
+```
+
+### Updating Priorities
+
+```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)
+```
+
+### Merging Queues
+
+```ruby
+pq1 = Philiprehberger::PriorityQueue::Queue.new
+pq1.push('a', priority: 1)
+
+pq2 = Philiprehberger::PriorityQueue::Queue.new
+pq2.push('b', priority: 2)
+
+pq1.merge(pq2)
+pq1.size  # => 2
+```
+
+## API
+
+### `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 |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/priority_queue/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module PriorityQueue
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/priority_queue.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+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
+
+        @heap = []
+        @comparator = comparator || default_comparator(mode)
+      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 }
+        @heap << entry
+        bubble_up(@heap.length - 1)
+        self
+      end
+
+      # Remove and return the highest-priority item
+      #
+      # @return [Object, nil] the item, or nil if empty
+      def pop
+        return nil if @heap.empty?
+
+        swap(0, @heap.length - 1)
+        entry = @heap.pop
+        bubble_down(0) unless @heap.empty?
+        entry[:item]
+      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 the number of items in the queue
+      #
+      # @return [Integer]
+      def size
+        @heap.length
+      end
+
+      # Check if the queue is empty
+      #
+      # @return [Boolean]
+      def empty?
+        @heap.empty?
+      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?
+
+        @heap[index][:priority] = new_priority
+        bubble_up(index)
+        bubble_down(index)
+        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]) }
+
+        result = []
+        result << clone.pop until clone.empty?
+        result
+      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) }
+        self
+      end
+
+      # @api private
+      def each_entry
+        @heap.each { |entry| yield entry[:item], entry[:priority] }
+      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
+      end
+
+      def bubble_up(index)
+        while index.positive?
+          parent = (index - 1) / 2
+          break unless @comparator.call(@heap[index], @heap[parent]).negative?
+
+          swap(index, parent)
+          index = parent
+        end
+      end
+
+      def bubble_down(index)
+        size = @heap.length
+
+        loop do
+          smallest = index
+          left = 2 * index + 1
+          right = 2 * index + 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?
+
+          break if smallest == index
+
+          swap(index, smallest)
+          index = smallest
+        end
+      end
+
+      def swap(i, j)
+        @heap[i], @heap[j] = @heap[j], @heap[i]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-priority_queue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+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.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/priority_queue.rb
+- lib/philiprehberger/priority_queue/version.rb
+homepage: https://github.com/philiprehberger/rb-priority-queue
+licenses:
+- MIT
+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: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Binary heap priority queue with min/max modes and custom comparators
+test_files: []