queap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7e14026a37ca2d8ef67eb8e7310b30333604b5b49f583406117c1a6b2beea94
+  data.tar.gz: 37e1be46c16584da9d292270c6ecba8117a58e8ace1ef33e52d1fb89f1974894
+SHA512:
+  metadata.gz: d627a6b824ca2b00639024cba91b0d717a5c3a8b0babef20f748e8e80d46ab8cbb4b7b0e85000885244f0160b9e8cb9b1ebfa9a5685ddef55765ff7b92d2799c
+  data.tar.gz: e518d807fad71698cc230d134952379f7e844cccc1cb16d96e6028fbe908a8255f08232a94d4fa7dcfa34f2b3735c692c39ec5966d798f8edae72867dd05a716

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Jeffrey Crowell
+
+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,156 @@
+# Queap
+
+[![RubyGems](https://img.shields.io/gem/v/queap.svg)](https://rubygems.org/gems/queap)
+[![CI](https://github.com/crowell/queap/actions/workflows/ci.yml/badge.svg)](https://github.com/crowell/queap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.txt)
+
+**Queap** is a pure‑Ruby implementation of the *queap* data structure
+a meld of queue and heap that gives  
+
+| Operation        | Amortised | Worst‑case |
+|------------------|-----------|-----------|
+| `insert(x)`      | **O(1)**  | O(k)\* |
+| `minimum`        | **O(1)**  | O(1)  |
+| `delete_min`     | **O(log n)** | O(log n) |
+| `delete(elem)`   | **O(log n)** | O(log n) |
+
+\*`k` is the number of items flushed from the buffer list into the tree—  
+in steady state this cost is spread out, so the amortised cost per insert is constant.
+
+Under the hood Queap combines:
+
+* A simple buffer list for **O(1) inserts**.
+* A left‑leaning Red‑Black tree for **log‑time deletions** (isomorphic to a 2‑4 tree).
+* A cached pointer to the list‑minimum so `minimum` never touches the tree.
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "queap", "~> 0.2"
+```
+
+or install globally:
+
+```console
+$ gem install queap
+```
+
+Supported Rubies: MRI 3.1 – 3.3, TruffleRuby, JRuby.
+
+---
+
+## Quick start
+
+```ruby
+require "queap"
+
+q = Queap.new            # same as Queap::Queue.new
+[5, 3, 9, 1].each { |k| q.insert(Queap::Queue::Element.new(key: k)) }
+
+q.minimum.key     # => 1
+q.delete_min.key  # => 1
+q.minimum.key     # => 3
+```
+
+---
+
+## API
+
+```ruby
+q = Queap.new
+elem   = q.insert(Queap::Queue::Element.new(key: 42))
+q.size # => 1
+
+q.delete(elem)    # arbitrary deletion
+q.empty?          # => true
+```
+
+**Element** is a tiny struct with a single mandatory field:
+
+```ruby
+Element.new(key: <comparable>)
+```
+
+Anything that implements `<=>` works—numbers, strings, structs, etc.
+
+---
+
+## Performance
+
+A micro‑benchmark on Ruby 3.3 (M1 Pro macOS 15):
+```console
+Benchmarking with n = 1000
+ruby 3.3.5 (2024-09-03 revision ef084cc8f4) [arm64-darwin24]
+Warming up --------------------------------------
+              insert    69.000 i/100ms
+             minimum   324.493k i/100ms
+          delete_min     1.113M i/100ms
+Calculating -------------------------------------
+              insert    687.073 (± 2.3%) i/s    (1.46 ms/i) -      3.450k in   5.024233s
+             minimum      3.242M (± 4.4%) i/s  (308.42 ns/i) -     16.225M in   5.015994s
+          delete_min     10.982M (± 0.8%) i/s   (91.06 ns/i) -     55.651M in   5.067814s
+
+Comparison:
+          delete_min: 10981987.0 i/s
+             minimum:  3242293.1 i/s - 3.39x  slower
+              insert:      687.1 i/s - 15983.72x  slower
+```
+
+Such numbers are competitive with `SortedSet`/`RBTree` gems while giving strictly better
+insertion complexity.
+
+Run your own benchmarks:
+
+```console
+$ rake benchmark
+```
+
+---
+
+## Algorithm background
+
+In essence, it keeps a *buffered queue* of recent inserts and a *balanced tree* of older
+items. Deletions that hit the buffer trigger a one‑off flush; otherwise they hit the tree.
+
+---
+
+## Development
+
+```console
+$ git clone https://github.com/crowell/queap.git
+$ cd queap
+$ bundle install
+$ bundle exec rspec       # run test suite
+```
+
+RuboCop and RSpec run automatically on every push via GitHub Actions.
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at  
+<https://github.com/crowell/queap>.
+
+1. Fork the project
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Open a pull request
+
+Please run `bundle exec rspec && rubocop` before submitting.
+
+---
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](LICENSE.txt).
+
+---
+
+© 2025 Jeffrey Crowell

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+desc "Run micro-benchmarks (default n = 1_000)"
+task :benchmark, [:n] do |_, args|
+  n = args[:n] || 1_000
+  exec "bundle exec ruby benchmark/queap_bench.rb #{n}"
+end

data/benchmark/queap_bench.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+#
+# Run with:
+#   bundle exec ruby benchmark/queap_bench.rb [n]
+#
+# n defaults to 1_000.  Use 1_000_000 for a heavier run.
+
+require "benchmark/ips"
+require "queap"
+
+N = (ARGV.shift || 1_000).to_i
+STDERR.puts "Benchmarking with n = #{N}"
+
+Benchmark.ips do |x|
+  # ------------------------------------------------------------------
+  x.report("insert") do
+    q = Queap.new
+    N.times { |i| q.insert(Queap::Queue::Element.new(key: i)) }
+  end
+
+  q_for_min = Queap.new
+  N.times { |i| q_for_min.insert(Queap::Queue::Element.new(key: i)) }
+  x.report("minimum") { q_for_min.minimum }
+
+  q_for_del = Queap.new
+  N.times { |i| q_for_del.insert(Queap::Queue::Element.new(key: i)) }
+  x.report("delete_min") { q_for_del.delete_min }
+
+  x.compare!
+end

data/lib/queap/queue.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+
+module Queap
+  #   q = Queap::Queue.new
+  #   elem = q.insert(42)
+  #   q.minimum         # => elem
+  #   q.delete_min      # => elem
+  #
+  # Elements are small structs that remember whether they currently sit in the
+  # buffer list (O(1) insertion area) or inside the balanced search tree.
+  class Queue
+    Element = Struct.new(:key, :in_list, :node, keyword_init: true) do
+      include Comparable
+      def <=>(other) = key <=> other.key
+    end
+
+    attr_reader :size
+
+    BUFFER_FLUSH_FACTOR = 2 # flush when list grows to n / factor
+
+    def initialize
+      @list  = []         # simple dynamic array works fine; we always scan O(k)
+      @min_l = nil
+      @tree  = RBTree.new
+      @size  = 0
+    end
+
+    # O(1) amortised
+    def insert(x)
+      raise ArgumentError, "Element must respond to #<=>" unless x.respond_to?(:<=>)
+
+      x.in_list = true
+      @list     << x
+      @min_l    = x if @min_l.nil? || x < @min_l
+      @size    += 1
+      maybe_flush
+      x
+    end
+
+    # O(1)
+    def minimum
+      tmin = @tree.min&.key
+      return @min_l if tmin.nil? || (@min_l && @min_l < tmin)
+
+      tmin
+    end
+
+    # O(log n)
+    def delete_min
+      m = minimum
+      return nil unless m
+
+      delete(m)
+      m
+    end
+
+    # O(log n) if element in tree, otherwise amortised O(k) for the one-off flush
+    def delete(element)
+      if element.in_list
+        flush_buffer!
+        # element’s node was set during insert_all
+      end
+      @tree.delete(element.node)
+      @size -= 1
+      recompute_min_l if element.equal?(@min_l)
+      element
+    end
+
+    def empty? = @size.zero?
+
+    # ----------------------------------------------------------------------
+    private
+
+    def flush_threshold
+      # k ≤ n; we flush when buffer length > n / F.
+      (@size / BUFFER_FLUSH_FACTOR).clamp(1, @size)
+    end
+
+    def maybe_flush
+      flush_buffer! if @list.length >= flush_threshold
+    end
+
+    def flush_buffer!
+      @list.each do |elem|
+        next unless elem.in_list
+
+        elem.in_list = false
+        elem.node    = @tree.insert(elem)
+      end
+      @list.clear
+      @min_l = nil
+    end
+
+    def recompute_min_l
+      @min_l = @list.min
+    end
+  end
+end

data/lib/queap/tree.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Queap
+  # Internal balanced BST.  A classic left-leaning Red–Black tree gives the
+  # same asymptotics as a 2-4 tree but is ~40 % less code and copies well to
+  # Ruby.  Public surface is deliberately tiny: insert, delete(node) and min.
+  class RBTree
+    Node     = Struct.new(:key, :left, :right, :parent, :red, keyword_init: true)
+    attr_reader :root
+
+    # ---- helpers ----------------------------------------------------------
+
+    def min(node = root)
+      return nil unless node
+
+      node = node.left while node.left
+      node
+    end
+
+    def insert(key)
+      n = Node.new(key:, red: true)
+      y = nil
+      x = @root
+      while x
+        y = x
+        x = key < x.key ? x.left : x.right
+      end
+      n.parent = y
+      if y.nil?
+        @root = n
+      elsif key < y.key
+        y.left = n
+      else
+        y.right = n
+      end
+      insert_fixup(n)
+      n
+    end
+
+    def delete(node)
+      return unless node
+
+      y      = node
+      y_orig = y.red
+      if node.left.nil?
+        x = node.right
+        transplant(node, node.right)
+      elsif node.right.nil?
+        x = node.left
+        transplant(node, node.left)
+      else
+        y     = min(node.right)
+        y_orig = y.red
+        x     = y.right
+        if y.parent.equal?(node)
+          x&.parent = y
+        else
+          transplant(y, y.right)
+          y.right        = node.right
+          y.right.parent = y
+        end
+        transplant(node, y)
+        y.left        = node.left
+        y.left.parent = y
+        y.red         = node.red
+      end
+      delete_fixup(x) unless y_orig
+      x
+    end
+
+    # ---- private ----------------------------------------------------------
+    private
+
+    def red?(n) = n&.red
+    def black?(n) = !red?(n)
+
+    def left_rotate(x)
+      y        = x.right
+      x.right  = y.left
+      y.left&.parent = x
+      y.parent = x.parent
+      if x.parent.nil?
+        @root = y
+      elsif x.equal?(x.parent.left)
+        x.parent.left = y
+      else
+        x.parent.right = y
+      end
+      y.left = x
+      x.parent = y
+    end
+
+    def right_rotate(x)
+      y        = x.left
+      x.left   = y.right
+      y.right&.parent = x
+      y.parent = x.parent
+      if x.parent.nil?
+        @root = y
+      elsif x.equal?(x.parent.right)
+        x.parent.right = y
+      else
+        x.parent.left = y
+      end
+      y.right  = x
+      x.parent = y
+    end
+
+    def insert_fixup(z)
+      while red?(z.parent)
+        if z.parent.equal?(z.parent.parent.left)
+          y = z.parent.parent.right
+          if red?(y)
+            z.parent.red = y.red = false
+            z.parent.parent.red = true
+            z = z.parent.parent
+          else
+            if z.equal?(z.parent.right)
+              z = z.parent
+              left_rotate(z)
+            end
+            z.parent.red = false
+            z.parent.parent.red = true
+            right_rotate(z.parent.parent)
+          end
+        else
+          y = z.parent.parent.left
+          if red?(y)
+            z.parent.red = y.red = false
+            z.parent.parent.red = true
+            z = z.parent.parent
+          else
+            if z.equal?(z.parent.left)
+              z = z.parent
+              right_rotate(z)
+            end
+            z.parent.red = false
+            z.parent.parent.red = true
+            left_rotate(z.parent.parent)
+          end
+        end
+      end
+      @root.red = false
+    end
+
+    def delete_fixup(x)
+      # keep going while x is a *real* node, not the root, and black
+      while x && x != @root && black?(x)
+        if x.equal?(x&.parent&.left)
+          w = x&.parent&.right
+          unless w                                   # ← new: sibling is nil
+            x = x.parent
+            next
+          end
+
+          if red?(w)
+            w.red = false
+            x.parent.red = true
+            left_rotate(x.parent)
+            w = x.parent.right
+          end
+
+          if black?(w&.left) && black?(w&.right)     # ← safe-nav
+            w.red = true
+            x = x.parent
+          else
+            if black?(w&.right)
+              w.left.red = false if w.left
+              w.red = true
+              right_rotate(w)
+              w = x.parent.right
+            end
+            w.red          = x.parent.red
+            x.parent.red   = false
+            w.right.red    = false if w.right
+            left_rotate(x.parent)
+            x = @root
+          end
+        else
+          w = x&.parent&.left
+          unless w                                   # ← new: sibling is nil
+            x = x.parent
+            next
+          end
+
+          if red?(w)
+            w.red = false
+            x.parent.red = true
+            right_rotate(x.parent)
+            w = x.parent.left
+          end
+
+          if black?(w&.right) && black?(w&.left)     # ← safe-nav
+            w.red = true
+            x = x.parent
+          else
+            if black?(w&.left)
+              w.right.red = false if w.right
+              w.red = true
+              left_rotate(w)
+              w = x.parent.left
+            end
+            w.red         = x.parent.red
+            x.parent.red  = false
+            w.left.red    = false if w.left
+            right_rotate(x.parent)
+            x = @root
+          end
+        end
+      end
+      x&.red = false
+    end
+
+    def transplant(u, v)
+      if u.parent.nil?
+        @root = v
+      elsif u.equal?(u.parent.left)
+        u.parent.left = v
+      else
+        u.parent.right = v
+      end
+      v&.parent = u.parent
+    end
+  end
+end

data/lib/queap/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Queap
+  VERSION = "0.1.0"
+end

data/lib/queap.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "queap/version"
+require_relative "queap/tree"
+require_relative "queap/queue"
+
+module Queap
+  # you can expose convenience aliases here if you like:
+  #
+  #   Queap.new is nicer than Queap::Queue.new
+  #
+  def self.new(*args, **kw) = Queue.new(*args, **kw)
+end

data/sig/queap.rbs

@@ -0,0 +1,4 @@
+module Queap
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: queap
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeffrey Crowell
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-02 00:00:00.000000000 Z
+dependencies: []
+description: Ruby implementation of the 'queap' data structure
+email:
+- jeff@crowell.biz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmark/queap_bench.rb
+- lib/queap.rb
+- lib/queap/queue.rb
+- lib/queap/tree.rb
+- lib/queap/version.rb
+- sig/queap.rbs
+homepage: https://github.com/crowell/queap
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/crowell/queap
+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.16
+signing_key:
+specification_version: 4
+summary: A doubly-ended priority queue (Queap) with O(1) amortised insert.
+test_files: []