hamster 0.1.1 → 0.1.2

data/History.rdoc

@@ -1,3 +1,11 @@
+=== 0.1.2 / 2009-10-23
+
+* Fixed all but one outstanding issue with #remove
+
+=== 0.1.1 / 2009-10-23
+
+* Added #remove
+
 === 0.1.0 / 2009-10-21
 
 * Initial version

data/README.rdoc

@@ -1,15 +1,15 @@
 = Hamster
 
-Hash Array Mapped Tries (HAMT) for Ruby (See http://lamp.epfl.ch/papers/idealhashtrees.pdf).
+Hash Array Mapped Tries (HAMT) for Ruby (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:
+HAMTs are hash tables with one really neat property: their structure enables you to perform very efficient copy-on-write operations. For example:
 
 	trie = Hamster::Trie.new
 
 	trie.put("Name", "Simon")
-	trie.get("Name")						# => nil
+	trie.get("Name")          # => nil
 
 Huh? That's not much use!
 
@@ -18,7 +18,7 @@ Remember, each instance of a trie is immutable. #put creates an efficient copy c
 	trie = Hamster::Trie.new
 
 	trie = trie.put("Name", "Simon")
-	trie.get("Name")									# => "Simon"
+	trie.get("Name")                 # => "Simon"
 
 The same goes for remove:
 
@@ -27,12 +27,18 @@ The same goes for remove:
 	trie = trie.put("Name", "Simon")
 	trie = trie.put("Gender", "Male")
 	trie = trie.remove("Name")
-	trie.get("Name")									# => nil
-	trie.get("Gender")								# => "Male"
+	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.
+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.
+
+Thats nice but I don't really have multi-threading issues.
+
+OK, how about transactional memory:
+
+	Need an example
 
 So what's the downside?
 

data/lib/hamster/trie.rb

@@ -77,38 +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)
+      remove!(key) || self
+    end
+
+    protected
+
+    def put!(key, value)
+      @entries[index_for(key)] = Entry.new(key, value)
+      self
+    end
+    
+    def 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)
+        self.class.new(@significant_bits, entries, @children) unless size == 1
       elsif child
-        new_child = child.remove(key)
+        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
-
-    protected
-
-    def put!(key, value)
-      @entries[index_for(key)] = Entry.new(key, value)
-      self
+      end
     end
 
     private
 
     def index_for(key)
-      key.hash.abs & 31
-      # puts "#{key}##{key.object_id}:#{key.hash}"
-      # (key.hash.abs >> @significant_bits) & 31
+      (key.hash.abs >> @significant_bits) & 31
     end
 
   end

data/lib/hamster/version.rb

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

data/spec/hamster/trie/each_spec.rb

@@ -0,0 +1,51 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+module Hamster
+
+  describe Trie do
+
+    describe "#each" do
+
+      before do
+        @trie = Trie.new
+        @expected_pairs = { "A" => "aye", "B" => "bee", "C" => "sea" }
+        @expected_pairs.each do |key, value|
+          @trie = @trie.put(key, value)
+        end
+      end
+
+      describe "with a block (internal iteration)" do
+
+        it "returns self" do
+          @trie.each {}.should == @trie
+        end
+
+        it "yields all key value pairs" do
+          actual_pairs = {}
+          @trie.each do |key, value|
+            actual_pairs[key] = value
+          end
+          actual_pairs.should == @expected_pairs
+        end
+
+      end
+
+      describe "with no block (external iteration)" do
+
+        it "returns an enumerator over all key value pairs" do
+          actual_pairs = {}
+          enum = @trie.each
+          loop do
+            key, value = enum.next
+            actual_pairs[key] = value
+          end
+          actual_pairs.should == @expected_pairs
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/spec/hamster/trie/empty_spec.rb

@@ -0,0 +1,22 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+module Hamster
+
+  describe Trie do
+
+    describe "#empty?" do
+
+      it "initially returns true" do
+        Trie.new.should be_empty
+      end
+
+      it "returns false once items have been added" do
+        trie = Trie.new.put("A", "aye")
+        trie.should_not be_empty
+      end
+
+    end
+
+  end
+
+end

data/spec/hamster/trie/enumerable_spec.rb

@@ -0,0 +1,13 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+module Hamster
+
+  describe Trie do
+
+    it "is Enumerable" do
+      Trie.ancestors.should include(Enumerable)
+    end
+
+  end
+
+end

data/spec/hamster/trie/get_spec.rb

@@ -0,0 +1,26 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+module Hamster
+
+  describe Trie do
+
+    describe "#get" do
+
+      before do
+        @trie = Trie.new
+        @trie = @trie.put("A", "aye")
+      end
+
+      it "returns the value for an existing key" do
+        @trie.get("A").should == "aye"
+      end
+
+      it "returns nil for a non-existing key" do
+        @trie.get("B").should be_nil
+      end
+
+    end
+
+  end
+
+end

data/spec/hamster/trie/has_key_spec.rb

@@ -0,0 +1,25 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+module Hamster
+
+  describe Trie do
+
+    describe "#has_key?" do
+
+      before do
+        @trie = Trie.new.put("A", "aye")
+      end
+
+      it "returns true for an existing key" do
+        @trie.has_key?("A").should be_true
+      end
+
+      it "returns false for a non-existing key" do
+        @trie.has_key?("B").should be_false
+      end
+
+    end
+
+  end
+
+end

data/spec/hamster/trie/put_spec.rb

@@ -0,0 +1,97 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+module Hamster
+
+  describe Trie do
+
+    describe "#put" do
+
+      describe "with a key/value pair that already exists" do
+
+        before do
+          @original = Trie.new.put("A", "aye").put("B", "bee")
+          @copy = @original.put("A", "yes")
+        end
+
+        it "returns a modified copy" do
+          @copy.should_not === @original
+        end
+
+        describe "the original" do
+
+          it "still has the original key/value pairs" do
+            @original.get("A").should == "aye"
+            @original.get("B").should == "bee"
+          end
+
+          it "still has the original size" do
+            @original.size.should == 2
+          end
+
+        end
+
+        describe "the modified copy" do
+
+          it "has the new key/value pairs" do
+            @copy.get("A").should == "yes"
+            @copy.get("B").should == "bee"
+          end
+
+          it "has the original size" do
+            @copy.size == 2
+          end
+
+        end
+
+      end
+
+      describe "with a key/value pair that doesn't exist" do
+
+        before do
+          @original = Trie.new.put("A", "aye")
+          @copy = @original.put("B", "bee")
+        end
+
+        it "returns a modified copy" do
+          @copy.should_not === @original
+        end
+
+        describe "the original" do
+
+          it "still has the original key/value pairs" do
+            @original.get("A").should == "aye"
+          end
+
+          it "doesn't contain the new key/value pair" do
+            @original.has_key?("B").should be_false
+          end
+
+          it "still has the original size" do
+            @original.size.should == 1
+          end
+
+        end
+
+        describe "the modified copy" do
+
+          it "has the original key/value pairs" do
+            @copy.get("A").should == "aye"
+          end
+
+          it "has the new key/value pair" do
+            @copy.get("B").should == "bee"
+          end
+
+          it "size is increased by one" do
+            @copy.size.should == 2
+          end
+
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/spec/hamster/trie/remove_spec.rb

@@ -0,0 +1,115 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+module Hamster
+
+  describe Trie do
+
+    describe "#remove" do
+
+      describe "with an existing key" do
+
+        before do
+          @original = Trie.new.put("A", "aye").put("B", "bee")
+          @copy = @original.remove("A")
+        end
+
+        it "returns a modified copy" do
+          @copy.should_not === @original
+        end
+
+        describe "the original" do
+
+          it "still has the original key/value pairs" do
+            @original.get("A").should == "aye"
+            @original.get("B").should == "bee"
+          end
+
+          it "still has the original size" do
+            @original.size.should == 2
+          end
+
+        end
+
+        describe "the modified copy" do
+
+          it "has all but the removed original key/value pairs" do
+            @copy.get("B").should == "bee"
+          end
+
+          it "doesn't have the removed key" do
+            @copy.has_key?("A").should be_false
+          end
+
+          it "has a size one less than the original" do
+            @copy.size.should == 1
+          end
+
+        end
+
+      end
+
+      describe "with non-existing keys" do
+
+        before do
+          @original = Trie.new.put("A", "aye")
+          @copy = @original.remove("missing")
+        end
+
+        it "returns self" do
+          @copy.should === @original
+        end
+
+        describe "the original" do
+
+          it "still has the original key/value pairs" do
+            @original.get("A").should == "aye"
+          end
+
+          it "still has the original size" do
+            @original.size.should == 1
+          end
+
+        end
+
+      end
+
+      describe "with keys of the same hash value" do
+
+        class Key
+          def hash; 1; end
+        end
+
+        def number_of_tries
+          ObjectSpace.garbage_collect
+          ObjectSpace.each_object(Trie) {}
+        end
+
+        before do
+          @a = Key.new
+          @b = Key.new
+          @original = Trie.new.put(@a, "aye").put(@b, "bee")
+        end
+        
+        it "no longer provides access to the removed key" do
+          copy = @original.remove(@b)
+          copy.has_key?(@b).should be_false
+        end
+
+        it "provides access to the remaining keys" do
+          copy = @original.remove(@a)
+          copy.get(@b).should == "bee"
+        end
+
+        it "cleans up empty tries" do
+          number_of_tries_before = number_of_tries
+          copy = @original.remove(@b)
+          number_of_tries.should == number_of_tries_before + 1
+        end
+
+      end
+
+    end
+
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: hamster
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Simon Harris
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-24 00:00:00 +11:00
+date: 2009-10-25 00:00:00 +11:00
 default_executable: 
 dependencies: []
 
@@ -29,7 +29,13 @@ files:
 - lib/hamster/trie.rb
 - lib/hamster/version.rb
 - lib/hamster.rb
-- spec/hamster/trie_spec.rb
+- spec/hamster/trie/each_spec.rb
+- spec/hamster/trie/empty_spec.rb
+- spec/hamster/trie/enumerable_spec.rb
+- spec/hamster/trie/get_spec.rb
+- spec/hamster/trie/has_key_spec.rb
+- spec/hamster/trie/put_spec.rb
+- spec/hamster/trie/remove_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
 - tasks/spec.rb

data/spec/hamster/trie_spec.rb

@@ -1,267 +0,0 @@
-require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
-
-module Hamster
-
-  describe Trie do
-
-    before do
-      @expected_pairs = {}
-      @trie = Trie.new
-      ("A".."Z").each do |letter|
-        @expected_pairs.store(letter, letter.downcase)
-        @trie = @trie.put(letter, letter.downcase)
-      end
-    end
-
-    it "is Enumerable" do
-      Trie.is_a?(Enumerable)
-    end
-
-    describe "#empty?" do
-
-      it "initially returns true" do
-        Trie.new.should be_empty
-      end
-
-      it "returns false once items have been added" do
-        @trie.should_not be_empty
-      end
-
-    end
-
-    describe "#each" do
-
-      describe "with a block (internal iteration)" do
-
-        it "returns self" do
-          @trie.each {}.should == @trie
-
-        end
-
-        it "yields all key value pairs" do
-          actual_pairs = {}
-          @trie.each do |key, value|
-            actual_pairs[key] = value
-          end
-          actual_pairs.should == @expected_pairs
-        end
-
-      end
-
-      describe "with no block (external iteration)" do
-
-        it "returns an enumerator over all key value pairs" do
-          actual_pairs = {}
-          enum = @trie.each
-          loop do
-            key, value = enum.next
-            actual_pairs[key] = value
-          end
-          actual_pairs.should == @expected_pairs
-        end
-
-      end
-
-    end
-
-    describe "#get" do
-
-      it "returns values associated with existing keys" do
-        @expected_pairs.each do |key, value|
-          @trie.get(key).should == value
-        end
-      end
-
-      it "returns nil for non-existing" do
-        @trie.get("missing").should be_nil
-      end
-
-    end
-
-    describe "#has_key?" do
-
-      it "returns true for existing keys" do
-        @expected_pairs.each_key do |key|
-          @trie.has_key?(key).should be_true
-        end
-      end
-
-      it "returns false for non-existing keys" do
-        @trie.has_key?("missing").should be_false
-      end
-
-    end
-
-    describe "#put" do
-
-      describe "with key/value pairs that already exists" do
-
-        before do
-          @copy = @trie.put("J", "jay")
-        end
-
-        it "returns a modified copy" do
-          @copy.should_not === @trie
-        end
-
-        describe "the original" do
-
-          it "still has the original key/value pairs" do
-            @expected_pairs.each do |key, value|
-              @trie.get(key).should == value
-            end
-          end
-
-          it "still has the original size" do
-            @trie.size.should == @expected_pairs.size
-          end
-
-        end
-
-        describe "the modified copy" do
-
-          it "has the new key/value pair" do
-            @copy.get("J").should == "jay"
-          end
-
-          it "has the original size" do
-            @trie.size.should == @expected_pairs.size
-          end
-
-        end
-
-      end
-
-      describe "with key/value pairs that don't exist"
-
-        before do
-          @copy = @trie.put("missing", "in action")
-        end
-
-        it "returns a modified copy" do
-          @copy.should_not === @trie
-        end
-
-        describe "the original" do
-
-          it "still has the original key/value pairs" do
-            @expected_pairs.each do |key, value|
-              @trie.get(key).should == value
-            end
-          end
-
-          it "doesn't contain the new key/value pair" do
-            @trie.has_key?("missing").should be_false
-          end
-
-          it "still has the original size" do
-            @trie.size.should == @expected_pairs.size
-          end
-
-        end
-
-        describe "the modified copy" do
-
-          it "returns values associated with existing keys" do
-            @expected_pairs.each do |key, value|
-              @copy.get(key).should == value
-            end
-          end
-
-          it "has the new key/value pair" do
-            @copy.get("missing").should == "in action"
-          end
-
-          it "size is increased by 1" do
-            @copy.size.should == @expected_pairs.size + 1
-          end
-
-        end
-
-    end
-
-    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
-          @copy = @trie.remove("J")
-        end
-
-        it "returns a modified copy" do
-          @copy.should_not === @trie
-        end
-
-        describe "the original" do
-
-          it "still has the original key/value pairs" do
-            @expected_pairs.each do |key, value|
-              @trie.get(key).should == value
-            end
-          end
-
-          it "still has the original size" do
-            @trie.size.should == @expected_pairs.size
-          end
-
-        end
-
-        describe "the modified copy" do
-
-          it "doesn't have the removed key" do
-            @copy.has_key?("J").should be_false
-          end
-
-          it "returns values associated with all but the removed key" do
-            @expected_pairs.each do |key, value|
-              next if key == "J"
-              @copy.get(key).should == value
-            end
-          end
-
-          it "has one less than the original" do
-            @copy.size.should == @expected_pairs.size - 1
-          end
-
-        end
-
-      end
-
-      describe "with non-existing keys" do
-
-        before do
-          @copy = @trie.remove("missing")
-        end
-
-        it "returns self" do
-          @copy.should === @trie
-        end
-
-        describe "the original" do
-
-          it "returns values associated with existing keys" do
-            @expected_pairs.each do |key, value|
-              @trie.get(key).should == value
-            end
-          end
-
-          it "has the original size" do
-            @trie.size.should == @expected_pairs.size
-          end
-
-        end
-
-      end
-
-    end
-
-  end
-
-end