ds 0.0.4 → 0.0.6

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.2.2
+  - 2.2.3
+  - 2.3.0
+  - jruby-head
+script:
+  - bundle exec rake
+before_install:
+  - gem install bundler
+  - gem update bundler

data/Gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source 'http://rubygems.org'
 
 # Specify your gem's dependencies in ds.gemspec
 gemspec

data/README.rdoc

@@ -1,39 +1,35 @@
-= DS - Data Structures
+= DS - Data Structures for Ruby
 
-DS provides some common data structures not implement in Ruby natively.
+{<img src="https://travis-ci.org/knife/ds.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/knife/ds]
 
-The DS gem supports the folowing data structures:
+DS provides some popular data structures not implemented in Ruby natively.
+
+Data structures included in this gem:
 
 * Pair
 * Stacks
   * Stack
 * Queues
-  * Queue
+  * SimpleQueue
   * PriorityQueue
 * Lists
   * List
-  * CyclicList
-  * Ring
 * Trees
   * Tree
   * BinaryTree
-  * CompleteBinaryTree
   * BinaryHeap
-  * BinarySearchTree
+  * RedBlackTree
   * Trie
-* Graphs
-  * Graph
-  * Digraph
 * Matrixes
   * Array2D
   * ExpandableArray
   * TriMatrix
 * Sets
-  * OrderedSet
+  * IndexedSet
 
 
 == Instalation
-  
+
   gem install ds
 
 == Usage
@@ -41,7 +37,8 @@ The DS gem supports the folowing data structures:
   require 'ds'
   stack = DS::Stack.new
 
-  # To not have to type "DS::" before each class, use:
+To not have to type "DS::" before each class, use:
+
   include DS
   stack = Stack.new
 
@@ -50,13 +47,15 @@ The DS gem supports the folowing data structures:
 Pair is simple key-value data structure.
 
 Creating new Pair
-  p = Pair.new(3,9)
+  p = Pair.new(3, 9)
 
 Accessors defined on Pair object:
 
   p.key #=> 3
-  p.first #=> 3
   p.value #=> 9
+  p.value = 27
+
+  p.first #=> 3
   p.second #=> 9
   p.second = 27
 
@@ -65,16 +64,21 @@ Accessors defined on Pair object:
 Stack is very simple data structure which allows access only to the top element.
 More: {Stack}[http://en.wikipedia.org/wiki/Stack_(abstract_data_type)]
 
-Creating new Stack (implemented as Array).  
+Creating new Stack (implemented as Array).
   stack = Stack.new
+with initial values:
+  s = Stack.new(:first, :second)
+
+Creating new Stack (implemented as List).
+  stack = Stack.create
 
 The following methods are available on a Stack:
 
 * push
 * pop
+* peek
 * size
 * empty?
-* size
 
 Examples:
   stack.empty? #=> true
@@ -87,29 +91,29 @@ Examples:
   stack.size #=> 1
 
 
-
 === Queues
 
-Queues is First-In-First-Out (FIFO) data structure.
+Queue is First-In-First-Out (FIFO) data structure.
 Which means that first element added to the queue will be the first one to be removed.
 More: {Queue}[http://en.wikipedia.org/wiki/Queue_(data_structure)]
 
 
-==== Queue
+==== SimpleQueue
 
-Creating new Queue (implemented as Array).  
-  q = Queue.new
+Creating new SimpleQueue (implemented as Array).
+  q = SimpleQueue.new
+with initial values:
+  q = SimpleQueue.new(1, 2, 3)
 
-Creating new Queue (implemented as List)
-  q1 = Queue.create
-  q1 = Queue.new(:list)
+Creating new SimpleQueue (implemented as List)
+  q1 = SimpleQueue.create
 
 The following methods are available on a Queue:
 
-* enqueue(push)
-* dequeue(shift)
+* enqueue or push
+* dequeue or shift
 * peek
-* length
+* length or size
 * empty?
 
 Examples:
@@ -123,16 +127,27 @@ Examples:
   q.empty? #=> true
 
 
-==== Priority Queue 
+==== Priority Queue
 
-PriorityQueue is special form of Queue (PriorityQueue inherits from Queue).
 In opposite to simple Queue, in PriorityQueue each element is associated with a "priority".
 More: {Priority Queue}[http://en.wikipedia.org/wiki/Priority_queue]
 
 Creating new Priority Queue (implemented as BinaryHeap)
-  
+
   q = PriorityQueue.new
 
+By default higher value means higher priority but you can define own priority
+order by passing block to constructor:
+
+  PriorityQueue.new { |a, b| a < b }
+
+
+To add new element to priority queue use #unshift or #push method:
+  q.push(value, priority)
+
+To remove element from priority queue use #shift or #pop method. The interface
+is very similar to SimpleQueue.
+
 Examples:
   q.push(:important, 3)
   q.push(:very_important, 5)
@@ -145,29 +160,28 @@ Examples:
   q.peek  #=> :nevermind
 
 
-
 === Lists
 
 === List
 
 List is an ordered collection of values. Each element of list has pointer to the next
-element (last element points to nil).
+element (last element points to nil). This implementation uses doubly linked
+list underhood.
 More: {List}[http://en.wikipedia.org/wiki/List_(data_structure)]
 
 Creating new List
-  l = List.new(1)
+  l = List.new
   l.append(2)
-or 
-  arr = [1,2,3,4]
-  list = List.from_array(arr)
+or
+  list = List.new(1, 2, 3, 4)
 
 Examples:
 
-Simple operation on lists
+Simple operations on lists
   list.length #=> 4
-  list.append(5).to_a #=> [1,2,3,4,5] 
-  list.prepend(0).to_a #=> [0,1,2,3,4,5]
-  list.remove(list.head).to_a #=> [1,2,3,4,5]
+  list.append(5).to_a #=> [1, 2, 3, 4, 5]
+  list.unshift(0).to_a #=> [0, 1, 2, 3, 4, 5]
+  list.remove(list.head).to_a #=> [1, 2, 3, 4, 5]
   list.shift #=> 1
 
 Accessing first and last element
@@ -177,41 +191,60 @@ Accessing first and last element
   list.first #=> 2
   list.last #=> 5
 
+Accessing by index
+  list[2].data #=> 2
+  list.at(2).data #=> 2
+  list[-1].data #=> 4
+  list[1..2].map(&:data) #=> [2, 3]
+  list[1,3].map(&:data) #=> [2, 3, 4]
+
+Modifying elements on given index:
+  list[2].data = 8
+  list[2].data #=> 8
+  list[2] = [9, 10] #=> [1, 2, 9, 10, 4]
+  list[0,1] = 0 #=> [0, 2, 3, 4]
+  list[2..3] = ['x', 'x'] #=> [1, 2, 'x', 'x']
+
+
+Checking if given element exists on list
+  list.get(el) #=> el or nil
+  list.get!(el) #=> raises Exception if not found
+
 Reversing
-  list.reverse!.to_a #=> [5,4,3,1,0]
+  list.reverse!.to_a #=> [5, 4, 3, 1, 0]
 
 Enumerable methods are also available
-  
-  list.map{ |e| e.data } #=> [1,2,3,4]
-  list.inject(0){ |mem, var| mem = mem + var.data } #=> 10
 
-Other operations
-* insert_before
-* insert_after
-* zip?
-* merge
+  list.map{ |e| e.data } #=> [1, 2, 3, 4]
+  list.inject(0){ |a, e|  a + e.data } #=> 10
 
+Append one list to other list
+  list1.concat(list2)
 
-==== Ring
+Comparable module is included so you can:
 
-Ring is a Cyclic List where the last element(head) points to the first element(tail).
-More: {Ring}[http://en.wikipedia.org/wiki/Ring_(data_structure)]
+Check if lists are equal
+  list1 == list2
 
-Creating new Ring
-  ring = Ring.from_array([1,2,3,4,5,6,7])
+Check if one list is greater than other (same rules as in Array class)
+  list1 > list2
 
-Examples:
-  ring.looped? #=> true
-  ring.cycle_size #=> 7
-  ring.eliminate_by(2) #=> 1
- 
 
+Other operations
+* clone
+* clear
+* insert_before
+* insert_after
+* zip?
+* looped?
+* cycle_size
+* to_s
 
 === Trees
 
 ==== Tree
 
-A tree is a data structure consisting of nodes organised as a hierarchy. 
+A tree is a data structure with nodes organised in hierarchy.
 More: {Tree}[http://en.wikipedia.org/wiki/Tree_(data_structure)]
 
 Building Tree
@@ -225,259 +258,198 @@ Building Tree
   c1 << 10
   c3 = c2 << 3
 
-Examples:
+Methods:
   t.leaf? #=> false
   c3.leaf? #=> true
 
+  c1.sibblings.map &:data #=> [8, 9]
+  c1.parent.data #=> 2
+
   t.height #=> 3
   t.width #=> 3
   t.leaf_count #=> 4
-  
-  t.levels #=> {1=>1,2=>3, 3=>3} 
+
+  t.levels #=> {1=>1, 2=>3, 3=>3}
 
 Other methods
 * get_leaves
 * isometric?
 * mirror!
 
-Enumerable Module is included.
-  t.map{ |node| node.data } #=> [2,5,8,9,4,10,3]
+Enumerable Module is also included.
+  t.map { |node| node.data } #=> [2, 5, 8, 9, 4, 10, 3]
 
 
 ==== Binary Tree
 
-BinaryTree is sublass of Tree class. In BinaryTree each node can have at most two children.
+BinaryTree is sublass of Tree. In BinaryTree each node can have at most two children.
 More: {BinaryTree}[http://en.wikipedia.org/wiki/Binary_tree]
 
 Building tree
   bin_tree = BinaryTree.new
-  [2,5,8,9,11,12,14].each{|x| bin_tree.insert(x)} #build complete binary Tree
+  [2, 5, 8, 9, 11, 12, 14].each { |x| bin_tree.insert(x) } #builds complete binary Tree
 
 Accessors defined on BinaryTree object:
-  bin_tree.left #=> 5
-  bin_tree.right #=> 8
+  bin_tree.left.data #=> 5
+  bin_tree.right.data #=> 8
 
 
-==== BinarySearchTree
+==== Red Black Tree
 
-BST is Binary Tree which has the following properties:
-* The left subtree of a node contains only nodes with keys less than the node's key.
-* The right subtree of a node contains only nodes with keys greater than the node's key.
-* Both the left and right subtrees must also be binary search trees.
+Red-black tree is symbol table data structure. It's very simmilar to hash, but internally
+uses tree (perfect balanced binary tree) and not depends on hash function. Red
+black trees aren't as fast as hashes but supports ordered operations.
 
-Creating
-  bst = BinarySearchTree.from_array([8,1,5,2,7,6,3])
+    rb = RedBlackTree.new
+    rb.insert(:z, 3)
+    rb.insert(:p, 2)
+    rb.insert(:a, 1)
+    rb.get(:a) #=> 1
 
-Examples
-  walker = TreeWalker.new(b)
-  walker.traverse(:inorder).must_equal [1,2,3,5,6,7,8]
+You can also create RBT by passing hash to constructor
+  rb = RedBlackTree.new(a: 1, p: 2, z: 3)
 
+Hash like accessors are defined
 
-==== CompleteBinaryTree
+  rb[:z] = 3
+  rb[:z] #=> 3
 
-A complete binary tree is a binary tree in which every level, except possibly
-the last, is completely filled, and all nodes are as far left as possible. 
-CompleteBinaryTree is binary tree but does not inherit from Tree and BinaryTree class! Nodes are stored
-internally in array.
-More: {Complete Binary Tree}[http://en.wikipedia.org/wiki/Complete_binary_tree]
-
-Creating
-  cbt = CompleteBinaryTree.new(1,2,3,4,5,6,7)
-
-Examples
-  cbt.root #=> 1
-  cbt.left(0) #=> 2
-  cbt.right(0) #=> 3
-  cbt.parent(1) #=> 0
-  
-  cbt.left_index(0) #=> 1
-  cbt.right_index(1) #=> 4
-  cpt.parent_index(1) #=> 0
+You can convert RedBlackTree to Hash with to_h method:
+  rb.to_h #=> {a: 1, p: 2, z: 3}
 
+Enumerable is included and traversing is ordered by key
+    rb.map(&:key) #=> [:a, :p, :z]
 
 ==== Binary Heap
 
-BinaryHeap is  Complete Binary Tree  in which every node satisfies heap property. Binary Heap allows very fast
-access to maximum or minimum element of the tree.
+BinaryHeap is tree in which every node satisfies heap property. Binary Heap allows very fast
+access to maximum or minimum element of the tree (const access).
 More: {Binary Heap}[http://en.wikipedia.org/wiki/Binary_heap]
 
 Creating
 
-Maximum Binary Heap 
-  max_heap = BinaryHeap.new(9,8,4,5,11,6)
+Maximum Binary Heap
+  max_heap = BinaryHeap.new(9, 8, 4, 5, 11, 6)
 or
-  max_heap = BinaryHeap.max(9,8,4,5,11,6)
+  max_heap = BinaryHeap.max(9, 8, 4, 5, 11, 6)
 
 Minimum Binary Heap
-  min_heap = BinaryHeap.min(9,8,4,5,11,6)
+  min_heap = BinaryHeap.min(9, 8, 4, 5, 11, 6)
 or
-  BinaryHeap.new(9,8,4,5,11,6){|parent,child| parent < child}
+  BinaryHeap.new(9, 8, 4, 5, 11, 6){ |parent, child| parent < child }
 
 You can set heap relation by passing block to BinaryHeap constructor.
 
 Examples
   max_heap.shift #returns max element (11)
-  max_heap.to_a #=> [9,8,6,5,4]
+  max_heap.to_a #=> [9, 8, 6, 5, 4]
   max_heap.insert 15
   max_heap.shift #=> 15
 
   min_heap.shift #returns min element (4)
 
 
-==== Trie 
+==== Trie
 
 Trie is an ordered tree data structure which allows very quick search: O(k), where k is word length.
 More: {Trie}[http://en.wikipedia.org/wiki/Trie]
 
-Creating 
+Creating
   trie = Trie.new
-  
+
+Setting custom alphabet (memory usage depends on alphabet size)
+  trie.alphabet = %w(a b c d)
+
 Examples
-  trie.insert("thing",true);
-  trie.find("thing")  # =>  true
+  trie.insert('thing', true);
+  trie.find('thing')  # =>  true
+  trie.delete('thing')
+or
+  trie['one'] = 'thing'
+  trie['one']  # =>  'thing'
+
+Enumerable module is included so you can iterate through trie:
+ trie.map { |k, v| [k, v] } # => [['he', true], ['hello', true], ['help', true]]
 
+Finding all words matching given prefix:
+  trie.with_prefix('th') # =>  ['the', 'thing']
+  trie.with_prefix('yeti') # =>  []
 
-==== Traversing Tree 
+Alternatively you can pass block to this method:
+  trie.with_prefix('th'){ |word, val| res[word] = val } # =>  {'the' => true, 'thing' => true}
 
-  b= BinaryTree.new
-  [2,5,8,9,11,12,14].each{|x| b.insert(x)} 
+==== Tree Traversals
 
-walker = TreeWalker.new(b)
+  b = BinaryTree.new
+  [2, 5, 8, 9, 11, 12, 14].each{ |x| b.insert(x) }
+
+  walker = TreeWalker.new(b)
 
-Iterating in postorder  
-  walker.traverse(:postorder) #=> [9,11,5,12,14,8,2]
+Iterating in postorder
+  walker.traverse(:postorder) #=> [9, 11, 5, 12, 14, 8, 2]
 Iterating in inorder
-  walker.traverse(:inorder) #=> [9,5,11,2,12,8,14] 
+  walker.traverse(:inorder) #=> [9, 5, 11, 2, 12, 8, 14]
 Iterating in preorder
-  walker.traverse(:preorder) #=> [2,5,9,11,8,12,14]
+  walker.traverse(:preorder) #=> [2, 5, 9, 11, 8, 12, 14]
 
 Iterating in BFS order
-  walker.each{ |x| x } #=> [2,5,8,9,11,12,14]
+  walker.each{ |x| x } #=> [2, 5, 8, 9, 11, 12, 14]
 
 
 You can also pass block to traverse method
-  walker.traverse(:inorder){|n| p n.data**2}
+  walker.traverse(:inorder){ |n| n.data**2 }
 
 If you want to change value of tree nodes, use recalculate! method
-  walker.recalculate!(b,:preorder,0){|x,memo| memo = memo+x.data} 
+  walker.recalculate!(b, :preorder, 0) { |e, a| a + e.data }
 
 
-
-=== Graphs
-
-A graph data structure consists of a finite (and possibly mutable) set of
-ordered pairs, called edges or arcs, of certain entities called nodes or
-vertices.
-More: {Graph}[http://en.wikipedia.org/wiki/Graph_(data_structure)]
-
-
-====Graph
-
-Creating new Graph
-    
-  edges = []
-  edges << Edge.new('Lukas','Marc')
-  edges << Edge.new('Lukas','Tom')
-  edges << Edge.new('Marc','Jack')
-  edges << Edge.new('Tom','Marc')
-
-New graph implemented as Triangular Matrix
-  graph = Graph.create(edges)
-
-New graph implemented as Matrix
-  graph = Graph.new(edges,:matrix)
-
-
-Examples:
-
-  graph.vertex_size #=> 4
-  graph.degree("Marc") #=> 3
-  graph.edge?("Marc","Tom") #=> true
-  graph.edge?("Tom","Jack") #=> false
-  graph.add_edges([Edge.new("Marc","Kate")])
-  graph.remove("Marc","Jack")
-  graph.neighbors('Tom') #=> ["Marc","Lucas"]
-
-Iterating
-  graph.each_edge{|e| p e}
-  graph.each_vertex{ |v| p v }
-
-
-==== Digraph
-
-Creating Directed Weighted Graph is simple like that:
-  
-  edges = []
-
-  edges << Edge.new(:A,:C,5)
-  edges << Edge.new(:A,:D,3)
-  edges << Edge.new(:A,:G,14)
-  edges << Edge.new(:C,:E,3)
-  edges << Edge.new(:C,:F,2)
-  edges << Edge.new(:D,:C,11)
-  edges << Edge.new(:D,:E,7)
-  edges << Edge.new(:D,:G,6)
-  edges << Edge.new(:G,:E,7)
-  edges << Edge.new(:E,:B,5)
-  edges << Edge.new(:G,:B,6)
-  edges << Edge.new(:F,:B,7)
-
-  wdigraph = Digraph.create(edges)
-
-Examples
-  wdigraph.get_edge(:D,:C).weight #=> 11
-  wdigraph.degree(:E) #=> 4
-  wdigraph.in_degree(:E) #=> 3
-  wdigraph.out_degree(:E) #=> 1
-  wdigraph.bfs(:A) #=> [:A, :C, :D, :G, :E, :F, :B]
-
-
-
-
-=== Matrixes
+=== Arrays
 
 ==== Array2D
 
-Simple two dimensional array(matrix).  
+Simple two dimensional array(matrix).
 Array2D extends automatically like simple Array.
 
 Creating
-  discrete_matrix = Array2D.new(2,0)
+  discrete_matrix = Array2D.new(2, 0)
 
-Examples
-  discrete_matrix.to_a  #=> [[0,0],[0,0]]
-  discrete_matrix[3,3] #=> 0
+First argument is size of row(or column) and second is default value of matrix.
 
+Examples
+  discrete_matrix.to_a  #=> [[0, 0], [0, 0]]
+  discrete_matrix[3, 3] #=> 0
 
 
 ==== ExpandableArray
 
-  arr = ExpandableArray.new(0,0)
-  arr[4]  = 1 #=> [0,0,0,0,4]
+Automaticaly fills empty slots with custom value:
+
+  arr = ExpandableArray.new(0, 0)
+  arr[4]  = 1 #=> [0, 0, 0, 0, 4]
 
 
 ==== TriMatrix
 Triangular matrix is a special kind of matrix where M[x,y] = M[y,x].
-More: {Triangular Matrixe}[http://en.wikipedia.org/wiki/Triangular_matrix]
+More: {Triangular Matrix}[http://en.wikipedia.org/wiki/Triangular_matrix]
 
 Creating
   tri_matrix = TriMatrix.new
-  tri_matrix[0,1] = true
-  tri_matrix[0,2] = true
+  tri_matrix[0, 1] = true
+  tri_matrix[0, 2] = true
 
 Examples
-  tri_matrix[0,1] == tri_matrix[1,0] #=> true
+  tri_matrix[0, 1] == tri_matrix[1, 0] #=> true
 
 
 
 === Sets
 
-==== OrderedSet
-OrderedSet is a set whose elements are ordered. In opposite to Array duplicates
-are not allowed.
+==== IndexedSet
+IndexedSet is a set whose elements are indexed. In opposite to Array, duplicates
+are not allowed. Internally uses hash for fast access and array for ordering.
 
-Creating new Ordered Set
-  set = OrderedSet.new
+Creating new Indexed Set
+  set = IndexedSet.new
 
 Examples
   set.push(:first)  #=>  0
@@ -485,4 +457,3 @@ Examples
   set.index(:first) #=> 0
   set.to_a #=> [:first, :second]
 
-