hamster 0.4.3 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a968ce4123ad40d563b7db0aa56b2b64b633c484
+  data.tar.gz: c2447b5cc66229a4f0020f406a2c576759bf8392
+SHA512:
+  metadata.gz: dbf628e0bc57eecb1114bc1079ec4275042ffc8c960407a4431b4abafeb968c354e1ff66eb753dc0bc22f976484f073b61bbbaceb7fd988706bf487f52c77982
+  data.tar.gz: 711c88053c81c50a6ba25eb5c5e3fb8eed58f7faff38f0f6146e86a55240e6606c4dcfd73957acda560b780df8763c9fb3bc2cb66616483257dc3d0461fa7cb2

data/lib/hamster.rb

@@ -1,9 +1,11 @@
-require 'hamster/core_ext'
-require 'hamster/immutable'
-require 'hamster/list'
-require 'hamster/stack'
-require 'hamster/queue'
-require 'hamster/hash'
-require 'hamster/set'
-require 'hamster/vector'
-require 'hamster/version'
+require "hamster/core_ext"
+require "hamster/immutable"
+require "hamster/list"
+require "hamster/deque"
+require "hamster/hash"
+require "hamster/set"
+require "hamster/vector"
+require "hamster/sorted_set"
+require "hamster/mutable_hash"
+require "hamster/nested"
+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'
+require "hamster/core_ext/enumerable"
+require "hamster/core_ext/io"

data/lib/hamster/core_ext/enumerable.rb

@@ -1,30 +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
+require "hamster/list"
 
+# 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,30 +1,21 @@
-require 'hamster/list'
+require "hamster/list"
 
-module Hamster
-
-  module CoreExt
-
-    module IO
-
-      def to_list(sep = $/)
-        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,252 @@
+require "hamster/immutable"
+require "hamster/list"
+
+module Hamster
+  # Create a new `Deque` populated with the given items.
+  # @return [Deque]
+  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
+    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
+
+    # Return the number of items in this `Deque`.
+    #
+    # @example
+    #   Hamster::Deque["A", "B", "C"].size  #=> 3
+    #
+    # @return [Integer]
+    def size
+      @front.size + @rear.size
+    end
+    alias :length :size
+
+    # Return the first item in the `Deque`. If the deque is empty, return `nil`.
+    #
+    # @example
+    #   Hamster::Deque["A", "B", "C"].first  #=> "A"
+    #
+    # @return [Object]
+    def first
+      return @front.head unless @front.empty?
+      @rear.last # memoize?
+    end
+
+    # Return the last item in the `Deque`. If the deque is empty, return `nil`.
+    #
+    # @example
+    #   Hamster::Deque["A", "B", "C"].last  #=> "C"
+    #
+    # @return [Object]
+    def last
+      return @rear.head unless @rear.empty?
+      @front.last # memoize?
+    end
+
+    # Return a new `Deque` with `item` added at the end.
+    #
+    # @example
+    #   Hamster::Deque["A", "B", "C"].add("Z")
+    #   # => Hamster::Deque["A", "B", "C", "Z"]
+    #
+    # @param item [Object] The item to add
+    # @return [Deque]
+    def push(item)
+      self.class.alloc(@front, @rear.cons(item))
+    end
+    alias :enqueue :push
+
+    # Return a new `Deque` with the last item removed.
+    #
+    # @example
+    #   Hamster::Deque["A", "B", "C"].pop
+    #   # => Hamster::Deque["A", "B"]
+    #
+    # @return [Deque]
+    def pop
+      front, rear = @front, @rear
+
+      if rear.empty?
+        return self.class.empty 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.
+    #
+    # @example
+    #   Hamster::Deque["A", "B", "C"].unshift("Z")
+    #   # => Hamster::Deque["Z", "A", "B", "C"]
+    #
+    # @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.
+    #
+    # @example
+    #   Hamster::Deque["A", "B", "C"].shift
+    #   # => Hamster::Deque["B", "C"]
+    #
+    # @return [Deque]
+    def shift
+      front, rear = @front, @rear
+
+      if front.empty?
+        return self.class.empty if rear.empty?
+        front, rear = rear.reverse, EmptyList
+      end
+
+      self.class.alloc(front.tail, rear)
+    end
+    alias :dequeue :shift
+
+    # 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
+    alias :== :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
+    alias :entries :to_a
+    alias :to_ary  :to_a
+
+    # 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,141 +1,152 @@
-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`).
+  # - `#select`, which takes a block, and returns an instance of the same class
+  #     with only the items for which the block returns a true value
+  #
   module Enumerable
+    include ::Enumerable
 
-    extend Forwardable
-
-    def each
-      raise NoMethodError, "undefined method `each' for #{self.class.name}"
-    end
-    def_delegator :self, :each, :foreach
-
-    def filter
-      raise NoMethodError, "undefined method `filter' for #{self.class.name}"
+    # Return a new collection with all the elements for which the block returns false.
+    def reject
+      return enum_for(:reject) if not block_given?
+      select { |item| !yield(item) }
     end
-    def_delegator :self, :filter, :select
-    def_delegator :self, :filter, :find_all
+    alias :delete_if :reject
 
-    def each_with_index(&block)
-      return self unless block_given?
-      reduce(0) do |index, item|
-        yield(item, index)
-        index + 1
-      end
-      nil
-    end
-
-    def reduce(memo = Undefined)
-      each do |item|
-        memo = memo.equal?(Undefined) ? item : yield(memo, item)
-      end if block_given?
-      Undefined.erase(memo)
-    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))
-    end
-
-    def find
-      return nil unless block_given?
-      each { |item| return item if yield(item) }
+    # Return a new collection with all `nil` elements removed.
+    def compact
+      select { |item| !item.nil? }
     end
-    def_delegator :self, :find, :detect
 
-    def include?(object)
-      any? { |item| item == object }
+    # 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 = select { |item| pattern === item }
+      result = result.map(&block) if block_given?
+      result
     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
+    # 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, :any?, :exist?
-    def_delegator :self, :any?, :exists?
 
-    def all?
-      return all? { |item| item } unless block_given?
-      each { |item| return false unless yield(item) }
-      true
+    # Multiply all the items (presumably numeric) in this collection together.
+    def product
+      reduce(1, &:*)
     end
-    def_delegator :self, :all?, :forall?
 
-    def none?
-      return none? { |item| item } unless block_given?
-      each { |item| return false if yield(item) }
-      true
+    # Add up all the items (presumably numeric) in this collection.
+    def sum
+      reduce(0, &:+)
     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
+
+    # 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 `#add` 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.add(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, :remove, :delete_if
+    alias :to_ary :to_a
+    alias :index :find_index
 
-    def compact
-      remove(&:nil?)
-    end
+    ## Compatibility fixes
 
-    def to_a
-      reduce([]) { |a, item| a << item }
+    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