rb_heap 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 66cfaef0351036198f0b4adb551c58c93a5cbcd5
+  data.tar.gz: 2d15030d700c18b8013d6916bc015942847427f7
+SHA512:
+  metadata.gz: 318644b3e21766745cec5396571cde7050a7a63401976e8da001e05e9cdda089be60fb720fac726ae6a36c8e75709b72f9fc1cf31a6f686e70bcf4a2759872f9
+  data.tar.gz: a8ec355b5956b6ca1440bb5a31d7d36a948d870e4ed5ce5ecf21bbf18cd410a275d2f0f95446ce6909c11c989cf4352929292604f885eb4a31a27ab59d53704f

data/.gitignore

@@ -0,0 +1,10 @@
+.bundle/
+.yardoc
+/Gemfile.lock
+_yardoc/
+coverage/
+doc/
+pkg/
+spec/reports/
+tmp/
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.0.0
+before_install: gem install bundler -v 1.13.1

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Florian Hartmann
+
+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,149 @@
+# Heap
+
+This is an heap implementation that can be used for priority queues. Internally
+it represents the heap as an array. It also contains an in-place heapsort
+implementation.
+
+```rb
+heap = Heap.new(:<)
+
+# << and .add are aliases
+heap << 3 << 1 << 2
+heap.add(4)
+
+heap.peak # => 4
+heap.pop # => 4
+heap.pop # => 3
+heap.pop # => 2
+heap.pop # => 1
+```
+
+## Different kind of heaps
+
+The default heap is a min heap, but you can also specifiy it explicitely.
+```rb
+minHeap = Heap.new
+anotherMinHeap = Heap.new(:<)
+```
+
+Creating a max heap is straight-forward:
+```rb
+maxHeap = Heap.new(:>)
+```
+
+You can also pass a custom comparison function using a block:
+```rb
+minAbsHeap = Heap.new{|a, b| a.abs < b.abs}
+minAbsHeap << 3 << 1 << -2
+minAbsHeap.pop # => 1
+minAbsHeap.pop # => -2
+minAbsHeap.pop # => 3
+```
+
+You can use this comparison function to compare specific fields:
+
+```rb
+Person = Struct.new(:name, :age)
+
+ageHeap = Heap.new{|a, b| a.age < b.age}
+ageHeap << Person.new("Richard Hendricks", 26)
+ageHeap << Person.new("Erlich Bachman", 32)
+ageHeap << Person.new("Dinesh Chugtai", 30)
+
+ageHeap.pop.name # => Richard Hendricks
+ageHeap.pop.name # => Dinesh Chugtai
+ageHeap.pop.name # => Erlich Bachman
+
+```
+
+## `pop` (O(log n)) and `peak` (O(1))
+
+`pop` removes the top element of the heap and returns it. `peak` returns the top
+element but doesn't change the heap itself.
+
+When the heap doesn't have any elements, `nil` is returned. You can also
+explicitly check if the heap still has elements using the `empty?` method.
+
+## `add` (O(log n))
+
+You can add elements to the heap using `.add`. As you already saw `<<` is
+aliased to `.add`.
+
+## `replace` (O(log n))
+
+You can replace the top element with a new one using this method. Of course you
+could also `pop` and `add` but that would cause two rebalance operations.
+`.replace` is optimised to only take one.
+
+```rb
+heap = Heap.new
+heap << 1 << 2 << 3
+heap.replace(4)
+
+heap.pop # => 2
+heap.pop # => 3
+heap.pop # => 4
+```
+
+## `offer` (O(log n))
+
+A lot of times you only want to replace the top element if it's smaller/larger
+than the potentially new element.
+
+```rb
+heap = Heap.new
+heap << 1
+
+heap.offer(0) # It's a min heap and 1 > 0, so it's not replaced
+heap.peak # => 1
+
+heap.offer(2) # 1 < 2, so it's replaced
+heap.peak # => 2
+```
+
+This method assumes that there's already a top element, so you have to check
+yourself that you don't call it on an empty heap.
+
+A potential use case would be finding the largest `k` numbers in a stream of
+incoming numbers, without actually storing all numbers.
+
+## Other utilities
+
+### `size`
+
+Returns the amount of elements that are in the heap.
+
+### `empty?`
+
+Returns a boolean that indicates whether the heap has any elements.
+
+### `to_a`
+
+Gives you all the heap contents as an array, but you shouldn't make any assumptions about
+the order of the elements.
+
+## Sorting
+
+Heapsort is pretty light-weight to implement once you have a working heap. For this
+reason this library also comes with an in-place heapsort function.
+
+```rb
+Heap.sort([3,1,2]) # => [1, 2, 3]
+Heap.sort([3,1,2], :>) # => [3, 2, 1]
+Heap.sort([3,1,-2]){|a, b| a.abs < b.abs} # => [1, -2, 3]
+```
+
+## Developing
+
+You can run the unit tests using `rake`.
+
+### Future ideas
+
+Ideas for functions that could be added:
+
+- Create a heap from an array. This is possible in O(n). Right now one could
+  repeatly add all the array elements into a new heap, but that'd be O(n log n)
+- Merging two heaps
+
+I guess it would also be fun to implement different kind of heaps, but maybe
+that's beyond the scope if this library.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rb_heap"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+$a = Heap.new
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rb_heap.rb

@@ -0,0 +1,5 @@
+require 'pp'
+
+require "rb_heap/version"
+require "rb_heap/heap"
+require "rb_heap/sort"

data/lib/rb_heap/heap.rb

@@ -0,0 +1,130 @@
+class Heap
+  def initialize(compare_symbol = :<, storage = [], &compare_fn)
+    @heap = storage
+    @size = 0
+    initialize_compare(compare_symbol, &compare_fn)
+  end
+
+  attr_reader :size
+
+  def empty?
+    size == 0
+  end
+
+  def peak
+    @heap[0]
+  end
+
+  def pop
+    result = peak
+
+    if size > 1
+      @size -= 1
+      @heap[0] = @heap[@size]
+      rebalance_down(0)
+    else
+      @size = 0
+    end
+
+    @heap[@size] = nil
+
+    result
+  end
+
+  def add(element)
+    @heap[@size] = element
+    @size += 1
+    rebalance_up(size - 1)
+    self
+  end
+
+  alias :<< :add
+
+  def replace(element)
+    @heap[0] = element
+    rebalance_down(0)
+  end
+
+  def offer(element)
+    if compare(peak, element)
+      result = peak
+      replace(element)
+      result
+    else
+      element
+    end
+  end
+
+  def clear
+    @heap = []
+    @size = 0
+  end
+
+  def to_a
+    @heap.dup
+  end
+
+  private
+
+  def initialize_compare(symbol, &fn)
+    @compare = if block_given?
+      fn
+    elsif symbol == :< or symbol.nil?
+      lambda{|a, b| a < b}
+    elsif symbol == :>
+      lambda{|a, b| a > b}
+    else
+      raise ArgumentError.new("The comparison symbol needs to be either :> or :<")
+    end
+  end
+
+  def compare(a, b)
+    @compare.call(a, b)
+  end
+
+  def rebalance_up(i)
+    parent_i = parent(i)
+
+    if has_parent(i) and compare(@heap[i], @heap[parent_i])
+      @heap[i], @heap[parent_i] = @heap[parent_i], @heap[i]
+      rebalance_up(parent_i)
+    end
+  end
+
+  def rebalance_down(i)
+    left_i = left(i)
+    right_i = right(i)
+
+    if has_left(i) and compare(@heap[left_i], @heap[i]) and (not has_right(i) or compare(@heap[left_i], @heap[right_i]))
+      @heap[i], @heap[left_i] = @heap[left_i], @heap[i]
+      rebalance_down(left_i)
+    elsif has_right(i) and compare(@heap[right_i], @heap[i])
+      @heap[i], @heap[right_i] = @heap[right_i], @heap[i]
+      rebalance_down(right_i)
+    end
+  end
+
+  def has_parent(i)
+    i >= 1
+  end
+
+  def parent(i)
+    ((i - 1) / 2).floor
+  end
+
+  def has_left(i)
+    left(i) < size
+  end
+
+  def left(i)
+    i * 2 + 1
+  end
+
+  def has_right(i)
+    right(i) < size
+  end
+
+  def right(i)
+    i * 2 + 2
+  end
+end

data/lib/rb_heap/sort.rb

@@ -0,0 +1,28 @@
+class Heap
+  def self.sort(array, order = :<, &compare_fn)
+    compare_fn = self.invertComparison(order, &compare_fn)
+    heap = Heap.new(order, array, &compare_fn)
+
+    array.each do |element|
+      heap.add(element)
+    end
+
+    (0...array.size).reverse_each do |i|
+      array[i] = heap.pop
+    end
+
+    heap.to_a
+  end
+
+  def self.invertComparison(order, &compare_fn)
+    if block_given?
+      lambda{|a, b| not compare_fn.call(a, b)}
+    elsif order == :< or order.nil?
+      lambda{|a, b| a > b}
+    elsif order == :>
+      lambda{|a, b| a < b}
+    else
+      raise ArgumentError.new("The comparison symbol needs to be either :> or :<")
+    end
+  end
+end

data/lib/rb_heap/version.rb

@@ -0,0 +1,3 @@
+class Heap
+  VERSION = "1.0.0"
+end

data/rb_heap.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rb_heap/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rb_heap"
+  spec.version       = Heap::VERSION
+  spec.authors       = ["Florian Hartmann"]
+  spec.email         = ["jscoderr@gmail.com"]
+
+  spec.summary       = %q{Light-weight priority queue implementation using a heap}
+  spec.homepage      = "https://github.com/florian/rb_heap"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: rb_heap
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Florian Hartmann
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-09-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- jscoderr@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/rb_heap.rb
+- lib/rb_heap/heap.rb
+- lib/rb_heap/sort.rb
+- lib/rb_heap/version.rb
+- rb_heap.gemspec
+homepage: https://github.com/florian/rb_heap
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14.1
+signing_key: 
+specification_version: 4
+summary: Light-weight priority queue implementation using a heap
+test_files: []