hamster 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,5 +1,39 @@
 = Hamster
 
-Hash Array Mapped Tries (HAMT) for Ruby.
+Hash Array Mapped Tries (HAMT) for Ruby (See http://lamp.epfl.ch/papers/idealhashtrees.pdf).
 
-See http://lamp.epfl.ch/papers/idealhashtrees.pdf
+Why do you care?
+
+HAMTs are hash tables with one really neat property: their structure enables you to perform very efficient write-on-copy. For example:
+
+	trie = Hamster::Trie.new
+
+	trie.put("Name", "Simon")
+	trie.get("Name")						# => nil
+
+Huh? That's not much use!
+
+Remember, each instance of a trie is immutable. #put creates an efficient copy containing the modifications. So, let's try that again:
+
+	trie = Hamster::Trie.new
+
+	trie = trie.put("Name", "Simon")
+	trie.get("Name")									# => "Simon"
+
+The same goes for remove:
+
+	trie = Hamster::Trie.new
+
+	trie = trie.put("Name", "Simon")
+	trie = trie.put("Gender", "Male")
+	trie = trie.remove("Name")
+	trie.get("Name")									# => nil
+	trie.get("Gender")								# => "Male"
+
+So tell me again why I care?
+
+As mentioned earlier, HAMTs perform a copy whenever they are modified means that there is never a chance that two threads could be modifying the same instance at any one time. And the fact that they are very efficient copies means you don't need to worry about using up gobs of heap space.
+
+So what's the downside?
+
+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!

data/lib/hamster/entry.rb

@@ -10,7 +10,7 @@ module Hamster
     end
 
     def has_key?(key)
-      @key == key
+      @key.eql?(key)
     end
 
   end

data/lib/hamster/trie.rb

@@ -4,10 +4,10 @@ module Hamster
 
     include Enumerable
 
-    def initialize(significant_bits = 0)
+    def initialize(significant_bits = 0, entries = [], children = [])
       @significant_bits = significant_bits
-      @entries = []
-      @children = []
+      @entries = entries
+      @children = children
     end
 
     # Returns the number of key-value pairs in the trie.
@@ -37,26 +37,28 @@ module Hamster
       self
     end
 
-    # Returns a copy of <tt>self</tt> with given value associated with the key.
+    # Returns a copy of <tt>self</tt> with the given value associated with the key.
     def put(key, value)
-      dup.put!(key, value)
-    end
-
-    # Associates the given value with the key and returns <tt>self</tt>
-    def put!(key, value)
       index = index_for(key)
       entry = @entries[index]
+
       if entry && !entry.has_key?(key)
-        child = @children[index]
-        @children[index] = if child
+        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[index] = Entry.new(key, value)
+        entries = @entries.dup
+        entries[index] = Entry.new(key, value)
+
+        self.class.new(@significant_bits, entries, @children)
       end
-      self
     end
 
     # Retrieves the value corresponding to the given key. If not found, returns <tt>nil</tt>.
@@ -75,25 +77,38 @@ module Hamster
 
     # Returns a copy of <tt>self</tt> with the given key/value pair removed. If not found, returns <tt>self</tt>.
     def remove(key)
-      has_key?(key) or return self
-      dup.remove!(key)
+      index = index_for(key)
+      entry = @entries[index]
+      child = @children[index]
+      if entry && entry.has_key?(key)
+        # TODO: Probably should "pull up" a child entry
+        entries = @entries.dup
+        entries[index] = nil
+        self.class.new(@significant_bits, entries, @children)
+      elsif child
+        new_child = child.remove(key)
+        if new_child != child
+          # TODO: Probably should "prune" empty children
+          children = @children.dup
+          children[index] = new_child
+          self.class.new(@significant_bits, @entries, children)
+        end
+      end || self
     end
 
-    # Removes the given key/value pair and returns <tt>self</tt>
-    def remove!(key)
+    protected
+
+    def put!(key, value)
+      @entries[index_for(key)] = Entry.new(key, value)
       self
     end
 
     private
 
-    def initialize_copy(other)
-      @significant_bits = other.instance_eval{@significant_bits}
-      @entries = other.instance_eval{@entries}.dup
-      @children = other.instance_eval{@children}.dup
-    end
-
     def index_for(key)
-      (key.hash.abs >> @significant_bits) & 31
+      key.hash.abs & 31
+      # puts "#{key}##{key.object_id}:#{key.hash}"
+      # (key.hash.abs >> @significant_bits) & 31
     end
 
   end

data/lib/hamster/version.rb

@@ -1,5 +1,5 @@
 module Hamster
 
-  VERSION = "0.1.0".freeze
+  VERSION = "0.1.1".freeze
 
 end

data/spec/hamster/trie_spec.rb

@@ -13,12 +13,6 @@ module Hamster
       end
     end
 
-    it "returns values associated with existing keys" do
-      @expected_pairs.each do |key, value|
-        @trie.get(key).should == value
-      end
-    end
-
     it "is Enumerable" do
       Trie.is_a?(Enumerable)
     end
@@ -112,13 +106,13 @@ module Hamster
 
         describe "the original" do
 
-          it "returns values associated with existing keys" do
+          it "still has the original key/value pairs" do
             @expected_pairs.each do |key, value|
               @trie.get(key).should == value
             end
           end
 
-          it "has the original size" do
+          it "still has the original size" do
             @trie.size.should == @expected_pairs.size
           end
 
@@ -150,7 +144,7 @@ module Hamster
 
         describe "the original" do
 
-          it "returns values associated with existing keys" do
+          it "still has the original key/value pairs" do
             @expected_pairs.each do |key, value|
               @trie.get(key).should == value
             end
@@ -160,7 +154,7 @@ module Hamster
             @trie.has_key?("missing").should be_false
           end
 
-          it "has the original size" do
+          it "still has the original size" do
             @trie.size.should == @expected_pairs.size
           end
 
@@ -188,6 +182,13 @@ module Hamster
 
     describe "#remove" do
 
+      it "can be used successively to remove all key/value pairs" do
+        @expected_pairs.each do |key, value|
+          @trie = @trie.remove(key)
+        end
+        @trie.should be_empty
+      end
+
       describe "with existing keys" do
 
         before do
@@ -200,13 +201,13 @@ module Hamster
 
         describe "the original" do
 
-          it "returns values associated with existing keys" do
+          it "still has the original key/value pairs" do
             @expected_pairs.each do |key, value|
               @trie.get(key).should == value
             end
           end
 
-          it "has the original size" do
+          it "still has the original size" do
             @trie.size.should == @expected_pairs.size
           end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: hamster
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Simon Harris
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-23 00:00:00 +11:00
+date: 2009-10-24 00:00:00 +11:00
 default_executable: 
 dependencies: []