grosser-algorithms 0.4.0

data/lib/containers/kd_tree.rb

@@ -0,0 +1,113 @@
+=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 = Algorithms::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
+module Algorithms
+  module Containers
+    class 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
+  end
+end

data/lib/containers/priority_queue.rb

@@ -0,0 +1,117 @@
+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
+module Algorithms
+  module Containers
+    class 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 = Heap.new(&block)
+      end
+  
+      # Returns the number of elements in the queue.
+      # 
+      #    q = Algorithms::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 = Algorithms::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 = Algorithms::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 = Algorithms::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
+  end
+end

data/lib/containers/queue.rb

@@ -0,0 +1,72 @@
+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
+module Algorithms
+  module Containers
+    class Queue
+      include Enumerable
+      # Create a new queue. Takes an optional array argument to initialize the queue.
+      #
+      #   q = Algorithms::Containers::Queue.new([1, 2, 3])
+      #   q.pop #=> 1
+      #   q.pop #=> 2
+      def initialize(ary=[])
+        @container = Deque.new(ary)
+      end
+   
+      # Returns the next item from the queue but does not remove it.
+      #
+      #   q = Algorithms::Containers::Queue.new([1, 2, 3])
+      #   q.next #=> 1
+      #   q.size #=> 3
+      def next
+        @container.front
+      end
+      
+      # Adds an item to the queue.
+      #
+      #   q = Algorithms::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 = Algorithms::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 = Algorithms::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
+  end
+end

data/lib/containers/rb_tree_map.rb

@@ -0,0 +1,402 @@
+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
+    
+    Algorithms::Containers::RBTreeMap automatically uses the faster C implementation if it was built 
+    when the gem was installed. Alternatively, Algorithms::Containers::RubyRBTreeMap and Algorithms::Containers::CRBTreeMap can be 
+    explicitly used as well; their functionality is identical.
+    
+    Most methods have O(log n) complexity.
+    
+=end
+module Algorithms
+  module Containers
+    class 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 = Algorithms::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 = Algorithms::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 = Algorithms::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 = Algorithms::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 = Algorithms::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 = Algorithms::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 = Algorithms::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 = Algorithms::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 = Algorithms::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 = Algorithms::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 = 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
+  end
+  
+  begin
+    require 'CRBTreeMap'
+    Containers::RBTreeMap = Containers::CRBTreeMap
+  rescue LoadError # C Version could not be found, try ruby version
+    Containers::RBTreeMap = Containers::RubyRBTreeMap
+  end
+end