hamster 0.1.14 → 0.1.15

data/History.rdoc

@@ -1,3 +1,9 @@
+=== 0.1.15 / 2009-12-15
+
+* Implemented IO#to_list.
+
+* Implemented Enumerable#to_list.
+
 === 0.1.14 / 2009-12-14
 
 * List#reduce supports optional initial value.

data/README.rdoc

@@ -6,8 +6,6 @@ Hamster started out as an implementation of Hash Array Mapped Hashes (HAMT) for
 
 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:
 
-  require 'hamster'
-
   hash = Hamster.hash
 
   hash.put("Name", "Simon")
@@ -18,8 +16,6 @@ Persistent data structures have a really neat property: very efficient copy-on-w
 
 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:
 
-  require 'hamster'
-
   original = Hamster.hash
   copy = original.put("Name", "Simon")
 
@@ -28,8 +24,6 @@ Whoops! Remember, each call to <tt>#put</tt> creates an efficient copy containin
 
 The same goes for <tt>#remove</tt>:
 
-  require 'hamster'
-
   original = Hamster.hash
   original = original.put("Name", "Simon")
   copy = hash.remove("Name")
@@ -47,8 +41,6 @@ Moreover, because they're immutable, you can pass them around between objects, m
 
 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:
 
-  require 'hamster'
-
   hash = Hamster.hash
   (1..10000).each { |i| hash = hash.put(i, i) }  # => 0.05s
   (1..10000).each { |i| hash.get(i) }  # => 0.008s
@@ -67,8 +59,6 @@ Well, yes and no. The previous comparison wasn't really fair. Sure, if all you w
 
 A more realistic comparison might look like:
 
-  require 'hamster'
-
   hash = Hamster.hash
   (1..10000).each { |i| hash = hash.put(i, i) }  # => 0.05s
   (1..10000).each { |i| hash.get(i) }  # => 0.008s
@@ -97,6 +87,9 @@ And don't forget that even if threading isn't a concern for you, the safety prov
 
 Indeed I did.
 
+=== Sets
+
+
 === Lists
 
 Lists have a head--the value of the item at the head of the list--and a tail--containing the remaining items. For example:
@@ -126,17 +119,41 @@ The following code will only call <tt>prime?</tt> as many times as necessary to
 
 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
+  (10000..1000000).select { |i| prime?(i) }[0, 3]   # => 10s
 
-Besides <tt>Hamster.list</tt> there is <tt>Hamster.interval(from, to)</tt> and <tt>Hamster.stream { a_block }</tt>.
+Besides <tt>Hamster.list</tt> there are other ways to construct lists:
 
-<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>Hamster.interval(from, to)</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.
+<tt>Hamster.stream { ... }</tt> allows you to creates infinite lists. Each time a new value is required, the supplied block is called.
 
-=== Stacks
+You also get <tt>Enumerable#to_list</tt> so you can slowly transition from built-in collection classes to Hamster.
 
-=== Sets
+And finally, you also <tt>IO#to_list</tt> allowing you to lazily processes huge files. For example, imagine the following code to process a 10MB file:
+
+  File.open("my_10_mb_file.txt") do |io|
+    lines = []
+    io.each_line do |line|
+      break if lines.size == 10
+      lines << line.chomp.downcase.reverse
+    end
+  end
+
+How many times/how long did you read the code before it became apparent what the code actually did? Now compare that to the following:
+
+  File.open("my_10_mb_file.txt") do |io|
+    io.map(&:chomp).map(&:downcase).map(&:reverse)[0, 10]
+  end
+
+Unfortunately, though the second example reads nicely, it takes around 3 seconds to run--compared with 0.033 seconds for the first--even though we're only interested in the first 10 lines! However, using a little <tt>#to_list</tt> magic, we can get the running time down to 0.033 seconds!
+
+  File.open("my_10_mb_file.txt") do |io|
+    puts io.to_list.map(&:chomp).map(&:downcase).map(&:reverse).take(10)
+  end
+
+How is this even possible? It's possible because <tt>IO#to_list</tt> creates a lazy list whereby each line is only ever read and processed as needed, in effect converting it to the first example without all the syntactic, imperative, noise.
+
+=== Stacks
 
 == Disclaimer
 

data/lib/hamster.rb

@@ -2,4 +2,5 @@ require 'hamster/list'
 require 'hamster/stack'
 require 'hamster/set'
 require 'hamster/hash'
+require 'hamster/core_ext'
 require 'hamster/version'

data/lib/hamster/core_ext.rb

@@ -0,0 +1,2 @@
+require 'hamster/core_ext/enumerable'
+require 'hamster/core_ext/io'

data/lib/hamster/core_ext/enumerable.rb

@@ -0,0 +1,23 @@
+require 'hamster/list'
+
+module Hamster
+
+  module CoreExt
+
+    module Enumerable
+
+      def to_list
+        Hamster.list(self)
+      end
+
+    end
+
+  end
+
+end
+
+module Enumerable
+
+  include Hamster::CoreExt::Enumerable
+
+end

data/lib/hamster/core_ext/io.rb

@@ -0,0 +1,29 @@
+require 'hamster/list'
+
+module Hamster
+
+  module CoreExt
+
+    module IO
+
+      def to_list(sep = $/)
+        line = gets(sep)
+        if line
+          Stream.new(line) { to_list }
+        else
+          EmptyList
+        end
+
+      end
+
+    end
+
+  end
+
+end
+
+class IO
+
+  include Hamster::CoreExt::IO
+
+end

data/lib/hamster/list.rb

@@ -164,6 +164,22 @@ module Hamster
     end
     alias_method :detect, :find
 
+    def partition(&block)
+      return self unless block_given?
+      EmptyList.cons(reject(&block)).cons(filter(&block))
+    end
+
+    def append(other)
+      Stream.new(head) { tail.append(other) }
+    end
+    alias_method :concat, :append
+    alias_method :cat, :append
+    alias_method :+, :append
+
+    def reverse
+      reduce(EmptyList) { |list, item| list.cons(item) }
+    end
+
     def eql?(other)
       return false unless other.is_a?(List)
 
@@ -290,6 +306,13 @@ module Hamster
         self
       end
 
+      def append(other)
+        other
+      end
+      alias_method :concat, :append
+      alias_method :cat, :append
+      alias_method :+, :append
+
     end
 
   end

data/lib/hamster/version.rb

@@ -1,5 +1,5 @@
 module Hamster
 
-  VERSION = "0.1.14".freeze
+  VERSION = "0.1.15".freeze
 
 end

data/spec/hamster/core_ext/enumerable_spec.rb

@@ -0,0 +1,34 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+require 'hamster/core_ext/enumerable'
+
+describe Enumerable do
+
+  class TestEnumerable
+
+    include Enumerable
+
+    def initialize(*values)
+      @values = values
+    end
+
+    def each(&block)
+      @values.each(&block)
+    end
+
+  end
+
+  describe "#to_list" do
+
+    before do
+      enumerable = TestEnumerable.new("A", "B", "C")
+      @list = enumerable.to_list
+    end
+
+    it "returns an equivalent list" do
+      @list == Hamster.list("A", "B", "C")
+    end
+
+  end
+
+end

data/spec/hamster/core_ext/io_spec.rb

@@ -0,0 +1,17 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+require 'hamster/core_ext/io'
+
+describe IO do
+
+  describe "#to_list" do
+
+    it "returns an equivalent list" do
+      File.open(File.dirname(__FILE__) + "/io_spec.txt") do |io|
+        io.to_list.should == Hamster.list("A\n", "B\n", "C\n")
+      end
+    end
+
+  end
+
+end

data/spec/hamster/core_ext/io_spec.txt

@@ -0,0 +1,3 @@
+A
+B
+C

data/spec/hamster/hash/all_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   describe "#all?" do

data/spec/hamster/hash/any_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:any?, :exist?, :exists?].each do |method|

data/spec/hamster/hash/construction_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   describe ".hash" do

data/spec/hamster/hash/copying_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   before do

data/spec/hamster/hash/each_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   describe "#each" do

data/spec/hamster/hash/empty_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   describe "#empty?" do

data/spec/hamster/hash/eql_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:eql?, :==].each do |method|

data/spec/hamster/hash/filter_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:filter, :select, :find_all].each do |method|

data/spec/hamster/hash/get_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:get, :[]].each do |method|

data/spec/hamster/hash/has_key_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:has_key?, :key?, :include?, :member?].each do |method|

data/spec/hamster/hash/map_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:map, :collect].each do |method|

data/spec/hamster/hash/none_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   describe "#none?" do

data/spec/hamster/hash/put_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:put, :[]=].each do |method|

data/spec/hamster/hash/reduce_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:reduce, :inject, :fold].each do |method|

data/spec/hamster/hash/reject_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:reject, :delete_if].each do |method|

data/spec/hamster/hash/remove_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   describe "#remove" do

data/spec/hamster/hash/size_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/hash'
+
 describe Hamster::Hash do
 
   [:size, :length].each do |method|

data/spec/hamster/list/all_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
+require 'hamster/list'
+
 describe Hamster::List do
 
   describe "#all?" do