facets 3.0.0 → 3.1.0

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

@@ -4,10 +4,7 @@ class Array
   # method is to provide polymorphism with Hash.
   #
   def each_pair #:yield:
-    i = -1
-    each_value do |x|
-      yield(i+=1, x)
-    end
+    each_with_index {|e, i| yield(i,e) }
   end
 
 end

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

@@ -0,0 +1 @@
+require 'facets/array/indexable'

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

@@ -1,32 +1,27 @@
 class Array
 
-  # Returns last _n_ elements.
+  # Returns elements from `index` until the end.
   #
-  #   %w{W o r l d}.from(3)  #=> %w{l d}
+  #   %w{W o r l d}.from(3)  #=> ["l", "d"]
+  #   %w{W o r l d}.from(9)  #=> []
   #
-  def from(i)
-    return self if i >= size
-    self[i, size - i]
+  def from(index)
+    return [] if index >= size
+    self[index..-1]
   end unless method_defined?(:from)
 
   # Fetch values from a start index thru an end index.
   #
-  #   [1,2,3,4,5].thru(0,2)  #=> [1,2,3]
-  #   [1,2,3,4,5].thru(2,4)  #=> [3,4,5]
-  #
   #   [1,2,3,4,5].thru(2)  #=> [1,2,3]
   #   [1,2,3,4,5].thru(4)  #=> [1,2,3,4,5]
   #
+  #   [1,2,3,4,5].thru(0,2)  #=> [1,2,3]
+  #   [1,2,3,4,5].thru(2,4)  #=> [3,4,5]
+  #
   def thru(from, to=nil)
     from, to = 0, from unless to
-    to = size - 1 if to >= size
-    a = []
-    i = from
-    while i <= to
-      a << self[i]
-      i += 1
-    end
-    a
+    return [] if from >= size
+    self[from..to]
   end unless method_defined?(:thru)
 
 end

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

@@ -1,6 +1,6 @@
 class Array
 
-	# Returns the values in common for an array set (nil, singe value/object, or range).
+	# Returns the values in common for an array set (nil, single value/object, or range).
   #
   # CREDIT: monocle
 

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

@@ -0,0 +1 @@
+require 'facets/array/indexable'

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

@@ -1,8 +1,8 @@
 class Array
 
-  # In Statistics mode is the value that occurs most frequently
+  # In Statistics. mode is the value that occurs most frequently
   # in a given set of data. This method returns an array in case
-  # their is a tie.
+  # there is a tie.
   #
   #   [:a, :b, :c, :b, :d].mode  #=> [:b]
   #   [:a, :b, :c, :b, :a].mode  #=> [:a, :b]

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

@@ -1,13 +1,14 @@
 class Array
 
-  # Create a hart of counts of duplicate elements.
+  # Create a hash of each uniq element of the array
+  # and how many time each appears.
   #
   # Examples
   #
   #   [:a,:a,:b,:c,:c,:c].occurrence
-  #   #=> { :a => 2, :b => 1, :c => 3 } 
+  #   #=> { :a => 2, :b => 1, :c => 3 }
   #
-  #   [2,2,3,4,4,4].occurence{|i| i % 2} 
+  #   [2,2,3,4,4,4].occurrence{|i| i % 2}
   #   #=> { 0 => 5, 1 => 1 }
   #
   def occurrence

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

@@ -1,5 +1,3 @@
-require 'facets/array/product'
-
 class Array
   # Array#** is an alias for Array#product.
   #

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

@@ -1,7 +1,7 @@
 class Array
 
   # Generates a hash mapping each unique element in the array to the
-  # relative frequency, i.e. the probablity, of it appearence.
+  # relative frequency, i.e. the probability, of it appearance.
   #
   #   [:a, :b, :c, :c].probability  #=> {:a=> 0.25, :b=>0.25, :c=>0.5}
   #

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

@@ -6,11 +6,11 @@ class Array
   # Apply a method to array, and recursively apply that method
   # to each sub-array or given +types+.
   #
-  # By default the sub-types are passed thru uneffected. Passing
+  # By default the sub-types are passed through unaffected. 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. 
+  # block - Optional filter procedure to apply on each recursion.
   #
   # Examples
   #

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

@@ -2,7 +2,7 @@ require 'facets/array/store'
 
 class Array
 
-  # Splice acts a combination of #slice! and #store.
+  # Splice acts as a combination of #slice! and #store.
   # If two arguments are given it calls #store.
   # If a single argument is given it calls slice!.
   #

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

@@ -0,0 +1,23 @@
+require 'facets/array/variance'
+
+class Array
+
+  # Calculate the standard_deviation of an array of numbers
+  #
+  # Examples
+  #
+  #   [].standard_deviation #=> nil
+  #   [1, 2, 3].standard_deviation #=> 0.816496580927726
+  #   [96, 35, 72, 30, 75, 33, 68, 13, 49, 71].standard_deviation #=> 24.69331893448104
+  #   [36, -67, -17, 85, -46, -64, -23, -13, 89, -47].standard_deviation #=> 54.67183918618432
+  #   [60.7829, 31.2622, 20.626, 78.8907, 61.5328].standard_deviation #=> 21.428815505053002
+  #
+  def standard_deviation
+    return nil if empty?
+    Math.sqrt(variance)
+  end
+
+  alias sd standard_deviation
+end
+
+

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

@@ -7,9 +7,6 @@ class Array
   #   [[:a, 1], [:b, 2]].to_h
   #   #=> {:a=>1, :b=>2}
   #
-  #   [[:a, 1], :b].to_h
-  #   #=> {:a=>1, :b=>nil}
-  #
   # Returns [Hash].
   #
   def to_h

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

@@ -9,6 +9,10 @@ class Array
   #   a.uniq_by!{ |i| i*i }
   #   a #=> [-5, -4, -3, -2, -1, 0]
   #
+  #   a = (-5..5).to_a.reverse
+  #   a.uniq_by!{ |i| i*i }
+  #   a #=> [5, 4, 3, 2, 1, 0]
+  #
   # Returns [Array] of unique elements.
   #
   def uniq_by! #:yield:

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

@@ -0,0 +1,20 @@
+require 'facets/array/average'
+
+class Array
+
+  # Calculate the variance of an array of numbers
+  #
+  # Examples
+  #
+  #   [].variance #=> nil
+  #   [1, 2, 3].variance #=> 0.6666666666666666
+  #   [96, 35, 72, 30, 75, 33, 68, 13, 49, 71].variance #=> 609.76
+  #   [36, -67, -17, 85, -46, -64, -23, -13, 89, -47].variance #=> 2989.0099999999993
+  #   [60.7829, 31.2622, 20.626, 78.8907, 61.5328].variance #=> 459.1941339495999
+  #
+  def variance
+    avg = average
+    map {|n| (n - avg) ** 2 }.average
+  end
+end
+

data/lib/core/facets/binding.rb

@@ -2,7 +2,6 @@ require_relative 'binding/caller.rb'
 require_relative 'binding/callstack.rb'
 require_relative 'binding/call_stack.rb'
 require_relative 'binding/defined.rb'
-#require_relative 'binding/local_variables.rb'  # uncommon
 require_relative 'binding/op.rb'
 require_relative 'binding/op_get.rb'
 require_relative 'binding/op_set.rb'

data/lib/core/facets/enumerable/cluster.rb

@@ -1,10 +1,12 @@
 module Enumerable
 
-  # Clusters together adjacent elements into a list of 
-  # sub-arrays.
+  # Clusters together adjacent elements into a list of sub-arrays.
   #
-  # >> [2,2,2,3,3,4,2,2,1].cluster{ |x| x }
-  # => [[2, 2, 2], [3, 3], [4], [2, 2], [1]]
+  #     [2,2,2,3,3,4,2,2,1].cluster{ |x| x }
+  #     => [[2, 2, 2], [3, 3], [4], [2, 2], [1]]
+  #
+  #     ["dog", "duck", "cat", "dude"].cluster{ |x| x[0] }
+  #     => [["dog", "duck"], ["cat"], ["dude"]]
   #
   # @author Oleg K
 

data/lib/core/facets/enumerable/hashify.rb

@@ -4,13 +4,13 @@ require 'facets/enumerable/value_by'
 
 module Enumerable
 
-  # The hashify methods is a higher-order message used to 
+  # The hashify methods is a higher-order message used to
   # convert an enumerable object into a hash. Converting an
   # enumerable object into a hash is not a one-to-one conversion,
   # for this reason #hashify is used to provide variant approches
   # for the conversion most suited to the use case at hand.
   # Here are some (but not a complete set of) examples.
-  # 
+  #
   # If the enumerable is a collection of perfect pairs, like that
   # which Hash#to_a generates, then #assoc can be used.
   #
@@ -23,13 +23,13 @@ module Enumerable
   #   a = [ [:a,1,2], [:b,2], [:c], [:d] ]
   #   a.hashify.concat  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
   #
-  # If the array contians objects other then arrays then
+  # If the array contains objects other then arrays then
   # the #splat method might do the trick.
   #
   #   a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
-  #   a.hashify.splat  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil } 
+  #   a.hashify.splat  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil }
   #
-  # Also, the particular dispatch can be left up the Hashify 
+  # Also, the particular dispatch can be left up the Hashify
   # using the #auto method. See Hashify#auto for details on this.
   #
   # TODO: This method takes arguments only for the sake of the old
@@ -64,11 +64,9 @@ module Enumerable
     #
     #   a = [:a,1,:b,2,:c]
     #   a.to_h_splat  #=> { :a=>1, :b=>2, :c=>nil }
-    #
-    # TODO: Can this be done without #size?
     def splat
-      a = @enum.dup
-      a << nil if a.size % 2 == 1
+      a = @enum.to_a
+      a << nil if a.size.odd?
       Hash[*a]
     end
 
@@ -78,48 +76,46 @@ module Enumerable
     #
     #   a = [:a,1,[:b,2,:c]]
     #   a.to_h_flat  #=> { :a=>1, :b=>2, :c=>nil }
-    #
-    # TODO: Need to do this without #size.
     def flat
-      a = @enum.flatten
-      a << nil if a.size % 2 == 1
+      a = @enum.to_a.flatten
+      a << nil if a.size.odd?
       Hash[*a]
     end
 
-    # When a mixed or multi-element accociative array
+    # When a mixed or multi-element associative array
     # is used, the result is as follows:
     #
     #   a = [ [:a,1,2], [:b,2], [:c], :d ]
     #   a.hashify.assoc  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
     #
     # If the first entry of any subelements are the same, then
-    # the value will be set to the last occuring value.
+    # the value will be set to the last occurring value.
     #
     #   a = [ :x, [:x], [:x,1,2], [:x,3], [:x,4] ]
     #   a.hashify.assoc  #=> { :x=>[4] }
     #
     def associate
       h = {}
-      each do |k,*v| 
+      each do |k,*v|
         h[k] = v
       end
       h
     end
 
     # Alias for #associate.
-    alias :assoc, :associate
+    alias :assoc :associate
 
     # Like associate but does force values into an array.
     #
     def merge
       h = {}
-      each do |k,v| 
+      each do |k,v|
         h[k] = v
       end
       h
     end
 
-    # When a mixed or multi-element accociative array
+    # When a mixed or multi-element associative array
     # is used, the result is as follows:
     #
     #   a = [ [:a,1,2], [:b,2], [:c], :d ]
@@ -129,11 +125,11 @@ module Enumerable
     # the values will be merged using #concat.
     #
     #   a = [ [:a,1,2], [:a,3], [:a,4], [:a], :a ]
-    #   a.hasify.concat  #=> { :a=>[1,2,3,4] }
+    #   a.hashify.concat  #=> { :a=>[1,2,3,4] }
     #
     def concat
       h = {}
-      each do |k,*v| 
+      each do |k,*v|
         h[k] ||= []
         h[k].concat(v)
       end
@@ -141,7 +137,7 @@ module Enumerable
     end
 
     # Older name for #concat.
-    alias :multi, :concat
+    alias :multi :concat
 
     # Convert enumerable object to Hash using index as keys.
     #
@@ -158,11 +154,11 @@ module Enumerable
     # Converts enumerable object into a hash. Converting an array
     # into a hash is not a one-to-one conversion, for this
     # reason #auto examines the enumerable being converted
-    # and then dispatches the conversion to the most sutiable
-    # specialized function. There are three possiblities for this.
+    # and then dispatches the conversion to the most suitable
+    # specialized function. There are three possibilities for this.
     #
     # If the enumerable is a collection of perfect pairs, like that
-    # which Hash#to_a generates, then conversion is handled by 
+    # which Hash#to_a generates, then conversion is handled by
     # #flat.
     #
     #   a = [ [:a,1], [:b,2] ]
@@ -174,14 +170,14 @@ module Enumerable
     #   a = [ [:a,1,2], [:b,2], [:c], [:d] ]
     #   a.hashify.auto  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
     #
-    # If it contians objects other then arrays then the #splat method
+    # If it contains objects other then arrays then the #splat method
     # is called.
     #
     #   a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
-    #   a.hashify.auto  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil } 
+    #   a.hashify.auto  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil }
     #
     # Be aware this is not as efficient as using the underlying methods
-    # directly becuase it must perform an initial iteration over the
+    # directly because it must perform an initial iteration over the
     # enumerable to determine its contents.
 
     def auto(&block)
@@ -206,18 +202,18 @@ module Enumerable
     end
 
     # Alias for `#auto`.
-    alias :automatic, :auto
+    alias :automatic :auto
 
   private
 
     #
     def each(&b)
-      @enum.each(&b) 
+      @enum.each(&b)
     end
 
     #
     def each_with_index(&b)
-      @enum.each_with_index(&b) 
+      @enum.each_with_index(&b)
     end
 
   end

data/lib/core/facets/enumerable/sum.rb

@@ -4,9 +4,19 @@ module Enumerable
   #
   #     [1,2,3].sum      #=> 6
   #     [3,3,3].sum      #=> 9
-  #     [].sum           #=> 0
   #
-  # A initial value can be passed to the method.
+  # Note that Facets' sum method is completely generic -- it can work
+  # on any objects that respond to #+.
+  #
+  #     [[1],[2],[3]].sum   #=> [1,2,3]
+  #
+  # For this reason it is usually a good idea to provide a default
+  # value. Consider the difference between the two expressions below.
+  #
+  #     [].sum           #=> nil
+  #     [].sum(0)        #=> 0
+  #
+  # This default value also acts as an initial value.
   #
   #     [].sum(5)        #=> 5
   #     [1,2,3].sum(10)  #=> 16

data/lib/core/facets/file/atomic_open.rb

@@ -12,7 +12,7 @@ class File
   #
   def self.atomic_open(file_name, mode="r", temp_dir=nil, &block)
     temp_dir  = temp_dir || Dir.tmpdir
-    temp_file = Tempfile.new("#{aomtic_id}-" + basename(file_name), temp_dir)
+    temp_file = Tempfile.new("#{atomic_id}-" + basename(file_name), temp_dir)
 
     if File.exist?(file_name)
       FileUtils.cp(file_name, temp_file)