hamster 1.0.1.pre.rc2 → 1.0.1.pre.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a12201961b658581cc147e8a0c99fdc7003bf3b0
-  data.tar.gz: 3f24be00255e640a0afcefd374f6e3d16e619e5c
+  metadata.gz: f3c8822d3a3758de0e490808c2012795a7a0de79
+  data.tar.gz: 1295b432e023a4c840d17fb9ca8a1500b97db0f0
 SHA512:
-  metadata.gz: abd019d8bcc64d60d75d734a8ee0e08e549ab3662b2e1638f25afb331a3fa7981b0f45f571625bc61f2a36b17bbce44c0a862aa4586f95f9949949ddc26dc1c0
-  data.tar.gz: 283b36da83e8dda6ab822e430eb2503d7abdf7be6cb142e0c217052acbd2cafcac52c0833e2a156018436cf6cb86b947c7c10a76a5dcfa4b9ab8247a88d6d35d
+  metadata.gz: 91e4df28a78d5aea2d423e03f8c6be123abae2f17ef67c7b6481ccaa20dc309d61b3d2ee864901cf9446fcb5d637ed5330f7622457de8ba0c74346089d06fec7
+  data.tar.gz: e379456f35778c21b8e37ea1525d20f520c5323acade1568a74deff7b950765d70acd4ad8e6889acf22421615bb75953e6631bc8372918460b6bbf991d511487

data/lib/hamster.rb

@@ -1,10 +1,10 @@
 require "hamster/core_ext"
 require "hamster/immutable"
 require "hamster/list"
-require "hamster/stack"
-require "hamster/queue"
+require "hamster/deque"
 require "hamster/hash"
 require "hamster/set"
 require "hamster/vector"
+require "hamster/sorted_set"
 require "hamster/mutable_hash"
 require "hamster/version"

data/lib/hamster/core_ext.rb

@@ -1,3 +1,2 @@
 require "hamster/core_ext/enumerable"
-require "hamster/core_ext/enumerator"
 require "hamster/core_ext/io"

data/lib/hamster/core_ext/enumerable.rb

@@ -1,21 +1,21 @@
 require "hamster/list"
 
-module Hamster
-  module CoreExt
-    module Enumerable
-      def self.included(base)
-        base.class_eval do
-          def to_list
-            list = EmptyList
-            reverse_each { |item| list = list.cons(item) }
-            list
-          end
-        end
-      end
+# Ruby's built-in `Enumerable` module.
+# @see http://www.ruby-doc.org/core/Enumerable.html
+module Enumerable
+  # Return a new {Hamster::List} populated with the items in this `Enumerable` object.
+  # @return [List]
+  def to_list
+    # use destructive operations to build up a new list, like Common Lisp's NCONC
+    # this is a very fast way to build up a linked list
+    list = tail = Hamster::Cons.allocate
+    each do |item|
+      new_node = Hamster::Cons.allocate
+      new_node.instance_variable_set(:@head, item)
+      tail.instance_variable_set(:@tail, new_node)
+      tail = new_node
     end
+    tail.instance_variable_set(:@tail, Hamster::EmptyList)
+    list.tail
   end
-end
-
-module Enumerable
-  include Hamster::CoreExt::Enumerable
-end
+end

data/lib/hamster/core_ext/io.rb

@@ -1,23 +1,21 @@
 require "hamster/list"
-require "English"
 
-module Hamster
-  module CoreExt
-    module IO
-      def to_list(sep = $INPUT_RECORD_SEPARATOR)
-        Stream.new do
-          line = gets(sep)
-          if line
-            Sequence.new(line, to_list)
-          else
-            EmptyList
-          end
-        end
+# Ruby's built-in `IO` class.
+# @see http://www.ruby-doc.org/core/IO.html
+class IO
+  # Return a lazy list of "records" read from this IO stream.
+  # "Records" are delimited by `$/`, the global input record separator string.
+  # By default, it is `"\n"`, a newline.
+  #
+  # @return [List]
+  def to_list(sep = $/) # global input record separator
+    Hamster::LazyList.new do
+      line = gets(sep)
+      if line
+        Hamster::Cons.new(line, to_list)
+      else
+        EmptyList
       end
     end
   end
 end
-
-class IO
-  include Hamster::CoreExt::IO
-end

data/lib/hamster/deque.rb

@@ -0,0 +1,229 @@
+require "forwardable"
+require "hamster/immutable"
+require "hamster/list"
+
+module Hamster
+  def self.deque(*items)
+    items.empty? ? EmptyDeque : Deque.new(items)
+  end
+
+  # A `Deque` (or double-ended queue) is an ordered, sequential collection of objects,
+  # which allows elements to be efficiently added and removed at the front and end of
+  # the sequence. Retrieving the elements at the front and end is also efficient. This
+  # makes `Deque` perfect for use as an immutable queue *or* stack.
+  #
+  # A `Deque` differs from a {Vector} in that vectors allow indexed access to any
+  # element in the collection. `Deque`s only allow access to the first and last
+  # element. But adding and removing from the ends of a `Deque` is faster than
+  # adding and removing from the ends of a {Vector}.
+  #
+  # To create a new `Deque`:
+  #
+  #     Hamster.deque('a', 'b', 'c')
+  #     Hamster::Deque.new([:first, :second, :third])
+  #     Hamster::Deque[1, 2, 3, 4, 5]
+  #
+  # Or you can start with an empty deque and build it up:
+  #
+  #     Hamster::Deque.empty.push('b').push('c').unshift('a')
+  #
+  # Like all Hamster collections, `Deque` is immutable. The 4 basic operations which
+  # "modify" deques ({#push}, {#pop}, {#shift}, and {#unshift}) all return a new
+  # collection and leave the existing one unchanged.
+  #
+  # @example
+  #   deque = Hamster::Deque.empty                 # => Hamster::Deque[]
+  #   deque = deque.push('a').push('b').push('c')  # => Hamster::Deque['a', 'b', 'c']
+  #   deque.first                                  # => 'a'
+  #   deque.last                                   # => 'c'
+  #   deque = deque.shift                          # => Hamster::Deque['b', 'c']
+  #
+  # @see http://en.wikipedia.org/wiki/Deque "Deque" on Wikipedia
+  #
+  class Deque
+    extend Forwardable
+    include Immutable
+
+    class << self
+      # Create a new `Deque` populated with the given items.
+      # @return [Deque]
+      def [](*items)
+        items.empty? ? empty : new(items)
+      end
+
+      # Return an empty `Deque`. If used on a subclass, returns an empty instance
+      # of that class.
+      #
+      # @return [Deque]
+      def empty
+        @empty ||= self.new
+      end
+
+      # "Raw" allocation of a new `Deque`. Used internally to create a new
+      # instance quickly after consing onto the front/rear lists or taking their
+      # tails.
+      #
+      # @return [Deque]
+      # @private
+      def alloc(front, rear)
+        result = allocate
+        result.instance_variable_set(:@front, front)
+        result.instance_variable_set(:@rear,  rear)
+        result
+      end
+    end
+
+    def initialize(items=[])
+      @front = items.to_list
+      @rear  = EmptyList
+    end
+
+    # Return `true` if this `Deque` contains no items.
+    # @return [Boolean]
+    def empty?
+      @front.empty? && @rear.empty?
+    end
+    def_delegator :self, :empty?, :null?
+
+    # Return the number of items in this `Deque`.
+    # @return [Integer]
+    def size
+      @front.size + @rear.size
+    end
+    def_delegator :self, :size, :length
+
+    # Return the first item in the `Deque`. If the deque is empty, return `nil`.
+    # @return [Object]
+    def first
+      return @front.head unless @front.empty?
+      @rear.last # memoize?
+    end
+    def_delegator :self, :first, :head
+    def_delegator :self, :first, :front
+
+    # Return the last item in the `Deque`. If the deque is empty, return `nil`.
+    # @return [Object]
+    def last
+      return @rear.head unless @rear.empty?
+      @front.last # memoize?
+    end
+    def_delegator :self, :last, :peek
+
+    # Return a new `Deque` with `item` added at the end.
+    # @param item [Object] The item to add
+    # @return [Deque]
+    def push(item)
+      self.class.alloc(@front, @rear.cons(item))
+    end
+    def_delegator :self, :push, :enqueue
+    def_delegator :self, :push, :<<
+    def_delegator :self, :push, :add
+    def_delegator :self, :push, :conj
+    def_delegator :self, :push, :conjoin
+
+    # Return a new `Deque` with the last item removed.
+    # @return [Deque]
+    def pop
+      front, rear = @front, @rear
+
+      if rear.empty?
+        return EmptyDeque if front.empty?
+        front, rear = EmptyList, front.reverse
+      end
+
+      self.class.alloc(front, rear.tail)
+    end
+
+    # Return a new `Deque` with `item` added at the front.
+    # @param item [Object] The item to add
+    # @return [Deque]
+    def unshift(item)
+      self.class.alloc(@front.cons(item), @rear)
+    end
+
+    # Return a new `Deque` with the first item removed.
+    # @return [Deque]
+    def shift
+      front, rear = @front, @rear
+
+      if front.empty?
+        return EmptyDeque if rear.empty?
+        front, rear = rear.reverse, EmptyList
+      end
+
+      self.class.alloc(front.tail, rear)
+    end
+    def_delegator :self, :shift, :dequeue
+    def_delegator :self, :shift, :tail
+
+    # Return an empty `Deque` instance, of the same class as this one. Useful if you
+    # have multiple subclasses of `Deque` and want to treat them polymorphically.
+    #
+    # @return [Deque]
+    def clear
+      self.class.empty
+    end
+
+    # Return true if `other` has the same type and contents as this `Deque`.
+    #
+    # @param other [Object] The collection to compare with
+    # @return [Boolean]
+    def eql?(other)
+      return true if other.equal?(self)
+      instance_of?(other.class) && to_ary.eql?(other.to_ary)
+    end
+    def_delegator :self, :eql?, :==
+
+    # Return an `Array` with the same elements, in the same order.
+    # @return [Array]
+    def to_a
+      @front.to_a.concat(@rear.to_a.tap { |a| a.reverse! })
+    end
+    def_delegator :self, :to_a, :entries
+    def_delegator :self, :to_a, :to_ary
+
+    # Return a {List} with the same elements, in the same order.
+    # @return [Hamster::List]
+    def to_list
+      @front.append(@rear.reverse)
+    end
+
+    # Return the contents of this `Deque` as a programmer-readable `String`. If all the
+    # items in the deque are serializable as Ruby literal strings, the returned string can
+    # be passed to `eval` to reconstitute an equivalent `Deque`.
+    #
+    # @return [String]
+    def inspect
+      result = "#{self.class}["
+      i = 0
+      @front.each { |obj| result << ', ' if i > 0; result << obj.inspect; i += 1 }
+      @rear.to_a.tap { |a| a.reverse! }.each { |obj| result << ', ' if i > 0; result << obj.inspect; i += 1 }
+      result << "]"
+    end
+
+    # @private
+    def pretty_print(pp)
+      pp.group(1, "#{self.class}[", "]") do
+        pp.breakable ''
+        pp.seplist(self.to_a) { |obj| obj.pretty_print(pp) }
+      end
+    end
+
+    # @return [::Array]
+    # @private
+    def marshal_dump
+      to_a
+    end
+
+    # @private
+    def marshal_load(array)
+      initialize(array)
+    end
+  end
+
+  # The canonical empty `Deque`. Returned by `Hamster.deque` and `Deque[]` when
+  # invoked with no arguments; also returned by `Deque.empty`. Prefer using this
+  # one rather than creating many empty deques using `Deque.new`.
+  #
+  EmptyDeque = Hamster::Deque.empty
+end

data/lib/hamster/enumerable.rb

@@ -1,136 +1,178 @@
 require "forwardable"
-require "hamster/undefined"
-require "hamster/tuple"
 
 module Hamster
+  # Helper module for Hamster's sequential collections
+  #
+  # Classes including `Hamster::Enumerable` must implement `#each` (just like `::Enumerable`).
+  #
+  # They must also implement:
+  #
+  # - `#filter`, which takes a block, and returns an instance of the same class
+  #     with only the items for which the block returns a true value
+  # - `#reverse` (or else undef `#foldr`, or provide another definition for it)
+  #
   module Enumerable
     extend Forwardable
+    include ::Enumerable
 
-    def each
-      fail NoMethodError, "undefined method `each' for #{self.class.name}"
-    end
-    def_delegator :self, :each, :foreach
-
-    def filter
-      fail NoMethodError, "undefined method `filter' for #{self.class.name}"
-    end
-    def_delegator :self, :filter, :select
-    def_delegator :self, :filter, :find_all
-
-    def each_with_index(&block)
-      return self unless block_given?
-      reduce(0) do |index, item|
-        yield(item, index)
-        index + 1
-      end
-      nil
+    # Return a new collection with all the elements for which the block returns false.
+    def remove
+      return enum_for(:remove) if not block_given?
+      filter { |item| !yield(item) }
     end
 
-    def reduce(memo = Undefined)
-      each do |item|
-        memo = memo.equal?(Undefined) ? item : yield(memo, item)
-      end if block_given?
-      Undefined.erase(memo)
+    # Return a new collection with all `nil` elements removed.
+    def compact
+      filter { |item| !item.nil? }
     end
-    def_delegator :self, :reduce, :inject
-    def_delegator :self, :reduce, :fold
-    def_delegator :self, :reduce, :foldr
 
-    def partition(&block)
-      return self unless block_given?
-      Tuple.new(filter(&block), remove(&block))
+    # Search the collection for elements which are `#===` to `item`. Yield them to
+    # the optional code block if provided, and return them as a new collection.
+    def grep(pattern, &block)
+      result = filter { |item| pattern === item }
+      result = result.map(&block) if block_given?
+      result
     end
 
-    def find
-      return nil unless block_given?
-      each { |item| return item if yield(item) }
+    # Yield all integers from 0 up to, but not including, the number of items in
+    # this collection. For collections which provide indexed access, these are all
+    # the valid, non-negative indices into the collection.
+    def each_index(&block)
+      return enum_for(:each_index) unless block_given?
+      0.upto(size-1, &block)
+      self
     end
-    def_delegator :self, :find, :detect
 
-    def include?(object)
-      any? { |item| item == object }
-    end
-    def_delegator :self, :include?, :member?
-    def_delegator :self, :include?, :contains?
-    def_delegator :self, :include?, :elem?
-
-    def any?
-      return any? { |item| item } unless block_given?
-      each { |item| return true if yield(item) }
-      false
+    # Multiply all the items (presumably numeric) in this collection together.
+    def product
+      reduce(1, &:*)
     end
-    def_delegator :self, :any?, :exist?
-    def_delegator :self, :any?, :exists?
 
-    def all?
-      return all? { |item| item } unless block_given?
-      each { |item| return false unless yield(item) }
-      true
+    # Add up all the items (presumably numeric) in this collection.
+    def sum
+      reduce(0, &:+)
     end
-    def_delegator :self, :all?, :forall?
 
-    def none?
-      return none? { |item| item } unless block_given?
-      each { |item| return false if yield(item) }
-      true
-    end
-
-    def one?
-      return one? { |item| !!item } unless block_given?
-      reduce(false) do |previously_matched, item|
-        if yield(item)
-          return false if previously_matched
-          true
-        else
-          previously_matched
-        end
+    # Return 2 collections, the first containing all the elements for which the block
+    # evaluates to true, the second containing the rest.
+    def partition
+      return enum_for(:partition) if not block_given?
+      a,b = super
+      [self.class.new(a), self.class.new(b)].freeze
+    end
+
+    # Combines all elements by applying a binary operation, like `#reduce`, but unlike
+    # `#reduce`, do so from starting from the last element to the first. In other words,
+    # the order in which elements are yielded is the opposite of `#reduce`.
+    def foldr(*args, &block)
+      reverse.reduce(*args, &block)
+    end
+
+    # Groups the collection into sub-collections by the result of yielding them to
+    # the block. Returns a {Hash} where the keys are return values from the block,
+    # and the values are sub-collections. All the sub-collections are built up from
+    # `empty_group`, which should respond to `#conj` by returning a new collection
+    # with an added element.
+    def group_by_with(empty_group, &block)
+      block ||= lambda { |item| item }
+      reduce(EmptyHash) do |hash, item|
+        key = block.call(item)
+        group = hash.get(key) || empty_group
+        hash.put(key, group.conj(item))
       end
     end
-
-    def minimum(&block)
-      return minimum { |minimum, item| item <=> minimum } unless block_given?
-      reduce { |minimum, item| yield(minimum, item) < 0 ? item : minimum }
-    end
-    def_delegator :self, :minimum, :min
-
-    def maximum(&block)
-      return maximum { |maximum, item| item <=> maximum } unless block_given?
-      reduce { |maximum, item| yield(maximum, item) > 0 ? item : maximum }
-    end
-    def_delegator :self, :maximum, :max
-
-    def grep(pattern, &block)
-      filter { |item| pattern === item  }.map(&block)
+    protected :group_by_with
+
+    # Groups the collection into sub-collections by the result of yielding them to
+    # the block. Returns a {Hash} where the keys are return values from the block,
+    # and the values are sub-collections (of the same type as this one).
+    def group_by(&block)
+      group_by_with(self.class.empty, &block)
+    end
+
+    # Compare with `other`, and return 0, 1, or -1 if it is (respectively) equal to,
+    # greater than, or less than this collection.
+    def <=>(other)
+      return 0 if self.equal?(other)
+      enum1, enum2 = self.to_enum, other.to_enum
+      loop do
+        item1 = enum1.next
+        item2 = enum2.next
+        comp  = (item1 <=> item2)
+        return comp if comp != 0
+      end
+      size1, size2 = self.size, other.size
+      return 0 if size1 == size2
+      size1 > size2 ? 1 : -1
+    end
+
+    # Return true if `other` contains the same elements, in the same order.
+    # @return [Boolean]
+    def ==(other)
+      self.eql?(other) || other.respond_to?(:to_ary) && to_ary.eql?(other.to_ary)
+    end
+
+    # Convert all the elements into strings and join them together, separated by
+    # `separator`. By default, the `separator` is `$,`, the global default string
+    # separator, which is normally `nil`.
+    def join(separator = $,)
+      result = ""
+      if separator
+        each_with_index { |obj, i| result << separator if i > 0; result << obj.to_s }
+      else
+        each { |obj| result << obj.to_s }
+      end
+      result
     end
 
-    def count(&block)
-      return size unless block_given?
-      reduce(0) { |count, item| yield(item) ? count + 1 : count }
+    # Convert this collection to a {Set}.
+    def to_set
+      Set.new(self)
     end
 
-    def product
-      reduce(1, &:*)
+    # Convert this collection to a programmer-readable `String` representation.
+    def inspect
+      result = "#{self.class}["
+      each_with_index { |obj, i| result << ', ' if i > 0; result << obj.inspect }
+      result << "]"
     end
 
-    def sum
-      reduce(0, &:+)
+    # @private
+    def pretty_print(pp)
+      pp.group(1, "#{self.class}[", "]") do
+        pp.breakable ''
+        pp.seplist(self) { |obj| obj.pretty_print(pp) }
+      end
     end
 
-    def remove
-      return self unless block_given?
-      filter { |item| !yield(item) }
-    end
-    def_delegator :self, :remove, :reject
+    def_delegator :self, :each, :foreach
+    def_delegator :self, :all?, :forall?
+    def_delegator :self, :any?, :exist?
+    def_delegator :self, :any?, :exists?
+    def_delegator :self, :to_a, :to_ary
+    def_delegator :self, :filter, :find_all
+    def_delegator :self, :filter, :select # make it return a Hamster collection (and possibly make it lazy)
+    def_delegator :self, :filter, :keep_if
+    def_delegator :self, :include?, :contains?
+    def_delegator :self, :include?, :elem?
+    def_delegator :self, :max, :maximum
+    def_delegator :self, :min, :minimum
+    def_delegator :self, :remove, :reject # make it return a Hamster collection (and possibly make it lazy)
     def_delegator :self, :remove, :delete_if
-
-    def compact
-      remove(&:nil?)
-    end
-
-    def to_a
-      reduce([]) { |a, item| a << item }
+    def_delegator :self, :reduce, :fold
+    def_delegator :self, :find_index, :index
+    def_delegator :self, :find_index, :elem_index
+
+    ## Compatibility fixes
+
+    if RUBY_ENGINE == 'rbx'
+      # Rubinius implements Enumerable#sort_by using Enumerable#map
+      # Because we do our own, custom implementations of #map, that doesn't work well
+      # @private
+      def sort_by(&block)
+        result = to_a
+        result.frozen? ? result.sort_by(&block) : result.sort_by!(&block)
+      end
     end
-    def_delegator :self, :to_a, :entries
-    def_delegator :self, :to_a, :to_ary
   end
-end
+end