immutable 0.1.0 → 0.2.0

data/README.md

@@ -3,37 +3,47 @@ immutable - immutable data structures for Ruby
 
 This project aims to provide immutable data structures for Ruby.
 
-Currently, immutable provides the following classes:
+Currently, immutable provides the following classes and modules:
 
+* Immutable::Foldable
 * Immutable::List
 * Immutable::Map
+* Immutable::Promise
+* Immutable::Stream
+* Immutable::Queue
 
 Install
 ========================
 
 	$ gem install immutable
 
+Documentation
+========================
+
+* [API Reference](http://rubydoc.info/github/shugo/immutable/frames)
+
 License
 ========================
-	(The MIT License)
-
-	Copyright (c) 2012 Shugo Maeda
-
-	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.
+
+(The MIT License)
+
+Copyright (c) 2012 Shugo Maeda
+
+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/benchmark/benchmark_queue.rb

@@ -0,0 +1,41 @@
+require 'benchmark'
+require 'immutable/queue'
+require 'immutable/map'
+
+TIMES = 100000
+key_size = 10
+
+def snoc(queue)
+  TIMES.times do
+    queue.snoc(0)
+  end
+end
+
+def head(queue)
+  TIMES.times do
+    queue.head
+  end
+end
+
+def tail(queue)
+  TIMES.times do
+    queue.tail
+  end
+end
+
+def run(bm, queue, num, method)
+  bm.report("#{method} for #{num}-elements queue") do
+    send(method, queue)
+  end
+end
+
+Benchmark.bmbm do |bm|
+  queues = [10, 1000, 100000].inject(Immutable::Map.empty) { |m, n|
+    m.insert(n, (1..n).inject(Immutable::Queue.empty, &:snoc))
+  }
+  for method in [:snoc, :head, :tail]
+    for num, queue in queues
+      run(bm, queue, num, method)
+    end
+  end
+end

data/lib/immutable.rb

@@ -0,0 +1,9 @@
+# +Immutable+ is a namespace for immutable data structures.
+module Immutable
+end
+
+require "immutable/list"
+require "immutable/map"
+require "immutable/promise"
+require "immutable/stream"
+require "immutable/queue"

data/lib/immutable/foldable.rb

@@ -0,0 +1,29 @@
+module Immutable
+  module Foldable
+    # Returns the number of elements in +self+. May be zero.
+    #
+    # @return [Integer] the number of elements in +self+.
+    def length
+      foldl(0) { |x, y| x + 1 }
+    end
+
+    # Returns the number of elements in +self+. May be zero.
+    #
+    # @return [Integer] the number of elements in +self+.
+    alias size length
+
+    # Computes the sum of the numbers in +self+.
+    #
+    # @return [#+] the sum of the numbers.
+    def sum
+      foldl(0, &:+)
+    end
+
+    # Computes the product of the numbers in +self+.
+    #
+    # @return [#*] the product of the numbers.
+    def product
+      foldl(1, &:*)
+    end
+  end
+end

data/lib/immutable/list.rb

@@ -1,121 +1,167 @@
-# -*- tailcall-optimization: true; trace-instruction: false -*-
+require "immutable/foldable"
 
 module Immutable
-  # <code>Immutable::List</code> represents an immutable list.
+  # +Immutable::List+ represents an immutable list.
   #
-  # <code>Immutable::List</code> is an abstract class and
-  # <code>Immutable::List.[]</code> should be used instead of
-  # <code>Immutable::List.new</code>. For example:
+  # +Immutable::List+ is an abstract class and
+  # {Immutable::List.[]} should be used instead of
+  # {Immutable::List.new}. For example:
   #
   #   include Immutable
   #   p List[]      #=> List[]
   #   p List[1, 2]  #=> List[1, 2]
   #
-  # <code>Immutable::Nil</code> represents an empty list, and
-  # <code>Immutable::Cons</code> represents a cons cell, which is a node in
+  # +Immutable::Nil+ represents an empty list, and
+  # +Immutable::Cons+ represents a cons cell, which is a node in
   # a list. For example:
   #
   #   p Nil                    #=> List[]
   #   p Cons[1, Cons[2, Nil]]  #=> List[1, 2]
   class List
+    include Enumerable
+    include Foldable
+
     class EmptyError < StandardError
       def initialize(msg = "list is empty")
         super(msg)
       end
     end
 
-    # Returns a new list populated with the given objects.
-    def self.[](*args)
-      from_array(args)
+    # Creates a new list populated with the given objects.
+    #
+    # @param [Array<Object>] elements the elements of the list.
+    # @return [List] the new list.
+    def self.[](*elements)
+      from_array(elements)
     end
 
-    # Converts the given array +ary+ to a list.
+    # Converts the given array to a list.
+    #
+    # @param [Array, #reverse_each] ary the array to convert.
+    # @return [List] the list converted from +ary+.
     def self.from_array(ary)
       ary.reverse_each.inject(Nil) { |x, y|
         Cons.new(y, x)
       }
     end
 
-    # Converts +enum+ to a list. +enum+ should respond to <code>each</code>.
+    # Converts the given Enumerable object to a list.
+    #
+    # @param [#inject] enum the Enumerable object to convert.
+    # @return [List] the list converted from +enum+.
     def self.from_enum(enum)
       enum.inject(Nil) { |x, y|
         Cons.new(y, x)
       }.reverse
     end
 
+    # Calls +block+ once for each element in +self+.
+    def each(&block)
+    end
+
     # Appends two lists +self+ and +xs+.
+    #
+    # @param [List] xs the list to append.
+    # @return [List] the new list.
     def +(xs)
       foldr(xs) { |y, ys| Cons[y, ys] }
     end
 
+    # Returns whether +self+ equals to +xs+.
+    #
+    # @param [List] xs the list to compare.
+    # @return [true, false] +true+ if +self+ equals to +xs+; otherwise,
+    # +false+.
+    def ==(xs)
+      # this method should be overriden
+    end
+
     # Returns the first element of +self+. If +self+ is empty,
-    # <code>Immutable::List::EmptyError</code> is raised.
+    # +Immutable::List::EmptyError+ is raised.
+    #
+    # @return [Object] the first element of +self+.
     def head
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
     # Returns the first element of +self+. If +self+ is empty,
-    # <code>Immutable::List::EmptyError</code> is raised.
+    # +Immutable::List::EmptyError+ is raised.
+    #
+    # @return [Object] the first element of +self+.
     def first
       head
     end
 
     # Returns the last element of +self+. If +self+ is empty,
-    # <code>Immutable::List::EmptyError</code> is raised.
+    # +Immutable::List::EmptyError+ is raised.
+    #
+    # @return [Object] the last element of +self+.
     def last
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
-    # Returns the element after the head of +self+. If +self+ is empty,
-    # <code>Immutable::List::EmptyError</code> is raised.
+    # Returns the elements after the head of +self+. If +self+ is empty,
+    # +Immutable::List::EmptyError+ is raised.
+    #
+    # @return [List] the elements after the head of +self+.
     def tail
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
-    # Returns all the element of +self+ except the last one.
-    # If +self+ is empty, <code>Immutable::List::EmptyError</code> is
+    # Returns all the elements of +self+ except the last one.
+    # If +self+ is empty, +Immutable::List::EmptyError+ is
     # raised.
+    #
+    # @return [List] the elements of +self+ except the last one.
     def init
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
-    # Returns <code>true</code> if +self+ is empty.
+    # Returns whether +self+ is empty.
+    #
+    # @return [true, false] +true+ if +self+ is empty; otherwise, +false+.
     def empty?
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
-    # Returns <code>true</code> if +self+ is empty.
+    # Returns whether +self+ is empty.
+    #
+    # @return [true, false] +true+ if +self+ is empty; otherwise, +false+.
     def null?
       empty?
     end
 
-    # Returns the number of elements in +self+. May be zero.
-    def length
-      foldl(0) { |x, y| x + 1 }
-    end
-
-    alias size length
-
     # Returns the list obtained by applying the given block to each element
     # in +self+.
+    #
+    # @return [List] the obtained list.
     def map
       foldr(Nil) { |x, xs| Cons[yield(x), xs] }
     end
 
     # Returns the elements of +self+ in reverse order.
+    #
+    # @return [List] the reversed list.
     def reverse
       foldl(Nil) { |x, y| Cons[y, x] }
     end
 
-    # Inserts +xs+ in between the lists in +self+.
-    def intersperse(xs)
-      raise ScriptError, "this method should be overriden"
+    # Returns a new list obtained by inserting +sep+ in between the elements
+    # of +self+.
+    #
+    # @param [Object] sep the object to insert between elements.
+    # @return [List] the new list.
+    def intersperse(sep)
+      # this method should be overriden
     end
 
-    # Inserts +xs+ in between the lists in +self+ and concatenates the
-    # result.
-    # <code>xss.intercalate(xs)</code> is equivalent to
-    # <code>xss.intersperse(xs).flatten</code>.
+    # Returns a new list obtained by inserting +xs+ in between the lists in
+    # +self+ and concatenates the result.
+    # +xss.intercalate(xs)+ is equivalent to
+    # +xss.intersperse(xs).flatten+.
+    #
+    # @param [List] xs the list to insert between lists.
+    # @return [List] the new list.
     def intercalate(xs)
       intersperse(xs).flatten
     end
@@ -124,78 +170,91 @@ module Immutable
     # 
     #   p List[List[1, 2, 3], List[4, 5, 6]].transpose
     #   #=> List[List[1, 4], List[2, 5], List[3, 6]]
+    #
+    # @return [List] the transposed list.
     def transpose
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
+    end
+
+    # Returns the list of all subsequences of +self+.
+    #
+    # @return [List<List>] the list of subsequences.
+    def subsequences
+      Cons[List[], nonempty_subsequences]
     end
 
     # Reduces +self+ using +block+ from right to left. +e+ is used as the
     # starting value. For example:
     #
     #   List[1, 2, 3].foldr(9) { |x, y| x + y } #=> 1 - (2 - (3 - 9)) = -7
+    #
+    # @param [Object] e the start value.
+    # @return [Object] the reduced value.
     def foldr(e, &block)
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
     # Reduces +self+ using +block+ from right to left. If +self+ is empty,
-    # <code>Immutable::List::EmptyError</code> is raised.
+    # +Immutable::List::EmptyError+ is raised.
+    #
+    # @return [Object] the reduced value.
     def foldr1(&block)
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
     # Reduces +self+ using +block+ from left to right. +e+ is used as the
     # starting value. For example:
     #
     #   List[1, 2, 3].foldl(9) { |x, y| x + y } #=> ((9 - 1) - 2) - 3 = 3
+    #
+    # @param [Object] e the start value.
+    # @return [Object] the reduced value.
     def foldl(e, &block)
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
     # Reduces +self+ using +block+ from left to right. If +self+ is empty,
-    # <code>Immutable::List::EmptyError</code> is raised.
+    # +Immutable::List::EmptyError+ is raised.
+    #
+    # @return [Object] the reduced value.
     def foldl1(&block)
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
     # Concatenates a list of lists.
+    #
+    # @return [List] the concatenated list.
     def flatten
       foldr(Nil) { |x, xs| x + xs }
     end
 
-    # An alias of <code>flatten</code>.
     alias concat flatten
 
     # Returns the list obtained by concatenating the results of the given
     # block for each element in +self+.
+    #
+    # @return [List] the obtained list.
     def flat_map
       foldr(Nil) { |x, xs| yield(x) + xs }
     end
 
-    # An alias of <code>flat_map</code>.
     alias concat_map flat_map
 
-    # An alias of <code>flat_map</code>.
     alias bind flat_map
 
-    # Computes the sum of the numbers in +self+.
-    def sum
-      foldl(0, &:+)
-    end
-
-    # Computes the product of the numbers in +self+.
-    def product
-      foldl(1, &:*)
-    end
-
     # Builds a list from the seed value +e+ and the given block. The block
-    # takes a seed value and returns <code>nil</code> if the seed should
-    # unfold to the empty list, or returns <code>[a, b]</code>, where
-    # <code>a</code> is the head of the list and <code>b</code> is the next
+    # takes a seed value and returns +nil+ if the seed should
+    # unfold to the empty list, or returns +[a, b]+, where
+    # +a+ is the head of the list and +b+ is the next
     # seed from which to unfold the tail.  For example:
     #
     #   xs = List.unfoldr(3) { |x| x == 0 ? nil : [x, x - 1] }
     #   p xs #=> List[3, 2, 1]
     #
-    # <code>unfoldr</code> is the dual of <code>foldr</code>.
+    # +unfoldr+ is the dual of +foldr+.
+    #
+    # @param [Object] e the seed value.
+    # @return [List] the list built from the seed value and the block.
     def self.unfoldr(e, &block)
       x = yield(e)
       if x.nil?
@@ -206,40 +265,68 @@ module Immutable
       end
     end
 
-    # Returns the first +n+ elements of +self+, or +self+ itself if
-    # <code>n > self.length</code>.
-    def take(n)
-      raise ScriptError, "this method should be overriden"
+    # Returns the +n+th element of +self+. If +n+ is out of range, +nil+ is
+    # returned.
+    #
+    # @return [Object] the +n+th element.
+    def [](n)
+      # this method should be overriden
     end
 
+    # Returns the first +n+ elements of +self+, or all the elements of
+    # +self+ if +n > self.length+.
+    #
+    # @param [Integer] n the number of elements to take.
+    # @return [List] the first +n+ elements of +self+.
+    def take(n)
+      # this method should be overriden
+    end
 
     # Returns the suffix of +self+ after the first +n+ elements, or
-    # <code>List[]</code> if <code>n > self.length</code>.
+    # +List[]+ if +n > self.length+.
+    #
+    # @param [Integer] n the number of elements to drop.
+    # @return [List] the suffix of +self+ after the first +n+ elements.
     def drop(n)
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
     # Returns the longest prefix of the elements of +self+ for which +block+
     # evaluates to true.
+    #
+    # @return [List] the prefix of the elements of +self+.
     def take_while(&block)
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
     # Returns the suffix remaining after
-    # <code>self.take_while(&block)</code>.
+    # +self.take_while(&block)+.
+    #
+    # @return [List] the suffix of the elements of +self+.
     def drop_while(&block)
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
+    end
+
+    # Returns +self+.
+    #
+    # @return [List] +self+.
+    def to_list
+      self
     end
 
     # Returns the first element in +self+ for which the given block
     # evaluates to true.  If such an element is not found, it
-    # returns <code>nil</code>.
+    # returns +nil+.
+    #
+    # @return [Object] the found element.
     def find(&block)
-      raise ScriptError, "this method should be overriden"
+      # this method should be overriden
     end
 
     # Returns the elements in +self+ for which the given block evaluates to
     # true.
+    #
+    # @return [List] the elements that satisfies the condition.
     def filter
       foldr(Nil) { |x, xs|
         if yield(x)
@@ -249,12 +336,38 @@ module Immutable
         end
       }
     end
+
+    # Takes zero or more lists and returns a new list in which each element
+    # is an array of the corresponding elements of +self+ and the input
+    # lists.
+    #
+    # @param [Array<List>] xss the input lists.
+    # @return [List] the new list.
+    def zip(*xss)
+      # this method should be overriden
+    end
+
+    # Takes zero or more lists and returns the list obtained by applying the
+    # given block to an array of the corresponding elements of +self+ and
+    # the input lists.
+    # +xs.zip_with(*yss, &block)+ is equivalent to
+    # +xs.zip(*yss).map(&block)+.
+    #
+    # @param [Array<List>] xss the input lists.
+    # @return [List] the new list.
+    def zip_with(*xss, &block)
+      # this method should be overriden
+    end
   end
 
+  # +Immutable::Nil+ represents an empty list.
   Nil = List.new
 
+  # +Immutable::Cons+ represents a cons cell.
   class Cons < List
-    # Creates a list obtained by prepending +head+ to the list +tail+.
+    # Creates a new list obtained by prepending +head+ to the list +tail+.
+    #
+    # @return [Cons] the new list.
     def self.[](head, tail = Nil)
       self.new(head, tail)
     end
@@ -329,6 +442,14 @@ module Immutable
       end
     end
 
+    def Nil.each
+    end
+
+    def each(&block)
+      yield(@head)
+      @tail.each(&block)
+    end
+
     def Nil.foldl(e)
       e
     end
@@ -345,8 +466,12 @@ module Immutable
       @tail.foldl(@head, &block)
     end
 
+    def Nil.==(xs)
+      equal?(xs)
+    end
+
     def ==(xs)
-      if xs.empty?
+      if !xs.is_a?(List) || xs.empty?
         false
       else
         @head == xs.head && @tail == xs.tail
@@ -392,6 +517,31 @@ module Immutable
       end
     end
 
+    def Nil.nonempty_subsequences
+      List[]
+    end
+
+    def nonempty_subsequences
+      yss = @tail.nonempty_subsequences.foldr(List[]) { |xs, xss|
+        Cons[xs, Cons[Cons[@head, xs], xss]]
+      }
+      Cons[List[@head], yss]
+    end
+
+    def Nil.[](n)
+      nil
+    end
+
+    def [](n)
+      if n < 0
+        nil
+      elsif n == 0
+        head
+      else
+        tail[n - 1]
+      end
+    end
+
     def Nil.take(n)
       Nil
     end
@@ -451,5 +601,25 @@ module Immutable
         @tail.find(&block)
       end
     end
+
+    def Nil.zip(*xss)
+      Nil
+    end
+
+    def zip(*xss)
+      heads = xss.map { |xs| xs.null? ? nil : xs.head }
+      tails = xss.map { |xs| xs.null? ? Nil : xs.tail }
+      Cons[[head, *heads], tail.zip(*tails)]
+    end
+
+    def Nil.zip_with(*xss, &block)
+      Nil
+    end
+
+    def zip_with(*xss, &block)
+      heads = xss.map { |xs| xs.null? ? nil : xs.head }
+      tails = xss.map { |xs| xs.null? ? Nil : xs.tail }
+      Cons[yield(head, *heads), tail.zip_with(*tails, &block)]
+    end
   end
 end