Merge branch 'master' of github.com:rubyworks/facets

Guardfile

@@ -42,8 +42,8 @@ end
 group :qed do
   guard :qed do
     watch('demo/applique/') { 'demo' }
-    watch(%r{^lib/(.+)/facets/(.+\.rdoc)$}) { |m| "demo/#{m[1]}/#{m[2]}" }
-    watch(%r{^demo/.+/.+\.rdoc$})
+    watch(%r{^lib/(.+)/facets/(.+\.md)$}) { |m| "demo/#{m[1]}/#{m[2]}" }
+    watch(%r{^demo/.+/.+\.md})
   end
 end
 

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)

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]

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]

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]

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?

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]

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 }
+

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]]

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
+

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]

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}

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]

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"]]

demo/core/array/recursively.md

@@ -2,14 +2,19 @@
 
     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']].recursively.each{ |v| r << v }
-    r.assert == [1,2,'a','b']
-
+    [1,2,['a','b'], 3].recursively.each{|v| r << v}
+    r.assert = [1,2,'a','b', 3]
+    
 map
 
-    r = [1,2,['a','b']].recursively.map{ |v| v.succ }
-    r.assert == [2,3,['b','c']]
-
+    arr = ['foo','bar',['a','b']]
+    arr.recursively.map{|v| v.to_sym}.assert == [:foo,:bar,[:a,:b]]

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]

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]

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']]
+
+

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]
+

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 == []

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"

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}

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']]
+
+        

demo/core/array/uniq_by.md

@@ -2,8 +2,15 @@
 
     require 'facets/array/uniq_by'
 
-    e = [-5, -4, -3, -2, -1, 0]
+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 == e
+    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]
+
 

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

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]]
+

demo/core/comparable/bound.md

@@ -1,5 +1,7 @@
 ## Comparable#bound
 
+    require 'facets/comparable/bound'
+
 The `#bound` method is an alias for `#clip`. It is the original name
 of the method before the `clip`/`cap` duo was decided upon.
 

demo/core/dir/recurse.md

@@ -25,8 +25,8 @@ list of all the entries.
 
 ## Dir#ls_r
 
-  Dir#ls_r is an alias for #recurse which can also be used to gather
-  a complete recursive list of all the entries.
+Dir#ls_r is an alias for #recurse which can also be used to gather
+a complete recursive list of all the entries.
 
     x = %w{
       recurse/A

demo/core/integer/times_collect.md

@@ -1,6 +1,6 @@
 ## Integer#times_collect
 
-    require 'facets/integer/times_collect'
+    require 'facets/integer/of'
 
     a = 4
     b = a.times_collect{ |i| i*2 }

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