amorim-algorithms 0.6.1

data/lib/containers/kd_tree.rb

@@ -0,0 +1,110 @@
+=begin rdoc
+
+    A kd-tree is a binary tree that allows one to store points (of any space dimension: 2D, 3D, etc). 
+    The structure of the resulting tree makes it so that large portions of the tree are pruned
+    during queries.
+    
+    One very good use of the tree is to allow nearest neighbor searching. Let's say you have a number
+    of points in 2D space, and you want to find the nearest 2 points from a specific point:
+    
+    First, put the points into the tree:
+    
+      kdtree = Containers::KDTree.new( {0 => [4, 3], 1 => [3, 4], 2 => [-1, 2], 3 => [6, 4],
+                                       4 => [3, -5], 5 => [-2, -5] })
+    
+    Then, query on the tree:
+    
+      puts kd.find_nearest([0, 0], 2) => [[5, 2], [9, 1]]
+      
+    The result is an array of [distance, id] pairs. There seems to be a bug in this version.
+      
+    Note that the point queried on does not have to exist in the tree. However, if it does exist,
+    it will be returned.
+
+=end
+
+class Containers::KDTree
+  Node = Struct.new(:id, :coords, :left, :right)
+  
+  # Points is a hash of id => [coord, coord] pairs.
+  def initialize(points)
+    raise "must pass in a hash" unless points.kind_of?(Hash)
+    @dimensions = points[ points.keys.first ].size
+    @root = build_tree(points.to_a)
+    @nearest = []
+  end
+  
+  # Find k closest points to given coordinates 
+  def find_nearest(target, k_nearest)
+    @nearest = []
+    nearest(@root, target, k_nearest, 0)
+  end
+  
+  # points is an array
+  def build_tree(points, depth=0)
+    return if points.empty?
+    
+    axis = depth % @dimensions
+    
+    points.sort! { |a, b| a.last[axis] <=> b.last[axis] }
+    median = points.size / 2
+    
+    node = Node.new(points[median].first, points[median].last, nil, nil)
+    node.left = build_tree(points[0...median], depth+1)
+    node.right = build_tree(points[median+1..-1], depth+1)
+    node
+  end
+  private :build_tree
+
+  # Euclidian distanced, squared, between a node and target coords
+  def distance2(node, target)
+    return nil if node.nil? or target.nil?
+    c = (node.coords[0] - target[0])
+    d = (node.coords[1] - target[1])
+    c * c + d * d
+  end
+  private :distance2
+
+  # Update array of nearest elements if necessary
+  def check_nearest(nearest, node, target, k_nearest)
+    d = distance2(node, target) 
+    if nearest.size < k_nearest || d < nearest.last[0]
+      nearest.pop if nearest.size >= k_nearest
+      nearest << [d, node.id]
+      nearest.sort! { |a, b| a[0] <=> b[0] }
+    end
+    nearest
+  end
+  private :check_nearest
+  
+  # Recursively find nearest coordinates, going down the appropriate branch as needed
+  def nearest(node, target, k_nearest, depth)
+    axis = depth % @dimensions
+  
+    if node.left.nil? && node.right.nil? # Leaf node
+      @nearest = check_nearest(@nearest, node, target, k_nearest)
+      return
+    end
+  
+    # Go down the nearest split
+    if node.right.nil? || (node.left && target[axis] <= node.coords[axis])
+      nearer = node.left
+      further = node.right
+    else
+      nearer = node.right
+      further = node.left
+    end
+    nearest(nearer, target, k_nearest, depth+1)
+  
+    # See if we have to check other side
+    if further
+      if @nearest.size < k_nearest || (target[axis] - node.coords[axis])**2 < @nearest.last[0]
+        nearest(further, target, k_nearest, depth+1)
+      end
+    end
+  
+    @nearest = check_nearest(@nearest, node, target, k_nearest)
+  end
+  private :nearest
+  
+end

data/lib/containers/priority_queue.rb

@@ -0,0 +1,113 @@
+require 'containers/heap'
+
+=begin rdoc
+    A Priority Queue is a data structure that behaves like a queue except that elements have an
+    associated priority. The #next and #pop methods return the item with the next highest priority.
+    
+    Priority Queues are often used in graph problems, such as Dijkstra's Algorithm for shortest
+    path, and the A* search algorithm for shortest path.
+    
+    This container is implemented using the Fibonacci heap included in the Collections library.
+=end
+class Containers::PriorityQueue
+  include Enumerable
+  
+  # Create a new, empty PriorityQueue
+  def initialize(&block)
+    # We default to a priority queue that returns the largest value
+    block ||= lambda { |x, y| (x <=> y) == 1 }
+    @heap = Containers::Heap.new(&block)
+  end
+  
+  # Returns the number of elements in the queue.
+  # 
+  #    q = Containers::PriorityQueue.new
+  #    q.size #=> 0
+  #    q.push("Alaska", 1)
+  #    q.size #=> 1
+  def size
+    @heap.size
+  end
+  alias_method :length, :size
+
+  # Add an object to the queue with associated priority.
+  # 
+  #   q = Containers::PriorityQueue.new
+  #   q.push("Alaska", 1)
+  #   q.pop #=> "Alaska"
+  def push(object, priority)    
+    @heap.push(priority, object)
+  end
+  
+  # Clears all the items in the queue.
+  def clear
+    @heap.clear
+  end
+  
+  # Returns true if the queue is empty, false otherwise.
+  def empty?
+    @heap.empty?
+  end
+
+  # call-seq:
+  #     has_priority? priority -> boolean
+  #     
+  # Return true if the priority is in the queue, false otherwise.
+  #
+  #     q = PriorityQueue.new
+  #     q.push("Alaska", 1)
+  #
+  #     q.has_priority?(1)    #=> true 
+  #     q.has_priority?(2)    #=> false
+  def has_priority?(priority)
+    @heap.has_key?(priority)
+  end
+  
+  # call-seq:
+  #     next -> object
+  #
+  # Return the object with the next highest priority, but does not remove it
+  #
+  #     q = Containers::PriorityQueue.new
+  #     q.push("Alaska", 50)
+  #     q.push("Delaware", 30)
+  #     q.push("Georgia", 35)
+  #     q.next          #=> "Alaska"
+  def next
+    @heap.next
+  end
+  
+  # call-seq:
+  #     pop -> object
+  #
+  # Return the object with the next highest priority and removes it from the queue
+  #
+  #     q = Containers::PriorityQueue.new
+  #     q.push("Alaska", 50)
+  #     q.push("Delaware", 30)
+  #     q.push("Georgia", 35)
+  #     q.pop         #=> "Alaska"
+  #     q.size        #=> 2
+  def pop
+    @heap.pop
+  end
+  alias_method :next!, :pop
+
+  # call-seq:
+  #     delete(priority) -> object
+  #     delete(priority) -> nil
+  #
+  # Delete an object with specified priority from the queue. If there are duplicates, an
+  # arbitrary object with that priority is deleted and returned. Returns nil if there are 
+  # no objects with the priority.
+  #
+  #     q = PriorityQueue.new
+  #     q.push("Alaska", 50)
+  #     q.push("Delaware", 30)
+  #     q.delete(50)            #=> "Alaska"
+  #     q.delete(10)            #=> nil
+  def delete(priority)
+    @heap.delete(priority)
+  end
+
+end

data/lib/containers/queue.rb

@@ -0,0 +1,68 @@
+require 'containers/deque'
+
+=begin rdoc
+    A Queue is a container that keeps elements in a first-in first-out (FIFO) order. Because of its
+    properties, it is often used as a buffer.
+    
+    This implementation uses a doubly-linked list, guaranteeing O(1) complexity for all operations.
+    
+=end
+class Containers::Queue
+  include Enumerable
+  # Create a new queue. Takes an optional array argument to initialize the queue.
+  #
+  #   q = Containers::Queue.new([1, 2, 3])
+  #   q.pop #=> 1
+  #   q.pop #=> 2
+  def initialize(ary=[])
+    @container = Containers::Deque.new(ary)
+  end
+   
+  # Returns the next item from the queue but does not remove it.
+  #
+  #   q = Containers::Queue.new([1, 2, 3])
+  #   q.next #=> 1
+  #   q.size #=> 3
+  def next
+    @container.front
+  end
+      
+  # Adds an item to the queue.
+  #
+  #   q = Containers::Queue.new([1])
+  #   q.push(2)
+  #   q.pop #=> 1
+  #   q.pop #=> 2
+  def push(obj)
+    @container.push_back(obj)
+  end
+  alias_method :<<, :push
+  
+  # Removes the next item from the queue and returns it.
+  #
+  #   q = Containers::Queue.new([1, 2, 3])
+  #   q.pop #=> 1
+  #   q.size #=> 2
+  def pop
+    @container.pop_front
+  end
+  
+  # Return the number of items in the queue.
+  #
+  #   q = Containers::Queue.new([1, 2, 3])
+  #   q.size #=> 3
+  def size
+    @container.size
+  end
+  
+  # Returns true if the queue is empty, false otherwise.
+  def empty?
+    @container.empty?
+  end
+  
+  # Iterate over the Queue in FIFO order.
+  def each(&block)
+    @container.each_forward(&block)
+  end
+
+end

data/lib/containers/rb_tree_map.rb

@@ -0,0 +1,398 @@
+require 'containers/stack'
+=begin rdoc
+    A RBTreeMap is a map that is stored in sorted order based on the order of its keys. This ordering is
+    determined by applying the function <=> to compare the keys. No duplicate values for keys are allowed,
+    so duplicate values are overwritten.
+    
+    A major advantage of RBTreeMap over a Hash is the fact that keys are stored in order and can thus be
+    iterated over in order. This is useful for many datasets.
+    
+    The implementation is adapted from Robert Sedgewick's Left Leaning Red-Black Tree implementation,
+    which can be found at http://www.cs.princeton.edu/~rs/talks/LLRB/Java/RedBlackBST.java
+    
+    Containers::RBTreeMap automatically uses the faster C implementation if it was built 
+    when the gem was installed. Alternatively, Containers::RubyRBTreeMap and Containers::CRBTreeMap can be 
+    explicitly used as well; their functionality is identical.
+    
+    Most methods have O(log n) complexity.
+    
+=end
+class Containers::RubyRBTreeMap
+  include Enumerable
+  
+  attr_accessor :height_black
+  
+  # Create and initialize a new empty TreeMap.
+  def initialize
+    @root = nil
+    @height_black = 0
+  end
+  
+  # Insert an item with an associated key into the TreeMap, and returns the item inserted
+  #
+  # Complexity: O(log n)
+  #
+  # map = Containers::TreeMap.new
+  # map.push("MA", "Massachusetts") #=> "Massachusetts"
+  # map.get("MA") #=> "Massachusetts"
+  def push(key, value)
+    @root = insert(@root, key, value)
+    @height_black += 1 if isred(@root)
+    @root.color = :black
+    value
+  end
+  alias_method :[]=, :push
+  
+  # Return the number of items in the TreeMap.
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.size #=> 2
+  def size
+    @root and @root.size or 0
+  end
+  
+  # Return the height of the tree structure in the TreeMap.
+  #
+  # Complexity: O(1)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.height #=> 2
+  def height
+    @root and @root.height or 0
+  end
+  
+  # Return true if key is found in the TreeMap, false otherwise
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.has_key?("GA") #=> true
+  #   map.has_key?("DE") #=> false
+  def has_key?(key)
+    !get(key).nil?
+  end
+  
+  # Return the item associated with the key, or nil if none found.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.get("GA") #=> "Georgia"
+  def get(key)
+    get_recursive(@root, key)
+  end
+  alias_method :[], :get
+  
+  # Return the smallest key in the map.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.min_key #=> "GA"
+  def min_key
+    @root.nil? ? nil : min_recursive(@root)
+  end
+  
+  # Return the largest key in the map.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.max_key #=> "MA"
+  def max_key
+    @root.nil? ? nil : max_recursive(@root)
+  end
+  
+  # Deletes the item and key if it's found, and returns the item. Returns nil
+  # if key is not present.
+  #
+  # !!! Warning !!! There is a currently a bug in the delete method that occurs rarely
+  # but often enough, especially in large datasets. It is currently under investigation.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.min_key #=> "GA"
+  def delete(key)
+    result = nil
+    if @root
+      @root, result = delete_recursive(@root, key)
+      @root.color = :black if @root
+    end
+    result
+  end
+  
+  # Returns true if the tree is empty, false otherwise
+  def empty?
+    @root.nil?
+  end
+  
+  # Deletes the item with the smallest key and returns the item. Returns nil
+  # if key is not present.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.delete_min #=> "Massachusetts"
+  #   map.size #=> 1
+  def delete_min
+    result = nil
+    if @root
+      @root, result = delete_min_recursive(@root)
+      @root.color = :black if @root
+    end
+    result
+  end
+  
+  # Deletes the item with the smallest key and returns the item. Returns nil
+  # if key is not present.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.delete_max #=> "Georgia"
+  #   map.size #=> 1
+  def delete_max
+    result = nil
+    if @root
+      @root, result = delete_max_recursive(@root)
+      @root.color = :black if @root
+    end
+    result
+  end
+  
+  # Iterates over the TreeMap from smallest to largest element. Iterative approach.
+  def each
+    return nil unless @root
+    stack = Containers::Stack.new
+    cursor = @root
+    loop do
+      if cursor
+        stack.push(cursor)
+        cursor = cursor.left
+      else
+        unless stack.empty?
+          cursor = stack.pop
+          yield(cursor.key, cursor.value)
+          cursor = cursor.right
+        else
+          break
+        end
+      end
+    end
+  end
+  
+  class Node # :nodoc: all
+    attr_accessor :color, :key, :value, :left, :right, :size, :height
+    def initialize(key, value)
+      @key = key
+      @value = value
+      @color = :red
+      @left = nil
+      @right = nil
+      @size = 1
+      @height = 1
+    end
+    
+    def red?
+      @color == :red
+    end
+    
+    def colorflip
+      @color       = @color == :red       ? :black : :red
+      @left.color  = @left.color == :red  ? :black : :red
+      @right.color = @right.color == :red ? :black : :red
+    end
+    
+    def update_size
+      @size = (@left ? @left.size : 0) + (@right ? @right.size : 0) + 1
+      left_height = (@left ? @left.height : 0)
+      right_height = (@right ? @right.height : 0)
+      if left_height > right_height
+        @height = left_height + 1
+      else
+        @height = right_height + 1
+      end
+      self
+    end
+    
+    def rotate_left
+      r = @right
+      r_key, r_value, r_color = r.key, r.value, r.color
+      b = r.left
+      r.left = @left
+      @left = r
+      @right = r.right
+      r.right = b
+      r.color, r.key, r.value = :red, @key, @value
+      @key, @value = r_key, r_value
+      r.update_size
+      update_size
+    end
+    
+    def rotate_right
+      l = @left
+      l_key, l_value, l_color = l.key, l.value, l.color
+      b = l.right
+      l.right = @right
+      @right = l
+      @left = l.left
+      l.left = b
+      l.color, l.key, l.value = :red, @key, @value
+      @key, @value = l_key, l_value
+      l.update_size
+      update_size
+    end
+    
+    def move_red_left
+      colorflip
+      if (@right.left && @right.left.red?)
+        @right.rotate_right
+        rotate_left
+        colorflip
+      end
+      self
+    end
+
+    def move_red_right
+      colorflip
+      if (@left.left && @left.left.red?)
+        rotate_right
+        colorflip
+      end
+      self
+    end
+    
+    def fixup
+      rotate_left if @right && @right.red?
+      rotate_right if (@left && @left.red?) && (@left.left && @left.left.red?)
+      colorflip if (@left && @left.red?) && (@right && @right.red?)
+
+      update_size
+    end
+  end
+
+  def delete_recursive(node, key)
+    if (key <=> node.key) == -1
+      node.move_red_left if ( !isred(node.left) && !isred(node.left.left) )
+      node.left, result = delete_recursive(node.left, key)
+    else
+      node.rotate_right if isred(node.left)
+      if ( ( (key <=> node.key) == 0) && node.right.nil? )
+        return nil, node.value
+      end
+      if ( !isred(node.right) && !isred(node.right.left) )
+        node.move_red_right
+      end
+      if (key <=> node.key) == 0
+        result = node.value
+        node.value = get_recursive(node.right, min_recursive(node.right))
+        node.key = min_recursive(node.right)
+        node.right = delete_min_recursive(node.right).first
+      else
+        node.right, result = delete_recursive(node.right, key)
+      end
+    end
+    return node.fixup, result
+  end
+  private :delete_recursive
+  
+  def delete_min_recursive(node)
+    if node.left.nil?
+      return nil, node.value 
+    end
+    if ( !isred(node.left) && !isred(node.left.left) )
+      node.move_red_left
+    end
+    node.left, result = delete_min_recursive(node.left)
+    
+    return node.fixup, result
+  end
+  private :delete_min_recursive
+  
+  def delete_max_recursive(node)
+    if (isred(node.left))
+      node = node.rotate_right
+    end
+    return nil, node.value if node.right.nil?
+    if ( !isred(node.right) && !isred(node.right.left) )
+      node.move_red_right
+    end
+    node.right, result = delete_max_recursive(node.right)
+    
+    return node.fixup, result
+  end
+  private :delete_max_recursive
+  
+  def get_recursive(node, key)
+    return nil if node.nil?
+    case key <=> node.key
+    when  0 then return node.value
+    when -1 then return get_recursive(node.left, key)
+    when  1 then return get_recursive(node.right, key)
+    end
+  end
+  private :get_recursive
+  
+  def min_recursive(node)
+    return node.key if node.left.nil?
+    
+    min_recursive(node.left)
+  end
+  private :min_recursive
+  
+  def max_recursive(node)
+    return node.key if node.right.nil?
+    
+    max_recursive(node.right)
+  end
+  private :max_recursive
+  
+  def insert(node, key, value)
+    return Node.new(key, value) unless node
+
+    case key <=> node.key
+    when  0 then node.value = value
+    when -1 then node.left = insert(node.left, key, value)
+    when  1 then node.right = insert(node.right, key, value)
+    end
+    
+    node.rotate_left if (node.right && node.right.red?)
+    node.rotate_right if (node.left && node.left.red? && node.left.left && node.left.left.red?)
+    node.colorflip if (node.left && node.left.red? && node.right && node.right.red?)
+    node.update_size
+  end
+  private :insert
+  
+  def isred(node)
+    return false if node.nil?
+    
+    node.color == :red
+  end
+  private :isred
+end
+
+begin
+  require 'CRBTreeMap'
+  Containers::RBTreeMap = Containers::CRBTreeMap
+rescue LoadError # C Version could not be found, try ruby version
+  Containers::RBTreeMap = Containers::RubyRBTreeMap
+end