immutable-ruby 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: de7204bc2220b5743b2d8b3344d562377bd692a9
-  data.tar.gz: 965f9782b7d7a5b803f2ee76c3ef10d5f1203a2b
+SHA256:
+  metadata.gz: 54e4768953f4e1a9afbfc0d8496bdb563ae850419c905ea4dce78b560c88da3c
+  data.tar.gz: 9237a022ed3107aad98adfaed510cbd4b76367b06aab7a2d6a1f8dc2d6d3c911
 SHA512:
-  metadata.gz: 3e7a5faa17dfdbbcbf86ba190a30537cf9b52c7b571cee68158fed8bfa69be547aeb8af91d9f91efd875a7b21462a1f84efce0edab1283fd132b9e8e819122c2
-  data.tar.gz: b06f1d17c9f1159433c2db10a2a30788a02cf379f093da86b24e77ccefe04323582beef964dcf7d220e5c3e54ac7e98e40f794e87a408da07f9c2b38da59951b
+  metadata.gz: 7aa2208347fcce032af7b0885cb5088ea7d93573dd54c59fbebf7d98bd962be8880533c3c0fabe92fb7cfc5eddf1a9cc06cb60a0180ee55507d09dde7b2a0396
+  data.tar.gz: f10991e1881c42941d9723eb0acc569126b06716273852089c7f25a3bf2e5fefc25e1d5c767682dbb75d88a52da9dc12aee90627c7e1a92cf513f586aab3ef42

data/lib/immutable/core_ext/enumerable.rb

@@ -1,4 +1,4 @@
-require "immutable/list"
+require 'immutable/list'
 
 # Monkey-patches to Ruby's built-in `Enumerable` module.
 # @see http://www.ruby-doc.org/core/Enumerable.html

data/lib/immutable/core_ext/io.rb

@@ -1,4 +1,4 @@
-require "immutable/list"
+require 'immutable/list'
 
 # Monkey-patches to Ruby's built-in `IO` class.
 # @see http://www.ruby-doc.org/core/IO.html

data/lib/immutable/core_ext.rb

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

data/lib/immutable/deque.rb

@@ -1,4 +1,4 @@
-require "immutable/list"
+require 'immutable/list'
 
 module Immutable
 
@@ -48,7 +48,7 @@ module Immutable
       #
       # @return [Deque]
       def empty
-        @empty ||= self.new
+        @empty ||= new
       end
 
       # "Raw" allocation of a new `Deque`. Used internally to create a new
@@ -86,7 +86,7 @@ module Immutable
     def size
       @front.size + @rear.size
     end
-    alias :length :size
+    alias length size
 
     # Return the first item in the `Deque`. If the deque is empty, return `nil`.
     #
@@ -110,10 +110,38 @@ module Immutable
       @front.last # memoize?
     end
 
+    # Return a new `Deque` with elements rotated by `n` positions.
+    # A positive rotation moves elements to the right, negative to the left, and 0 is a no-op.
+    #
+    # @example
+    #   Immutable::Deque["A", "B", "C"].rotate(1)
+    #   # => Immutable::Deque["C", "A", "B"]
+    #   Immutable::Deque["A", "B", "C"].rotate(-1)
+    #   # => Immutable::Deque["B", "C", "A"]
+    #
+    # @param n [Integer] number of positions to move elements by
+    # @return [Deque]
+    def rotate(n)
+      return self.class.empty if empty?
+
+      n %= size
+      return self if n == 0
+
+      a, b = @front, @rear
+
+      if b.size >= n
+        n.times { a = a.cons(b.head); b = b.tail }
+      else
+        (size - n).times { b = b.cons(a.head); a = a.tail }
+      end
+
+      self.class.alloc(a, b)
+    end
+
     # Return a new `Deque` with `item` added at the end.
     #
     # @example
-    #   Immutable::Deque["A", "B", "C"].add("Z")
+    #   Immutable::Deque["A", "B", "C"].push("Z")
     #   # => Immutable::Deque["A", "B", "C", "Z"]
     #
     # @param item [Object] The item to add
@@ -121,7 +149,7 @@ module Immutable
     def push(item)
       self.class.alloc(@front, @rear.cons(item))
     end
-    alias :enqueue :push
+    alias enqueue push
 
     # Return a new `Deque` with the last item removed.
     #
@@ -170,7 +198,7 @@ module Immutable
 
       self.class.alloc(front.tail, rear)
     end
-    alias :dequeue :shift
+    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.
@@ -180,6 +208,13 @@ module Immutable
       self.class.empty
     end
 
+    # Return a new `Deque` with the same items, but in reverse order.
+    #
+    # @return [Deque]
+    def reverse
+      self.class.alloc(@rear, @front)
+    end
+
     # Return true if `other` has the same type and contents as this `Deque`.
     #
     # @param other [Object] The collection to compare with
@@ -188,15 +223,15 @@ module Immutable
       return true if other.equal?(self)
       instance_of?(other.class) && to_ary.eql?(other.to_ary)
     end
-    alias :== :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! })
+      @front.to_a.concat(@rear.to_a.tap(&:reverse!))
     end
-    alias :entries :to_a
-    alias :to_ary  :to_a
+    alias entries to_a
+    alias to_ary  to_a
 
     # Return a {List} with the same elements, in the same order.
     # @return [Immutable::List]
@@ -213,8 +248,8 @@ module Immutable
       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 << "]"
+      @rear.to_a.tap(&:reverse!).each { |obj| result << ', ' if i > 0; result << obj.inspect; i += 1 }
+      result << ']'
     end
 
     # Return `self`. Since this is an immutable object duplicates are
@@ -223,13 +258,13 @@ module Immutable
     def dup
       self
     end
-    alias :clone :dup
+    alias clone dup
 
     # @private
     def pretty_print(pp)
-      pp.group(1, "#{self.class}[", "]") do
+      pp.group(1, "#{self.class}[", ']') do
         pp.breakable ''
-        pp.seplist(self.to_a) { |obj| obj.pretty_print(pp) }
+        pp.seplist(to_a) { |obj| obj.pretty_print(pp) }
       end
     end
 

data/lib/immutable/enumerable.rb

@@ -15,7 +15,7 @@ module Immutable
       return enum_for(:reject) if not block_given?
       select { |item| !yield(item) }
     end
-    alias :delete_if :reject
+    alias delete_if reject
 
     # Return a new collection with all `nil` elements removed.
     def compact
@@ -30,6 +30,15 @@ module Immutable
       result
     end
 
+    # Search the collection for elements which are not `#===` to `item`. Yield
+    # them to the optional code block if provided, and return them as a new
+    # collection.
+    def grep_v(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.
@@ -82,15 +91,15 @@ module Immutable
     # 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
+      return 0 if equal?(other)
+      enum1, enum2 = 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
+      size1, size2 = size, other.size
       return 0 if size1 == size2
       size1 > size2 ? 1 : -1
     end
@@ -98,14 +107,14 @@ module Immutable
     # 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)
+      eql?(other) || (other.respond_to?(:to_ary) && to_ary == 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 = ""
+      result = ''
       if separator
         each_with_index { |obj, i| result << separator if i > 0; result << obj.to_s }
       else
@@ -123,19 +132,19 @@ module Immutable
     def inspect
       result = "#{self.class}["
       each_with_index { |obj, i| result << ', ' if i > 0; result << obj.inspect }
-      result << "]"
+      result << ']'
     end
 
     # @private
     def pretty_print(pp)
-      pp.group(1, "#{self.class}[", "]") do
+      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
+    alias to_ary to_a
+    alias index find_index
 
     ## Compatibility fixes
 

data/lib/immutable/hash.rb

@@ -1,8 +1,8 @@
-require "immutable/undefined"
-require "immutable/enumerable"
-require "immutable/trie"
-require "immutable/set"
-require "immutable/vector"
+require 'immutable/undefined'
+require 'immutable/enumerable'
+require 'immutable/trie'
+require 'immutable/set'
+require 'immutable/vector'
 
 module Immutable
 
@@ -78,7 +78,7 @@ module Immutable
       #
       # @return [Hash]
       def empty
-        @empty ||= self.new
+        @empty ||= new
       end
 
       # "Raw" allocation of a new `Hash`. Used internally to create a new
@@ -119,7 +119,7 @@ module Immutable
     def size
       @trie.size
     end
-    alias :length :size
+    alias length size
 
     # Return `true` if this `Hash` contains no key/value pairs.
     #
@@ -140,9 +140,9 @@ module Immutable
     def key?(key)
       @trie.key?(key)
     end
-    alias :has_key? :key?
-    alias :include? :key?
-    alias :member?  :key?
+    alias has_key? key?
+    alias include? key?
+    alias member?  key?
 
     # Return `true` if this `Hash` has one or more keys which map to the provided value.
     #
@@ -155,7 +155,7 @@ module Immutable
       each { |k,v| return true if value == v }
       false
     end
-    alias :has_value? :value?
+    alias has_value? value?
 
     # Retrieve the value corresponding to the provided key object. If not found, and
     # this `Hash` has a default block, the default block is called to provide the
@@ -182,7 +182,7 @@ module Immutable
         @default.call(key)
       end
     end
-    alias :[] :get
+    alias [] get
 
     # Retrieve the value corresponding to the given key object, or use the provided
     # default value or block, or otherwise raise a `KeyError`.
@@ -264,6 +264,12 @@ module Immutable
       end
     end
 
+    # @private
+    # @raise NoMethodError
+    def []=(*)
+      raise NoMethodError, "Immutable::Hash doesn't support `[]='; use `put' instead"
+    end
+
     # Return a new `Hash` with a deeply nested value modified to the result of
     # the given code block.  When traversing the nested `Hash`es and `Vector`s,
     # non-existing keys are created with empty `Hash` values.
@@ -287,7 +293,7 @@ module Immutable
     # @return [Hash]
     def update_in(*key_path, &block)
       if key_path.empty?
-        raise ArgumentError, "must have at least one key in path"
+        raise ArgumentError, 'must have at least one key in path'
       end
       key = key_path[0]
       if key_path.size == 1
@@ -342,7 +348,7 @@ module Immutable
       @trie.each(&block)
       self
     end
-    alias :each_pair :each
+    alias each_pair each
 
     # Call the block once for each key/value pair in this `Hash`, passing the key/value
     # pair as parameters. Iteration order will be the opposite of {#each}.
@@ -417,7 +423,7 @@ module Immutable
       return self if empty?
       self.class.new(super, &@default)
     end
-    alias :collect :map
+    alias collect map
 
     # Return a new `Hash` with all the key/value pairs for which the block returns true.
     #
@@ -433,8 +439,8 @@ module Immutable
       return enum_for(:select) unless block_given?
       derive_new_hash(@trie.select(&block))
     end
-    alias :find_all :select
-    alias :keep_if  :select
+    alias find_all select
+    alias keep_if  select
 
     # Yield `[key, value]` pairs until one is found for which the block returns true.
     # Return that `[key, value]` pair. If the block never returns true, return `nil`.
@@ -452,7 +458,7 @@ module Immutable
       each { |entry| return entry if yield entry }
       nil
     end
-    alias :detect :find
+    alias detect find
 
     # Return a new `Hash` containing all the key/value pairs from this `Hash` and
     # `other`. If no block is provided, the value for entries with colliding keys
@@ -479,7 +485,7 @@ module Immutable
     def merge(other)
       trie = if block_given?
         other.reduce(@trie) do |trie, (key, value)|
-          if entry = trie.get(key)
+          if (entry = trie.get(key))
             trie.put(key, yield(key, entry[1], value))
           else
             trie.put(key, value)
@@ -570,20 +576,54 @@ module Immutable
     end
 
     # Return a {Vector} of the values which correspond to the `wanted` keys.
-    # If any of the `wanted` keys are not present in this `Hash`, they will be skipped.
+    # If any of the `wanted` keys are not present in this `Hash`, `nil` will be
+    # placed instead, or the result of the default proc (if one is defined),
+    # similar to the behavior of {#get}.
     #
     # @example
     #   h = Immutable::Hash["A" => 1, "B" => 2, "C" => 3]
-    #   h.values_at("B", "A", "D")  # => Immutable::Vector[2, 1]
+    #   h.values_at("B", "A", "D")  # => Immutable::Vector[2, 1, nil]
     #
     # @param wanted [Array] The keys to retrieve
     # @return [Vector]
     def values_at(*wanted)
-      array = []
-      wanted.each { |key| array << get(key) if key?(key) }
+      Vector.new(wanted.map { |key| get(key) }.freeze)
+    end
+
+    # Return a {Vector} of the values which correspond to the `wanted` keys.
+    # If any of the `wanted` keys are not present in this `Hash`, raise `KeyError`
+    # exception.
+    #
+    # @example
+    #   h = Immutable::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.fetch_values("C", "A")  # => Immutable::Vector[3, 1]
+    #   h.fetch_values("C", "Z")  # => KeyError: key not found: "Z"
+    #
+    # @param wanted [Array] The keys to retrieve
+    # @return [Vector]
+    def fetch_values(*wanted)
+      array = wanted.map { |key| fetch(key) }
       Vector.new(array.freeze)
     end
 
+    # Return the value of successively indexing into a nested collection.
+    # If any of the keys is not present, return `nil`.
+    #
+    # @example
+    #   h = Immutable::Hash[a: 9, b: Immutable::Hash[c: 'a', d: 4], e: nil]
+    #   h.dig(:b, :c) # => "a"
+    #   h.dig(:b, :f) # => nil
+    #
+    # @return [Object]
+    def dig(key, *rest)
+      value = self[key]
+      if rest.empty? || value.nil?
+        value
+      else
+        value.dig(*rest)
+      end
+    end
+
     # Return a new {Set} containing the keys from this `Hash`.
     #
     # @example
@@ -731,7 +771,51 @@ module Immutable
     # @param other [Object] The object to compare with
     # @return [Boolean]
     def ==(other)
-      self.eql?(other) || (other.respond_to?(:to_hash) && to_hash.eql?(other.to_hash))
+      eql?(other) || (other.respond_to?(:to_hash) && to_hash == other.to_hash)
+    end
+
+    # Return true if this `Hash` is a proper superset of `other`, which means
+    # all `other`'s keys are contained in this `Hash` with identical
+    # values, and the two hashes are not identical.
+    #
+    # @param other [Immutable::Hash] The object to compare with
+    # @return [Boolean]
+    def >(other)
+      self != other && self >= other
+    end
+
+    # Return true if this `Hash` is a superset of `other`, which means all
+    # `other`'s keys are contained in this `Hash` with identical values.
+    #
+    # @param other [Immutable::Hash] The object to compare with
+    # @return [Boolean]
+    def >=(other)
+      other.each do |key, value|
+        if self[key] != value
+          return false
+        end
+      end
+      true
+    end
+
+    # Return true if this `Hash` is a proper subset of `other`, which means all
+    # its keys are contained in `other` with the identical values, and the two
+    # hashes are not identical.
+    #
+    # @param other [Immutable::Hash] The object to compare with
+    # @return [Boolean]
+    def <(other)
+      other > self
+    end
+
+    # Return true if this `Hash` is a subset of `other`, which means all its
+    # keys are contained in `other` with the identical values, and the two
+    # hashes are not identical.
+    #
+    # @param other [Immutable::Hash] The object to compare with
+    # @return [Boolean]
+    def <=(other)
+      other >= self
     end
 
     # See `Object#hash`.
@@ -756,7 +840,7 @@ module Immutable
         result << key.inspect << ' => ' << val.inspect
         i += 1
       end
-      result << "]"
+      result << ']'
     end
 
     # Return `self`. Since this is an immutable object duplicates are
@@ -765,7 +849,7 @@ module Immutable
     def dup
       self
     end
-    alias :clone :dup
+    alias clone dup
 
     # Allows this `Hash` to be printed at the `pry` console, or using `pp` (from the
     # Ruby standard library), in a way which takes the amount of horizontal space on
@@ -774,7 +858,7 @@ module Immutable
     #
     # @private
     def pretty_print(pp)
-      pp.group(1, "#{self.class}[", "]") do
+      pp.group(1, "#{self.class}[", ']') do
         pp.breakable ''
         pp.seplist(self, nil) do |key, val|
           pp.group do
@@ -799,7 +883,23 @@ module Immutable
       end
       output
     end
-    alias :to_h :to_hash
+    alias to_h to_hash
+
+    # Return a `Proc` which accepts a key as an argument and returns the value.
+    # The `Proc` behaves like {#get} (when the key is missing, it returns nil or
+    # the result of the default proc).
+    #
+    # @example
+    #   h = Immutable::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.to_proc.call("B")
+    #   # => 2
+    #   ["A", "C", "X"].map(&h)   # The & is short for .to_proc in Ruby
+    #   # => [1, 3, nil]
+    #
+    # @return [Proc]
+    def to_proc
+      lambda { |key| get(key) }
+    end
 
     # @return [::Hash]
     # @private