Class | Array

In:

lib/core/facets/array/before.rb
lib/core/facets/array/collapse.rb
lib/core/facets/array/combination.rb
lib/core/facets/array/commonality.rb
lib/core/facets/array/conjoin.rb
lib/core/facets/array/contains.rb
lib/core/facets/array/delete_unless.rb
lib/core/facets/array/delete_values.rb
lib/core/facets/array/divide.rb
lib/core/facets/array/entropy.rb
lib/core/facets/array/extract_options.rb
lib/core/facets/array/from.rb
lib/core/facets/array/index.rb
lib/core/facets/array/indexable.rb
lib/core/facets/array/merge.rb
lib/core/facets/array/mode.rb
lib/core/facets/array/nonuniq.rb
lib/core/facets/array/not_empty.rb
lib/core/facets/array/only.rb
lib/core/facets/array/pad.rb
lib/core/facets/array/permutation.rb
lib/core/facets/array/probability.rb
lib/core/facets/array/product.rb
lib/core/facets/array/pull.rb
lib/core/facets/array/recurse.rb
lib/core/facets/array/recursively.rb
lib/core/facets/array/rotate.rb
lib/core/facets/array/select.rb
lib/core/facets/array/splice.rb
lib/core/facets/array/split.rb
lib/core/facets/array/store.rb
lib/core/facets/array/traverse.rb
lib/core/facets/array/uniq_by.rb
lib/core/facets/boolean.rb
lib/core/facets/enumerable/count.rb
lib/core/facets/kernel/blank.rb
lib/core/facets/object/object_state.rb
lib/core/facets/to_hash.rb
lib/core-uncommon/facets/array/median.rb
lib/core-uncommon/facets/array/op_pow.rb
lib/core-uncommon/facets/array/percentile.rb
lib/standard/facets/random.rb
lib/standard/facets/set.rb
lib/standard/facets/shellwords.rb
lib/supplemental/facets/tuple.rb

Parent: | Object

### Methods

** after before collapse collisions combination commonality conjoin delete_unless delete_values delete_values_at divide duplicates entropy extract_options! from ideal_entropy index median merge! mode nonuniq nonuniq! not_empty? object_state only pad pad! peek percentile permutation poke power_set probability product recurse recurse! recursively rotate rotate! select! shelljoin shellwords splice split thru to_b to_h to_h_assoc to_h_auto to_h_flat to_h_multi to_h_splat to_t traverse traverse! uniq_by!

### Included Modules

Indexable Random::ArrayExtensions

### External Aliases

include? | -> | contains?
| Alias for include?.
shift | -> | first!

Alias for shift, which removes and returns the first element in an array.

      a = ["a","y","z"]
      a.first!      #=> "a"
      a             #=> ["y","z"]

CREDIT: Trans

pop | -> | last!

Alias for pop, which removes and returns the last element in an array.

      a = [1,2,3]
      a.last!       #=> 3
      a             #=> [1,2]

CREDIT: Trans

| | -> | merge

Alias for `|`.

      [1,2].merge([2,3])  #=> [1,2,3]

shift | -> | pull
| Alias for shift which removes an object off first slot of an array. This is the opposite of pop.
[]= | -> | store

Store a value at a given index. Store is an alias for #[]=.

      a = []
      a.store(1, "A")
      a[1] #=> "A"

empty? | -> | blank?

### Public Instance methods

**(*enums)

Alias for product

after(value)

Returns the value after the given value. The value before the last is the first. Returns nil if the given value is not in the array.

Examples

      sequence = ['a', 'b', 'c']
      sequence.after('a')           #=> 'b'
      sequence.after('b')           #=> 'c'
      sequence.after('c')           #=> 'a'
      sequence.after('d')           #=> nil

CREDIT: Tyler Rick

before(value)

Returns the value previous to the given value. The value previous to the first is the last. Returns nil if the given value is not in the array.

Examples

      sequence = ['a', 'b', 'c']
      sequence.before('a')           #=> 'c'
      sequence.before('b')           #=> 'a'
      sequence.before('c')           #=> 'b'
      sequence.before('d')           #=> nil

CREDIT: Tyler Rick

collapse()

Simplify an array by flattening it then compacting it.

      [1,[2,nil,[3]],nil,4].collapse  #=> [1,2,3,4]

collisions(&block)

Alias for commonality

combination(k=2) {|s.values_at(*idx)| ...}

Yields the block to each unique combination of n elements.

      a = %w|a b c d|
      a.combination(3)

produces

      [["a", "b", "c"],
       ["a", "b", "d"],
       ["a", "c", "d"],
       ["b", "c", "d"]]

CREDIT: Florian Gross

commonality(&block)

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.

      [1, 2, 2, 3, 4, 4].commonality  #=> { 2 => [2, 2], 4 => [4, 4] }

      ["foo", "bar", "a"].commonality { |str| str.length }
      #=> { 3 => ["foo", "bar"] }

This can be useful, for instance, in determining all persons that share their last name with another person …

      persons.collisions { |person| person.last_name }

CREDIT: Florian Gross

conjoin(*args) {|i, *slice(i,2)| ...}

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 paramters are given, it acts like join but will a space separator.

      [1,2,3].conjoin
      #=> "1 2 3"

Use comma+space and ‘and’ on tail.

      [1,2,3].conjoin(', ', ' and ')
      #=> "1, 2 and 3"

Use comma+space and ‘or’ on tail using :last option.

      [1,2,3].conjoin(', ', :last => ' or ')
      #=> "1, 2 or 3"

Use semicolon+space and ampersand on tail using index.

      [1,2,3].conjoin('; ', -1 => ' & ')
      #=> "1; 2 & 3"

Can take a block to determine separator.

      [1,2,3,4].conjoin{ |i, a, b| i % 2 == 0 ? '.' : '-' }
      #=> "1.2-3.4"

This makes very esoteric transformation possible.

      [1,1,2,2].conjoin{ |i, a, b| a == b ? '=' : ' != ' }
      #=> "1=1 != 2=2"

      [1,2,3,4].conjoin{ |i, x, y| "<#{i} #{x} #{y}>" }
      #=> "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)
      #=> "1  ,  2  &  3"

And the :spacer option can set an alternate spacing string.

      [1,2,3].conjoin('|', '>', :space=>2, :spacer=>'-')
      #=> "1--|--2-->--3"

CREDIT: Trans

delete_unless(&block)

Inverse of delete_if.

      [1,2,3].delete_unless{ |x| x < 2 }
      #=> [1]

CREDIT: Daniel Schierbeck

delete_values(*values)

Delete multiple values from array.

      a = [1,2,3,4]
      a.delete_values(1,2)   #=> [1,2]
      a                      #=> [3,4]

CREDIT: Trans

delete_values_at(*selectors)

Delete multiple values from array given indexes or index range.

      a = [1,2,3,4]
      a.delete_values_at(1,2)   #=> [2,3]
      a                         #=> [1,4]
      a = [1,2,3,4]
      a.delete_values_at(0..2)  #=> [1,2,3]
      a                         #=> [4]

NOTE: It would be nice to see delete_at incorporate this funcitonaility.

CREDIT: Trans

divide(pattern)

Divide on matching pattern.

      ['a1','b1','a2','b2'].divide(/^a/)
      #=> [['a1','b1'],['a2','b2']]

CREDIT: Trans

duplicates()

Alias for nonuniq

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"

CREDIT: Derek

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)           # => {}
      options(1, 2, :a => :b) # => {:a=>:b}

from(i)

Returns last n elements.

      %w{W o r l d}.from(3)  #=> %w{l d}

ideal_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).

CREDIT: Derek

index(obj=nil, &block)

Allows index to accept a block.

      ['a', 'b', 'c'].index{ |x| x.upcase == 'C' } #=> 2

IMPORTANT: This is one of the few core overrides in Facets.

median()

Returns the median for the array; nil if array is empty.

NOTE: This is not (presently) a common core extension and is not loaded automatically when using `require ‘facets‘`.

merge!( other )

In place merge.

      a = [1,2]
      a.merge! [2,3]
      a #=> [1,2,3]

CREDIT: Trans

mode()

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.

      [:a, :b, :c, :b, :d].mode  #=> [:b]
      [:a, :b, :c, :b, :a].mode  #=> [:a, :b]

Returns an Array of most common elements.

CREDIT: Robert Klemme

nonuniq()

Returns a list of non-unique elements

      [1,1,2,2,3,4,5].nonuniq  #=> [1,2]

CREDIT: Martin DeMello

nonuniq!()
not_empty?()

Not empty?

      [].not_empty?     #=> false
      [1,2].not_empty?  #=> true

object_state(data=nil)
only()

Returns the only element in the array. Raises an IndexError if the array‘s size is not 1.

      [5].only      # => 5

      expect IndexError do
        [1,2,3].only
      end

      expect IndexError do
        [].only
      end

CREDIT: Gavin Sinclair, Noah Gibbs

pad(len, val=nil)

Pad an array with a given `value` up to a given `length`.

      [0,1,2].pad(6,"a")  #=> [0,1,2,"a","a","a"]

If `length` is a negative number padding will be added to the beginning of the array.

      [0,1,2].pad(-6,"a")  #=> ["a","a","a",0,1,2]

CREDIT: Richard Laugesen

pad!(len, val=nil)

Like pad but changes the array in place.

       a = [0,1,2]
       a.pad!(6,"x")
       a  #=> [0,1,2,"x","x","x"]

CREDIT: Richard Laugesen

peek(i=0)

Peek at the top of the stack (the end of the array).

      a = [1, 2, 3]
      a.peek          #=> 3
      a               #=> [1, 2, 3]

Or provide an index to inspect the array from back to front.

percentile(p)

Returns the percentile value for percentile p; nil if array is empty.

`p` should be expressed as an integer; `percentile(90)` returns the 90th percentile of the array.

Algorithm from NIST

NOTE: This is not (presently) a common core extension and is not loaded automatically when using `require ‘facets‘`.

CREDT: ?

permutation(n=size) {|[]| ...}

Permutation provids the possible orders of an enumerable. Each is indexed by a permutation number. The maximum number of arrangements is the factorial of the size of the array.

       [1,2].permutation(2).to_a #=> [[1,2], [2,1]]

CREDIT: Shin-ichiro Hara

poke(x, i=0)

Put an object on the bottom of the stack (front of the array).

      a = [2, 3]
      a.poke(1)
      a               #=> [1, 2, 3]

Or supply an index and poke works like insert.

power_set()
probability()

Generates a hash mapping each unique element in the array to the relative frequency, i.e. the probablity, of it appearence.

      [:a, :b, :c, :c].probability  #=> {:a=> 0.25, :b=>0.25, :c=>0.5}

CREDIT: Brian Schröder

product(*enums)

Provides the cartesian product of two or more arrays.

      a = [1,2].product([4,5])
      a  #=> [[1, 4],[1, 5],[2, 4],[2, 5]]

CREDIT: Thomas Hafner

recurse(*types) {|a| ...}

Apply a block to array, and recursively apply that block to each sub-array or `types`.

      arr = ["a", ["b", "c", nil], nil]
      arr.recurse{ |a| a.compact! }
      #=> ["a", ["b", "c"]]

recurse!(&block)

In place form of recurse.

recursively(*types, &block)

Apply a method to array, and recursively apply that method to each sub-array or `types`.

      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 ?

rotate(n=1)

Rotates an array‘s elements from back to front n times.

      [1,2,3].rotate      #=> [2,3,1]
      [2,3,1].rotate      #=> [3,1,2]
      [3,1,2].rotate      #=> [1,2,3]

      [1,2,3].rotate(3)   #=> [1,2,3]

A negative parameter reverses the order from front to back.

      [1,2,3].rotate(-1)  #=> [3,1,2]

CREDIT: Florian Gross, Thomas Sawyer

rotate!(n=1)

Same as rotate, but acts in place.

      a = [1,2,3]
      a.rotate!
      a  #=> [2,3,1]

CREDIT: Florian Gross, Thomas Sawyer

select!( {|| ...}

As with select but modifies the Array in place.

      a = [1,2,3,4,5,6,7,8,9,10]
      a.select!{ |e| e % 2 == 0 }
      a  #=> [2,4,6,8,10]

CREDIT: Gavin Sinclair

shelljoin()
shellwords()

Convert an array into command line parameters. The array is accepted in the format of Ruby method arguments —ie. [arg1, arg2, …, hash]

splice(*args)

Splice acts a combination of slice! and store. If two arguments are given it calls store. If a single argument is given it calls slice!.

      a = [1,2,3]
      a.splice(1)    #=> 2
      a              #=> [1,3]

      a = [1,2,3]
      a.splice(1,4)  #=> 4
      a              #=>[1,4,3]

CREDIT: Trans

split(pattern)

Split on matching pattern. Unlike divide this does not include matching elements.

      ['a1','a2','b1','a3','b2','a4'].split(/^b/)
      #=> [['a1','a2'],['a3'],['a4']]

CREDIT: Trans

thru(from, to=nil)

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]

to_b()

Boolean conversion for not empty?

to_h(mode=nil)

Converts an array into a hash. Converting an array into a hash is not a one-to-one conversion, for this reason to_h examines at the array being converted and then dispatches the conversion to the most sutiable specialized function. There are three possiblities for this.

If the array is a collection of perfect pairs, like that which Hash#to_a generates, then conversion is handled by to_h_flat.

      a = [ [:a,1], [:b,2] ]
      a.to_h  #=> { :a=>1, :b=>2 }

If the array contains only arrays, but are not perfect pairs, then to_h_multi is called.

      a = [ [:a,1,2], [:b,2], [:c], [:d] ]
      a.to_h  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }

If the array contians objects other then arrays then the to_h_splat method is called.

      a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
      a.to_h  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil }

Finally, a particular dispatch can be forced by specifying the `mode` of conversion, eg. +:multi+, +:splat+, +:flat+, +:assoc+, etc.

Setting `mode` to `true` is the same as setting it +:multi+. This has been left in for backward compatability.

NOTE: The use of a `values` parameter has been deprecated because that functionality is as simple as …

      array1.zip(array2).to_h

CREDIT: Robert Klemme, Trans

to_h_assoc()

When a mixed or multi-element accociative array is used, the result is as follows:

      a = [ [:a,1,2], [:b,2], [:c], :d ]
      a.to_h  #=> { :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.

      a = [ :x, [:x], [:x,1,2], [:x,3], [:x,4] ]
      a.to_h_assoc  #=> { :x=>[4] }

to_h_auto()

Converts an array into a hash. Converting an array into a hash is not a one-to-one conversion, for this reason to_h examines at the array being converted and then dispatches the conversion to the most sutiable specialized function. There are three possiblities for this.

If the array is a collection of perfect pairs, like that which Hash#to_a generates, then conversion is handled by to_h_flat.

      a = [ [:a,1], [:b,2] ]
      a.to_h_auto  #=> { :a=>1, :b=>2 }

If the array contains only arrays, but are not perfect pairs, then to_h_multi is called.

      a = [ [:a,1,2], [:b,2], [:c], [:d] ]
      a.to_h_auto  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }

If the array contians objects other then arrays then the to_h_splat method is called.

      a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
      a.to_h_auto  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil }

to_h_flat()

This is equivalent to Hash, but it will pad the array with a `nil` object if there are not an even number of elements.

      a = [:a,1,[:b,2,:c]]
      a.to_h_flat  #=> { :a=>1, :b=>2, :c=>nil }

to_h_multi()

When a mixed or multi-element accociative array is used, the result is as follows:

      a = [ [:a,1,2], [:b,2], [:c], :d ]
      a.to_h  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }

If the first entry of the subelements is the same, then the values will be merged using concat.

      a = [ [:a,1,2], [:a,3], [:a,4], [:a], :a ]
      a.to_h_multi  #=> { :a=>[1,2,3,4] }

to_h_splat()

This is equivalent to Hash[*array], but it will pad the array with a `nil` object if there are not an even number of elements.

      a = [:a,1,:b,2,:c]
      a.to_h_splat  #=> { :a=>1, :b=>2, :c=>nil }

to_t()

Convert an array into a tuple.

traverse(&block)

Returns 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  #=> ["a", "b", ["x", "y"]]

This is the same as `recursive.map` and will likely be deprecated in the future because of it.

CREDIT: Trans

traverse!(&block)

Like recursive_map, but will change the array in place.

      h = ["A", "B", ["X", "Y"]]

      h.traverse!{ |e| e.downcase }

      h  #=> ["a", "b", ["x", "y"]]

CREDIT: Trans

uniq_by!( {|| ...}

Like uniq, but determines uniqueness based on a given block.

      a = (-5..5).to_a
      a.uniq_by!{ |i| i*i }
      a #=> [-5, -4, -3, -2, -1, 0]

As can be seen in the example, order is significant.

[Validate]