hamster 0.1.11 → 0.1.12

data/History.rdoc

@@ -1,3 +1,9 @@
+=== 0.1.12 / 2009-12-10
+
+* List methods are now lazy where feasible
+
+* Now works under Ruby >= 1.8.6
+
 === 0.1.8 / 2009-11-29
 
 * Add convenience constructors: List[], Set[], and Hash[]

data/README.rdoc

@@ -41,6 +41,8 @@ The same goes for <tt>#remove</tt>:
 
 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.
 
+Moreover, because they're immutable, you can pass them around between objects, methods, and functions and never worry about data corruption; no more defensive calls to <tt>collection.dup</tt>!
+
 == OK, that sounds mildly interesting. What's the downside--there's always a 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:
@@ -89,7 +91,7 @@ The <tt>Hamster::Hash</tt> version on the other hand was unchanged from the orig
 
 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 :)
+And don't forget that even if threading isn't a concern for you, the safety provided by immutability is worth it.
 
 == So, you mentioned Sets, Lists, and Stacks?
 
@@ -97,20 +99,49 @@ Indeed I did.
 
 === Lists
 
-list = Hamster.list(1, 2, 3)
+Lists have a head--the value of the item at the head of the list--and a tail--containing the remaining items. For example:
+
+  list = Hamster.list(1, 2, 3)
+
+  list.head    # => 1
+  list.tail    # => Hamster.list(2, 3)
+
+To add to a list you use <tt>#cons</tt>:
+
+  original = Hamster.list(1, 2, 3)
+  copy = original.cons(0)           # => Hamster.list(0, 1, 2, 3)
+
+Notice how modifying a list actually returns a new list. That's because Hamster lists are immutable. Thankfully, just like Hamster <tt>Set</tt> and <tt>Hash</tt>, they're also very efficient at making copies!
+
+Lists are, where possible, lazy. That is, they try to defer processing items until absolutely necessary. For example, given a crude function to detect prime numbers:
+
+  def prime?(n)
+    2.upto(Math.sqrt(n).round) { |i| return false  if n % i == 0 }
+    true
+  end
 
-list.head    # => 1
-list.tail    # => Hamster.list(2, 3)
+The following code will only call <tt>#prime?</tt> as many times as necessary to generate the first 3 prime numbers between 10000 and 1000000:
 
-def prime?(n)
-  2.upto(Math.sqrt(n).round) { |i| return false  if n % i == 0 }
-  true
-end
+  Hamster.interval(10000, 1000000).filter { |i| prime?(i) }.take(3)    # => 0.0009s
 
-Hamster.interval(10000, 1000000).filter { |i| prime?(i) }.take(3)
+Compare that to the conventional equivalent which needs to calculate all possible values in the range before taking the first 3:
+
+  (10000..1000000).select { |i| prime?(i) }[1, 3]   # => 10s
+
+Besides <tt>Hamster.list</tt> there is <tt>Hamster.interval(from, to)</tt> and <tt>Hamster.stream { a_block }</tt>.
+
+<tt>.interval</tt> (aliased as <tt>.range</tt>) creates a lazy list equivalent to a list containing all the values between <tt>from</tt> and <tt>to</tt> without actually creating a list that big.
+
+<tt>.stream</tt> allows you to creates infinite lists. Each time a new value is required, the supplied block is called.
 
 === Stacks
 
 === Sets
 
-=== Hash
+== Disclaimer
+
+Hamster started out as a spike to prove a point and has since morphed into something I actually use. My primary concern has been to round out the functionality with good test coverage and clean, readable code.
+
+Performance is pretty good--especially with lazy lists--but there are some things which need to be converted from recursive to iterative due to a lack of Tail-Call-Optimisation in Ruby. It's on the list ;-)
+
+Documentation is sparse but I've tried as best I can to write specs that reads as documentation. I've also tried to alias methods as their <tt>Enumerable</tt> equivalents where possible to make it easier for people to migrate code.

data/lib/hamster/hash.rb

@@ -3,7 +3,7 @@ require 'hamster/trie'
 module Hamster
 
   def self.hash(pairs = {})
-    pairs.reduce(Hash.new) { |hash, pair| hash.put(pair.first, pair.last) }
+    pairs.inject(Hash.new) { |hash, pair| hash.put(pair.first, pair.last) }
   end
 
   class Hash
@@ -51,13 +51,13 @@ module Hamster
     end
 
     def each
-      block_given? or return enum_for(__method__)
+      block_given? or return self
       @trie.each { |entry| yield(entry.key, entry.value) }
       self
     end
 
     def map
-      block_given? or return enum_for(:each)
+      block_given? or return self
       if empty?
         self
       else
@@ -73,7 +73,7 @@ module Hamster
     alias_method :inject, :reduce
 
     def filter
-      block_given? or return enum_for(__method__)
+      block_given? or return self
       trie = @trie.filter { |entry| yield(entry.key, entry.value) }
       if !trie.equal?(@trie)
         self.class.new(trie)
@@ -84,7 +84,7 @@ module Hamster
     alias_method :select, :filter
 
     def reject
-      block_given? or return enum_for(__method__)
+      block_given? or return self
       select { |key, value| !yield(key, value) }
     end
 
@@ -96,6 +96,8 @@ module Hamster
       end
       false
     end
+    alias_method :exist?, :any?
+    alias_method :exists?, :any?
 
     def all?
       if block_given?

data/lib/hamster/list.rb

@@ -3,7 +3,12 @@ module Hamster
   class << self
 
     def list(*items)
-      items.reverse.reduce(EmptyList) { |list, item| list.cons(item) }
+      items.reverse.inject(EmptyList) { |list, item| list.cons(item) }
+    end
+
+    def stream(&block)
+      block_given? or return EmptyList
+      Stream.new(yield) { stream(&block) }
     end
 
     def interval(from, to)
@@ -43,6 +48,7 @@ module Hamster
       block_given? or return self
       Stream.new(yield(head)) { tail.map(&block) }
     end
+    alias_method :collect, :map
 
     def reduce(memo, &block)
       block_given? or return memo
@@ -120,6 +126,14 @@ module Hamster
     end
     alias_method :clone, :dup
 
+    def to_a
+      reduce([]) { |ary, item| ary << item }
+    end
+
+    def inspect
+      to_a.inspect
+    end
+
     private
 
     def method_missing(name, *args, &block)
@@ -135,7 +149,7 @@ module Hamster
     # 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!.reduce(self) do |memo, char|
+      sequence.split(//).reverse!.inject(self) do |memo, char|
         case char
         when "a" then memo.head
         when "d" then memo.tail
@@ -206,6 +220,7 @@ module Hamster
       def map
         self
       end
+      alias_method :collect, :map
 
       def reduce(memo)
         memo

data/lib/hamster/set.rb

@@ -3,7 +3,7 @@ require 'hamster/trie'
 module Hamster
 
   def self.set(*items)
-    items.reduce(Set.new) { |set, item| set.add(item) }
+    items.inject(Set.new) { |set, item| set.add(item) }
   end
 
   class Set
@@ -45,13 +45,13 @@ module Hamster
     end
 
     def each
-      block_given? or return enum_for(__method__)
+      block_given? or return self
       @trie.each { |entry| yield(entry.key) }
       self
     end
 
     def map
-      block_given? or return enum_for(:each)
+      block_given? or return self
       if empty?
         self
       else
@@ -67,7 +67,7 @@ module Hamster
     alias_method :inject, :reduce
 
     def filter
-      block_given? or return enum_for(__method__)
+      block_given? or return self
       trie = @trie.filter { |entry| yield(entry.key) }
       if !trie.equal?(@trie)
         self.class.new(trie)
@@ -78,7 +78,7 @@ module Hamster
     alias_method :select, :filter
 
     def reject
-      block_given? or return enum_for(__method__)
+      block_given? or return self
       select { |item| !yield(item) }
     end
 
@@ -90,6 +90,8 @@ module Hamster
       end
       false
     end
+    alias_method :exist?, :any?
+    alias_method :exists?, :any?
 
     def all?
       if block_given?

data/lib/hamster/stack.rb

@@ -3,12 +3,12 @@ require 'hamster/list'
 module Hamster
 
   def self.stack
-    Stack.new
+    EmptyStack
   end
 
   class Stack
 
-    def initialize(list = Hamster.list)
+    def initialize(list)
       @list = list
     end
 
@@ -19,6 +19,7 @@ module Hamster
     def size
       @list.size
     end
+    alias_method :length, :size
 
     def top
       @list.head
@@ -30,15 +31,17 @@ module Hamster
 
     def pop
       list = @list.tail
-      if !list.equal?(@list)
-        self.class.new(list)
+      if list.empty?
+        EmptyStack
       else
-        self
+        self.class.new(list)
       end
     end
 
     def eql?(other)
-      other.is_a?(self.class) && @list.eql?(other.instance_eval{@list})
+      return true if other.equal?(self)
+      return false unless other.class.equal?(self.class)
+      @list.eql?(other.instance_eval{@list})
     end
     alias_method :==, :eql?
 
@@ -49,4 +52,6 @@ module Hamster
 
   end
 
+  EmptyStack = Stack.new(Hamster.list)
+
 end

data/lib/hamster/version.rb

@@ -1,5 +1,5 @@
 module Hamster
 
-  VERSION = "0.1.11".freeze
+  VERSION = "0.1.12".freeze
 
 end

data/spec/hamster/hash/any_spec.rb

@@ -2,55 +2,59 @@ require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
 describe Hamster::Hash do
 
-  describe "#any?" do
+  [:any?, :exist?, :exists?].each do |method|
 
-    describe "when empty" do
+    describe "##{method}" do
 
-      before do
-        @hash = Hamster.hash
-      end
+      describe "when empty" do
 
-      it "with a block returns false" do
-        @hash.any? {}.should be_false
-      end
+        before do
+          @hash = Hamster.hash
+        end
+
+        it "with a block returns false" do
+          @hash.send(method) {}.should be_false
+        end
+
+        it "with no block returns false" do
+          @hash.send(method).should be_false
+        end
 
-      it "with no block returns false" do
-        @hash.any?.should be_false
       end
 
-    end
+      describe "when not empty" do
 
-    describe "when not empty" do
+        before do
+          @hash = Hamster.hash("A" => "aye", "B" => "bee", "C" => "see", nil => "NIL")
+        end
 
-      before do
-        @hash = Hamster.hash("A" => "aye", "B" => "bee", "C" => "see", nil => "NIL")
-      end
+        describe "with a block" do
 
-      describe "with a block" do
+          [
+            ["A", "aye"],
+            ["B", "bee"],
+            ["C", "see"],
+            [nil, "NIL"],
+          ].each do |pair|
 
-        [
-          ["A", "aye"],
-          ["B", "bee"],
-          ["C", "see"],
-          [nil, "NIL"],
-        ].each do |pair|
+            it "returns true if the block ever returns true (#{pair.inspect})" do
+              @hash.send(method) { |key, value| key == pair.first && value == pair.last }.should be_true
+            end
 
-          it "returns true if the block ever returns true (#{pair.inspect})" do
-            @hash.any? { |key, value| key == pair.first && value == pair.last }.should be_true
-          end
+            it "returns false if the block always returns false" do
+              @hash.send(method) { |key, value| key == "D" && value == "dee" }.should be_false
+            end
 
-          it "returns false if the block always returns false" do
-            @hash.any? { |key, value| key == "D" && value == "dee" }.should be_false
           end
 
         end
 
-      end
+        describe "with no block" do
 
-      describe "with no block" do
+          it "returns true" do
+            @hash.send(method).should be_true
+          end
 
-        it "returns true" do
-          @hash.any?.should be_true
         end
 
       end

data/spec/hamster/hash/each_spec.rb

@@ -22,10 +22,10 @@ describe Hamster::Hash do
 
     end
 
-    describe "with no block (external iteration)" do
+    describe "with no block" do
 
-      it "returns an enumerator over all key/value pairs" do
-        Hash[*@hash.each.to_a.flatten].should == {"A" => "aye", "B" => "bee", "C" => "see"}
+      it "returns self" do
+        @hash.each.should equal(@hash)
       end
 
     end

data/spec/hamster/hash/filter_spec.rb

@@ -43,11 +43,11 @@ describe Hamster::Hash do
         describe "with no block" do
 
           before do
-            @enumerator = @original.send(method)
+            @result = @original.send(method)
           end
 
-          it "returns an enumerator over the values" do
-            Hamster.hash(@enumerator.to_a).should == Hamster.hash("A" => "aye", "B" => "bee", "C" => "see")
+          it "returns self" do
+            @result.should equal(@original)
           end
 
         end

data/spec/hamster/hash/map_spec.rb

@@ -44,15 +44,11 @@ describe Hamster::Hash do
         describe "with no block" do
 
           before do
-            @enumerator = @original.send(method)
+            @result = @original.send(method)
           end
 
-          it "preserves the original values" do
-            @original.should == Hamster.hash("A" => "aye", "B"  => "bee", "C" => "see")
-          end
-
-          it "returns an enumerator over the key value pairs" do
-            Hamster.hash(@enumerator.to_a).should == @original
+          it "returns self" do
+            @result.should equal(@original)
           end
 
         end

data/spec/hamster/hash/reject_spec.rb

@@ -41,11 +41,11 @@ describe Hamster::Hash do
       describe "with no block" do
 
         before do
-          @enumerator = @original.reject
+          @result = @original.reject
         end
 
-        it "returns an enumerator over the values" do
-          Hamster.hash(@enumerator.to_a).should == Hamster.hash("A" => "aye", "B" => "bee", "C" => "see")
+        it "returns self" do
+          @result.should equal(@original)
         end
 
       end

data/spec/hamster/list/construction_spec.rb

@@ -38,6 +38,35 @@ describe Hamster do
 
   end
 
+  describe ".stream" do
+
+    describe "with no block" do
+
+      before do
+        @stream = Hamster.stream
+      end
+
+      it "returns an empty list" do
+        @stream.should == Hamster.list
+      end
+
+    end
+
+    describe "with a block" do
+
+      before do
+        count = 0
+        @stream = Hamster.stream { count += 1 }
+      end
+
+      it "repeatedly calls the block" do
+        @stream.take(5).should == Hamster.list(1, 2, 3, 4, 5)
+      end
+
+    end
+
+  end
+
   [:interval, :range].each do |method|
 
     describe ".#{method}" do

data/spec/hamster/list/inspect_spec.rb

@@ -0,0 +1,27 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+describe Hamster::List do
+
+  describe "#inspect" do
+
+    [
+      [],
+      ["A"],
+      ["A", "B", "C"],
+    ].each do |values|
+
+      describe "on #{values.inspect}" do
+
+        list = Hamster.list(*values)
+
+        it "returns #{values.inspect}" do
+          list.inspect.should == values.inspect
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/spec/hamster/list/map_spec.rb

@@ -2,36 +2,40 @@ require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
 describe Hamster::List do
 
-  describe "#map" do
+  [:map, :collect].each do |method|
 
-    [
-      [[], []],
-      [["A"], ["a"]],
-      [["A", "B", "C"], ["a", "b", "c"]],
-    ].each do |values, result|
+    describe "##{method}" do
 
-      describe "on #{values.inspect}" do
+      [
+        [[], []],
+        [["A"], ["a"]],
+        [["A", "B", "C"], ["a", "b", "c"]],
+      ].each do |values, result|
 
-        list = Hamster.list(*values)
+        describe "on #{values.inspect}" do
 
-        describe "with a block" do
+          list = Hamster.list(*values)
 
-          it "returns #{result}" do
-            list.map { |item| item.downcase }.should == Hamster.list(*result)
-          end
+          describe "with a block" do
+
+            it "returns #{result}" do
+              list.send(method) { |item| item.downcase }.should == Hamster.list(*result)
+            end
+
+            it "is lazy" do
+              count = 0
+              list.send(method) { |item| count += 1 }
+              count.should <= 1
+            end
 
-          it "is lazy" do
-            count = 0
-            list.map { |item| count += 1 }
-            count.should <= 1
           end
 
-        end
+          describe "without a block" do
 
-        describe "without a block" do
+            it "returns self" do
+              list.send(method).should == list
+            end
 
-          it "returns self" do
-            list.map.should == list
           end
 
         end

data/spec/hamster/list/to_a_spec.rb

@@ -0,0 +1,27 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+describe Hamster::List do
+
+  describe "#to_a" do
+
+    [
+      [],
+      ["A"],
+      ["A", "B", "C"],
+    ].each do |values|
+
+      describe "on #{values.inspect}" do
+
+        list = Hamster.list(*values)
+
+        it "returns #{values.inspect}" do
+          list.to_a.should == values
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/spec/hamster/set/any_spec.rb

@@ -2,54 +2,58 @@ require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
 describe Hamster::Set do
 
-  describe "#any?" do
+  [:any?, :exist?, :exists?].each do |method|
 
-    describe "when empty" do
+    describe "##{method}" do
 
-      before do
-        @set = Hamster.set
-      end
+      describe "when empty" do
 
-      it "with a block returns false" do
-        @set.any? {}.should be_false
-      end
+        before do
+          @set = Hamster.set
+        end
+
+        it "with a block returns false" do
+          @set.send(method) {}.should be_false
+        end
+
+        it "with no block returns false" do
+          @set.send(method).should be_false
+        end
 
-      it "with no block returns false" do
-        @set.any?.should be_false
       end
 
-    end
+      describe "when not empty" do
 
-    describe "when not empty" do
+        describe "with a block" do
 
-      describe "with a block" do
+          before do
+            @set = Hamster.set("A", "B", "C", nil)
+          end
 
-        before do
-          @set = Hamster.set("A", "B", "C", nil)
-        end
+          ["A", "B", "C", nil].each do |value|
 
-        ["A", "B", "C", nil].each do |value|
+            it "returns true if the block ever returns true (#{value.inspect})" do
+              @set.send(method) { |item| item == value }.should be_true
+            end
 
-          it "returns true if the block ever returns true (#{value.inspect})" do
-            @set.any? { |item| item == value }.should be_true
           end
 
-        end
+          it "returns false if the block always returns false" do
+            @set.send(method) { |item| item == "D" }.should be_false
+          end
 
-        it "returns false if the block always returns false" do
-          @set.any? { |item| item == "D" }.should be_false
         end
 
-      end
+        describe "with no block" do
 
-      describe "with no block" do
+          it "returns true if any value is truthy" do
+            Hamster.set(nil, false, true, "A").send(method).should be_true
+          end
 
-        it "returns true if any value is truthy" do
-          Hamster.set(nil, false, true, "A").any?.should be_true
-        end
+          it "returns false if all values are falsey" do
+            Hamster.set(nil, false).send(method).should be_false
+          end
 
-        it "returns false if all values are falsey" do
-          Hamster.set(nil, false).any?.should be_false
         end
 
       end

data/spec/hamster/set/each_spec.rb

@@ -23,10 +23,10 @@ describe Hamster::Set do
 
     end
 
-    describe "with no block (external iteration)" do
+    describe "with no block" do
 
-      it "returns an enumerator over all key value pairs" do
-        Set[*@set.each.to_a.flatten].should == Set["A", "B", "C"]
+      it "returns self" do
+        @set.each.should equal(@set)
       end
 
     end

data/spec/hamster/set/filter_spec.rb

@@ -43,11 +43,11 @@ describe Hamster::Set do
         describe "with no block" do
 
           before do
-            @enumerator = @original.send(method)
+            @result = @original.send(method)
           end
 
-          it "returns an enumerator over the values" do
-            Hamster.set(*@enumerator.to_a).should == Hamster.set("A", "B", "C")
+          it "returns self" do
+            @result.should equal(@original)
           end
 
         end

data/spec/hamster/set/map_spec.rb

@@ -44,15 +44,11 @@ describe Hamster::Set do
         describe "with no block" do
 
           before do
-            @enumerator = @original.send(method)
+            @result = @original.send(method)
           end
 
-          it "preserves the original values" do
-            @original.should == Hamster.set("A", "B", "C")
-          end
-
-          it "returns an enumerator over the values" do
-            Hamster.set(*@enumerator.to_a).should == @original
+          it "returns self" do
+            @result.should equal(@original)
           end
 
         end

data/spec/hamster/set/reject_spec.rb

@@ -41,11 +41,11 @@ describe Hamster::Set do
       describe "with no block" do
 
         before do
-          @enumerator = @original.reject
+          @result = @original.reject
         end
 
-        it "returns an enumerator over the values" do
-          Hamster.set(*@enumerator.to_a).should == Hamster.set("A", "B", "C")
+        it "returns self" do
+          @result.should equal(@original)
         end
 
       end

data/spec/hamster/stack/copying_spec.rb

@@ -6,18 +6,14 @@ describe Hamster::Stack do
     @stack = Hamster.stack.push("A").push("B").push("C")
   end
 
-  describe "#dup" do
+  [:dup, :clone].each do |method|
 
-    it "returns self" do
-      @stack.dup.should equal(@stack)
-    end
-
-  end
+    describe "##{method}" do
 
-  describe "#clone" do
+      it "returns self" do
+        @stack.send(method).should equal(@stack)
+      end
 
-    it "returns self" do
-      @stack.clone.should equal(@stack)
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: hamster
 version: !ruby/object:Gem::Version 
-  version: 0.1.11
+  version: 0.1.12
 platform: ruby
 authors: 
 - Simon Harris
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-08 00:00:00 +11:00
+date: 2009-12-10 00:00:00 +11:00
 default_executable: 
 dependencies: []
 
@@ -59,7 +59,7 @@ files:
 - spec/hamster/list/filter_spec.rb
 - spec/hamster/list/head_spec.rb
 - spec/hamster/list/include_spec.rb
-- spec/hamster/list/lazy_spec.rb
+- spec/hamster/list/inspect_spec.rb
 - spec/hamster/list/map_spec.rb
 - spec/hamster/list/reduce_spec.rb
 - spec/hamster/list/reject_spec.rb
@@ -67,6 +67,7 @@ files:
 - spec/hamster/list/tail_spec.rb
 - spec/hamster/list/take_spec.rb
 - spec/hamster/list/take_while_spec.rb
+- spec/hamster/list/to_a_spec.rb
 - spec/hamster/set/add_spec.rb
 - spec/hamster/set/all_spec.rb
 - spec/hamster/set/any_spec.rb
@@ -108,7 +109,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      version: 1.9.1
+      version: 1.8.6
   version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 

data/spec/hamster/list/lazy_spec.rb

@@ -1,21 +0,0 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
-
-describe Hamster::List do
-
-  describe "laziness" do
-
-    def prime?(n)
-      2.upto(Math.sqrt(n).round) { |i| return false if n % i == 0 }
-      true
-    end
-
-    it "primes" do
-      numbers = Hamster.interval(10000, 1000000)
-      primes = numbers.filter { |i| prime?(i) }
-      primes.take(3)
-
-    end
-
-  end
-
-end