pqueue 1.0.0 → 2.0.0

data/.ruby

@@ -0,0 +1,58 @@
+---
+source:
+- meta
+authors:
+- name: K. Kodama
+- name: Ronald Butler
+- name: Olivier Renaud
+- name: Rick Bradley
+- name: Thomas Sawyer
+  email: transfire@gmail.com
+copyrights:
+- holder: K. Kodama
+  year: '2001'
+replacements: []
+alternatives: []
+requirements:
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: microtest
+  groups:
+  - test
+  development: true
+- name: ae
+  groups:
+  - test
+  development: true
+dependencies: []
+conflicts: []
+repositories:
+- uri: git://github.com/rubyworks/pqueue.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubyworks.github.com/pqueue
+  code: http://github.com/rubyworks/pqueue
+  mail: http://groups.google.com/group/rubyworks-mailinglist
+  bugs: http://github.com/rubyworks/pqueue/issues
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2001-03-10'
+summary: Queue of Prioritized Elements
+title: PQueue
+version: 2.0.0
+name: pqueue
+description: ! 'A priority queue is like a standard queue, except that each inserted
+  elements
+
+  is given a certain priority, based on the result of the comparison block given
+
+  at instantiation time. Retrieving an element from the queue will always return
+
+  the one with the highest priority.'
+organization: rubyworks
+date: '2011-10-29'

data/COPYING.rdoc

@@ -0,0 +1,31 @@
+= COPYRIGHT NOTICES
+
+== PQueue
+
+Copyright:: (c) 2011 Rubyworks
+License:: BSD-2-Clause
+Website:: http://rubyworks.github.com/pqueue
+
+    Copyright 2011 Rubyworks. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+       1. Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+       2. Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+    AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+    OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/HISTORY.rdoc

@@ -0,0 +1,28 @@
+= CHANGE HISTORY
+
+== 2.0.0 / 2011-10-29
+
+This is a complete rewrite to simplify the design and use more
+of Ruby's internal methods.  Overall performance should be markedly
+improved. A few method names have changed to be more consistent with
+Ruby's other data structure. Note that the internal heap is now in reverse
+order from the previous version. If using #to_a be aware that the priority
+order will be reversed. This release also switches the library to 
+distribution under the BSD-2-Clause license.
+
+Changes:
+
+* Rewrite library.
+* Modernize build configuration.
+* Switch to BSD-2-Clause license.
+
+
+== 1.0.0 / 2009-07-05
+
+This is the initial standalone release of PQueue, spun-off from the
+Ruby Facets and originally written by K. Komada.
+
+Changes:
+
+* Happy New Birthday!
+

data/README.rdoc

@@ -0,0 +1,57 @@
+= PQueue
+
+{Home}[http://rubyworks.github.com/pqueue] |
+{Code}[http://github.com/rubyworks/pqueue] |
+{Docs}[http://rubydoc.info/gems/pqueue/frames] |
+{Mail}[http://groups.google.com/group/rubyworks] | #rubyworks
+
+{<img src="http://travis-ci.org/rubyworks/pqueue.png" />}[http://travis-ci.org/rubyworks/pqueue]
+
+== DESCRIPTION
+
+Priority queue with array based heap.
+
+A priority queue is like a standard queue, except that each inserted
+elements is given a certain priority, based on the result of the
+comparison block given at instantiation time. Also, retrieving an element
+from the queue will always return the one with the highest priority
+(see #pop and #top).
+
+The default is to compare the elements in respect to their #<=> method.
+For example, Numeric elements with higher values will have higher
+priorities.
+
+This library is  a rewrite of the original PQueue.rb by K. Kodama and
+Heap.rb by Ronald Butler. The two libraries were later merged
+and generally improved by Olivier Renaud. Then the whole library 
+rewritten by Trans using the original as a functional reference.
+
+
+== SYNOPSIS
+
+  require 'pqueue'
+
+  pq = PQueue.new([2,3,1]){ |a,b| a > b }
+
+  pq.pop  #=> 3
+
+
+== ACKNOWLEDGMENTS
+
+Although the library has been completely rewritten since, we still would
+like to acknowledge the efforts of the original PQueue authors and
+contributors.
+
+* Olivier Renaud (2007)
+* Rick Bradley (2003)
+* Ronald Butler (2002)
+* K Kodama (2001, original library)
+
+
+== COPYRIGHTS
+
+Copyright (c) 2011 Rubyworks
+
+PQueue is distributable in accordance with the *FreeBSD* license.
+
+See the COPYING.rdoc file for details.

data/lib/pqueue.rb

@@ -6,147 +6,128 @@
 # from the queue will always return the one with the highest priority
 # (see #pop and #top).
 #
-# The default is to compare the elements in repect to their #> method.
+# The default is to compare the elements in repect to their #<=> method.
 # For example, Numeric elements with higher values will have higher
 # priorities.
 #
+# Note that as of version 2.0 the internal queue is kept in the reverse order
+# from how it was kept in previous version. If you had used #to_a in the
+# past then be sure to adjust for the priorities to be ordered back-to-front
+# instead of the oterh way around.
+#
 class PQueue
 
-  # number of elements
-  attr_reader :size
-  # compare Proc
-  attr_reader :gt
-  attr_reader :qarray #:nodoc:
-  protected :qarray
+  #
+  VERSION = "2.0.0"  #:erb: VERSION = "<%= version %>"
 
+  #
   # Returns a new priority queue.
   #
   # If elements are given, build the priority queue with these initial
   # values. The elements object must respond to #to_a.
   #
   # If a block is given, it will be used to determine the priority between
-  # the elements.
+  # the elements. The block must must take two arguments and return `1`, `0`,
+  # or `-1` or `true`, `nil` or `false. It should return `0` or `nil` if the
+  # two arguments are considered equal, return `1` or `true` if the first
+  # argument is considered greater than the later, and `-1` or `false` if
+  # the later is considred to be greater than the first.
   #
   # By default, the priority queue retrieves maximum elements first
-  # (using the #> method).
+  # using the #<=> method.
+  #
   def initialize(elements=nil, &block) # :yields: a, b
-    @qarray = [nil]
-    @size = 0
-    @gt = block || lambda {|a,b| a > b}
+    @que = []
+    @cmp = block || lambda{ |a,b| a <=> b }
     replace(elements) if elements
   end
 
-  private
+ protected
 
-  # Assumes that the tree is a heap, for nodes < k.
   #
-  # The element at index k will go up until it finds its place.
-  def upheap(k)
-    k2 = k.div(2)
-    v = @qarray[k]
-    while k2 > 0 && @gt[v, @qarray[k2]]
-      @qarray[k] = @qarray[k2]
-      k = k2
-      k2 = k2.div(2)
-    end
-    @qarray[k] = v
-  end
+  # The underlying heap.
+  #
+  attr_reader :que #:nodoc:
 
-  # Assumes the entire tree is a heap.
-  #
-  # The element at index k will go down until it finds its place.
-  def downheap(k)
-    v = @qarray[k]
-    q2 = @size.div(2)
-    loop {
-      break if k > q2
-      j = 2 * k
-      if j < @size && @gt[@qarray[j+1], @qarray[j]]
-        j += 1
-      end
-      break if @gt[v, @qarray[j]]
-      @qarray[k] = @qarray[j]
-      k = j
-    }
-    @qarray[k] = v;
-  end
+ public
 
+  #
+  # Priority comparison procedure.
+  #
+  attr_reader :cmp
 
-  # Recursive version of heapify. I kept the code, since it may be
-  # easier to understand than the non-recursive one.
-  #  def heapify
-  #    @size.div(2).downto(1) {|i| h(i)}
-  #  end
-  #  def h(t)
-  #    l = 2 * t
-  #    r = l + 1
-  #    hi = if r > @size || @gt[@qarray[l],@qarray[r]] then l else r end
-  #    if @gt[@qarray[hi],@qarray[t]]
-  #      @qarray[hi], @qarray[t] = @qarray[t], @qarray[hi]
-  #      h(hi) if hi <= @size.div(2)
-  #    end
-  #  end
-
-  # Make a heap out of an unordered array.
-  def heapify
-    @size.div(2).downto(1) do |t|
-      begin
-        l = 2 * t
-        r = l + 1
-        hi = if r > @size || @gt[@qarray[l],@qarray[r]] then l else r end
-        if @gt[@qarray[hi],@qarray[t]]
-          @qarray[hi], @qarray[t] = @qarray[t], @qarray[hi]
-          if hi <= @size.div(2)
-            t = hi
-            redo
-          end # if
-        end #if
-      end #begin
-    end # downto
+  #
+  # Returns the size of the queue.
+  #
+  def size
+    @que.size
   end
 
-  public
+  #
+  # Alias of size.
+  #
+  alias length size
 
+  #
   # Add an element in the priority queue.
   #
-  # The insertion time is O(log n), with n the size of the queue.
   def push(v)
-    @size += 1
-    @qarray[@size] = v
-    upheap(@size)
-    return self
+    @que << v
+    reheap(@que.size-1)
+    self
   end
 
+  #
+  # Alias of #push.
+  #
   alias :<< :push
 
+  #
+  # Alias of #push.
+  #
+  alias enq push
+
+  #
   # Return the element with the highest priority and remove it from
   # the queue.
   #
-  # The highest priority is determined by the block given at instanciation
+  # The highest priority is determined by the block given at instantiation
   # time.
   #
-  # The deletion time is O(log n), with n the size of the queue.
+  # The deletion time is O(log n), with n is the size of the queue.
   #
   # Return nil if the queue is empty.
+  #
   def pop
     return nil if empty?
-    res = @qarray[1]
-    @qarray[1] = @qarray[@size]
-    @size -= 1
-    downheap(1)
-    return res
+    @que.pop
   end
 
-  # Return the element with the highest priority.
+  #
+  # Alias of #push.
+  #
+  alias shift push
+
+  #
+  # Alias of #pop.
+  #
+  alias deq push
+
+  #
+  # Returns the element with the highest priority, but
+  # does not remove it from the queue.
+  #
   def top
     return nil if empty?
-    return @qarray[1]
+    return @que.last
   end
 
+  #
   # Add more than one element at the same time. See #push.
   #
-  # The elements object must respond to #to_a, or to be a PQueue itself.
-  def push_all(elements)
+  # The elements object must respond to #to_a, or be a PQueue itself.
+  #
+  def concat(elements)
     if empty?
       if elements.kind_of?(PQueue)
         initialize_copy(elements)
@@ -155,115 +136,182 @@ class PQueue
       end
     else
       if elements.kind_of?(PQueue)
-        @qarray[@size + 1, elements.size] = elements.qarray[1..-1]
-        elements.size.times{ @size += 1; upheap(@size)}
+        @que.concat(elements.que)
+        sort!
       else
-        ary = elements.to_a
-        @qarray[@size + 1, ary.size] = ary
-        ary.size.times{ @size += 1; upheap(@size)}
+        @que.concat(elements.to_a)
+        sort!
       end
     end
     return self
   end
 
-  alias :merge :push_all
-
+  #
+  # Alias for #concat.
+  #
+  alias :merge! :concat
 
+  #
   # Return top n-element as a sorted array.
-  def pop_array(n=@size)
-    ary = []
-    n.times{ary.push(pop)}
-    return ary
+  #
+  def take(n=@size)
+    a = []
+    n.times{a.push(pop)}
+    a
   end
 
-
-  # True if there is no more elements left in the priority queue.
+  #
+  # Returns true if there is no more elements left in the queue.
+  #
   def empty?
-    return @size.zero?
+    @que.empty?
   end
 
+  #
   # Remove all elements from the priority queue.
+  #
   def clear
-    @qarray.replace([nil])
-    @size = 0
-    return self
+    @que.clear
+    self
   end
 
+  #
   # Replace the content of the heap by the new elements.
   #
-  # The elements object must respond to #to_a, or to be a PQueue itself.
+  # The elements object must respond to #to_a, or to be
+  # a PQueue itself.
+  #
   def replace(elements)
     if elements.kind_of?(PQueue)
       initialize_copy(elements)
     else
-      @qarray.replace([nil] + elements.to_a)
-      @size = @qarray.size - 1
-      heapify
+      @que.replace(elements.to_a)
+      sort!
     end
-    return self
+    self
   end
 
+  #
   # Return a sorted array, with highest priority first.
+  #
   def to_a
-    old_qarray = @qarray.dup
-    old_size = @size
-    res = pop_array
-    @qarray = old_qarray
-    @size = old_size
-    return res
+    @que.dup
   end
 
-  alias :sort :to_a
-
-  # Replace the top element with the given one, and return this top element.
   #
-  # Equivalent to successively calling #pop and #push(v).
-  def replace_top(v)
-    # replace top element
-    if empty?
-      @qarray[1] = v
-      @size += 1
-      return nil
-    else
-      res = @qarray[1]
-      @qarray[1] = v
-      downheap(1)
-      return res
-    end
-  end
-
   # Return true if the given object is present in the queue.
+  #
   def include?(element)
-    return @qarray.include?(element)
+    @que.include?(element)
+  end
+
+  #
+  # Push element onto queue while popping off and returning the next element.
+  # This is qquivalent to successively calling #pop and #push(v).
+  #
+  def swap(v)
+    r = pop
+    push(v)
+    r
   end
 
+  #
   # Iterate over the ordered elements, destructively.
+  #
   def each_pop #:yields: popped
     until empty?
       yield pop
     end
-    return nil
+    nil
   end
 
-  # Pretty print
+  #
+  # Pretty inspection string.
+  #
   def inspect
-    "<#{self.class}: size=#{@size}, top=#{top || "nil"}>"
+    "<#{self.class}: size=#{size}, top=#{top || "nil"}>"
   end
 
-  ###########################
-  ### Override Object methods
-
+  #
   # Return true if the queues contain equal elements.
+  #
   def ==(other)
-    return size == other.size && to_a == other.to_a
+    size == other.size && to_a == other.to_a
   end
 
-  private
+ private
 
+  #
+  #
+  #
   def initialize_copy(other)
-    @gt = other.gt
-    @qarray = other.qarray.dup
-    @size = other.size
+    @cmp  = other.cmp
+    @que  = other.que.dup
+    sort!
   end
-end # class PQueue
 
+  #
+  # The element at index k will be repositioned to its proper place.
+  #
+  # This, of course, assumes the queue is already sorted.
+  #
+  def reheap(k)
+    return self if size <= 1
+
+    que = @que.dup
+
+    v = que.delete_at(k)
+
+    i = que.size.div(2)
+    q = i
+    r = nil
+
+    loop do
+      case @cmp.call(v, que[i])
+      when 0, nil
+        r = i
+        break
+      when 1, true
+        i = (que.size + i).div(2)
+        i += 1 if i == q  # don't repeat yourself
+      when -1, false
+        i = (i).div(2)
+        i -= 1 if i == q  # don't repeat yourself
+      else
+        warn "bad comparison procedure in #{self.inspect}"
+        r = i
+        break
+      end
+      q = i
+    end
+
+    que.insert(r, v)
+
+    @que = que
+
+    return self
+  end
+
+  #
+  # Sort the queue in accorance to the given comparison procedure.
+  #
+  def sort!
+    @que.sort! do |a,b|
+      case @cmp.call(a,b)
+      when  0, nil   then  0
+      when  1, true  then  1
+      when -1, false then -1
+      else
+        warn "bad comparison procedure in #{self.inspect}"
+        0
+      end
+    end
+    self
+  end
+
+  #
+  # Alias of #sort!
+  #
+  alias heapify sort!
+
+end # class PQueue