binaryheap 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: af0658be36292995ead9ab8ce6e1e4c273b6d67c
+  data.tar.gz: 9cfc88a2bbee5c757c5e3265fb58726f41fd58dd
+SHA512:
+  metadata.gz: e0536e2fada1619d979f2c3219cc354be86417288bd6569dced4a165a7d314203a8f9e084bb1237c544724c86eaabdeae2b281dc3f469993ea65ba43d09785d2
+  data.tar.gz: 4d3493a8c5979764500405719ed51bc255cfc1027a99deebca2d673bd29e1bca04545e698a35d22d71580823f3c4cfdecbbbfdb18ea912182cc3e0b8de08540c

data/lib/binaryheap.rb

@@ -0,0 +1,178 @@
+require 'thread'
+
+# An implementation of standard binary heap data structure. 
+# Internally, it uses an array as data store and a mutex for thread synchronization (insert and eject operations)
+class BinaryHeap
+  class Error < RuntimeError
+  end
+
+  class HeapError < Error
+  	def mesage
+      "Heap Error: #{self.to_s}"
+  	end
+  end
+ 	
+  class ParameterError < Error
+  	def message
+  		"Parameter Error: #{self.to_s}"
+  	end
+  end
+ 	
+ 	# The constructor
+  # @param data [Array] the existent Array data on which the binary heap will be built
+  # @param block [Block] the comparator block, see examples.  
+  #   default comparator is lambda {|parent, child| parent <=> child} which makes it a max binary heap.
+  # @return [BinaryHeap] the Binary Heap instance
+ 	# @example A default max heap
+ 	#   bh = BinaryHeap.new
+ 	# @example A min heap
+ 	#   bh = BinaryHeap.new{|parent, child| child <=> parent}
+ 	# @example A max heap using self-defined comparator 
+ 	#   bh = BinaryHeap.new{|parent, child| parent.bigger_or_equal_than(child)}
+	def initialize(data=nil, &block)
+		@cmp = block || lambda{|parent, child| parent <=> child }
+		@mutex = Mutex.new
+
+		raise ParameterError.new("type of data must be Array or its subclass") unless data.nil? || data.is_a?(Array)
+		@ary = data.nil? ? [] : build_from(data)
+	end
+
+	# Insert an element into the heap (heap will be adjusted automatically)
+	# @param element [Object] the element to be inserted into the heap
+	# @return [BinaryHeap] the binary heap instance itself
+	def insert(element)
+		@mutex.synchronize do
+			@ary.push(element) 
+			adjust(:bottom_up)
+		end
+		self
+	end
+
+	alias :push :insert
+
+	# Eject the top(max or min) element of the heap (heap will be adjusted automatically)
+	# @return [Object] the ejected element
+	def eject
+		@mutex.synchronize do
+			return nil if @ary.empty?
+			e = @ary.first
+			@ary[0] = @ary.last
+			@ary.pop
+			adjust(:top_down)
+			e
+		end
+	end
+
+	# Return the the top(max or min) element of the heap
+	def top 
+		@ary.first
+	end
+
+	# Set the top element of the heap
+	# @param element [Object] 
+	# @note in most cases, this method should be used with the BinaryHeap#adjust method
+	# @see BinaryHeap#adjust
+	def top=(element)
+		@ary[0] = element
+	end
+
+	# Return the underlying Aarray data 
+	def data
+		@ary
+	end
+
+	# Adjust the heap to make it in good shape
+	# @param direction [Symbol] direction of adjustment, one of [:top_down, bottom_up]
+	# @return [BinaryHeap] the binay heap instance itself
+	# @note this method should be used carefully since it is not thread-safe, please check the implementation of BinaryHeap#eject and BinaryHeap#insert
+	def adjust(direction = :top_down)
+		return if @ary.size < 2
+		case direction
+			when :top_down
+				parent_idx = 0
+				until is_good?(parent_idx)
+					child_idx = target_child_idx(parent_idx)
+					swap(parent_idx, child_idx)
+					parent_idx = child_idx
+				end
+			when :bottom_up
+				child_idx = @ary.size - 1
+				parent_idx = p_idx(child_idx)
+				until child_idx == 0 || @cmp.call(@ary[parent_idx], @ary[child_idx]) >= 0
+				 	swap(parent_idx, child_idx)
+				 	child_idx = parent_idx
+				 	parent_idx = p_idx(child_idx)
+				end 
+			else
+				raise ParameterError.new("invalid direction type")
+		end
+		self
+	end
+
+	# Forward methods to underlying Array instance
+	def method_missing(name, *args, &blcok)
+		@ary.send(name, *args, &blcok)
+	end
+
+private
+	def build_from(data)
+		heap = BinaryHeap.new(&(@cmp))
+		data.each{|e| heap.insert e}
+		heap.data
+	end
+
+	def swap(i, j)
+		temp = @ary[i]
+		@ary[i] = @ary[j]
+		@ary[j] = temp
+	end
+
+	def p_idx(child_idx)
+		return nil if child_idx == 0
+		child_idx%2 == 0 ? (child_idx-2)/2 : child_idx/2 
+	end
+
+	def l_idx(parent_idx)
+		2*parent_idx + 1 
+	end
+
+	def r_idx(parent_idx)
+		2*parent_idx + 2
+	end
+
+	def lchid(parent_idx)
+		@ary[l_idx(parent_idx)]
+	end
+
+	def rchild(parent_idx)
+		@ary[r_idx(parent_idx)]
+	end
+
+	def is_good?(idx)
+		if !lchid(idx).nil?
+			return false unless @cmp.call(@ary[idx], lchid(idx)) >= 0 
+		end
+
+		if !rchild(idx).nil?
+			return false unless @cmp.call(@ary[idx], rchild(idx)) >= 0
+		end
+
+		true
+	end
+
+	# return the max/min child index
+	def target_child_idx(parent_idx)
+		return nil if lchid(parent_idx).nil? && rchild(parent_idx).nil?
+
+		l = lchid(parent_idx)
+		r = rchild(parent_idx)
+		l_idx = l_idx(parent_idx)
+		r_idx = r_idx(parent_idx)
+
+		return r_idx if l.nil?
+		return l_idx if r.nil?
+
+		return @cmp.call(l, r) >= 0 ? l_idx : r_idx
+	end
+
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: binaryheap
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Hailong Cao
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-04-05 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      A standard binary heap implementation in ruby.
+      Internally, it uses an array as data store and a mutex to keep insert and eject opeations thread-safe (both on CRuby and JRuby).
+email: hailengc@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/binaryheap.rb
+homepage: https://github.com/hailengc/binaryheap
+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.5.2
+signing_key: 
+specification_version: 4
+summary: binary heap implementation
+test_files: []