hamster 0.1.0

data/History.rdoc

@@ -0,0 +1,3 @@
+=== 0.1.0 / 2009-10-21
+
+* Initial version

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Simon Harris
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,5 @@
+= Hamster
+
+Hash Array Mapped Tries (HAMT) for Ruby.
+
+See http://lamp.epfl.ch/papers/idealhashtrees.pdf

data/Rakefile

@@ -0,0 +1,5 @@
+Dir["tasks/**/*.rb"].each do |task_file|
+  require task_file
+end
+
+task :default => [ :spec ]

data/lib/hamster.rb

@@ -0,0 +1,3 @@
+require 'hamster/entry'
+require 'hamster/trie'
+require 'hamster/version'

data/lib/hamster/entry.rb

@@ -0,0 +1,18 @@
+module Hamster
+
+  class Entry
+
+    attr_reader :key, :value
+
+    def initialize(key, value)
+      @key = key
+      @value = value
+    end
+
+    def has_key?(key)
+      @key == key
+    end
+
+  end
+
+end

data/lib/hamster/trie.rb

@@ -0,0 +1,101 @@
+module Hamster
+
+  class Trie
+
+    include Enumerable
+
+    def initialize(significant_bits = 0)
+      @significant_bits = significant_bits
+      @entries = []
+      @children = []
+    end
+
+    # Returns the number of key-value pairs in the trie.
+    def size
+      # TODO: This definitely won't scale!
+      to_a.size
+    end
+
+    # Returns <tt>true</tt> if the trie contains no key-value pairs.
+    def empty?
+      size == 0
+    end
+
+    # Returns <tt>true</tt> if the given key is present in the trie.
+    def has_key?(key)
+      !! 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>
+    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 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
+          child.put(key, value)
+        else
+          self.class.new(@significant_bits + 5).put!(key, value)
+        end
+      else
+        @entries[index] = Entry.new(key, value)
+      end
+      self
+    end
+
+    # Retrieves the value corresponding to the given key. If not found, returns <tt>nil</tt>.
+    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
+        end
+      end
+    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)
+      has_key?(key) or return self
+      dup.remove!(key)
+    end
+
+    # Removes the given key/value pair and returns <tt>self</tt>
+    def remove!(key)
+      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
+    end
+
+  end
+
+end

data/lib/hamster/version.rb

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

data/spec/hamster/trie_spec.rb

@@ -0,0 +1,266 @@
+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 "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
+
+    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 "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
+
+        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 "returns values associated with existing keys" 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 "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
+
+      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 "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
+
+        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

data/spec/spec.opts

@@ -0,0 +1,3 @@
+--colour
+--loadby random
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+
+# Support running specs with "rake spec" and "spec"
+lib = File.expand_path(File.dirname(__FILE__) + '/../lib')
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'hamster'

data/tasks/spec.rb

@@ -0,0 +1,6 @@
+require "spec/rake/spectask"
+
+desc "Run specifications"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts << "--options" << "spec/spec.opts" if File.exists?("spec/spec.opts")
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: hamster
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Simon Harris
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-23 00:00:00 +11:00
+default_executable: 
+dependencies: []
+
+description: Hash Array Mapped Tries (HAMT) for Ruby
+email: haruki.zaemon@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- History.rdoc
+- TODO
+- LICENSE
+files: 
+- lib/hamster/entry.rb
+- lib/hamster/trie.rb
+- lib/hamster/version.rb
+- lib/hamster.rb
+- spec/hamster/trie_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- tasks/spec.rb
+- Rakefile
+- README.rdoc
+- History.rdoc
+- TODO
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/harukizaemon/hamster
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Hash Array Mapped Tries (HAMT) for Ruby
+test_files: []
+