immutable-ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: de7204bc2220b5743b2d8b3344d562377bd692a9
+  data.tar.gz: 965f9782b7d7a5b803f2ee76c3ef10d5f1203a2b
+SHA512:
+  metadata.gz: 3e7a5faa17dfdbbcbf86ba190a30537cf9b52c7b571cee68158fed8bfa69be547aeb8af91d9f91efd875a7b21462a1f84efce0edab1283fd132b9e8e819122c2
+  data.tar.gz: b06f1d17c9f1159433c2db10a2a30788a02cf379f093da86b24e77ccefe04323582beef964dcf7d220e5c3e54ac7e98e40f794e87a408da07f9c2b38da59951b

data/lib/immutable.rb

@@ -0,0 +1,9 @@
+require "immutable/core_ext"
+require "immutable/list"
+require "immutable/deque"
+require "immutable/hash"
+require "immutable/set"
+require "immutable/vector"
+require "immutable/sorted_set"
+require "immutable/nested"
+require "immutable/version"

data/lib/immutable/core_ext.rb

@@ -0,0 +1,2 @@
+require "immutable/core_ext/enumerable"
+require "immutable/core_ext/io"

data/lib/immutable/core_ext/enumerable.rb

@@ -0,0 +1,11 @@
+require "immutable/list"
+
+# Monkey-patches to Ruby's built-in `Enumerable` module.
+# @see http://www.ruby-doc.org/core/Enumerable.html
+module Enumerable
+  # Return a new {Immutable::List} populated with the items in this `Enumerable` object.
+  # @return [List]
+  def to_list
+    Immutable::List.from_enum(self)
+  end
+end

data/lib/immutable/core_ext/io.rb

@@ -0,0 +1,21 @@
+require "immutable/list"
+
+# 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.
+  # "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
+    Immutable::LazyList.new do
+      line = gets(sep)
+      if line
+        Immutable::Cons.new(line, to_list)
+      else
+        EmptyList
+      end
+    end
+  end
+end

data/lib/immutable/deque.rb

@@ -0,0 +1,254 @@
+require "immutable/list"
+
+module Immutable
+
+  # 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}.
+  #
+  # To create a new `Deque`:
+  #
+  #     Immutable::Deque.new([:first, :second, :third])
+  #     Immutable::Deque[1, 2, 3, 4, 5]
+  #
+  # Or you can start with an empty deque and build it up:
+  #
+  #     Immutable::Deque.empty.push('b').push('c').unshift('a')
+  #
+  # Like all `immutable-ruby` 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 = Immutable::Deque.empty               # => Immutable::Deque[]
+  #   deque = deque.push('a').push('b').push('c')  # => Immutable::Deque['a', 'b', 'c']
+  #   deque.first                                  # => 'a'
+  #   deque.last                                   # => 'c'
+  #   deque = deque.shift                          # => Immutable::Deque['b', 'c']
+  #
+  # @see http://en.wikipedia.org/wiki/Deque "Deque" on Wikipedia
+  #
+  class Deque
+    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.freeze
+      end
+    end
+
+    def initialize(items=[])
+      @front = List.from_enum(items)
+      @rear  = EmptyList
+      freeze
+    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
+    #   Immutable::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
+    #   Immutable::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
+    #   Immutable::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
+    #   Immutable::Deque["A", "B", "C"].add("Z")
+    #   # => Immutable::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
+    #   Immutable::Deque["A", "B", "C"].pop
+    #   # => Immutable::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
+    #   Immutable::Deque["A", "B", "C"].unshift("Z")
+    #   # => Immutable::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
+    #   Immutable::Deque["A", "B", "C"].shift
+    #   # => Immutable::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 [Immutable::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
+
+    # Return `self`. Since this is an immutable object duplicates are
+    # equivalent.
+    # @return [Deque]
+    def dup
+      self
+    end
+    alias :clone :dup
+
+    # @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 `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 = Immutable::Deque.empty
+end

data/lib/immutable/enumerable.rb

@@ -0,0 +1,152 @@
+module Immutable
+
+  # Helper module for immutable-ruby's sequential collections
+  #
+  # Classes including `Immutable::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
+
+    # 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
+    alias :delete_if :reject
+
+    # Return a new collection with all `nil` elements removed.
+    def compact
+      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 = select { |item| pattern === item }
+      result = result.map(&block) if block_given?
+      result
+    end
+
+    # 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
+
+    # Multiply all the items (presumably numeric) in this collection together.
+    def product
+      reduce(1, &:*)
+    end
+
+    # Add up all the items (presumably numeric) in this collection.
+    def sum
+      reduce(0, &:+)
+    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(Immutable::EmptyHash) do |hash, item|
+        key = block.call(item)
+        group = hash.get(key) || empty_group
+        hash.put(key, group.add(item))
+      end
+    end
+    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
+
+    # Convert this collection to a {Set}.
+    def to_set
+      Immutable::Set.new(self)
+    end
+
+    # 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
+
+    # @private
+    def pretty_print(pp)
+      pp.group(1, "#{self.class}[", "]") do
+        pp.breakable ''
+        pp.seplist(self) { |obj| obj.pretty_print(pp) }
+      end
+    end
+
+    alias :to_ary :to_a
+    alias :index :find_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
+  end
+end