Class Array
In: lib/core/facets/array/combination.rb
lib/core/facets/array/conjoin.rb
lib/core/facets/array/delete_unless.rb
lib/core/facets/array/delete_values.rb
lib/core/facets/array/index.rb
lib/core/facets/array/indexable.rb
lib/core/facets/array/merge.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/product.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/stackable.rb
lib/core/facets/array/traverse.rb
lib/core/facets/blank.rb
lib/core/facets/boolean.rb
lib/core/facets/kernel/object_state.rb
lib/core/facets/string/contains.rb
lib/core/facets/to_hash.rb
lib/more/facets/random.rb
lib/more/facets/set.rb
lib/more/facets/shellwords.rb
lib/more/facets/tuple.rb
Parent: Object

Convert and array into a tuple.

Methods

Included Modules

Indexable Stackable Random

External Aliases

shift -> first!
  Alias for shift, which removes and returns the first element in an array.
  a = ["a","y","z"]
  a.first!      #=> "a"
  p a           #=> ["y","z"]

CREDIT: Trans

pop -> last!
  Alias for pop, which removes and returns the last element in an array.
  a = [1,2]
  a.last! 3
  p a           #=> [1,2,3]

CREDIT: Trans

| -> merge
  Alias for |.
  [1,2].merge [2,3]  #=> [1,2,3]
[]= -> store
  Store a value at a givne index. Store is an alias for #[]=.
unshift -> poke
  "Put On Top". This is an alias for unshift which puts an object# on top of the stack. It is the converse of push.
  a=[1,2,3]
  a.poke(9)   #=> [9,1,2,3]
  a           #=> [9,1,2,3]

CREDIT: Trans

shift -> pull
  Alias for shift which removes an object off first slot of an array. This is the contrary of pop.
  a=[1,2,3]
  a.pull  #=> 1
  a       #=> [2,3]

CREDIT: Trans

empty? -> blank?
include? -> contains?
  Alias for include?.

Public Instance methods

**(*enums)

Alias for product

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

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.

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

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

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

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

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

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

CREDIT: Trans

Inverse of delete_if.

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

CREDIT: Daniel Schierbeck

Delete multiple values from array.

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

CREDIT: Trans

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

Allows index to accept a block.

OVERRIDE! This is one of the bery few core overrides in Facets.

In place merge.

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

CREDIT: Trans

Not empty?

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

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

  [5].only      # -> 5
  [1,2,3].only  # -> IndexError
  [].only       # -> IndexError

CREDIT: Gavin Sinclair, Noah Gibbs

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

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

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.

CREDIT: Shin-ichiro Hara

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

Apply a block to array, and recursively apply that block to each subarray.

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

TODO: Can this be generalized in Enumerbale?

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

  [1,2,3].rotate      #=> [3,1,2]
  [3,1,2].rotate      #=> [2,3,1]
  [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)  #=> [2,3,1]

CREDIT: Florian Gross, Thomas Sawyer

Same as rotate, but acts in place.

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

CREDIT: Florian Gross, Thomas Sawyer

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

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

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

Boolean conversion for not empty?

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 CREDIT: Trans

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 }

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 }

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 }

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

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 }

[Validate]