facets 3.0.0 → 3.1.0

data/demo/core/array/mode.md

@@ -0,0 +1,9 @@
+## Array#mode
+
+    require 'facets/array/mode'
+    
+In Statistics, mode is the value that occurs most frequently in a given set of
+data. This method returns an array in case there is a tie.
+
+    [1, 1, 2, 3].mode.assert    == [1]
+    [1, 1, 2, 2, 3].mode.assert == [1,2]

data/demo/core/array/nonuniq.md

@@ -0,0 +1,16 @@
+## Array#nonuniq
+
+    require 'facets/array/nonuniq'
+    
+Returns a list of non uniq elements.
+  
+    a = [1, 1, 2, 2, 3, 4, 5]
+    a.nonuniq.sort.assert == [1, 2]
+
+## Array#nonuniq!
+
+Same as #nonuniq but acts in place.
+
+    a = [1, 1, 2, 2, 3, 4, 5]
+    a.nonuniq!
+    a.sort.assert == [1,2]

data/demo/core/array/not_empty.md

@@ -0,0 +1,8 @@
+## Array#not_empty?
+
+    require 'facets/array/not_empty'
+    
+Array is not empty?
+
+    [1,2].assert.not_empty?
+    [].refute.not_empty?

data/demo/core/array/occur.md

@@ -0,0 +1,18 @@
+## Array#occur
+
+    require 'facets/array/occur'
+    
+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.
+
+    a = [:a,:b,:a]
+    a.occur(1).assert == [:b]
+    a.occur(2).assert == [:a]
+
+    a = [:a,:b,:a]
+    a.occur(1..2).assert == [:a,:b]
+
+    a = [:a,:b,:a]
+    a.occur{ |n| n % 2 == 0 }.assert == [:a]

data/demo/core/array/occurrence.md

@@ -0,0 +1,13 @@
+## Array#occurrence
+
+    require 'facets/array/occurrence'
+
+Create a hash of each uniq element of the array
+and how many time each appears.
+
+    r = [:a,:a,:b,:c,:c,:c].occurrence
+    r.assert == { :a => 2, :b => 1, :c => 3 }
+
+    r = [2,2,3,4,4,4].occurrence{|i| i % 2}
+    r.assert == { 0 => 5, 1 => 1 }
+

data/demo/core/array/only.md

@@ -0,0 +1,9 @@
+## Array#only
+
+    require 'facets/array/only'
+
+    [5].only.assert == 5
+    [nil].only.assert == nil
+    expect(IndexError){ [].only }
+    expect(IndexError){ [1,2,3].only }
+

data/demo/core/array/op_pow.md

@@ -0,0 +1,10 @@
+## Array#**
+
+    require 'facets/array/op_pow'
+
+Alias for Array#product
+
+NOTE: This method is not a common core extension and is not loaded automatically
+when using ```require 'facets'```
+
+    ([1,2] ** [3,4]).assert == [[1, 3], [1, 4], [2, 3], [2, 4]]

data/demo/core/array/pad.md

@@ -0,0 +1,28 @@
+## Array#pad
+
+    require 'facets/array/pad'
+
+    r = [0,1,2,3].pad(7,"x")
+    x = [0,1,2,3,"x","x","x"]
+    r.assert == x
+
+negative index
+
+    r = [0,1,2,3].pad(-7,"n")
+    x = ["n","n","n",0,1,2,3]
+    r.assert == x
+
+## Array#pad!
+
+    a = [0,1,2,3]
+    r = a.pad!(6,"y")
+    x = [0,1,2,3,"y","y"]
+    r.assert == x
+
+negative index
+
+    a = [0,1,2,3]
+    r = a.pad!(-6,"q")
+    x = ["q","q",0,1,2,3]
+    r.assert == x
+

data/demo/core/array/peek.md

@@ -0,0 +1,10 @@
+## Array#peek
+
+    require 'facets/array/peek'
+    
+Provide an index to inspect the array from back to front.
+
+    [1,2,3].peek    .assert == 3
+    [1,2,3].peek(1) .assert == 2
+    [1,2,3].peek(-1).assert == 1
+

data/demo/core/array/poke.md

@@ -0,0 +1,15 @@
+## Array#poke
+
+    require 'facets/array/poke'
+    
+Put an object on the bottom of the stack (front of the array).
+
+    a = [2,3]
+    a.poke(1)
+    a.assert == [1,2,3]
+    
+Or supply an index and #poke works like insert.
+
+    a = [1,3]
+    a.poke(2,1)
+    a.assert == [1,2,3]

data/demo/core/array/probability

@@ -0,0 +1,8 @@
+## Array#probability
+
+    require 'facets/array/probability'
+
+Generates a hash mapping each unique element in the array to the relative
+frequency, i.e. the probability, of it's appearance.
+
+    [:a, :b, :c, :c].probability.assert == {a: 0.25, b: 0.25, c: 0.50}

data/demo/core/array/pull.md

@@ -0,0 +1,10 @@
+## Array#pull
+
+    require 'facets/array/pull'
+    
+Alias for Array#shift which removes an object off the first slot of an array.
+This is the opposite of pop.
+
+    a = [1,2,3]
+    a.pull.assert == 1
+    a.assert == [2,3]

data/demo/core/array/recurse.md

@@ -0,0 +1,10 @@
+## Array#recurse
+
+    require 'facets/array/recurse'
+    
+Apply a block to array, and recursively apply that block to each sub-array
+or +type+.
+
+    a = ["a", ["b", "c", nil], nil]
+    r = a.recurse{|a| a.compact!}
+    r.assert == ["a", ["b", "c"]]

data/demo/core/array/recursively.md

@@ -0,0 +1,20 @@
+## Array#recursively
+
+    require 'facets/array/recursively'
+
+Apply a method to  array, and recursively apply that method to each sub-array
+or given +types+.
+
+By default the sub-types are passed through unaffected. Passing a block
+to #recursively can be used to change this.
+
+each
+
+    r = []
+    [1,2,['a','b'], 3].recursively.each{|v| r << v}
+    r.assert = [1,2,'a','b', 3]
+    
+map
+
+    arr = ['foo','bar',['a','b']]
+    arr.recursively.map{|v| v.to_sym}.assert == [:foo,:bar,[:a,:b]]

data/demo/core/array/reject_values.md

@@ -0,0 +1,10 @@
+## Array#reject_values
+
+    require 'facets/array/reject_values'
+    
+Non-destructive form of Array#delete_values. Unlike delete_values this method
+returns a new array.
+
+    a = [1,2,3,4,5]
+    a.reject_values(2,4).assert == [1,3,5]
+    a.assert [1,2,3,4,5]

data/demo/core/array/splice.md

@@ -0,0 +1,14 @@
+## Array#splice
+
+    require 'facets/array/splice'
+    
+Splice acts as a combination of #slice! and #store.  If one argument is given it
+calls #slice!, if two are given it calls #store.
+
+    a = [1,2,3]
+    a.splice(1).assert == 2
+    a.assert == [1,3]
+    
+    b = [1,2,3]
+    b.splice(1,4).assert == 4
+    b.assert == [1,4,3]

data/demo/core/array/split.md

@@ -0,0 +1,13 @@
+## Array#split
+
+    require 'facets/array/split'
+    
+Split on matching pattern.  Unlike #divide, this does not include matching 
+elements.
+
+    ['a','b','c'].split('b').assert == [['a'],['c']]
+    
+    a = ['a1','a2','b1','a3','b2','a4']
+    a.split(/^b/).assert == [['a1','a2'],['a3'],['a4']]
+    
+    

data/demo/core/array/squeeze.md

@@ -0,0 +1,14 @@
+## Array#squeeze!
+
+    require 'facets/array/squeeze'
+    
+Destructive version of Enumerable#squeeze.
+
+    a = [1,2,2,3,3,2,1]
+    a.squeeze!
+    a.assert == [1,2,3,2,1]
+    
+    a = [1,2,2,3,3,2,1]
+    a.squeeze!(3)
+    a.assert == [1,2,2,3,2,1]
+    

data/demo/core/array/step.md

@@ -0,0 +1,16 @@
+## Array#step
+
+    require 'facets/array/step'
+    
+Iterate over every nth element of an array.  Without a block, it returns an 
+Enumerator.
+
+    r = []
+    [:a, :b, :c, :d].step(2) { |x| r << x }
+    r.assert == [:b, :d]
+    
+    [:a, :b, :c, :d].step(1).to_a.assert == [:a, :b, :c, :d]
+    [:a, :b, :c, :d].step(2).to_a.assert == [:b, :d]
+    [:a, :b, :c, :d].step(3).to_a.assert == [:c]
+    [:a, :b, :c, :d].step(4).to_a.assert == [:d]
+    [:a, :b, :c, :d].step(5).to_a.assert == []

data/demo/core/array/store.md

@@ -0,0 +1,9 @@
+## Array#store
+
+    require 'facets/array/store'
+    
+Store a value at a given index.  Store is an alias for #[]=
+
+    a = []
+    a.store(1,"A")
+    a[1].assert == "A"

data/demo/core/array/thru.md

@@ -0,0 +1,12 @@
+## Array#thru
+
+    require 'facets/array/thru'
+
+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]
+

data/demo/core/array/to_h.md

@@ -0,0 +1,11 @@
+## Array#to_h
+
+    require 'facets/array/to_h'
+
+Convert an associative array to a Hash.  Each element of the associative array 
+should be a 1 or 2 element array
+
+Note this is built into ruby as of 2.1.0
+
+    arr = [[:a, 1], [:b, 2]]
+    arr.to_h.assert == {:a => 1, :b => 2}

data/demo/core/array/traverse.md

@@ -0,0 +1,20 @@
+## Array#traverse
+
+    require 'facets/array/traverse'
+    
+Construct a new array created by traversing the array and its sub-arrays,
+executing the given block on the elements.
+
+    h = ['A', 'B', ['X', 'Y']]
+    g = h.traverse{ |e| e.downcase }
+    g.assert = ['a','b',['x', 'y']]
+    
+## Array#traverse!
+
+Like #traverse, but will change the array in place.
+
+    h = ['A', 'B', ['X', 'Y']]
+    h.traverse!{ |e| e.downcase }
+    h.assert = ['a','b',['x', 'y']]
+
+        

data/demo/core/array/uniq_by.md

@@ -0,0 +1,16 @@
+## Array#uniq_by!
+
+    require 'facets/array/uniq_by'
+
+Like #uniq, but determines uniqueness based on a given block.  
+As can be seen from the examples, order is significant.
+
+    r = (-5..5).to_a
+    r.uniq_by!{ |i| i*i }
+    r.assert == [-5, -4, -3, -2, -1, 0]
+    
+    r = (-5..5).to_a.reverse
+    r.uniq_by!{ |i| i*i }
+    r.assert == [5, 4, 3, 2, 1, 0]
+    
+

data/demo/core/array/unique_permutation.md

@@ -0,0 +1,14 @@
+## Array#unique_permutation
+
+    require 'facets/array/unique_permutation'
+    
+Enumerates permutation of Array.  Unlike Array#permutation, there are no 
+duplicates in generated permutations.  Instead elements must be comparable
+
+      p = [1,1,2,2,3].unique_permutation(2).to_a
+      e = [[1, 1], [1, 2], [1, 3], [2, 1], [2, 2], [2, 3], [3, 1], [3, 2]]
+      p.assert == e
+
+      [1,1,2,3].unique_permutation.to_a.assert != [1,1,2,3].permutation.to_a
+
+      [1,1,2,3].unique_permutation.to_a.assert == [1,1,2,3].permutation.to_a.uniq

data/demo/core/array/zip.md

@@ -0,0 +1,8 @@
+## Array::zip
+
+    require 'facets/array/zip'
+    
+Class level rendition of Array#zip
+
+    Array.zip([1,2], [3,4]).assert == [[1,3],[2,4]]
+

data/demo/core/binding/caller.md

@@ -0,0 +1,57 @@
+The caller.rb script includes a few related methods.
+We will use the following code to demonstrate their use.
+
+    require 'facets/binding/caller'
+
+    a = 1
+    b = 2
+    x = "hello"
+  
+    @bind = binding
+    @line = __LINE__  # the line number must be updated if it moves
+    @file = __FILE__  # why does it equal basename only?
+
+## Binding#caller
+
+    @bind.caller
+
+## Binding#callstack
+
+    @bind.callstack.assert.is_a?(Array)
+
+## Binding#__LINE__
+
+    @bind.__LINE__.assert == @line - 1
+ 
+## Binding#__FILE__
+
+    @bind.__FILE__.assert == @file
+
+## Binding#__DIR__
+
+    @bind.__DIR__.assert == File.dirname(@file)
+
+## Binding#__callee__
+
+This only works for certain versions.
+
+    def alternate_callee
+      binding
+    end
+
+    unless RUBY_VERSION < "1.9"
+      alternate_callee.__callee__.assert == :alternate_callee
+    end
+
+## Binding#__method__
+
+This only works for certain versions.
+
+    def alternate_method
+      binding
+    end
+
+    unless RUBY_VERSION < "1.8.7"
+      alternate_method.__method__.assert == :alternate_method
+    end
+

data/demo/core/binding/defined.md

@@ -0,0 +1,10 @@
+## Binding#defined?
+
+    require 'facets/binding/defined'
+
+    a = 1
+    b = 2
+    x = "hello"
+
+    binding.assert.defined?("x")
+