pqueue 1.0.0

data/HISTORY

@@ -0,0 +1,11 @@
+= CHANGE HISTORY
+
+== 1.0.0 / 2009-07-05
+
+This is the initial standalone release of PQueue,
+spun-off from the Ruby Facets.
+
+* 1 Major Enhancement
+
+    * Happy Birthday!
+

data/LICENSE

@@ -0,0 +1,167 @@
+
+= GNU LESSER GENERAL PUBLIC LICENSE
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+== 0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+"The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+== 1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+== 2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+a) under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+b) under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+== 3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+a) Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+== 4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+a) Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+c) For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+d) Do one of the following:
+
+d.0) Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+
+d.1) Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that (a) uses at run time
+a copy of the Library already present on the user's computer
+system, and (b) will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version.
+
+e) Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option 4d0, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option 4d1, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+== 5. Combined Libraries.
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+a) Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+
+b) Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+== 6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+

data/MANIFEST

@@ -0,0 +1,21 @@
+test
+test/test_pqueue.rb
+RELEASE
+LICENSE
+README
+HISTORY
+meta
+meta/created
+meta/repository
+meta/homepage
+meta/summary
+meta/abstract
+meta/package
+meta/title
+meta/released
+meta/version
+meta/license
+meta/authors
+meta/project
+lib
+lib/pqueue.rb

data/README

@@ -0,0 +1,44 @@
+= PQueue
+
+* http://death.rubyforge.org
+* http://death.rubyforge.org/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 repect to their #> method.
+For example, Numeric elements with higher values will have higher
+priorities.
+
+This library is based off the original PQueue.rb by K.Kodama and
+Heap.rb by Ronald Butler. It was later improved by  Olivier Renaud.
+
+
+== SYNOPSIS
+
+  ... to be done ...
+
+
+== INSTALLATION
+
+  $ gem install pqueue
+
+
+== COPYING
+
+Copyright (c) 2009 The Coding Dead
+Copyright (c) 2006 Olivier Renaud
+Copyright (c) 2005 K.Kodama, Ronald Butler
+
+This software is distributed under the terms of the LGPL v3 license.
+
+See LICENSE file for details.
+

data/RELEASE

@@ -0,0 +1,10 @@
+= RELEASE NOTES
+
+This is the initial standalone release of PQueue,
+spun-off from the Ruby Facets.
+
+### 1.0.0 / 2009-07-05
+
+* 1 Major Enhancement
+
+    * Happy Birthday!

data/lib/pqueue.rb

@@ -0,0 +1,269 @@
+# 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 repect to their #> method.
+# For example, Numeric elements with higher values will have higher
+# priorities.
+#
+class PQueue
+
+  # number of elements
+  attr_reader :size
+  # compare Proc
+  attr_reader :gt
+  attr_reader :qarray #:nodoc:
+  protected :qarray
+
+  # 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.
+  #
+  # By default, the priority queue retrieves maximum elements first
+  # (using the #> method).
+  def initialize(elements=nil, &block) # :yields: a, b
+    @qarray = [nil]
+    @size = 0
+    @gt = block || lambda {|a,b| a > b}
+    replace(elements) if elements
+  end
+
+  private
+
+  # 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
+
+  # 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
+
+
+  # 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
+  end
+
+  public
+
+  # 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
+  end
+
+  alias :<< :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
+  # time.
+  #
+  # The deletion time is O(log n), with n 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
+  end
+
+  # Return the element with the highest priority.
+  def top
+    return nil if empty?
+    return @qarray[1]
+  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)
+    if empty?
+      if elements.kind_of?(PQueue)
+        initialize_copy(elements)
+      else
+        replace(elements)
+      end
+    else
+      if elements.kind_of?(PQueue)
+        @qarray[@size + 1, elements.size] = elements.qarray[1..-1]
+        elements.size.times{ @size += 1; upheap(@size)}
+      else
+        ary = elements.to_a
+        @qarray[@size + 1, ary.size] = ary
+        ary.size.times{ @size += 1; upheap(@size)}
+      end
+    end
+    return self
+  end
+
+  alias :merge :push_all
+
+
+  # Return top n-element as a sorted array.
+  def pop_array(n=@size)
+    ary = []
+    n.times{ary.push(pop)}
+    return ary
+  end
+
+
+  # True if there is no more elements left in the priority queue.
+  def empty?
+    return @size.zero?
+  end
+
+  # Remove all elements from the priority queue.
+  def clear
+    @qarray.replace([nil])
+    @size = 0
+    return 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.
+  def replace(elements)
+    if elements.kind_of?(PQueue)
+      initialize_copy(elements)
+    else
+      @qarray.replace([nil] + elements.to_a)
+      @size = @qarray.size - 1
+      heapify
+    end
+    return 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
+  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)
+  end
+
+  # Iterate over the ordered elements, destructively.
+  def each_pop #:yields: popped
+    until empty?
+      yield pop
+    end
+    return nil
+  end
+
+  # Pretty print
+  def inspect
+    "<#{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
+  end
+
+  private
+
+  def initialize_copy(other)
+    @gt = other.gt
+    @qarray = other.qarray.dup
+    @size = other.size
+  end
+end # class PQueue
+

data/meta/abstract

@@ -0,0 +1,4 @@
+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.

data/meta/authors

@@ -0,0 +1,6 @@
+K.Kodama
+Ronald Butler
+Olivier Renaud
+Rick Bradley
+Trans <transfire@gmail.com>
+

data/meta/created

@@ -0,0 +1 @@
+2005-01-01

data/meta/homepage

@@ -0,0 +1 @@
+http://death.rubyforge.org/

data/meta/license

@@ -0,0 +1 @@
+LGPLv3

data/meta/package

@@ -0,0 +1 @@
+pqueue

data/meta/project

@@ -0,0 +1 @@
+death

data/meta/released

@@ -0,0 +1 @@
+2009-07-05

data/meta/repository

@@ -0,0 +1 @@
+svn://rubyforge.org/var/svn/death/pqueue

data/meta/summary

@@ -0,0 +1 @@
+Queue with prioritized elements.

data/meta/title

@@ -0,0 +1 @@
+PQueue

data/meta/version

@@ -0,0 +1 @@
+1.0.0

data/test/test_pqueue.rb

@@ -0,0 +1,139 @@
+require 'pqueue'
+require 'test/unit'
+
+class TC_PQueue < Test::Unit::TestCase
+  ARY_TEST = [2,6,1,3,8,15,0,-4,7,8,10]
+  ARY_TEST_2 = [25,10,5,13,16,9,16,12]
+
+  def test_initialize
+    assert_nothing_raised { PQueue.new }
+    assert_nothing_raised { PQueue.new([3]) }
+    assert_nothing_raised { PQueue.new(ARY_TEST) }
+    assert_nothing_raised { PQueue.new {|a,b| a<b} }
+    assert_nothing_raised { PQueue.new([3]) {|a,b| a<b} }
+    assert_nothing_raised { PQueue.new(ARY_TEST) {|a,b| a<b} }
+  end
+
+  def test_top
+    assert_equal(ARY_TEST.max, PQueue.new(ARY_TEST).top)
+    assert_nil(PQueue.new.top)
+  end
+
+  def test_pop
+    sorted_ary = ARY_TEST.sort
+    q = PQueue.new(ARY_TEST)
+    ARY_TEST.size.times do
+      assert_equal(sorted_ary.pop, q.pop)
+    end
+    assert_equal(0, q.size)
+    assert_nil(PQueue.new.pop)
+  end
+
+  def test_insertion
+    q = PQueue.new(ARY_TEST)
+    assert_equal(ARY_TEST.size, q.size)
+
+    ret = q.push(24)
+    assert_equal(q, ret)
+    assert_equal(ARY_TEST.size+1, q.size)
+
+    ret = q.push_all(ARY_TEST_2)
+    assert_equal(q, ret)
+    assert_equal(ARY_TEST.size+1+ARY_TEST_2.size, q.size)
+
+    q = PQueue.new(ARY_TEST)
+    r = PQueue.new(ARY_TEST_2)
+    q.push_all(r)
+    assert_equal(ARY_TEST.size + ARY_TEST_2.size, q.size)
+  end
+
+  def test_clear
+    q = PQueue.new(ARY_TEST).clear
+    assert_equal(q, q.clear)
+    assert_equal(0, q.size)
+  end
+
+  def test_replace
+    q = PQueue.new(ARY_TEST)
+    q.replace(ARY_TEST_2)
+    assert_equal(ARY_TEST_2.size, q.size)
+
+    q = PQueue.new(ARY_TEST)
+    q.replace(PQueue.new(ARY_TEST_2))
+    assert_equal(ARY_TEST_2.size, q.size)
+  end
+
+  def test_inspect
+    assert_equal("<PQueue: size=#{ARY_TEST.size}, top=#{ARY_TEST.max}>",
+                 PQueue.new(ARY_TEST).inspect)
+  end
+
+  def test_to_a
+    q = PQueue.new(ARY_TEST)
+    assert_equal(ARY_TEST.sort.reverse, q.sort)
+    q = PQueue.new(0..4)
+    assert_equal([4,3,2,1,0], q.sort)
+  end
+
+  def pop_array
+    q = PQueue.new(ARY_TEST)
+    assert_equal(ARY_TEST.sort.reverse[0..5], q.pop_array(5))
+    q = PQueue.new(ARY_TEST)
+    assert_equal(ARY_TEST.sort.reverse, q.pop_array)
+  end
+
+  def test_include
+    q = PQueue.new(ARY_TEST + [21] + ARY_TEST_2)
+    assert_equal(true, q.include?(21))
+
+    q = PQueue.new(ARY_TEST - [15])
+    assert_equal(false, q.include?(15))
+  end
+
+  def test_assert_equal
+    assert_equal(PQueue.new, PQueue.new)
+    assert_equal(PQueue.new(ARY_TEST), PQueue.new(ARY_TEST.sort_by{rand}))
+  end
+
+  def test_replace_top
+    q = PQueue.new
+    assert_nil(q.replace_top(6))
+    assert_equal(6, q.top)
+
+    q = PQueue.new(ARY_TEST)
+    h = PQueue.new(ARY_TEST)
+    q.pop; q.push(11)
+    h.replace_top(11)
+    assert_equal(q, h)
+  end
+
+  def test_dup
+    q = PQueue.new(ARY_TEST)
+    assert_equal(q, q.dup)
+  end
+
+  def test_array_copied
+    ary = ARY_TEST.dup
+    q = PQueue.new(ary)
+    q.pop
+    assert_equal(ARY_TEST, ary)
+
+    ary = ARY_TEST.dup
+    q = PQueue.new
+    q.replace(ary)
+    q.pop
+    assert_equal(ARY_TEST, ary)
+
+    ary = ARY_TEST.dup
+    q = PQueue.new([1])
+    q.push_all(ary)
+    q.pop
+    assert_equal(ARY_TEST, ary)
+
+    q = PQueue.new(ARY_TEST)
+    r = q.dup
+    q.pop
+    assert_not_equal(q, r)
+  end
+end
+

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: pqueue
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- K.Kodama
+- Ronald Butler
+- Olivier Renaud
+- Rick Bradley
+- Trans <transfire@gmail.com>
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-05 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+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.
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- MANIFEST
+- RELEASE
+- LICENSE
+- HISTORY
+files: 
+- test/test_pqueue.rb
+- RELEASE
+- LICENSE
+- README
+- HISTORY
+- meta/created
+- meta/repository
+- meta/homepage
+- meta/summary
+- meta/abstract
+- meta/package
+- meta/title
+- meta/released
+- meta/version
+- meta/license
+- meta/authors
+- meta/project
+- lib/pqueue.rb
+- MANIFEST
+has_rdoc: true
+homepage: http://death.rubyforge.org/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --title
+- pqueue api
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: death
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: A priority queue is like a standard queue, except that each inserted
+test_files: 
+- test/test_pqueue.rb