hamster 0.1.2 → 0.1.5

data/History.rdoc

@@ -1,4 +1,16 @@
-=== 0.1.2 / 2009-10-23
+=== 0.1.5 / 2009-11-5
+
+* Add some examples
+
+=== 0.1.4 / 2009-10-26
+
+* Simplify and share Trie between Hash and Set
+
+=== 0.1.3 / 2009-10-26
+
+* All known issues fixed.
+
+=== 0.1.2 / 2009-10-25
 
 * Fixed all but one outstanding issue with #remove
 

data/README.rdoc

@@ -1,45 +1,92 @@
 = Hamster
 
-Hash Array Mapped Tries (HAMT) for Ruby (see http://lamp.epfl.ch/papers/idealhashtrees.pdf).
+Hamster started out as an implementation of Hash Array Mapped Hashs (HAMT) for Ruby (see http://lamp.epfl.ch/papers/idealhashtrees.pdf) and has since expanded to include implementations of other Persistent Data Structures (see http://en.wikipedia.org/wiki/Persistent_data_structure) such as Sets, Lists, Stacks, etc.
 
-Why do you care?
+== Huh?
 
-HAMTs are hash tables with one really neat property: their structure enables you to perform very efficient copy-on-write operations. For example:
+Persistent data structures have a really neat property: very efficient copy-on-write operations. That allows you to create immutable data-structures that only need copying when something changes. For example:
 
-	trie = Hamster::Trie.new
+  require 'hamster'
 
-	trie.put("Name", "Simon")
-	trie.get("Name")          # => nil
+  hash = Hamster::Hash.new
 
-Huh? That's not much use!
+  hash.put("Name", "Simon")
+  hash.has_key?("Name")     # => false
+  hash.get("Name")          # => nil
 
-Remember, each instance of a trie is immutable. #put creates an efficient copy containing the modifications. So, let's try that again:
+== Double Huh? That's not much use!
 
-	trie = Hamster::Trie.new
+Whoops! Remember, each call to <tt>#put</tt> creates an efficient copy containing the modifications, leaving the original unmodified. So, unlike Ruby's built-in <tt>Hash</tt> all Hamster classes follow Command-Query-Seperation (see http://martinfowler.com/bliki/CommandQuerySeparation.html) and return the modified copy of themselves after any mutating operation. Let's try that again:
 
-	trie = trie.put("Name", "Simon")
-	trie.get("Name")                 # => "Simon"
+  require 'hamster'
 
-The same goes for remove:
+  original = Hamster::Hash.new
+  copy = hash.put("Name", "Simon")
 
-	trie = Hamster::Trie.new
+  original.get("Name")             # => nil
+  copy.get("Name")                 # => "Simon"
 
-	trie = trie.put("Name", "Simon")
-	trie = trie.put("Gender", "Male")
-	trie = trie.remove("Name")
-	trie.get("Name")    # => nil
-	trie.get("Gender")  # => "Male"
+The same goes for <tt>#remove</tt>:
 
-So tell me again why I care?
+  require 'hamster'
 
-As mentioned earlier, HAMTs perform a copy whenever they are modified meaning there is never any chance that two threads could be modifying the same instance at any one time. And, because they are very efficient copies, you don't need to worry about using up gobs of heap space in the process.
+  original = Hamster::Hash.new
+  original = hash.put("Name", "Simon")
+  copy = hash.remove("Name")
+  
+  original.get("Name")  # => Simon
+  copy.get("Name")      # => nil
 
-Thats nice but I don't really have multi-threading issues.
+== Oh, I get it. Cool. But I still don't understand why I should care?
 
-OK, how about transactional memory:
+As mentioned earlier, persistent data structures perform a copy whenever they are modified meaning there is never any chance that two threads could be modifying the same instance at any one time. And, because they are very efficient copies, you don't need to worry about using up gobs of heap space in the process.
 
-	Need an example
+== OK, that sounds mildly interesting. What's the downside--there's always a downside?
 
-So what's the downside?
+There's a potential performance hit when compared with MRI's built-in, native, hand-crafted C-code implementation of <tt>Hash</tt>. For example:
 
-The downside is that because the implementation is pure Ruby, MRI's built-in, native, hand-crafted C-code implementation of Hash is 10-times faster!
+  require 'hamster'
+
+  hash = Hamster::Hash.new
+  (1..10000).each { |i| hash = hash.put(i, i) }  # => 0.05s
+  (1..10000).each { |i| hash.get(i) }  # => 0.008s
+
+versus
+
+  hash = {}
+  (1..10000).each { |i| hash[i] = i }  # => 0.004s
+  (1..10000).each { |i| hash[i] }  # => 0.001s
+
+== That seems pretty bad?
+
+Well, yes and no. The previous comparison wasn't really fair. Sure, if all you want to do is replace your existing uses of <tt>Hash</tt> in single-threaded environments then don't even bother. However, if you need something that can be used efficiently in concurrent environments where multiple threads are accessing--reading AND writing--the contents things get much better.
+
+== Do you have a better example?
+
+A more realistic comparison might look like:
+
+  require 'hamster'
+
+  hash = Hamster::Hash.new
+  (1..10000).each { |i| hash = hash.put(i, i) }  # => 0.05s
+  (1..10000).each { |i| hash.get(i) }  # => 0.008s
+
+versus
+
+  hash = {}
+  (1..10000).each { |i|
+    hash = hash.dup
+    hash[i] = i
+  } # => 19.8s
+
+  (1..10000).each { |i| hash[i] }  # => 0.001s
+
+Impressive huh? What's even better is--or worse depending on your perspective--is that after all that, the native <tt>Hash</tt> version still isn't thread-safe and still requires some synchronisation around it slowing it down even further!
+
+The <tt>Hamster::Hash</tt> version on the other hand was unchanged from the original whilst remaining inherently thread-safe, and 3 orders of magnitude faster!
+
+== Sure, but as you say, you still need synchronisation so why bother with the copying?
+
+Well, I could show you one but I'd have to re-write--or at least wrap--most <tt>Hash</tt> methods to make it generic, or at least write some application-specific code that synchronised using a <tt>Mutex</tt> and ... well ... it's hard, I always make mistakes, I always end up with weird edge cases and race conditions so, I'll leave that as an exercise for you :)
+
+== And that, my friends, is why you might want to use one :)

data/TODO

@@ -0,0 +1 @@
+* Implement Enumerable methods such that they return instances of the class (or List as a last resort) rather than Array.

data/lib/hamster.rb

@@ -1,3 +1,6 @@
-require 'hamster/entry'
 require 'hamster/trie'
+require 'hamster/list'
+require 'hamster/stack'
+require 'hamster/set'
+require 'hamster/hash'
 require 'hamster/version'

data/lib/hamster/hash.rb

@@ -0,0 +1,66 @@
+module Hamster
+
+  class Hash
+
+    def initialize(trie = Trie.new)
+      @trie = trie
+    end
+
+    # Returns the number of key-value pairs in the hash.
+    def size
+      @trie.size
+    end
+
+    # Returns <tt>true</tt> if the hash contains no key-value pairs.
+    def empty?
+      @trie.empty?
+    end
+
+    # Returns <tt>true</tt> if the given key is present in the hash.
+    def has_key?(key)
+      @trie.has_key?(key)
+    end
+
+    # Retrieves the value corresponding to the given key. If not found, returns <tt>nil</tt>.
+    def get(key)
+      @trie.get(key)
+    end
+
+    # Returns a copy of <tt>self</tt> with the given value associated with the key.
+    def put(key, value)
+      self.class.new(@trie.put(key, value))
+    end
+
+    # Returns a copy of <tt>self</tt> with the given key/value pair removed. If not found, returns <tt>self</tt>.
+    def remove(key)
+      copy = @trie.remove(key)
+      if copy.equal?(@trie)
+        self
+      else
+        self.class.new(copy)
+      end
+    end
+
+    # Calls <tt>block</tt> once for each entry in the hash, passing the key-value pair as parameters.
+    # Returns <tt>self</tt>
+    def each
+      block_given? or return enum_for(__method__)
+      @trie.each { |key, value| yield key, value }
+      self
+    end
+
+    # Returns <tt>true</tt> if . <tt>eql?</tt> is synonymous with <tt>==</tt>
+    def eql?(other)
+      equal?(other) || (self.class.equal?(other.class) && @trie.eql?(other.instance_eval{@trie}))
+    end
+    alias :== :eql?
+
+    # Returns <tt>self</tt>
+    def dup
+      self
+    end
+    alias :clone :dup
+
+  end
+
+end

data/lib/hamster/list.rb

@@ -0,0 +1,105 @@
+module Hamster
+
+  class List
+
+    include Enumerable
+
+    def initialize(head = nil, tail = self)
+      @head = head
+      @tail = tail
+    end
+
+    # Returns <tt>true</tt> if the list contains no items.
+    def empty?
+      @tail.equal?(self)
+    end
+
+    # Returns the number of items in the list.
+    def size
+      if empty?
+        0
+      else
+        @tail.size + 1
+      end
+    end
+
+    # Returns the first item.
+    def car
+      @head
+    end
+
+    # Returns a copy of <tt>self</tt> without the first item.
+    def cdr
+      @tail
+    end
+
+    # Returns a copy of <tt>self</tt> with it as the head.
+    def cons(item)
+      self.class.new(item, self)
+    end
+
+    # Calls <tt>block</tt> once for each item in the list, passing the item as the only parameter.
+    # Returns <tt>self</tt>
+    def each
+      block_given? or return enum_for(__method__)
+      unless empty?
+        yield(@head)
+        @tail.each { |item| yield(item) }
+      end
+      self
+    end
+
+    # Returns <tt>true</tt> if . <tt>eql?</tt> is synonymous with <tt>==</tt>
+    def eql?(other)
+      blammo!
+    end
+    alias :== :eql?
+
+    # Returns <tt>self</tt>
+    def dup
+      self
+    end
+    alias :clone :dup
+    
+    def map
+      if empty?
+        self
+      else
+        @tail.map { |item| yield(item) }.cons(yield(@head))
+      end
+    end
+    
+    def reduce(memo)
+      if empty?
+        memo
+      else
+        @tail.reduce(yield(memo, @head)) { |memo, item| yield(memo, item) }
+      end
+    end
+
+    private
+
+    def method_missing(name, *args, &block)
+      if name.to_s =~ /^c([ad]+)r$/
+        accessor($1)
+      else
+        super
+      end
+    end
+
+    # Perform compositions of <tt>car</tt> and <tt>cdr</tt> operations. Their names consist of a 'c', followed by at
+    # least one 'a' or 'd', and finally an 'r'. The series of 'a's and 'd's in each function's name is chosen to
+    # identify the series of car and cdr operations that is performed by the function. The order in which the 'a's and
+    # 'd's appear is the inverse of the order in which the corresponding operations are performed.
+    def accessor(sequence)
+      sequence.split(//).reverse!.inject(self) do |memo, char|
+        case char
+        when "a" then memo.car
+        when "d" then memo.cdr
+        end
+      end
+    end
+
+  end
+
+end

data/lib/hamster/set.rb

@@ -0,0 +1,65 @@
+module Hamster
+
+  class Set
+
+    def initialize(trie = Trie.new)
+      @trie = trie
+    end
+
+    # Returns the number of items in the set.
+    def size
+      @trie.size
+    end
+
+    # Returns <tt>true</tt> if the set contains no items.
+    def empty?
+      @trie.size
+    end
+
+    # Returns <tt>true</tt> if the given item is present in the set.
+    def include?(item)
+      @trie.has_key?(item)
+    end
+
+    # Returns a copy of <tt>self</tt> with the given item added. If already exists, returns <tt>self</tt>.
+    def add(item)
+      if include?(item)
+        self
+      else
+        self.class.new(@trie.put(item, nil))
+      end
+    end
+
+    # Returns a copy of <tt>self</tt> with the given item removed. If not found, returns <tt>self</tt>.
+    def remove(key)
+      copy = @trie.remove(item)
+      if copy.equal?(@trie)
+        self
+      else
+        self.class.new(copy)
+      end
+    end
+
+    # Calls <tt>block</tt> once for each item in the set, passing the item as the only parameter.
+    # Returns <tt>self</tt>
+    def each
+      block_given? or return enum_for(__method__)
+      @trie.each { |key, value| yield key }
+      self
+    end
+
+    # Returns <tt>true</tt> if . <tt>eql?</tt> is synonymous with <tt>==</tt>
+    def eql?(other)
+      equal?(other) || (self.class.equal?(other.class) && @trie.eql?(other.instance_eval{@trie}))
+    end
+    alias :== :eql?
+
+    # Returns <tt>self</tt>
+    def dup
+      self
+    end
+    alias :clone :dup
+
+  end
+
+end

data/lib/hamster/stack.rb

@@ -0,0 +1,53 @@
+module Hamster
+
+  class Stack
+
+    def initialize(list = List.new)
+      @list = list
+    end
+
+    # Returns <tt>true</tt> if the stack contains no items.
+    def empty?
+      @list.empty?
+    end
+
+    # Returns the number of items on the stack.
+    def size
+      @list.size
+    end
+
+    # Returns the item at the top of the stack.
+    def top
+      @list.car
+    end
+
+    # Returns a copy of <tt>self</tt> with the given item as the new top
+    def push(item)
+      self.class.new(@list.cons(item))
+    end
+
+    # Returns a copy of <tt>self</tt> without the top item.
+    def pop
+      copy = @list.cdr
+      if !copy.equal?(@list)
+        self.class.new(copy)
+      else
+        self
+      end
+    end
+
+    # Returns <tt>true</tt> if . <tt>eql?</tt> is synonymous with <tt>==</tt>
+    def eql?(other)
+      equal?(other) || (self.class.equal?(other.class) && @list.eql?(other.instance_eval{@list}))
+    end
+    alias :== :eql?
+
+    # Returns <tt>self</tt>
+    def dup
+      self
+    end
+    alias :clone :dup
+
+  end
+
+end

data/lib/hamster/trie.rb

@@ -2,8 +2,6 @@ module Hamster
 
   class Trie
 
-    include Enumerable
-
     def initialize(significant_bits = 0, entries = [], children = [])
       @significant_bits = significant_bits
       @entries = entries
@@ -12,8 +10,9 @@ module Hamster
 
     # Returns the number of key-value pairs in the trie.
     def size
-      # TODO: This definitely won't scale!
-      to_a.size
+      count = 0
+      each { count += 1 }
+      count
     end
 
     # Returns <tt>true</tt> if the trie contains no key-value pairs.
@@ -26,37 +25,30 @@ module Hamster
       !! get(key)
     end
 
-    # Calls <tt>block</tt> once for each key in the trie, passing the key-value pair as parameters.
-    # Returns <tt>self</tt>
+    # Calls <tt>block</tt> once for each entry in the trie, passing the key-value pair as parameters.
     def each
-      block_given? or return enum_for(__method__)
       @entries.each { |entry| yield entry.key, entry.value if entry }
       @children.each do |child|
         child.each { |key, value| yield key, value } if child
       end
-      self
     end
 
     # Returns a copy of <tt>self</tt> with the given value associated with the key.
     def put(key, value)
       index = index_for(key)
       entry = @entries[index]
-
       if entry && !entry.has_key?(key)
         children = @children.dup
         child = children[index]
-
         children[index] = if child
           child.put(key, value)
         else
           self.class.new(@significant_bits + 5).put!(key, value)
         end
-
         self.class.new(@significant_bits, @entries, children)
       else
         entries = @entries.dup
         entries[index] = Entry.new(key, value)
-
         self.class.new(@significant_bits, entries, @children)
       end
     end
@@ -65,12 +57,12 @@ module Hamster
     def get(key)
       index = index_for(key)
       entry = @entries[index]
-      if entry
-        if entry.has_key?(key)
-          entry.value
-        else
-          child = @children[index]
-          child.get(key) if child
+      if entry && entry.has_key?(key)
+        entry.value
+      else
+        child = @children[index]
+        if child
+          child.get(key)
         end
       end
     end
@@ -80,6 +72,12 @@ module Hamster
       remove!(key) || self
     end
 
+    # Returns <tt>true</tt> if . <tt>eql?</tt> is synonymous with <tt>==</tt>
+    def eql?(other)
+      blammo!
+    end
+    alias :== :eql?
+
     protected
 
     def put!(key, value)
@@ -90,17 +88,21 @@ module Hamster
     def remove!(key)
       index = index_for(key)
       entry = @entries[index]
-      child = @children[index]
       if entry && entry.has_key?(key)
-        entries = @entries.dup
-        entries[index] = nil
-        self.class.new(@significant_bits, entries, @children) unless size == 1
-      elsif child
-        new_child = child.remove!(key)
-        if new_child != child
-          children = @children.dup
-          children[index] = new_child
-          self.class.new(@significant_bits, @entries, children)
+        if size > 1
+          entries = @entries.dup
+          entries[index] = nil
+          self.class.new(@significant_bits, entries, @children)
+        end
+      else
+        child = @children[index]
+        if child
+          copy = child.remove!(key)
+          if !copy.equal?(child)
+            children = @children.dup
+            children[index] = copy
+            self.class.new(@significant_bits, @entries, children)
+          end
         end
       end
     end
@@ -111,6 +113,21 @@ module Hamster
       (key.hash.abs >> @significant_bits) & 31
     end
 
+    class Entry
+
+      attr_reader :key, :value
+
+      def initialize(key, value)
+        @key = key
+        @value = value
+      end
+
+      def has_key?(key)
+        @key.eql?(key)
+      end
+
+    end
+
   end
 
 end