Class | Array

In:

lib/facets/more/tuple.rb
lib/facets/more/typecast.rb
lib/facets/more/json.rb
lib/facets/more/elementor.rb
lib/facets/more/syncarray.rb
lib/facets/more/snapshot.rb
lib/facets/core/kernel/to_data.rb
lib/facets/core/enumerable/each_combination.rb
lib/facets/core/enumerable/every.rb
lib/facets/core/enumerable/each_unique_pair.rb
lib/facets/core/array/delete_unless.rb
lib/facets/core/array/select.rb
lib/facets/core/array/op_div.rb
lib/facets/core/array/to_b.rb
lib/facets/core/array/op_fetch.rb
lib/facets/core/array/to_h.rb
lib/facets/core/array/shuffle.rb
lib/facets/core/array/store.rb
lib/facets/core/array/op_mod.rb
lib/facets/core/array/merge.rb
lib/facets/core/array/pot.rb
lib/facets/core/array/each_with_key.rb
lib/facets/core/array/unzip.rb
lib/facets/core/array/mid.rb
lib/facets/core/array/pull.rb
lib/facets/core/array/rand_index.rb
lib/facets/core/array/delete_values_at.rb
lib/facets/core/array/delete_values.rb
lib/facets/core/array/thru.rb
lib/facets/core/array/join_sentence.rb
lib/facets/core/array/to_hash.rb
lib/facets/core/array/pick.rb
lib/facets/core/array/first.rb
lib/facets/core/array/last_index.rb
lib/facets/core/array/range.rb
lib/facets/core/array/rotate.rb
lib/facets/core/array/middle.rb
lib/facets/core/array/pos.rb
lib/facets/core/array/head.rb
lib/facets/core/array/rand_subset.rb
lib/facets/core/array/at_rand.rb
lib/facets/core/array/each_combo.rb
lib/facets/core/array/to_path.rb
lib/facets/core/array/index.rb
lib/facets/core/array/pad.rb

Parent: | Object

CREDIT Richard Laugesen

### Methods

/ [] []= at_rand at_rand! body cast_from combos delete_unless delete_values delete_values_at each_combination each_combo each_unique_pair every every! every! first= foot head index join_sentence last= last_index merge! mid middle mutable_methods pad pad! pick pick! pos rand_index rand_subset range restore_snapshot rotate rotate! select! shuffle shuffle! store tail take_snapshot thru to_b to_data to_elementor to_elementor! to_h to_hash to_json to_path to_t unzip

### External Aliases

[] | -> | /
| Use division as a fetch notation.
| | -> | merge
unshift | -> | pot

"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.pot(9)   #=> [9,1,2,3]
      a          #=> [9,1,2,3]

each_with_index | -> | each_with_key
| Increase polymorphysim between Hash and Array.
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]

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

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]

index | -> | index_of

### Public Class methods

cast_from(object)
mutable_methods()

### Public Instance methods

/(len)

Partition an array into parts of given length.

[](*args)

Modifies #[] to also accept an array of indexes.

      a = ['a','b','c','d','e','f']

      a[[1]]      #=> ['b']
      a[[1,1]]    #=> ['b','b']
      a[[1,-1]]   #=> ['b','f']
      a[[0,2,4]]  #=> ['a','c','e']

[]=(*args)

Modifies #[]= to accept an array of indexes for assignment.

      a = ['a','b','c','d']

      a[[1,-1]] = ['m','n']    #=> ['m','n']
      a                        #=> ['a','m','c','n']

at_rand()

Return a random element of the array.

      [1, 2, 3, 4].at_rand           #=> 2
      [1, 2, 3, 4].at_rand           #=> 4

at_rand!()

Same as at_rand, but acts in place removing a random element from the array.

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

body()

Returns an array of the first element upto, but not including, the last element.

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

combos()

As with each_combo but returns combos collected in an array.

delete_unless(&block)
delete_values(*values)

Delete multiple values from array.

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

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]

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

Yields the block to each unique combination of n elements.

      a = %w|a b c d|
      a.each_combination(3) do |c|
        p c
      end

produces

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

each_combo() {|n| ...}

The array is expected to be and array of arrays, which iterates through combinations of each in position.

      a = [ [0,1], [2,3] ]
      a.each_combo { |c| p c }

produces

      [0, 2]
      [0, 3]
      [1, 2]
      [1, 3]

each_unique_pair(&yld)

Processes each unique pair (of indices, not value) in the array by yielding them to the supplied block.

      a = [1,2,3,4]
      a.each_unique_pair{ |a,b| puts a+','+b }

produces

      1,2
      1,3
      1,4
      2,3
      2,4
      3,4

This does not guarantee the uniqueness of values. For example:

      a = [1,2,1]
      a.each_unique_pair{ |a,b| puts a+','+b }

prduces

      1,2
      1,1
      2,1

This is equivalent to `each_combination(2){ … }`.

every()
every!()
every!()

In place version of every.

first=(x)

Change the first element.

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

foot()

Like last, returning the last element in an array.

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

head()

Like first but returns the first element in a new array.

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

index(obj=nil) {|self[i]| ...}

Allows block usage with index.

join_sentence()
last=(x)

Change the last element.

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

last_index()

Returns the last index of the array. Returns nil is array has no elements.

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

merge!( other )
mid(offset=0)

Returns the middle element of an array, or the element offset from middle if the parameter is given. Even-sized arrays, not having an exact middle, return the middle-right element.

      [1,2,3,4,5].mid        #=> 3
      [1,2,3,4,5,6].mid      #=> 4
      [1,2,3,4,5,6].mid(-1)  #=> 3
      [1,2,3,4,5,6].mid(-2)  #=> 2
      [1,2,3,4,5,6].mid(1)   #=> 5

In other words, If there are an even number of elements the higher-indexed of the two center elements is indexed as orgin (0).

middle()

Returns the middle element(s) of an array. Even-sized arrays, not having an exact middle, returns a two-element array of the two middle elements.

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

In contrast to mid which utilizes an offset.

pad(len, val=nil)

Pad an array with a given `value` upto 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]

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

pick(n=nil)

Similar to at_rand, but will return an array of randomly picked exclusive elements if given a number.

pick!(n=nil)

Similar to at_rand!, but given a number will return an array of exclusive elements.

pos(i)

Returns the positive ordinal index given a cardinal position, 1 to n or -n to -1.

      [1,2,3,4,5].pos(1)   #=> 0
      [1,2,3,4,5].pos(-1)  #=> 4

rand_index()
rand_subset( number=nil, exclusive=true )

Returns a random subset of an Array. If a number of elements is specified then returns that number of elements, otherwise returns a random number of elements upto the size of the Array.

By defualt the returned values are exclusive of each other, but if exclusive is set to `false`, the same values can be choosen more than once.

When exclusive is `true` (the default) and the number given is greater than the size of the array, then all values are returned.

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

range(a=nil,z=nil)

Returns the index range between two elements. If no elements are given, returns the range from first to last.

      ['a','b','c','d'].range            #=> 0..3
      ['a','b','c','d'].range('b','d')   #=> 1..2

restore_snapshot(snap)
rotate(n=1)

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]

rotate!(n=1)

Same as rotate, but acts in place.

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

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]

shuffle()

Randomize the order of an array.

      [1,2,3,4].shuffle  #=> [2,4,1,3]

shuffle!()

As with shuffle but modifies the array in place. The algorithm used here is known as a Fisher-Yates shuffle.

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

store(*args)

Alias for #[]=

tail()

Returns an array from second element to last element.

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

take_snapshot()
thru( from, to )

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]

to_b()

Boolean conversion for not empty?

to_data()
to_elementor()
to_elementor!()
to_h(arrayed=nil)

Converts a two-element associative array into a hash.

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

If `arrayed` is set it will maintain trailing arrays.

      a = [ [:a,1,2], [:b,3] ]
      a.to_h(true)  #=> { :a=>[1,2], :b=>[3] }

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

      array1.zip(array2).to_h

to_hash()

Converts an array into a hash.

This methd is just like Enumerable#to_h. But has been moved in order to accomodate associtiave arrays. We use to_hash becasue an Array is, in essence, a hash, just with a restricted set of keys and maintained order.

      a = [ :a, :b, :c ]
      a.to_hash  #=> { 0=>:a, 1=>:b, 2=>:c }

to_json(state = nil, depth = 0)

Returns a JSON string containing a JSON array, that is unparsed from this Array instance. state is a JSON::State object, that can also be used to configure the produced JSON string output further. depth is used to find out nesting depth, to indent accordingly.

to_path()

Turn an array into a file path.

to_t()
unzip(level)

[Validate]