binary_heap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: faaa2815340f3e63149991ade157103211160d2fa957e72c4ab2a19025adb10a
+  data.tar.gz: 97c61d6a57e6fdb3d217c300568951193eeec8741139c1dc92dcfc902097696d
+SHA512:
+  metadata.gz: 3d492d350927815d34b1c5403c12488986bdf44746b0adaf73fc1e7fc28fdaa8ebf8727181b7fd9cb747eecf220b2befa89f8eac82661caf2d06f2db9c2ca46a
+  data.tar.gz: 93d1571f07f19b3ae36fa48232f673b3e6cd92c64836d80808aa26551f7a16cd8344bd8fee20df744602fa09ca6f7dd902bbfb932426b3b6a2972143a050e34a

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-03-06
+
+- Initial release

data/README.md

@@ -0,0 +1,61 @@
+# BinaryHeap
+
+BinaryHeap is a pure ruby implementation of a binary heap, that can be used as a priority queue.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG 
+
+## Usage
+
+````ruby
+
+    require 'binary_heap'
+    q = BinaryHeap::Base.new([4,5,7])
+    q.push(2)  
+    q.min # => 2
+    q.pop # => 2
+    q.min # => 4
+
+````
+
+## Benchmarks
+
+On modern Ruby (>= 3.2) with YJIT enabled it is about as fast as priority_queue_cxx 
+which is a Heap Implementation written as a C++-Extension to Ruby. In any case it compares 
+favorably against other heap implementations written in pure Ruby.
+
+Library             | user       |system     | total    |    real
+--------------------|------------|-----------|----------|------------
+binary_heap         |  3.089522  | 0.005000  | 3.094522 |(  3.094816)
+priority_queue_cxx  |  0.726967  | 0.000000  | 0.726967 |(  0.726975)
+lazy-priority-queue | 10.646469  | 0.032996  |10.679465 |( 10.681288)
+
+With YJIT enabled:
+
+
+Library             |   user   |  system  |    total|   real
+--------------------|----------|----------|---------|----------
+binary_heap         | 0.697922 | 0.003981| 0.701903|(  0.702160)
+priority_queue_cxx  | 0.707953 |  0.001005|  0.708958|(  0.708970)
+lazy-priority-queue | 5.456912 | 0.027023|  5.483935|(  5.484204)
+
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/skr0504/binary_heap.

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+
+Minitest::TestTask.create
+
+task default: :test
+
+desc "Run benchmarks"
+task :benchmark do
+  Dir.glob('./benchmark/bench_*.rb') { |file| require file }
+end

data/Steepfile

@@ -0,0 +1,32 @@
+# D = Steep::Diagnostic
+#
+target :lib do
+   signature "sig"
+#   ignore_signature "sig/test"
+#
+   check "lib"                       # Directory name
+#   check "path/to/source.rb"         # File name
+#   check "app/models/**/*.rb"        # Glob
+#   # ignore "lib/templates/*.rb"
+#
+library "pathname"              # Standard libraries
+#   # library "strong_json"           # Gems
+#
+#   # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+#configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+#   # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+#   # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+#   # configure_code_diagnostics do |hash|             # You can setup everything yourself
+#   #   hash[D::Ruby::NoMethod] = :information
+#   # end
+end
+
+# target :test do
+#   unreferenced!                     # Skip type checking the `lib` code when types in `test` target is changed
+#   signature "sig/test"              # Put RBS files for tests under `sig/test`
+#   check "test"                      # Type check Ruby scripts under `test`
+#
+#   configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
+#
+#   # library "pathname"              # Standard libraries
+# end

data/benchmark/bench_binary_heap.rb

@@ -0,0 +1,25 @@
+require_relative 'bench_helper'
+
+
+puts "Comparison with priority_queue_cxx"
+
+Benchmark.bmbm do |b|
+
+  b.report("binary_heap") do
+    pq = BinaryHeap::Base.new
+    RUNS.times { pq.push(rand(RUNS)) }
+    RUNS.times { pq.pop }
+  end
+
+  b.report("priority_queue_cxx") do
+    pq = FastContainers::PriorityQueue.new(:min)
+    RUNS.times { |i| pq.push(i, rand(RUNS)) }
+    RUNS.times { pq.pop }
+  end
+
+  b.report("lazy-priority-queue") do
+    pq = MinPriorityQueue.new
+    RUNS.times { |i| pq.push(i, rand(RUNS)) }
+    RUNS.times { pq.pop }
+  end
+end

data/benchmark/bench_helper.rb

@@ -0,0 +1,7 @@
+require 'benchmark'
+require 'bundler/setup'
+require 'binary_heap'
+require 'fc'
+require 'lazy_priority_queue'
+
+RUNS = 400_000

data/lib/binary_heap/base.rb

@@ -0,0 +1,102 @@
+module BinaryHeap
+  class Base
+
+    include Enumerable
+
+    def initialize(ary=[])
+      if ary.is_a? Array
+        @heap = ary.dup
+        heapify
+      else
+        raise ArgumentError
+      end
+    end
+
+    def length
+      @heap.length
+    end
+
+    def each
+      @heap.each
+    end
+
+    def <<(el)
+      @heap << el
+      rebalance_up(@heap.size - 1)
+      self
+    end
+
+    def push(*els)
+      if els.length < length
+        els.each do |el|
+          self << el
+        end
+      else
+        @heap.push(*els)
+        heapify
+      end
+      self
+    end
+
+    def pop
+      @heap[0], @heap[-1] = @heap[-1], @heap[0]
+      res = @heap.pop
+      if @heap.size.positive?
+        rebalance_down(0)
+      end
+      res
+    end
+
+    def min
+      @heap[0]
+    end
+
+    def replace_min(el)
+      @heap[0] = el
+      rebalance_down(0)
+    end
+
+    def clear
+      @heap.clear
+      self
+    end
+
+
+    private 
+
+    def heapify
+      ((@heap.size >> 1)-1).downto(0).each do |n| # all internal nodes
+        rebalance_down(n)
+      end
+    end
+
+    def rebalance_up(i)
+      while i.positive?
+        parent_i = i >> 1
+        if @heap[i] < @heap[parent_i]
+          @heap[i], @heap[parent_i] = @heap[parent_i], @heap[i]
+          i = parent_i
+        else
+          break
+        end
+      end
+    end
+
+    def rebalance_down(i)
+      while (i << 1).succ < @heap.size
+        left_i = (i << 1).succ
+        right_i = (i.succ) << 1
+
+        if @heap[right_i] && @heap[right_i] <= @heap[left_i] && @heap[right_i] < @heap[i]
+          @heap[i], @heap[right_i] = @heap[right_i], @heap[i]
+          i = right_i
+        elsif @heap[left_i] < @heap[i]
+          @heap[i], @heap[left_i] = @heap[left_i], @heap[i]
+          i = left_i
+        else
+          break
+        end
+      end
+    end
+  end
+end

data/lib/binary_heap/version.rb

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

data/lib/binary_heap.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+
+
+require_relative "binary_heap/version"
+require_relative "binary_heap/base"
+
+
+module BinaryHeap
+  class Error < StandardError; end
+  # Your code goes here...
+
+
+end

data/sig/binary_heap.rbs

@@ -0,0 +1,42 @@
+module BinaryHeap
+
+  VERSION: String
+
+  class Error
+  end
+
+  interface _Comparable
+    def <: (_Comparable) -> bool
+    def <=: (_Comparable) -> bool
+  end
+
+  class Base[unchecked out Elem < _Comparable]
+    @heap: Array[Elem]
+
+    def initialize: (?Array[Elem] ary) -> void
+
+    def length: () -> Integer
+
+    def each: () -> Enumerator[Elem]
+
+    def <<: (Elem el) -> self
+
+    def push: (*Elem els) -> self
+
+    def pop: () -> Elem?
+
+    def min: () -> Elem
+
+    def replace_min: (Elem el) -> self
+
+    def clear: () -> self
+
+    private
+
+    def heapify: () -> untyped
+
+    def rebalance_up: (untyped i) -> untyped
+
+    def rebalance_down: (untyped i) -> untyped
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: binary_heap
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sebastian Krause
+bindir: exe
+cert_chain: []
+date: 2025-03-06 00:00:00.000000000 Z
+dependencies: []
+description: A binary heap can be used as a priority queue.
+email:
+- skrause216@posteo.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- Steepfile
+- benchmark/bench_binary_heap.rb
+- benchmark/bench_helper.rb
+- lib/binary_heap.rb
+- lib/binary_heap/base.rb
+- lib/binary_heap/version.rb
+- sig/binary_heap.rbs
+licenses: []
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.0.dev
+specification_version: 4
+summary: A simple implementation of a binary heap in Ruby.
+test_files: []