facets 3.0.0 → 3.1.0

data/demo/core/array/after.md

@@ -0,0 +1,13 @@
+## Array#after
+
+    require 'facets/array/after'
+
+`Array#after` returns the first value that comes after a given value. The
+value after the last is the first. Returns `nil` if the given value is not
+in the array.
+
+    sequence = ['a', 'b', 'c']
+    sequence.after('a').assert == 'b'
+    sequence.after('b').assert == 'c'
+    sequence.after('c').assert == 'a'
+    sequence.after('d').assert == nil

data/demo/core/array/arrange.md

@@ -0,0 +1,17 @@
+## Array#arrange
+
+    require 'facets/array/arrange'
+
+The `arrange` method produces appropriate ranges from the objects in the array.
+It assumes inclusive ranges (i.e. `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.
+
+    [1,2,3,6,7,8].arrange.assert == [1..3, 6..8]
+
+    [10..15, 16..20, 21, 22].arrange.assert == [10..22]
+
+    a = %w{a b c g h i j k  m o}
+    a.arrange.assert == ['a'..'c','g'..'k', 'm' , 'o']
+

data/demo/core/array/before.md

@@ -0,0 +1,14 @@
+## Array#before
+
+    require 'facets/array/before'
+
+Returns the value prior to the given value. The value previous
+to the first is the last. Returns nil if the given value is not
+in the array.
+
+    sequence = ['a', 'b', 'c']
+    sequence.before('a').assert == 'c'
+    sequence.before('b').assert == 'a'
+    sequence.before('c').assert == 'b'
+    sequence.before('d').assert == nil
+

data/demo/core/array/collapse.md

@@ -0,0 +1,15 @@
+## Array#collapse
+
+    require 'facets/array/collapse'
+
+Simplify an array by flattening it then compacting it.
+
+    [1,[2,nil,[3]],nil,4].collapse.assert == [1,2,3,4]
+
+## Array#collapse!
+
+Simplify an array by flattening it in place then compacting it in place.
+
+    a = [1, nil, [1, 2], nil, [[3]]]
+    a.collapse!
+    a.assert == [1, 1, 2, 3]

data/demo/core/array/collisions.md

@@ -0,0 +1,30 @@
+## Array#collisions
+
+_alias for Array#commonality_.
+
+    require 'facets/array/collisions'
+
+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.
+
+This can be useful, for instance, in determining all persons that share
+their last name with another person.
+
+    Person = Struct.new(:name)
+    persons = %w{Wayne Pennyworth Grayson Wayne Pennyworth}.map{|n| Person.new(n)}
+    persons.collisions { |person| person.name }.keys.assert == ["Wayne","Pennyworth"]
+
+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 }`.
+
+    expected = { 2 => [2, 2], 4 => [4, 4] }
+
+    [1, 2, 2, 3, 4, 4].group_by{ |e| e }.
+                       select{ |k,v| v.size > 1 }.assert == expected
+
+    [1, 2, 2, 3, 4, 4].collisions.assert == expected
+
+    %w{foo bar baz}.collisions{|str| str[0]}.assert == {'b' =>["bar", "baz"] }
+
+Returns a Hash mapping common attribute to those elements.

data/demo/core/array/commonality.md

@@ -0,0 +1,31 @@
+## Array#commonality
+
+    require 'facets/array/commonality'
+
+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.
+
+This can be useful, for instance, in determining all persons that share
+their last name with another person.
+
+    Person = Struct.new(:name)
+    persons = %w{Wayne Pennyworth Grayson Wayne Pennyworth}.map{|n| Person.new(n)}
+    persons.commonality { |person| person.name }.keys # => ["Wayne","Pennyworth"]
+
+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 }`.
+
+    expected = { 2 => [2, 2], 4 => [4, 4] }
+
+    [1, 2, 2, 3, 4, 4].group_by{ |e| e }.
+                       select{ |k,v| v.size > 1 }.assert == expected
+
+    [1, 2, 2, 3, 4, 4].commonality.assert == expected
+
+
+    %w{foo bar baz}.commonality{|str| str[0]}.assert == {'b' =>["bar", "baz"] }
+
+Returns a Hash mapping common attribute to those elements.
+
+

data/demo/core/array/conjoin.md

@@ -0,0 +1,47 @@
+## Array#conjoin
+
+    require 'facets/array/conjoin'
+
+This is more advanced form of #join. It allows for fine control
+of separators.
+
+NOTE: The old version used to default its separator to ", " and
+default the terminating separator to " and ". This is no longer
+the case. You must specifically provide these parameters.
+
+If no parameters are given, it acts like #join but will a space
+separator.
+
+    [1,2,3].conjoin.assert == "1 2 3"
+
+Use comma+space and 'and' on tail.
+
+    [1,2,3].conjoin(', ', ' and ').assert == "1, 2 and 3"
+
+Use comma+space and 'or' on tail using :last option.
+
+    [1,2,3].conjoin(', ', :last => ' or ').assert == "1, 2 or 3"
+
+Use semicolon+space and ampersand on tail using index.
+
+    [1,2,3].conjoin('; ', -1 => ' & ').assert == "1; 2 & 3"
+
+Can take a block to determine separator.
+
+    [1,2,3,4].conjoin{ |i, a, b| i % 2 == 0 ? '.' : '-' }.assert == "1.2-3.4"
+
+This makes very esoteric transformation possible.
+
+    [1,1,2,2].conjoin{ |i, a, b| a == b ? '=' : ' != ' }.assert == "1=1 != 2=2"
+
+    [1,2,3,4].conjoin{ |i, x, y| "<#{i} #{x} #{y}>" }.assert == "1<0 1 2>2<1 2 3>3<2 3 4>4"
+
+There are also spacing options. Providing the :space option
+pads the separators.
+
+    [1,2,3].conjoin(',', '&', :space=>2).assert == "1  ,  2  &  3"
+
+And the :spacer option can set an alternate spacing string.
+
+    [1,2,3].conjoin('|', '>', :space=>2, :spacer=>'-').assert == "1--|--2-->--3"
+

data/demo/core/array/contains.md

@@ -0,0 +1,9 @@
+## Array#contains?
+
+_alias of Array#include? _
+
+    require 'facets/array/contains'
+
+    [1,2,3,4].assert.contains?(2)
+    [1,2,3,4].refute.contains?(9)
+

data/demo/core/array/delete_unless.md

@@ -0,0 +1,13 @@
+## Array#delete_unless
+
+    require 'facets/array/delete_unless'
+
+The method `#delete_unless` is the inverse of `#delete_if`.
+
+    a = [1,2,3]
+    a.delete_unless{ |e| e == 2 }
+    a.assert == [2]
+
+    [1,2,3].delete_unless{ |x| x < 2 }.assert == [1]
+    [1,2,3].delete_unless(&:even?).assert == [2]
+

data/demo/core/array/delete_values.md

@@ -0,0 +1,10 @@
+## Array#delete_values
+
+    require 'facets/array/delete_values'
+
+Delete multiple values from array.
+
+    a = [1,2,3,4]
+    a.delete_values(1,2)   #=> [1,2]
+    a                      #=> [3,4]
+

data/demo/core/array/delete_values_at.md

@@ -0,0 +1,15 @@
+## Array#delete_values_at
+
+    require 'facets/array/delete_values_at'
+
+Delete multiple values from array given
+indexes or index range.
+
+    a = [1,2,3,4]
+    a.delete_values_at(1,2).assert == [2,3]
+    a.assert                       == [1,4]
+
+    a = [1,2,3,4]
+    a.delete_values_at(0..2).assert == [1,2,3]
+    a.assert                        == [4]
+

data/demo/core/array/divide.md

@@ -0,0 +1,14 @@
+## Array#divide
+
+    require 'facets/array/divide'
+
+Divide into sub arrays at elemetns matching given pattern
+
+    r = ['a1','b1','a2','b2'].divide(/^a/)
+    r.assert == [['a1','b1'],['a2','b2']]
+
+    r = ['a1','b1','a2','b2'].divide(/^b/)
+    r.assert == [['a1'],['b1','a2'],['b2']]
+
+    r = ['a1','b1','a2','b2'].divide(/c/)
+    r.assert = [['a1','b1','a2','b2']]

data/demo/core/array/duplicates.md

@@ -0,0 +1,14 @@
+## Array#duplicates
+
+    require 'facets/array/duplicates'
+
+Return list of duplicate elements.
+
+    [1,1,2,3].duplicates #=> [1]
+
+Return list of those duplicated min times.
+
+    [1,1,2,3,2,4,5,4,2].duplicates(3) #=> [2]
+
+
+

data/demo/core/array/each_overlap.md

@@ -0,0 +1,12 @@
+## Array#each_overlap
+
+    require 'facets/array/each_overlap'
+
+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.assert == [[1,2],[2,3],[3,4],[4,5]]
+

data/demo/core/array/each_pair.md

@@ -0,0 +1,13 @@
+## Array#each_pair
+
+    require 'facets/array/each_pair'
+
+Iterate over an array yielding with index and value.
+
+    result = {}
+    a = [:a,:b,:c,:d]
+    a.each_pair{|i,e| result[e] = i + 1}
+    result.assert == {a: 1, b: 2, c: 3, d: 4}
+
+*NOTE* this is the inverse of `Array#each_with_index`, and is intended to provide
+polymorphism with `Hash#each_pair`.

data/demo/core/array/each_value.md

@@ -0,0 +1,12 @@
+## Array#each_value
+
+    require 'facets/array/each_value'
+
+This is an alias of Alias#each, and is provided to provide polymorphism with
+Hash#each_value.
+
+    a = [ "a", "b", "c" ]
+    out = ''
+    a.each_value {|x| out +=  "#{x} -- " }
+    out.assert == 'a -- b -- c -- '
+

data/demo/core/array/entropy.md

@@ -0,0 +1,13 @@
+## Array#entropy
+
+    require 'facets/array/entropy'
+
+Shannon's entropy for an array - returns the average
+bits per symbol required to encode the array.
+Lower values mean less "entropy" - i.e. less unique
+information in the array.
+
+    e = %w{ a b c d e e e }.entropy
+
+    ("%.3f" % e)  #=> "2.128"
+

data/demo/core/array/extract_options.md

@@ -0,0 +1,13 @@
+## Array#extract_options!
+
+    require 'facets/array/extract_options'
+
+Extracts options from a set of arguments. Removes and returns the last
+element in the array if it's a hash, otherwise returns a blank hash.
+
+    def options(*args)
+      args.extract_options!
+    end
+
+    options(1, 2).assert           == {}
+    options(1, 2, :a => :b).assert == {:a=>:b}

data/demo/core/array/first.md

@@ -0,0 +1,11 @@
+## Array#first!
+
+    require 'facets/array/indexable'
+
+Alias for shift, which removes and returns the first element in an array
+  
+    a = ['a','y','z']
+    a.first!.assert == 'a'
+    a.assert ['y','z']
+    
+    

data/demo/core/array/from.md

@@ -0,0 +1,11 @@
+## Array#thru
+
+    require 'facets/array/from'
+
+Returns elements from index i until the end.
+
+    %w{W o r l d}.from(3).assert == %w{l d}
+
+Returns entire array for i > length
+
+    %w{W o r l d}.from(7).assert == nil

data/demo/core/array/ideal_entropy.md

@@ -0,0 +1,11 @@
+## Array#ideal_entropy
+
+    require 'facets/array/entropy'
+
+Returns the maximum possible Shannon entropy of the array
+with given size assuming that it is an "order-0" source
+(each element is selected independently of the next).
+
+    %w{ a b }.ideal_entropy.assert == 1.0
+    %w{ a a b b }.ideal_entropy.assert == 2.0
+

data/demo/core/array/intersection.md

@@ -0,0 +1,11 @@
+## Array#intersection
+
+    require 'facets/array/intersection'
+    
+Returns the values in common for an array set (nil, single value/object, or range).
+
+    [1,2].intersection.assert == nil
+    [1..10,11..20].intersection.assert == nil
+    [10,1..10].intersection.assert == 10
+    [1..10,5,5..8,4..8].intersection.assert == 5
+    [1..10, 5..8, 5..10 ].intersection.assert == (5..8)

data/demo/core/array/last.md

@@ -0,0 +1,11 @@
+## Array#last!
+
+    require 'facets/array/indexable'
+    
+Alias for pop, which removes and returns the last element in an
+array.
+
+    a = [1,2,3]
+    a.last!.assert == 3
+    a.assert == [1,2]
+    

data/demo/core/array/median.md

@@ -0,0 +1,23 @@
+# Array#median
+
+    require 'facets/array/median'
+
+Determines the _sorted_ middle element.
+
+    a = %w{a a b b c c c}
+    a.median     #=> "b"
+
+When there are an even number of elements, the greater
+of the two middle elements is given.
+
+    a = %w{a a b b c c c d}
+    a.median     #=> "c"
+
+An offset can be supplied to get an element relative
+to the middle.
+
+    a = %w{a a b b c c c d}
+    a.median(-1) #=> "b"
+
+The the array is empty, +nil+ is returned.
+

data/demo/core/array/merge.md

@@ -0,0 +1,15 @@
+## Array#merge
+
+    require 'facets/array/merge'
+
+    a = [1,2,3]
+    b = [3,4,5]
+    a.merge(b).assert == [1,2,3,4,5]
+
+## Array#merge!
+
+    a = [1,2,3]
+    b = [3,4,5]
+    a.merge!(b)
+    a.assert == [1,2,3,4,5]
+

data/demo/core/array/missing.md

@@ -0,0 +1,10 @@
+## Array#missing
+
+    require 'facets/array/missing'
+
+Determine the 'holes' in the values of an array.  Returns the missing elements
+in an array set.
+
+    [1,3..3].missing.assert == [2]
+    [1..5,10..12].missing.assert == [6..9]
+    [100, 9..11, 14, 1..5, 16, 10..12, 17..17].missing.assert == [6..8, 13, 15, 18..99]