RubyDataStructures 0.0.4 → 1.0.0

data/README.md

@@ -0,0 +1,193 @@
+RubyDatStructures
+=============
+
+`RubyDataStructures` gem is a `ruby` implementation of common data structures that are not by default supported by the Ruby programming language.
+The `RubyDatStructures` supports the following data structures:
+
+- Multi Dimensional Array
+- Stack (Implemented as an array)
+- Queue (Implemented as an array)
+- Singly Linked List
+- Doubly Linked List
+- Max Heap
+
+Installation
+------------
+
+    gem install RubyDataStructures
+
+Usage
+-----
+
+The `RubyDatStructures` library can be easily imported by running:
+
+    require 'rubygems'
+    require 'RubyDatStructures'
+
+The usage of each of the data structures is described below.
+
+## Multi Dimensional Array
+
+A `multi dimensional array` can be initialized by running:
+
+    RubyDataStructures::MultiDimensionalArray.new(n)
+
+where `n` is the number of dimensions of the multi dimensional array.
+
+The key at a particular index can be easily accessed by calling the array with the dimensions of the index.
+The key at the index with dimensions `(2,4,3)` of a multi dimensional array `mul_dim_array` can be access by calling:
+
+    mul_dim_array[2,4,3]
+
+The key for an index can also be easily set by calling the setter with the dimensions of the index.
+The key at the index with dimensions `(2,4,3)` of a multi dimensional array `mul_dim_array` can be set to `36` by calling:
+
+    mul_dim_array[2,4,3] = 36
+
+## Stack
+
+A `Stack` can be initialized by running:
+
+    RubyDataStructures::StackAsArray.new(n)
+
+where `n` is the max-size of stack.
+
+The following methods available on a `stack` are self explanatory:
+
+- empty?
+- full?
+- singleton?
+- push(`element`)
+- pop
+- reset
+
+Examples:
+
+    my_stack = RubyDataStructures::StackAsArray.new(5)
+    my_stack.empty?     # Returns `true`
+    my_stack.full?      # Returns `false`
+    my_stack.singleton? # Returns `false`
+    my_stack.push(1)
+    my_stack.push(2)
+    my_stach.push(3)
+    my_stack.pop        # Return `3`
+
+## Queue
+
+A `Queue` can be initialized by calling:
+
+    RubyDataStructures::QueueAsArray.new(n)
+
+where `n` is the max-size of the queue.
+
+The following methods available on a `queue` are self explanatory:
+
+- empty?
+- full?
+- enqueue(`element`)
+- dequeue
+- reset
+
+Examples:
+
+    my_queue = RubyDataStructures::QueueAsArray.new(5)
+    my_queue.empty?     # Returns `true`
+    my_queue.full?      # Returns `false`
+    my_queue.enqueue(1)
+    my_queue.enqueue(2)
+    my_queue.enqueue(3)
+    my_queue.dequeue    # Returns `1`
+
+## Singly Linked List
+
+A `singly linked list` can be initialized by running:
+
+    RubyDataStructures::SinglyLinkedList.new
+
+The following methods available on a  `singly linked list` are self explanatory:
+
+- head
+- empty?
+- insert(`item`)
+- search(`key`)
+- delete(`key`)
+- reset
+
+Examples:
+
+    my_list = RubyDataStructures::SinglyLinkedList.new
+    my_list.head # Returns `nil`
+    my_list.empty? # Returns `true`
+    my_list.insert(7)
+    my_list.search(7) # Returns a `RubyDataStructures::SinglyLinkedList::Element` element, whose key is `7`
+    my_list.delete(7)
+
+## Doubly Linked List
+
+A `doubly linked list` can be intialized by running:
+
+    RubyDataStructures::DoublyLinkedList.new
+
+The following methods available on a  `doubly linked list` are self explanatory:
+
+- head
+- tail
+- empty?
+- insert(`item`)
+- search(`key`)
+- delete(`key`)
+- reset
+
+Examples:
+
+    my_list = RubyDataStructures::DoublyLinkedList.new
+    my_list.head       # Returns a `RubyDataStructures::DoublyLinkedList::Element` element, whose key is nil
+    my_list.tail       # Returns a `RubyDataStructures::DoublyLinkedList::Element` element, whose key is nil
+    my_list.empty?     # Returns `true`
+    my_list.insert(7)
+    my_list.search(7)  # Returns a `RubyDataStructures::DoublyLinkedList::Element` element, whose key is `7`
+    my_list.delete(7)
+
+## Max Heap
+
+`MaxHeap` inherits most of its functionality from `Array`.
+A `max heap` can be initialized by running:
+
+  RubyDataStructures::MaxHeap.build(array)
+
+where `array` is an array, out of which we would like to build a max heap.
+
+For example, a heap can be built out of an array `[4, 1, 3, 2, 16, 9, 10, 14, 8, 7]` by running:
+
+    heap = RubyDataStructures::MaxHeap.build([4, 1, 3, 2, 16, 9, 10, 14, 8, 7])
+    # Returns the MaxHeap: [16, 14, 10, 8, 7, 9, 3, 2, 4, 1]
+
+The `maximum` of the heap can be accessed by running:
+
+    heap.maximum # Returns `16`
+
+The maximum of the heap can be extracted by running:
+
+    heap.extract_maximum!
+
+The key of a particular element can be increased by running:
+
+    heap.increase_key!(index, key)
+
+Example:
+
+    heap.increase_key!(8, 15)
+
+A key can be inserted into a heap by running:
+
+    heap.insert!(key)
+
+Example:
+
+    heap.insert!(11)
+
+
+Author
+------
+
+B V Satyaram <[bvsatyaram.com](http://bvsatyaram.com)>

data/lib/RubyDataStructures/max_heap.rb

@@ -0,0 +1,101 @@
+class RubyDataStructures::MaxHeap < Array
+  Infinity = 1.0/0
+
+  attr_accessor :heapsize
+
+  # It is assumed that the binary trees rooted at left(i) and right(i) are max heaps,
+  # but self[i] might be smaller than its children, thus violating the max-heap property.
+  # max_heapify! lets the value at self[i] float down in the max-heap,
+  # so that the subtree rooted at index i obeys the max-heap property
+  def max_heapify!(i)
+    l = left(i)
+    r = right(i)
+
+    if l < self.heapsize && self[l] > self[i]
+      largest = l
+    else
+      largest = i
+    end
+
+    if r < self.heapsize && self[r] > self[largest]
+      largest = r
+    end
+
+    if largest != i
+      exchange(i, largest)
+      max_heapify!(largest)
+    end
+
+    return self
+  end
+
+  # Builds a max-heap from an array
+  def self.build(array)
+    heap = self.new(array)
+    heap.heapsize = array.size
+
+    if heap.heapsize > 0
+      ((heap.heapsize/2) - 1).downto(0) do |i|
+        heap.max_heapify!(i)
+      end
+    end
+
+    return heap
+  end
+
+  # Returns the maximum element of the heap
+  def maximum
+    return self[0]
+  end
+
+  # Extracts the maximum of the heap and max_heapifies the remaining heap.
+  # Returns the maximum of the input heap
+  def extract_maximum!
+    raise "Heap Underflow - The heap is empty" if self.heapsize < 1
+
+    max_value = self[0]
+    self[0] = self[self.heapsize - 1]
+    self.heapsize = self.heapsize - 1
+    self.max_heapify!(0)
+
+    return max_value
+  end
+
+  def increase_key!(i, key)
+    raise "New key is smaller than the current key" if key < self[i]
+
+    self[i] = key
+    while (i > 0) && (self[parent(i)] < self[i])
+      exchange(i, parent(i))
+      i = parent(i)
+    end
+
+    return self
+  end
+
+  def insert!(key)
+    self.heapsize = self.heapsize + 1
+    self[self.heapsize  - 1] = -Infinity
+    self.increase_key!(self.heapsize - 1, key)
+  end
+
+  private
+
+  def parent(i)
+    return ((i+1)/2) - 1
+  end
+
+  def left(i)
+    return (2*i) + 1
+  end
+
+  def right(i)
+    return (2*i) + 2
+  end
+
+  def exchange(i, j)
+    tmp = self[i]
+    self[i] = self[j]
+    self[j] = tmp
+  end
+end

data/lib/RubyDataStructures/version.rb

@@ -1,3 +1,3 @@
 module Rubydatastructures
-  VERSION = "0.0.4"
+  VERSION = "1.0.0"
 end

data/lib/RubyDataStructures.rb

@@ -8,4 +8,5 @@ require 'RubyDataStructures/queue_as_array'
 require 'RubyDataStructures/singly_linked_list'
 require 'RubyDataStructures/singly_linked_list/element'
 require 'RubyDataStructures/doubly_linked_list'
-require 'RubyDataStructures/doubly_linked_list/element'
+require 'RubyDataStructures/doubly_linked_list/element'
+require 'RubyDataStructures/max_heap'

data/test/max_heap_test.rb

@@ -0,0 +1,46 @@
+$:.unshift File.join(File.dirname(__FILE__),'..','lib')
+
+require 'test/unit'
+require 'RubyDataStructures'
+
+class MaxHeapTest < Test::Unit::TestCase
+  def test_build
+    assert_equal [16, 14, 10, 8, 7, 9, 3, 2, 4, 1], RubyDataStructures::MaxHeap.build([4, 1, 3, 2, 16, 9, 10, 14, 8, 7])
+  end
+
+  def test_maximum
+    array = [4, 1, 3, 2, 16, 9, 10, 14, 8, 7]
+    heap = RubyDataStructures::MaxHeap.build(array)
+
+    assert_equal 16, heap.maximum
+  end
+
+  def test_extract_maximum
+    array = [4, 1, 3, 2, 16, 9, 10, 14, 8, 7]
+    heap = RubyDataStructures::MaxHeap.build(array)
+
+    assert_equal 10, heap.heapsize
+    assert_equal 16, heap.extract_maximum!
+    assert_equal 9, heap.heapsize
+    assert_equal [14,  8, 10, 4, 7, 9, 3, 2, 1, 1], heap
+  end
+
+  def test_increase_key
+    array = [4, 1, 3, 2, 16, 9, 10, 14, 8, 7]
+    heap = RubyDataStructures::MaxHeap.build(array)
+
+    assert_equal [16, 15, 10, 14, 7, 9, 3, 2, 8, 1], heap.increase_key!(8, 15)
+  end
+
+  def test_insert
+    array = [4, 1, 3, 2, 16, 9, 10, 14, 8, 7]
+    heap = RubyDataStructures::MaxHeap.build(array)
+
+    assert_equal 10, heap.heapsize
+    assert_equal 16, heap.extract_maximum!
+    assert_equal 9, heap.heapsize
+    assert_equal [14,  8, 10, 4, 7, 9, 3, 2, 1, 1], heap
+
+    assert_equal [14, 11, 10, 4, 8, 9, 3, 2, 1, 7], heap.insert!(11)
+  end
+end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: RubyDataStructures
 version: !ruby/object:Gem::Version 
-  hash: 23
   prerelease: false
   segments: 
+  - 1
   - 0
   - 0
-  - 4
-  version: 0.0.4
+  version: 1.0.0
 platform: ruby
 authors: 
 - Satyaram B V
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-05 00:00:00 +05:30
+date: 2011-05-16 00:00:00 +05:30
 default_executable: 
 dependencies: []
 
@@ -32,13 +31,14 @@ files:
 - .gitignore
 - Gemfile
 - LICENSE
-- README
+- README.md
 - RELEASE_NOTES
 - Rakefile
 - RubyDataStructures.gemspec
 - lib/RubyDataStructures.rb
 - lib/RubyDataStructures/doubly_linked_list.rb
 - lib/RubyDataStructures/doubly_linked_list/element.rb
+- lib/RubyDataStructures/max_heap.rb
 - lib/RubyDataStructures/multi_dimensional_array.rb
 - lib/RubyDataStructures/queue_as_array.rb
 - lib/RubyDataStructures/ruby_data_structures.rb
@@ -49,6 +49,7 @@ files:
 - test/RubyDataStructureTest.rb
 - test/doubly_linked_list_element_test.rb
 - test/doubly_linked_list_test.rb
+- test/max_heap_test.rb
 - test/multi_dimensional_array_test.rb
 - test/queue_as_array_test.rb
 - test/singly_linked_list_element_test.rb
@@ -64,27 +65,23 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: RubyDataStructures
-rubygems_version: 1.3.7
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Implementation of standard data structures in Ruby

data/README

@@ -1,3 +0,0 @@
-== RubyDataStructures
-
-Implementation of standard data structures in Ruby.