hamster 1.0.1.pre.rc3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f3c8822d3a3758de0e490808c2012795a7a0de79
-  data.tar.gz: 1295b432e023a4c840d17fb9ca8a1500b97db0f0
+  metadata.gz: 010476a87d79b515fa2da08903f6c36ebffd550e
+  data.tar.gz: 080ace89fb94c62d9ef29cc3a83c879e64a6b577
 SHA512:
-  metadata.gz: 91e4df28a78d5aea2d423e03f8c6be123abae2f17ef67c7b6481ccaa20dc309d61b3d2ee864901cf9446fcb5d637ed5330f7622457de8ba0c74346089d06fec7
-  data.tar.gz: e379456f35778c21b8e37ea1525d20f520c5323acade1568a74deff7b950765d70acd4ad8e6889acf22421615bb75953e6631bc8372918460b6bbf991d511487
+  metadata.gz: 596a85aa07273c8912dc6f42a8dcec58684a3eb9ce469f6a1219fd8f3cad242b7b69e72d06b185d77f95496b86b8e197ebedd5cd77e5ce3865fa07c687ee26e2
+  data.tar.gz: b14a0366601d364dd10a78b9c068c8849fd1471ef01cb0b0656391d2096e5408ba96ad2dcda125e9c99cd7867bf129310bc027995272d865656b1b760b89b3bd

data/lib/hamster.rb

@@ -7,4 +7,6 @@ require "hamster/set"
 require "hamster/vector"
 require "hamster/sorted_set"
 require "hamster/mutable_hash"
+require "hamster/nested"
 require "hamster/version"
+require "hamster/associable"

data/lib/hamster/associable.rb

@@ -0,0 +1,49 @@
+module Hamster
+  # Including `Associable` in your container class gives it an `update_in`
+  # method.
+  #
+  # To mix in `Associable`, your class must implement two methods:
+  #
+  # * `fetch(index, default = (missing_default = true))`
+  # * `put(index, item = yield(get(index)))`
+  #
+  # See {Vector#fetch}, {Vector#put}, {Hash#fetch}, and {Hash#put} for examples.
+  module Associable
+    # Return a new container with a deeply nested value modified to the result
+    # of the given code block.  When traversing the nested containers
+    # non-existing keys are created with empty `Hash` values.
+    #
+    # The code block receives the existing value of the deeply nested key/index
+    # (or `nil` if it doesn't exist). This is useful for "transforming" the
+    # value associated with a certain key/index.
+    #
+    # Naturally, the original container and sub-containers are left unmodified;
+    # new data structure copies are created along the path as needed.
+    #
+    # @example
+    #   v = Hamster::Vector[123, 456, 789, Hamster::Hash["a" => Hamster::Vector[5, 6, 7]]]
+    #   v.update_in(3, "a", 1) { |value| value + 9 }
+    #   # => Hamster::Vector[123, 456, 789, Hamster::Hash["a" => Hamster::Vector[5, 15, 7]]]
+    #   hash = Hamster::Hash["a" => Hamster::Hash["b" => Hamster::Hash["c" => 42]]]
+    #   hash.update_in("a", "b", "c") { |value| value + 5 }
+    #   # => Hamster::Hash["a" => Hamster::Hash["b" => Hamster::Hash["c" => 47]]]
+    #
+    # @param key_path [Object(s)] List of keys/indexes which form the path to the key to be modified
+    # @yield [value] The previously stored value
+    # @yieldreturn [Object] The new value to store
+    # @return [Associable]
+    def update_in(*key_path, &block)
+      if key_path.empty?
+        raise ArgumentError, "must have at least one key in path"
+      end
+      key = key_path[0]
+      if key_path.size == 1
+        new_value = block.call(fetch(key, nil))
+      else
+        value = fetch(key, EmptyHash)
+        new_value = value.update_in(*key_path[1..-1], &block)
+      end
+      put(key, new_value)
+    end
+  end
+end

data/lib/hamster/core_ext/enumerable.rb

@@ -1,21 +1,11 @@
 require "hamster/list"
 
-# Ruby's built-in `Enumerable` module.
+# Monkey-patches to 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
+    Hamster::List.from_enum(self)
   end
-end
+end

data/lib/hamster/core_ext/io.rb

@@ -1,6 +1,6 @@
 require "hamster/list"
 
-# Ruby's built-in `IO` class.
+# Monkey-patches to 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.

data/lib/hamster/core_ext/struct.rb

@@ -0,0 +1,9 @@
+class Struct
+  # Implement Struct#to_h for Ruby interpreters which don't have it
+  # (such as MRI 1.9.3 and lower)
+  unless method_defined?(:to_h)
+    def to_h
+      Hash[each_pair.to_a]
+    end
+  end
+end

data/lib/hamster/deque.rb

@@ -1,25 +1,20 @@
-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` (or double-ended queue) is an ordered, sequential collection of
+  # objects, which allows elements to be retrieved, added and removed at the
+  # front and end of the sequence in constant time. 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}.
+  # 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]
   #
@@ -27,9 +22,10 @@ module Hamster
   #
   #     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.
+  # Like all Hamster collections, `Deque` is immutable. The four basic
+  # operations that "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[]
@@ -41,7 +37,6 @@ module Hamster
   # @see http://en.wikipedia.org/wiki/Deque "Deque" on Wikipedia
   #
   class Deque
-    extend Forwardable
     include Immutable
 
     class << self
@@ -69,12 +64,12 @@ module Hamster
         result = allocate
         result.instance_variable_set(:@front, front)
         result.instance_variable_set(:@rear,  rear)
-        result
+        result.freeze
       end
     end
 
     def initialize(items=[])
-      @front = items.to_list
+      @front = Hamster::List.from_enum(items)
       @rear  = EmptyList
     end
 
@@ -83,51 +78,65 @@ module Hamster
     def empty?
       @front.empty? && @rear.empty?
     end
-    def_delegator :self, :empty?, :null?
 
     # 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
-    def_delegator :self, :size, :length
+    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
-    def_delegator :self, :first, :head
-    def_delegator :self, :first, :front
 
     # 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
-    def_delegator :self, :last, :peek
 
     # 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
-    def_delegator :self, :push, :enqueue
-    def_delegator :self, :push, :<<
-    def_delegator :self, :push, :add
-    def_delegator :self, :push, :conj
-    def_delegator :self, :push, :conjoin
+    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 EmptyDeque if front.empty?
+        return self.class.empty if front.empty?
         front, rear = EmptyList, front.reverse
       end
 
@@ -135,6 +144,11 @@ module Hamster
     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)
@@ -142,19 +156,23 @@ module Hamster
     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 EmptyDeque if rear.empty?
+        return self.class.empty 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
+    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.
@@ -172,15 +190,15 @@ module Hamster
       return true if other.equal?(self)
       instance_of?(other.class) && to_ary.eql?(other.to_ary)
     end
-    def_delegator :self, :eql?, :==
+    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
-    def_delegator :self, :to_a, :entries
-    def_delegator :self, :to_a, :to_ary
+    alias :entries :to_a
+    alias :to_ary  :to_a
 
     # Return a {List} with the same elements, in the same order.
     # @return [Hamster::List]
@@ -221,9 +239,10 @@ module Hamster
     end
   end
 
-  # The canonical empty `Deque`. Returned by `Hamster.deque` and `Deque[]` when
+  # The canonical empty `Deque`. Returned by `Deque[]` when
   # invoked with no arguments; also returned by `Deque.empty`. Prefer using this
   # one rather than creating many empty deques using `Deque.new`.
   #
+  # @private
   EmptyDeque = Hamster::Deque.empty
-end
+end

data/lib/hamster/enumerable.rb

@@ -1,35 +1,30 @@
-require "forwardable"
-
 module Hamster
   # Helper module for Hamster's sequential collections
   #
-  # Classes including `Hamster::Enumerable` must implement `#each` (just like `::Enumerable`).
-  #
-  # They must also implement:
+  # Classes including `Hamster::Enumerable` must implement:
   #
-  # - `#filter`, which takes a block, and returns an instance of the same class
+  # - `#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
-  # - `#reverse` (or else undef `#foldr`, or provide another definition for it)
-  #
   module Enumerable
-    extend Forwardable
     include ::Enumerable
 
     # 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) }
+    def reject
+      return enum_for(:reject) if not block_given?
+      select { |item| !yield(item) }
     end
+    alias :delete_if :reject
 
     # Return a new collection with all `nil` elements removed.
     def compact
-      filter { |item| !item.nil? }
+      select { |item| !item.nil? }
     end
 
     # 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 = select { |item| pattern === item }
       result = result.map(&block) if block_given?
       result
     end
@@ -61,24 +56,17 @@ module Hamster
       [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
+    # `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.conj(item))
+        hash.put(key, group.add(item))
       end
     end
     protected :group_by_with
@@ -145,23 +133,8 @@ module Hamster
       end
     end
 
-    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_delegator :self, :reduce, :fold
-    def_delegator :self, :find_index, :index
-    def_delegator :self, :find_index, :elem_index
+    alias :to_ary :to_a
+    alias :index :find_index
 
     ## Compatibility fixes
 
@@ -175,4 +148,4 @@ module Hamster
       end
     end
   end
-end
+end

data/lib/hamster/experimental/mutable_queue.rb

@@ -1,21 +1,18 @@
-require "forwardable"
 require "hamster/deque"
 require "hamster/read_copy_update"
 
 module Hamster
-  def self.mutable_queue(*items)
-    MutableQueue.new(deque(*items))
-  end
-
+  # @api private
   class MutableQueue
-    extend Forwardable
     include ReadCopyUpdate
 
+    def self.[](*items)
+      MutableQueue.new(Deque[*items])
+    end
+
     def enqueue(item)
       transform { |queue| queue.enqueue(item) }
     end
-    def_delegate :self, :enqueue, :<<
-    def_delegate :self, :enqueue, :add
 
     def dequeue
       head = nil