facets 2.9.3 → 3.0.0

data/lib/core/facets/array/arrange.rb

@@ -0,0 +1,42 @@
+class Array
+
+  # The `arrange` method produces appropriate ranges from the objects in the array.
+  #
+  # Examples
+  #
+  #     [1,2,3,6,7,8].arrange  #=> [1..3, 6..8]
+  #
+  #     [10..15, 16..20, 21, 22].arrange  #=> [10..22]
+  #
+  # Assumes inclusive ranges (ie. 1..4) and range.first <= range.last.
+  #
+  # Works with integers, dates and strings. However, all the objects in the array must
+  # be of the same class.
+  #
+  # CREDIT: monocle
+
+  def arrange
+		array = uniq.sort_by { |e| Range === e ? e.first : e }
+		array.inject([]) do |c, value|
+			unless c.empty?
+				last = c.last
+				last_value    = (Range === last  ? last.last   : last)
+				current_value = (Range === value ? value.first : value)
+				if (last_value.succ <=> current_value) == -1
+					c << value
+				else
+					first  = (Range === last ? last.first : last)
+					second = [Range === last ? last.last : last, Range === value ? value.last : value].max
+					c[-1] = [first..second]
+					c.flatten!
+				end
+			else
+				c << value
+			end
+		end
+	end
+
+  alias rangify arrange
+
+end
+

data/lib/core/facets/array/before.rb

@@ -13,6 +13,7 @@ class Array
   #   sequence.before('d')           #=> nil
   #
   # CREDIT: Tyler Rick
+
   def before(value)
     return nil unless include? value
     self[(index(value).to_i - 1) % length]
@@ -30,6 +31,7 @@ class Array
   #   sequence.after('d')           #=> nil
   #
   # CREDIT: Tyler Rick
+
   def after(value)
     return nil unless include? value
     self[(index(value).to_i + 1) % length]

data/lib/core/facets/array/collapse.rb

@@ -2,6 +2,8 @@ class Array
 
   # Simplify an array by flattening it then compacting it.
   #
+  # Examples
+  #
   #   [1,[2,nil,[3]],nil,4].collapse  #=> [1,2,3,4]
   #
   def collapse

data/lib/core/facets/array/commonality.rb

@@ -1,37 +1,49 @@
 class Array
 
-  # Returns all items that are equal in terms of the supplied block.
-  # If no block is given objects are considered to be equal if they
-  # return the same value for Object#hash and if obj1 == obj2.
+  # Get a list of all items that have something in common in terms of the
+  # supplied block. If no block is given objects are considered to be in 
+  # common if they return the same value for Object#hash and if obj1 == obj2.
   #
-  #   [1, 2, 2, 3, 4, 4].commonality  #=> { 2 => [2, 2], 4 => [4, 4] }
+  # This can be useful, for instance, in determining all persons that share
+  # their last name with another person.
   #
-  #   ["foo", "bar", "a"].commonality { |str| str.length }
-  #   #=> { 3 => ["foo", "bar"] }
+  #     persons.commonality { |person| person.last_name }
   #
-  # This can be useful, for instance, in determining all persons that share
-  # their last name with another person ...
+  # The method is similar to #group_by which is a standard Ruby method as of 1.9.
+  # To get effectively the same results with #group_by use `select{ |k,v| v.size > 1 }`.
   #
-  #   persons.collisions { |person| person.last_name }
+  #     [1, 2, 2, 3, 4, 4].group_by{ |e| e }.select{ |k,v| v.size > 1 }
+  #     #=> { 2 => [2, 2], 4 => [4, 4] }
+  #
+  # Examples
+  #
+  #   [1, 2, 2, 3, 4, 4].commonality  #=> { 2 => [2, 2], 4 => [4, 4] }
+  #
+  #   ["foo", "bar", "baz"].commonality { |str| str[0] }
+  #   #=> { 'b' => ["bar", "baz"] }
+  #
+  # Returns [Hash] mapping common attribute to those elements. 
   #
   # CREDIT: Florian Gross
 
   def commonality(&block)
-    had_no_block = !block
     block ||= lambda { |item| item }
+
     result = Hash.new { |hash, key| hash[key] = Array.new }
     each do |item|
       key = block.call(item)
       result[key] << item
     end
+
     result.reject! do |key, values|
       values.size <= 1
     end
-    # -- return had_no_block ? result.values.flatten : result
+
     return result
   end
 
-  alias_method :collisions, :commonality
+  # Deprecated: Alias for #commonality.
+  alias collisions commonality
 
 end
 

data/lib/core/facets/array/duplicates.rb

@@ -1 +1,22 @@
-require 'facets/array/nonuniq'
+class Array
+
+  # Return list of duplicate elements.
+  #
+  # min - The minimum number of duplication necessary for inclusion. [Integer]
+  #
+  # Examples:
+  #
+  #   [1,1,2,3].duplicates #=> [1]
+  #
+  # CREDIT: Rebort Dober (current implementation)
+  # CREDIT: Thibaut Barrère
+
+  def duplicates(min=2)
+    h = Hash.new( 0 )
+    each {|i|
+      h[i] += 1
+    }
+    h.delete_if{|_,v| v < min}.keys
+  end
+
+end

data/lib/core/facets/array/each_overlap.rb

@@ -0,0 +1,25 @@
+class Array
+
+  # Iterate over each slice where the last n values of a preceding slice
+  # overlap with the first n values of the following slice. The value of n
+  # is specified by the second `overlap` argument.
+  #
+  #     a, r = [1,2,3,4,5], []
+  #     a.each_overlap(2,1) { |x,y| r << [x,y] } 
+  #     r # => [[1,2],[2,3],[3,4],[4,5]]
+  #
+  # Returns nothing.
+
+  def each_overlap(slice_size, overlap)
+    if block_given?
+		  i = 0
+		  while i + slice_size <= length
+		    yield slice(i...i+slice_size)
+		    i += (slice_size - overlap)
+		  end
+    else
+      to_enum(:each_overlap, slice_size, overlap)
+    end
+  end
+
+end

data/lib/core/facets/array/intersection.rb

@@ -0,0 +1,25 @@
+class Array
+
+	# Returns the values in common for an array set (nil, singe value/object, or range).
+  #
+  # CREDIT: monocle
+
+	def intersection
+		array = uniq.sort_by { |e| Range === e ? e.first : e }
+		array.inject() do |c, e|
+			f = (Range === c ? c.last  : c)
+			v = (Range === e ? e.first : e)
+			case f <=> v
+			when -1 then return nil
+			when  0 then f
+			else
+				if Range === e
+					v..([f, e.last].min)
+				else
+					v
+				end
+			end
+		end
+	end
+
+end

data/lib/core/facets/array/missing.rb

@@ -0,0 +1,29 @@
+require 'facets/array/arrange'
+
+class Array
+
+  # Determine the "holes" in the values of an array.
+  #
+  # TODO: Better name?
+  #
+	# Returns the missing elements in an array set.
+  #
+  # CREDIT: monocle
+
+	def missing
+		missing, array = [], arrange
+		i, length = 0, array.size - 1
+		while i < length 
+      x0 = array[i]
+      x1 = array[i+1]
+			c = (Range === x0 ? x0.last  : x0)
+			n = (Range === x1 ? x1.first : x1)
+			missing << (
+        c.succ.succ == n ? c.succ : ((c.succ)..(n.pred))
+      )
+			i += 1
+		end
+    return missing
+	end
+
+end

data/lib/core/facets/array/nonuniq.rb

@@ -1,10 +1,12 @@
 class Array
 
-  # Returns a list of non-unique elements
+  # Returns a list of non-unique elements.
+  #
+  # Examples
   #
   #   [1,1,2,2,3,4,5].nonuniq  #=> [1,2]
   #
-  # @author Martin DeMello
+  # CREDIT: Martin DeMello
 
   def nonuniq
     h1 = {}
@@ -16,58 +18,10 @@ class Array
     h2.keys
   end
 
-  # Same as `#nonuniq` but acting in place.
-  def nonuniq!
-    h1 = {}
-    h2 = {}
-    each {|i|
-      h2[i] = true if h1[i]
-      h1[i] = true
-    }
-    self.replace(h2.keys)
-  end
-
-  # Return list of duplictate elements.
-  #
-  # @param [Integer] min
-  #   The minimum number of duplicatation necessary for inclusion.
-  #
-  # @author Rebort Dober (current implementation)
-  # @author Thibaut Barrère
+  # Same as `#nonuniq` but acts in place.
 
-  def duplicates(min=2)
-    h = Hash.new( 0 )
-    each {|i|
-      h[i] += 1
-    }
-    h.delete_if{|_,v| v < min}.keys
-  end
-
-  # Returns a list of elements that occur +n+ times.
-  #
-  #  [0,1,1,1,3,0,1,2,4].occurent(3) #=> [1]
-  #
-  # If +n+ is a Range then returns elements that occur a number
-  # of time within the range.
-  #
-  #  [0,1,1,1,3,0,1,2,4].occurent(2..4) #=> [0,1]
-  #
-  # @author Robert Dober
-
-  def occurent(n=2)
-    h = Hash.new( 0 )
-    each do |i|
-      h[i] += 1
-    end
-
-    case n
-    when nil
-      h.delete_if{ |_,v| ! yield(v) }.keys
-    when Range
-      h.delete_if{ |_,v| ! n.include?(v) }.keys
-    else
-      h.delete_if{|_,v| v != n}.keys
-    end
+  def nonuniq!
+    self.replace(self.nonuniq)
   end
 
 end

data/lib/core/facets/array/occur.rb

@@ -0,0 +1,38 @@
+class Array
+
+  # Returns a list of elements that occur +n+ times.
+  #
+  # If +n+ is a Range then returns elements that occur a number
+  # of time within the range.
+  #
+  # Examples
+  #
+  #  [0,1,1,1,3,0,1,2,4].occur(3) #=> [1]
+  #
+  #  [0,1,1,1,3,0,1,2,4].occur(2..4) #=> [0,1]
+  #
+  # Returns [Array] of reoccurring elements.
+  #
+  # CREDIT: Robert Dober
+
+  def occur(n=nil) #:yield:
+    h = Hash.new(0)
+
+    each do |i|
+      h[i] += 1
+    end
+
+    case n
+    when nil
+      h.delete_if{ |_,v| ! yield(v) }.keys
+    when Range
+      h.delete_if{ |_,v| ! n.include?(v) }.keys
+    else
+      h.delete_if{|_,v| v != n}.keys
+    end
+  end
+
+  # Plural alias of #occur.
+  alias :occurs :occur
+
+end

data/lib/core/facets/array/occurrence.rb

@@ -0,0 +1,28 @@
+class Array
+
+  # Create a hart of counts of duplicate elements.
+  #
+  # Examples
+  #
+  #   [:a,:a,:b,:c,:c,:c].occurrence
+  #   #=> { :a => 2, :b => 1, :c => 3 } 
+  #
+  #   [2,2,3,4,4,4].occurence{|i| i % 2} 
+  #   #=> { 0 => 5, 1 => 1 }
+  #
+  def occurrence
+    h = Hash.new(0)
+    if block_given?
+      each do |e|
+        h[yield(e)] += 1
+      end
+    else
+      each do |e|
+        h[e] += 1
+      end
+    end
+    h
+  end
+
+end
+

data/lib/core/facets/array/only.rb

@@ -17,10 +17,21 @@ class Array
 
   def only
     unless size == 1
-      raise IndexError, "Array#only called on non-single-element array"
+      raise IndexError, "not the only element of array"
     end
     first
   end
 
+  # Does this Array have only one element?
+  # 
+  # TODO: While clearly this goes along with the regular #only method,
+  # the name doesn't seem quite right. Perhaps rename to #lonely.
+  #
+  # CREDIT: Lavir the Whiolet
+  #
+  def only?
+    size == 1
+  end
+ 
 end
 

data/lib/core/facets/array/recursively.rb

@@ -4,20 +4,26 @@ require 'facets/enumerable/recursively'
 class Array
 
   # Apply a method to array, and recursively apply that method
-  # to each sub-array or +types+.
+  # to each sub-array or given +types+.
+  #
+  # By default the sub-types are passed thru uneffected. Passing
+  # a block to #recursively can be used to change this.
+  #
+  # types - List of class types to recurse. [Array<Class>]
+  # block - Optional filter procedure to apply on each recursion. 
+  #
+  # Examples
   #
   #   arr = ["a", ["b", "c"]]
   #   arr.recursively.map{ |v| v.to_sym }
   #   #=> [:a, [:b, :c]]
   #
-  # By default the sub-types are passed thru uneffected. Passing a block
-  # to #recursively changes this.
-  #
   #   arr = ["a", ["b", "c"]]
   #   arr.recursively{ |a| a.reverse }.map{ |v| v.to_sym }
   #   #=> [:a, [:c, :b]]
   #
-  # TODO: Return Enumerator if no +yld+ block is given ?
+  # Returns [Recursor].
+
   def recursively(*types, &block)
     Recursor.new(self, *types, &block)
   end

data/lib/core/facets/array/reject_values.rb

@@ -0,0 +1,21 @@
+class Array
+
+  # Non-destructive form of `Array#delete_values`. Unlike `delete_values`
+  # this method returns a new array.
+  #
+  # values - List of array elements to reject.
+  #
+  # Examples
+  #
+  #     [1,2,3,4,5].reject_values(2,4)  # => [1,3,5]
+  #
+  # Returns [Array]
+  #
+  # CREDIT: Sean Mackesey
+
+  def reject_values(*values)
+    reject { |x| values.include?(x) }
+  end
+
+end
+