datastructures 0.2.1 → 0.3.0

data/README.md

@@ -26,7 +26,7 @@ A queue is a simple container-based structure that mimics a real-life queue (e.g
 Usage:
 
 ```ruby
-require 'datastructure'
+require 'datastructures'
 queue = DataStructures::Queue.new
 queue.enqueue('first')
 queue.enqueue('second')
@@ -46,7 +46,7 @@ The stack is the sibling of the queue. It mimicks a real-life stack (e.g. of pap
 Usage:
 
 ```ruby
-require 'datastructure'
+require 'datastructures'
 stack = DataStructures::Stack.new
 stack.push('first')
 stack.push('second')
@@ -57,4 +57,120 @@ stack.bottom # => 'first'
 stack.pop # => 'second'
 stack.pop # => 'first'
 stack.pop # => RuntimeError, "Stack underflow: nothing to pop"
+```
+
+## Day 3: Tree
+
+A tree is a directed graph where any two nodes are connected by only one edge, and there is a specified 'root' node, away from which all edges are directed. For any edge, the node that it points from is the *parent*, and the node it points to is the *child*. This implementation is currently very crude, and I hope to expand it by:
+
+- separating the node and tree classes
+- including search and shortest path algorithms
+- include more traversal algorithms
+
+Currently the implementation offers the ability to construct a tree and traverse it manually using family methods (*parent*, *child*, *siblings*, *descendents*). Nodes can have associated data.
+
+```ruby
+require 'datastructures'
+
+# start with a root TreeNode
+tree = DataStructures::TreeNode.new('root node')
+tree.is_root? # => true
+tree.is_leaf? # => true
+
+# children are also TreeNodes
+child1 = DataStructures::TreeNode.new('child')
+tree.add_child(child1)
+tree.child_count # => 1
+tree.add_child(DataStructures::TreeNode.new('another child'))
+tree.child_count # => 2
+tree.is_root? # => true
+tree.is_leaf? # => false
+child1.is_leaf? # => true
+
+# we can traverse by querying the family
+tree.siblings # => []
+child1.siblings.map{ |sibling| sibling.data } # => ["another child"]
+
+child1.parent == tree # => true
+child1.parent == child.siblings.first.parent # => true
+
+tree.descendents.map { |d| d.data } # => ["child", "another child"]
+```
+
+## Day 4: Linked List
+
+A linked list is a group of items which are ordered, and where the ordering is determined solely by the information each item contains about its neighbours.
+
+This implementation is a doubly-linked list, which means that each item retains a reference to the *next* and *previous* items in the list.
+
+The advantage of a linked list over a traditional array is that elements can be inserted and deleted efficiently.
+
+```ruby
+ll = DataStructures::LinkedList.new('one')
+ll.first.data # => 'one'
+ll[0] # => 'one'
+ll << 'two' # => ["one", "two"]
+ll.size # => 2
+ll.length # => 2
+ll.last.data # => 'two'
+ll[ll.size - 1] # => 'two'
+
+# linked lists can act as stacks
+ll.push 'three' # => ["one", "two", "three"]
+ll.size # => 3
+ll.pop # => "three"
+ll.size # => 2
+puts ll # => ["one", "two"]
+
+# or as queues
+ll.push 'three' # => ["one", "two", "three"]
+ll.shift # => 'one'
+ll.size # => 2
+ll.first.data 'two'
+
+# we can insert and delete
+ll.insert(1, 'one point five') # => ["two", "one point five", "three"]
+ll.delete(1)
+ll.to_s # => ['two', 'three']
+```
+
+## Day 5: Adjacency List
+
+An adjacency list is a structure for representing a graph. Nodes are named; the name can be any hashable object. Data can be stored in nodes, but not edges. The graph can be traversed manually by querying the neighbours of a node.
+
+The implementation is currently basic. I plan to improve it by:
+
+* implementing depth- and breadth-first search
+* implementing Dijkstra's algorithm for finding the shortest path between two nodes
+* visualise the graph (maybe d3.js)
+
+```ruby
+require 'datastructures'
+
+al = DataStructures::AdjacencyList.new
+
+al.add('one', 1, [2])
+al.add('two', 2, [3])
+al.add('three', 3, [1])
+al.add('four', 4, [2])
+
+al.get_node_value(1) # => 'one'
+al.set_node_value(1, 'new value')
+
+al.neighbours(1) # => [2]
+al.adjacent?(2, 3) # => true
+al.adjacent?(1, 4) # => false
+
+al.add_edge(1, 4)
+al.adjacent?(1, 4) # => true
+
+al.delete_edge(2, 3)
+al.adjacent?(2, 3) # => false
+
+al.to_s
+# 1 (new value) => [2, 4]
+# 2 (two) => []
+# 3 (three) => [1]
+# 4 (four) => [2]
+
 ```

data/lib/datastructures.rb

@@ -1,3 +1,6 @@
 require 'datastructures/version'
 require 'datastructures/queue'
-require 'datastructures/stack'
+require 'datastructures/stack'
+require 'datastructures/tree_node'
+require 'datastructures/linked_list'
+require 'datastructures/adjacency_list'

data/lib/datastructures/adjacency_list.rb

@@ -0,0 +1,82 @@
+module DataStructures
+
+  # Implements an Adjacency list with indexed nodes
+  class AdjacencyList
+
+    ALNode = Struct.new(:value)
+
+    attr_accessor :edges
+
+    # Returns a new AdjacencyList
+    # Nodes are accessed with unique names if +:named+ is true,
+    # otherwise they are accessed with integer indices (default).
+    def initialize(named=false)
+      @nodes = {}
+      @edges = {}
+    end
+
+    # Assignment - adds a new node with +:value+, and
+    # +:nodeidentifier+, and optionally an array of
+    # identifiers of other nodes defining +:edges+.
+    # Returns self, so that assignments can be chained.
+    def add(value, nodeidentifier, edges=Array.new)
+      node = ALNode.new(value)
+      @nodes[nodeidentifier] = node
+      @edges[nodeidentifier] = edges
+      self
+    end
+
+    # Removal - deletes the node at +:nodeidentifier+, which should be
+    # an integer index if this is an indexed adjacency list, or the name
+    # of the node if this is a names adjacency list.
+    def delete(nodeidentifier)
+      node = @nodes[nodeidentifier]
+      @nodes[nodeidentifier] = nil
+      @edges.delete node
+    end
+
+    # Removal - deletes the edge(s) +:edges+ connected to the node
+    # referenced by +:nodeidentifer+.
+    def delete_edge(nodeidentifier, *edges)
+      alledges = @edges[nodeidentifier]
+      edges.each { |edge| alledges.delete edge }
+    end
+
+    # Returns the value of the node with +:nodeidentifier+
+    def get_node_value nodeidentifier
+      @nodes[nodeidentifier].value
+    end
+
+    # Set with value of node at +:nodeidentifier+ to +:value+
+    def set_node_value(nodeidentifier, value)
+      @nodes[nodeidentifier].value = value
+    end
+
+    # Adds an edge from node with identifier +:x+ to node
+    # with identifier +:y+.
+    def add_edge(x, y)
+      @edges[x] << y
+    end
+
+    # True if +:x+ and +:y+ are connected by an edge.
+    def adjacent?(x, y)
+      @edges[x].include?(y) || @edges[y].include?(x)
+    end
+
+    # Return an array of identifiers of all nodes connected to 
+    # node at +:nodeidentifier+ by edges.
+    def neighbours nodeidentifier
+      @edges[nodeidentifier]
+    end
+
+    # Return a string representation of the graph
+    def to_s
+      s = ""
+      @nodes.each do |identifier, node|
+        s += "#{identifier} (#{node.value}) => #{@edges[identifier]} \n"
+      end
+      s
+    end
+
+  end
+end

data/lib/datastructures/linked_list.rb

@@ -0,0 +1,179 @@
+module DataStructures
+  # Implements a doubly Linked List.
+  class LinkedList
+
+    require 'pp'
+
+    LLNode = Struct.new(:data, :next, :previous)
+
+    attr_accessor :first
+    attr_accessor :last
+    attr_accessor :size
+
+    alias :length :size
+
+    # Returns a new LinkedList
+    #
+    # If no arguments are sent, the new LinkedList will be empty.
+    # When one or more objects are sent as arguments, the LinkedList
+    # is populated with those objects in the order sent.
+    def initialize *entries
+      @size = 0
+      unless entries.empty?
+        @first = LLNode.new(entries.shift, nil, nil)
+        @last = @first
+        @size = 1
+        self.push(*entries) unless entries.empty?
+      end
+    end
+
+    # Returns true if the LinkedList is empty
+    def empty?
+      @size == 0
+    end
+
+    # Element Reference - Returns the element at +index+
+    def [] index
+      current = @first
+      index.times do
+        current = current.next
+      end
+      current.data
+    end
+
+    # Element Assignment - Sets the element at +index+ to
+    # +:data+
+    def []= index, data
+      if index > @size - 1
+        # fill in the gaps
+        ((index - @size) + 1).times do
+          self.push nil
+        end
+        @last.data = data
+      else
+        # replace existing value
+        current = @first
+        index.times do
+          current = current.next
+        end
+        current.data = data
+      end
+      self
+    end
+
+    # Insert a node with +:data+ at +:index+.
+    # All nodes +:index+ and above get moved along one.
+    def insert index, data
+      old_node = @first 
+      index.times do
+        old_node = old_node.next
+      end
+      new_node = LLNode.new(data, old_node, old_node.previous)
+      old_node.previous.next = new_node
+      old_node.previous = new_node
+      self
+    end
+
+    # Delete the node at +:index+
+    def delete index
+      current = @first
+      index.times do
+        current = current.next
+      end
+      current.previous.next = current.next
+      current.next.previous = current.previous
+    end
+
+    # Calls the given block once for each element in +self+, passing
+    # that element as a parameter
+    def each &block
+      current = @first
+      @size.times do
+        yield current.data
+        current = current.next
+      end
+    end
+
+    # Append - Pushes the given object(s) on to the end of this
+    # Linked List. The expression returns the list itself, so several
+    # appends may be chained together. See also #pop for the opposite effect.
+    def push *elements
+      elements.each do |element|
+        node = LLNode.new(element, nil, @last)
+        @first = node if @first.nil?
+        @last.next = node unless @last.nil?
+        @last = node
+        @size += 1
+      end
+      self
+    end
+
+    alias :<< :push
+
+    # Removes the last element from +self+ and returns it.
+    # Raises an underflow error if empty.
+    def pop
+      raise "Linked List underflow: nothing to pop." if self.size == 0
+      last = @last
+      @last = @last.previous
+      @size -= 1
+      last.data
+    end
+
+    # Prepends objects to the front of +self+, moving other elements
+    # upwards. See also #shift for the opposite effect.
+    def unshift *elements
+      elements.each do |element|
+        node = LLNode.new(element, @first, nil)
+        @last = node if @last.nil?
+        @first.previous = node unless @first.nil?
+        @first = node
+        @size += 1
+      end
+      self
+    end
+
+    # Removes the first element of self and returns it (shifting all
+    # other elements down by one. 
+    def shift
+      raise "Linked List underflow: nothing to shift." if self.size == 0
+      first = @first
+      @first = @first.next
+      @size -= 1
+      first.data
+    end
+
+    # Returns the first index equal to +data+ (using == comparison).
+    # Counts from the beginning of the list.
+    def index data
+      current = @first
+      i = 0
+      while !current.nil?
+        return i if current.data == data
+        current = current.next
+        i += 1
+      end
+      nil
+    end
+
+    # Returns an array containing the data from the nodes in the list
+    def to_a
+      current = @first
+      array = []
+      while !current.nil?
+        array << current.data
+        current = current.next
+      end
+      array
+    end
+
+    # Returns a string representation of the list
+    def to_s
+      self.to_a.to_s
+    end
+
+  end # LinkedList
+
+end # Biopsy
+
+ll = DataStructures::LinkedList.new(*[1,2,3])

data/lib/datastructures/tree_node.rb

@@ -0,0 +1,73 @@
+module DataStructures
+  # Implements a Tree data structure. TreeNode represents a single node,
+  # and has methods for accessing parents, siblings and children.
+  class TreeNode
+
+    attr_accessor :children
+    attr_accessor :parent
+    attr_accessor :data
+
+    # new TreeNode object.
+    # +:data+ is the content of the node, can be any Ruby object
+    # +:parent+ optionally specify the parent node. Must be a TreeNode. Not specifying a parent makes this a root node.
+    def initialize(data,parent=nil)
+      @data = data
+      @parent = nil
+      raise "parent must be a TreeNode" unless @parent.nil? || @parent.class == TreeNode
+      self.clear
+    end
+
+    # add a child node.
+    #+:child+ the node to add as a child. must be a TreeNode
+    def add_child child
+      child.parent = self
+      @children << child
+    end
+
+    # remove a child node.
+    #+:child+ the child node to remove. must be a TreeNode
+    def remove_child! child
+      @children.delete child
+    end
+
+    alias :<< :add_child
+
+    # count the direct children of this node
+    def child_count
+      @children.size
+    end
+
+    # true if the node is a leaf, i.e. has no children
+    def is_leaf?
+      @children.empty?
+    end
+
+    alias :empty? :is_leaf?
+
+    # true if this node is root, i.e. has no parent
+    def is_root?
+      @parent.nil?
+    end
+
+    # return an array of the siblings of this node. Nil if root.
+    def siblings
+      if self.is_root?
+        nil
+      else
+        @parent.children.reject { |sibling| sibling.equal? self }
+      end
+    end
+
+    # return an array of all descendents
+    def descendents
+      @children.map { |child| [child, child.descendents] }.flatten
+    end
+
+    # remove all children
+    def clear
+      @children = Array.new
+    end
+
+  end # TreeNode
+
+end # Biopsy