hamster 0.1.16 → 0.1.17

data/History.rdoc

@@ -1,3 +1,33 @@
+=== 0.1.17 / 2010-01-02
+
+* Alias #empty? as #null?
+
+* Implement List#split_at.
+
+* Implement List.iterate.
+
+* Implement List#cycle.
+
+* Implement List.replicate.
+
+* Implement List.repeat.
+
+* Simplify List#take.
+
+* Simplify any?, all?, and none?
+
+* Re-write List#one? to be less complex.
+
+* Add Set#to_list.
+
+* Implement List#zip.
+
+* Implement Set#grep.
+
+* Implement Set#uniq (aliased as #nub).
+
+* Implement List#grep.
+
 === 0.1.16 / 2009-12-30
 
 * Ensure streams cache results.

data/README.rdoc

@@ -2,7 +2,7 @@
 
 Hamster started out as an implementation of Hash Array Mapped Trees (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.
 
-== Huh?
+== What are persistent data structures?
 
 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:
 
@@ -14,7 +14,7 @@ Persistent data structures have a really neat property: very efficient copy-on-w
 
 == Double Huh? That's not much use!
 
-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:
+Whoops! Unlike Ruby's standard library, each call to <tt>Hamster::hash#put</tt> creates an efficient copy containing the modifications, leaving the original unmodified. Thus, 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:
 
   original = Hamster.hash
   copy = original.put("Name", "Simon")
@@ -33,9 +33,9 @@ The same goes for <tt>#remove</tt>:
 
 == Oh, I get it. Cool. But I still don't understand why I should care?
 
-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.
+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 memory 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>!
 
-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>!
+For an interesting read on why immutability is a good thing, take a look at Matthias Felleisen's Function Objects presnetation (http://www.ccs.neu.edu/home/matthias/Presentations/ecoop2004.pdf).
 
 == OK, that sounds mildly interesting. What's the downside--there's always a downside?
 
@@ -127,6 +127,12 @@ Besides <tt>Hamster.list</tt> there are other ways to construct lists:
 
 <tt>Hamster.stream { ... }</tt> allows you to creates infinite lists. Each time a new value is required, the supplied block is called.
 
+<tt>Hamster.repeat(x)</tt> creates an infinite list with x the value for every element.
+
+<tt>Hamster.replicate(n, x)</tt> creates a list of size n with x the value for every element.
+
+<tt>Hamster.iterate(x) { ... }</tt> creates an infinite list where the first item is calculated by applying the block on the initial argument, the second item by applying the function on the previous result and so on.
+
 You also get <tt>Enumerable#to_list</tt> so you can slowly transition from built-in collection classes to Hamster.
 
 And finally, you get <tt>IO#to_list</tt> allowing you to lazily processes huge files. For example, imagine the following code to process a 100MB file:
@@ -159,6 +165,6 @@ How is this even possible? It's possible because <tt>IO#to_list</tt> creates a l
 
 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 unfortunately had to be converted from recursive to iterative due to a lack of Tail-Call-Optimisation in Ruby, making them a little less readable than I would otherwise have preferred.
+Performance is pretty good--especially with lazy lists--but there are some things which unfortunately had to be converted from recursive to iterative due to a lack of Tail-Call-Optimisation in Ruby, making them a little less readable, and a little more memory hungry, than I would otherwise have preferred.
 
-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.
+Documentation is sparse but I've tried as best I can to write specs that read 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

@@ -20,6 +20,7 @@ module Hamster
     def empty?
       @trie.empty?
     end
+    alias_method :null?, :empty?
 
     def has_key?(key)
       @trie.has_key?(key)

data/lib/hamster/list.rb

@@ -21,6 +21,18 @@ module Hamster
     end
     alias_method :range, :interval
 
+    def repeat(item)
+      Sequence.new(item)
+    end
+
+    def replicate(number, item)
+      Sequence.new(item).take(number)
+    end
+
+    def iterate(item, &block)
+      Stream.new(item) { iterate(yield(item), &block) }
+    end
+
   end
 
   module List
@@ -28,6 +40,7 @@ module Hamster
     def empty?
       false
     end
+    alias_method :null?, :empty?
 
     def size
       reduce(0) { |memo, item| memo.succ }
@@ -100,11 +113,8 @@ module Hamster
     end
 
     def take(number)
-      if number > 0
-        Stream.new(head) { tail.take(number - 1) }
-      else
-        EmptyList
-      end
+      return EmptyList unless number > 0
+      Stream.new(head) { tail.take(number - 1) }
     end
 
     def drop(number)
@@ -123,52 +133,33 @@ module Hamster
     alias_method :member?, :include?
 
     def any?
-      if block_given?
-        each { |item| return true if yield(item) }
-      else
-        each { |item| return true if item }
-      end
+      return any? { |item| item } unless block_given?
+      each { |item| return true if yield(item) }
       false
     end
     alias_method :exist?, :any?
     alias_method :exists?, :any?
 
     def all?
-      if block_given?
-        each { |item| return false unless yield(item) }
-      else
-        each { |item| return false unless item }
-      end
+      return all? { |item| item } unless block_given?
+      each { |item| return false unless yield(item) }
       true
     end
 
     def none?
-      if block_given?
-        each { |item| return false if yield(item) }
-      else
-        each { |item| return false if item }
-      end
+      return none? { |item| item } unless block_given?
+      each { |item| return false if yield(item) }
       true
     end
 
-    def one?
-      found_one = false
-      if block_given?
-        each do |item|
-          if yield(item)
-            return false if found_one
-            found_one = true
-          end
-        end
-      else
-        each do |item|
-          if item
-            return false if found_one
-            found_one = true
-          end
-        end
+    def one?(&block)
+      return one? { |item| item } unless block_given?
+      list = self
+      while !list.empty?
+        return list.tail.none?(&block) if yield(list.head)
+        list = list.tail
       end
-      found_one
+      false
     end
 
     def find
@@ -205,6 +196,22 @@ module Hamster
     end
     alias_method :max, :maximum
 
+    def grep(pattern, &block)
+      filter { |item| pattern === item }.map(&block)
+    end
+
+    def zip(other)
+      Stream.new(EmptyList.cons(other.head).cons(head)) { tail.zip(other.tail) }
+    end
+
+    def cycle
+      Stream.new(head) { tail.append(self.cycle) }
+    end
+
+    def split_at(number)
+      EmptyList.cons(drop(number)).cons(take(number))
+    end
+
     def eql?(other)
       return false unless other.is_a?(List)
 
@@ -270,7 +277,7 @@ module Hamster
 
     attr_reader :head, :tail
 
-    def initialize(head, tail)
+    def initialize(head, tail = self)
       @head = head
       @tail = tail
     end
@@ -317,6 +324,7 @@ module Hamster
       def empty?
         true
       end
+      alias_method :null?, :empty?
 
       def map
         self
@@ -349,6 +357,15 @@ module Hamster
       alias_method :cat, :append
       alias_method :+, :append
 
+      def zip(other)
+        return super unless other.empty?
+        self
+      end
+
+      def cycle
+        self
+      end
+
     end
 
   end

data/lib/hamster/set.rb

@@ -1,4 +1,5 @@
 require 'hamster/trie'
+require 'hamster/list'
 
 module Hamster
 
@@ -15,6 +16,7 @@ module Hamster
     def empty?
       @trie.empty?
     end
+    alias_method :null?, :empty?
 
     def size
       @trie.size
@@ -114,6 +116,10 @@ module Hamster
       true
     end
 
+    def grep(pattern, &block)
+      filter { |item| pattern === item }.map(&block)
+    end
+
     def eql?(other)
       other.is_a?(self.class) && @trie.eql?(other.instance_eval{@trie})
     end
@@ -123,12 +129,18 @@ module Hamster
       self
     end
     alias_method :clone, :dup
+    alias_method :uniq, :dup
+    alias_method :nub, :dup
 
     def to_a
       reduce([]) { |a, item| a << item }
     end
     alias_method :entries, :to_a
 
+    def to_list
+      reduce(Hamster.list) { |list, item| list.cons(item) }
+    end
+
   end
 
 end

data/lib/hamster/version.rb

@@ -1,5 +1,5 @@
 module Hamster
 
-  VERSION = "0.1.16".freeze
+  VERSION = "0.1.17".freeze
 
 end

data/spec/hamster/hash/empty_spec.rb

@@ -4,16 +4,20 @@ require 'hamster/hash'
 
 describe Hamster::Hash do
 
-  describe "#empty?" do
+  [:empty?, :null?].each do |method|
 
-    [
-      [[], true],
-      [["A" => "aye"], false],
-      [["A" => "aye", "B" => "bee", "C" => "see"], false],
-    ].each do |pairs, result|
+    describe "##{method}" do
+
+      [
+        [[], true],
+        [["A" => "aye"], false],
+        [["A" => "aye", "B" => "bee", "C" => "see"], false],
+      ].each do |pairs, result|
+
+        it "returns #{result} for #{pairs.inspect}" do
+          Hamster.hash(*pairs).send(method).should == result
+        end
 
-      it "returns #{result} for #{pairs.inspect}" do
-        Hamster.hash(*pairs).empty?.should == result
       end
 
     end

data/spec/hamster/list/all_spec.rb

@@ -8,20 +8,16 @@ describe Hamster::List do
 
     describe "doesn't run out of stack space on a really big" do
 
-      before do
-        @interval = Hamster.interval(0, 10000)
-      end
-
       it "stream" do
-        @list = @interval
+        @list = Hamster.interval(0, 10000)
       end
 
       it "list" do
-        @list = @interval.reduce(Hamster.list) { |list, i| list.cons(i) }
+        @list = (0..10000).reduce(Hamster.list) { |list, i| list.cons(i) }
       end
 
       after do
-        @interval.all? { true }
+        @list.all? { true }
       end
 
     end

data/spec/hamster/list/any_spec.rb

@@ -10,20 +10,16 @@ describe Hamster::List do
 
       describe "doesn't run out of stack space on a really big" do
 
-        before do
-          @interval = Hamster.interval(0, 10000)
-        end
-
         it "stream" do
-          @list = @interval
+          @list = Hamster.interval(0, 10000)
         end
 
         it "list" do
-          @list = @interval.reduce(Hamster.list) { |list, i| list.cons(i) }
+          @list = (0..10000).reduce(Hamster.list) { |list, i| list.cons(i) }
         end
 
         after do
-          @interval.any? { false }
+          @list.any? { false }
         end
 
       end

data/spec/hamster/list/append_spec.rb

@@ -10,16 +10,12 @@ describe Hamster::List do
 
       describe "doesn't run out of stack space on a really big" do
 
-        before do
-          @interval = Hamster.interval(0, 10000)
-        end
-
         it "stream" do
-          @a = @b = @interval
+          @a = @b = Hamster.interval(0, 10000)
         end
 
         it "list" do
-          @a = @b = @interval.reduce(Hamster.list) { |list, i| list.cons(i) }
+          @a = @b = (0..10000).reduce(Hamster.list) { |list, i| list.cons(i) }
         end
 
         after do

data/spec/hamster/list/construction_spec.rb

@@ -45,11 +45,11 @@ describe Hamster do
     describe "with no block" do
 
       before do
-        @stream = Hamster.stream
+        @list = Hamster.stream
       end
 
       it "returns an empty list" do
-        @stream.should == Hamster.list
+        @list.should == Hamster.list
       end
 
     end
@@ -58,11 +58,11 @@ describe Hamster do
 
       before do
         count = 0
-        @stream = Hamster.stream { count += 1 }
+        @list = Hamster.stream { count += 1 }
       end
 
       it "repeatedly calls the block" do
-        @stream.take(5).should == Hamster.list(1, 2, 3, 4, 5)
+        @list.take(5).should == Hamster.list(1, 2, 3, 4, 5)
       end
 
     end
@@ -74,15 +74,51 @@ describe Hamster do
     describe ".#{method}" do
 
       before do
-        @interval = Hamster.send(method, "A", "D")
+        @list = Hamster.send(method, "A", "D")
       end
 
       it "is equivalent to a list with explicit values" do
-        @interval.should == Hamster.list("A", "B", "C", "D")
+        @list.should == Hamster.list("A", "B", "C", "D")
       end
 
     end
 
   end
 
+  describe ".repeat" do
+
+    before do
+      @list = Hamster.repeat("A")
+    end
+
+    it "returns an infinite list with specified value for each element" do
+      @list.take(5).should == Hamster.list("A", "A", "A", "A", "A")
+    end
+
+  end
+
+  describe ".replicate" do
+
+    before do
+      @list = Hamster.replicate(5, "A")
+    end
+
+    it "returns a list with the specified value repeated the specified number of times" do
+      @list.should == Hamster.list("A", "A", "A", "A", "A")
+    end
+
+  end
+
+  describe ".iterate" do
+
+    before do
+      @list = Hamster.iterate(1) { |item| item * 2 }
+    end
+
+    it "returns an infinite list where the first item is calculated by applying the block on the initial argument, the second item by applying the function on the previous result and so on" do
+      @list.take(10).should == Hamster.list(1, 2, 4, 8, 16, 32, 64, 128, 256, 512)
+    end
+
+  end
+
 end