Skip to content

Latest commit

 

History

History
5473 lines (4053 loc) · 115 KB

markdown.md

File metadata and controls

5473 lines (4053 loc) · 115 KB
Raw

Array API

[Not yet complete. A few methods still to go.]

Contents

Public Class Methods

::new

Array.new → new_empty_array
Array.new(array) → new_array
Array.new(size) → new_array
Array.new(size, default_value) → new_array
Array.new(size) { |index| ... } → new_array

Returns a new Array.

Argument array, if given, must be an Array-convertible object, which will be converted to an Array.

Argument size, if given must be an Integer-convertible object, which will be converted to an Integer.

Argument default_value may be any object.

With no block and no arguments, returns a new empty Array object:

a = Array.new
a # => []

With no block and a single argument array, returns a new Array formed from array:

a = Array.new([:foo, 'bar', baz = 2])
a.class # => Array
a # => [:foo, "bar", 2]

With no block and a single argument size, returns a new Array of the given size whose elements are all nil:

a = Array.new(0)
a # => []
a = Array.new(3)
a # => [nil, nil, nil]

With no block and arguments size and default_value, returns an Array of the given size; each element is that same default_value:

a = Array.new(3, :X)
a # => [:X, :X, :X]
a[0].object_id == a[1].object_id # => true
a[1].object_id == a[2].object_id # => true

With a block and a argument size, returns an Array of the given size; the block is called with each successive integer index; the element for that index is the return value from the block:

a = Array.new(3) { |index| "Element #{index}" }
a # => ["Element 0", "Element 1", "Element 2"]

With a block and no argument, or a single argument 0, ignores the block and returns a new empty Array:

a = Array.new(0) { |n| fail 'Cannot happen' }
a # => []
a = Array.new { |n| fail 'Cannot happen' }
a # => []

With a block and both size and default_value, gives a warning message (warning: block supersedes default value argument), and assigns elements from the block's return values:

Array.new(4, :default) {} # => [nil, nil, nil, nil]

Raises an exception if size is a negative integer:

Array.new(-1) # Raises ArgumentError (negative array size)
Array.new(-1, :default) # Raises ArgumentError (negative array size)
Array.new(-1) { |n| } # Raises ArgumentError (negative array size)

Raises an exception if the single argument is neither an Array-convertible object nor an Integer-convertible object:

Array.new(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

::try_convert

Array.try_convert(obj) → new_array or nil

Tries to convert obj to an Array.

When obj is an Array-convertible object, returns the Array object created by converting it:

class ToAryReturnsArray < Set
  def to_ary
    self.to_a
  end
end
as = ToAryReturnsArray.new([:foo, :bar, :baz])
Array.try_convert(as) # => [:foo, :bar, :baz]

Returns nil unless obj.respond_to?(:to_ary):

s = 'foo'
s.respond_to?(:to_ary) # => false
Array.try_convert(s) # => nil

Raises an exception if obj.to_ary takes an argument:

class ToAryTakesArgument
  def to_ary(x)
    []
  end
end
Array.try_convert(ToAryTakesArgument.new) # Raises ArgumentError (wrong number of arguments (given 0, expected 1))

Raises an exception if obj.to_ary returns a non-Array:

class ToAryTakesArgument
  def to_ary
    :foo
  end
end
Array.try_convert(ToAryTakesArgument.new) # Raises TypeError (can't convert ToAryTakesArgument to Array (ToAryTakesArgument#to_ary gives Symbol))

Public Instance Methods

& (Intersection)

ary & other_array→ new_array

Argument other_array must be an Array-convertible object.

Returns a new Array containing each element found in both in ary and in other_array; duplicates are omitted; comparisons use eql?:

[0, 1, 2, 3] & [1, 2] # => [1, 2]
[0, 1, 0, 1] & [0, 1] # => [0, 1]

Preserves order from ary:

[0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]

Raises an exception if other_array is not an Array-convertible object:

[] & :foo # Raises TypeError (no implicit conversion of Symbol into Array)

* (Repetition)

ary * an_integer → new_array
ary * a_string → new_string

The argument must be an Integer-convertible object, which will be converted to an Integer, or a String-convertible object, which will be converted to a String.

When the argument is an integer n, returns a new Array.

If n is positive, returns the concatenation of n repetitions of ary:

a = ['x', 'y']
a1 = a * 3 # => ["x", "y", "x", "y", "x", "y"]
a1[0].object_id == a1[2].object_id # => true

If n is zero, returns an empty Array:

a = [0, 1]
a * 0 # => []

When the argument is a string separator, returns a new String equivalent to the result of array.join(separator).

If ary is non-empty, returns the join of each element's to_s value:

[0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"

Raises an exception if the argument is not an Integer-convertible object or a String-convertible object:

[] * :foo # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if the argument is negative:

[] * -1 # Raises ArgumentError (negative argument)

Raises an exception if the argument is a string and any array element lacks instance method to_s:

[BasicObject.new] * ',' # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)

+ (Concatenation)

ary + other_array → new_array

Argument other_array must be an Array-convertible object, which will be converted to an Array.

Returns a new Array containing all elements of ary followed by all elements of other_array:

a = [0, 1] + [2, 3]
a # => [0, 1, 2, 3]

Raises an exception if other_array is not an Array-convertible object:

[] + :foo # Raises TypeError (no implicit conversion of Symbol into Array)

- (Difference)

ary - other_array → new_array

Argument other_array must be an Array-convertible object.

Returns a new Array containing only those elements from ary that are not eql? some element in other_array:

[0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
[0, 1, 2, 3] - [3, 0] # => [1, 2]
[0, 1, 2] - [4] # => [0, 1, 2]

Raises an exception if other_array is not an Array-convertible object:

[] - :foo # Raises TypeError (no implicit conversion of Symbol into Array)

<< (Append)

ary << obj → self

Appends obj to ary; returns ary (self):

a = [:foo, 'bar', baz = 2]
a1 = a << :bam
a1 # => [:foo, "bar", 2, :bam]
a1.object_id == a.object_id # => true

<=> (Comparison)

ary <=> other_array → -1, 0, or 1

Returns -1, 0, or 1 as ary is less than, equal to, or greater than other_array.

For each index n in ary, evaluates result = ary[n] <=> other_ary[n].

Returns -1 for the first result of -1:

[0, 1, 2] <=> [0, 1, 3] # => -1

Returns 1 for the first result of 1:

[0, 1, 2] <=> [0, 1, 1] # => 1

Returns -1 if the result for each element in ary is 0, and ary.size < other_array.size:

[0, 1, 2] <=> [0, 1, 2, 3] # => -1

Returns 1 if the result for each element in other_array is 0, and ary.size > other_array.size:

[0, 1, 2] <=> [0, 1] # => 1

Returns 0 if each result is 0, and ary.size == other_array.size:

[0, 1, 2] <=> [0, 1, 2] # => 0

Argument other_array may be an Array-convertible object:

require 'csv'
[] <=> CSV::Row.new([], []) # => 0

Returns nil if other_array is not an Array-convertible object:

[] <=> 0 # => nil

== (Equality)

ary == other_array → true or false

Returns true if ary.size == other_array.size, and for each index i in ary, ary[i] == other_array[i]:

a = [0, 1, 2]
a == [0, 1, 2] # => true
[] == [] # => true

Otherwise, returns false:

a = [0, 1, 2]
a == [0, 1] # => false
a == [0, 1, 3] # => false
[] == BasicObject.new # => false

[] (Element Reference)

ary[index] → obj or nil
ary[start, length] → obj or nil
ary[range] → obj or nil

Returns elements from ary.

Arguments index, start, and length, if given, must be Integer-convertible objects, which will be converted to Integers.

Argument range, if given, must be a Range object.

When a single argument index is given, returns the element in ary at offset index:

a = [:foo, 'bar', baz = 2]
a[0] # => :foo
a[2] # => 2
a # => [:foo, "bar", 2]

If index is negative, counts relative to the end of ary:

a = [:foo, 'bar', baz = 2]
a[-1] # => 2
a[-2] # => "bar"

If index is out of range, returns nil:

a = [:foo, 'bar', baz = 2]
a[50] # => nil
a[-50] # => nil

When two arguments start and length are given, returns a new array of size length containing successive elements of ary beginning at offset start:

a = [:foo, 'bar', baz = 2]
a[0, 2] # => [:foo, "bar"]
a[1, 2] # => ["bar", 2]

If start + length > ary.length, returns ary.size - start elements:

a = [:foo, 'bar', baz = 2]
a[0, 4] # => [:foo, "bar", 2]
a[1, 3] # => ["bar", 2]
a[2, 2] # => [2]

If start == a.size and length >= 0, returns a new empty Array:

a = [:foo, 'bar', baz = 2]
a[a.size, 0] # => []
a[a.size, 50] # => []

If length is negative, returns nil:

a = [:foo, 'bar', baz = 2]
a[2, -1] # => nil
a[1, -2] # => nil

When a single argument range is given, treats rng.min as start above and rng.size as length above:

a = [:foo, 'bar', baz = 2]
a[0..1] # => [:foo, "bar"]
a[1..2] # => ["bar", 2]

Special case: If rng.start == a.size, returns a new empty Array:

a = [:foo, 'bar', baz = 2]
a[a.size..0] # => []
a[a.size..50] # => []
a[a.size..-1] # => []
a[a.size..-50] # => []

If rng.end is negative, calculates the end index from the end of ary:

a = [:foo, 'bar', baz = 2]
a[0..-1] # => [:foo, "bar", 2]
a[0..-2] # => [:foo, "bar"]
a[0..-3] # => [:foo]
a[0..-4] # => []

If rng.start is negative, calculates the start index from the end of ary:

a = [:foo, 'bar', baz = 2]
a[-1..2] # => [2]
a[-2..2] # => ["bar", 2]
a[-3..2] # => [:foo, "bar", 2]

Raises an exception if given a single argument that is not an Integer-convertible object or a Range object:

a = [:foo, 'bar', baz = 2]
a[:foo] # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if given two arguments that are not both Integer-convertible objects

a = [:foo, 'bar', baz = 2]
a[:foo, 3] # Raises TypeError (no implicit conversion of Symbol into Integer)
a[1, :bar] # Raises TypeError (no implicit conversion of Symbol into Integer)

[]= (Element Assignment)

ary[index] = obj → obj
ary[start, length] = obj →  obj
ary[range] = obj →  obj

Assigns elements in ary; returns the given obj.

Arguments index, start, and length, if given, must be Integer-convertible objects, which will be converted to Integers.

Argument range, if given, must be a Range object.

If obj is an Array-convertible object, it will be converted to an Array.

When index is given, assigns obj to an element in ary.

If index is non-negative, assigns obj the element at offset index:

a = [:foo, 'bar', baz = 2]
a[0] = 'foo' # => "foo"
a # => ["foo", "bar", 2]

If index >= ary.length, extends ary:

a = [:foo, 'bar', baz = 2]
a[7] = 'foo' # => "foo"
a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]

If index is negative, counts backward from the end of ary:

a = [:foo, 'bar', baz = 2]
a[-1] = 'two' # => "two"
a # => [:foo, "bar", "two"]

When start and length are given and obj is not an Array-convertible object, removes length - 1 elements beginning at offset start, and assigns obj at offset start:

a = [:foo, 'bar', baz = 2]
a[0, 2] = 'foo' # => "foo"
a # => ["foo", 2]

if start is negative, counts backward from the end of ary:

a = [:foo, 'bar', baz = 2]
a[-2, 2] = 'foo' # => "foo"
a # => [:foo, "foo"]

If start >= ary.size, extends ary with nil, assigns ary[start] = obj, and ignores length:

a = [:foo, 'bar', baz = 2]
a[6, 50] = 'foo' # => "foo"
a # => [:foo, "bar", 2, nil, nil, nil, "foo"]

If length == 0, shifts elements at and following offset start and assigns obj at offset start:

a = [:foo, 'bar', baz = 2]
a[1, 0] = 'foo' # => "foo"
a # => [:foo, "foo", "bar", 2]

If length is too large for the existing ary, does not extend ary:

a = [:foo, 'bar', baz = 2]
a[1, 5] = 'foo' # => "foo"
a # => [:foo, "foo"]

When range is given and obj is an Array-convertible object, removes length - 1 elements beginning at offset start, and assigns obj at offset start:

a = [:foo, 'bar', baz = 2]
a[0..1] = 'foo' # => "foo"
a # => ["foo", 2]

if range.begin is negative, counts backward from the end of ary:

a = [:foo, 'bar', baz = 2]
a[-2..2] = 'foo' # => "foo"
a # => [:foo, "foo"]

If range.begin >= ary.size, extends ary with nil, assigns ary[range.begin] = obj, and ignores length:

a = [:foo, 'bar', baz = 2]
a[6..50] = 'foo' # => "foo"
a # => [:foo, "bar", 2, nil, nil, nil, "foo"]

If range.end == 0, shifts elements at and following offset start and assigns obj at offset start:

a = [:foo, 'bar', baz = 2]
a[1..0] = 'foo' # => "foo"
a # => [:foo, "foo", "bar", 2]

If range.end is negative, assigns obj at offset start, retains range.end.abs -1 elements past that, and removes those beyond:

a = [:foo, 'bar', baz = 2]
a[1..-1] = 'foo' # => "foo"
a # => [:foo, "foo"]
a = [:foo, 'bar', baz = 2]
a[1..-2] = 'foo' # => "foo"
a # => [:foo, "foo", 2]
a = [:foo, 'bar', baz = 2]
a[1..-3] = 'foo' # => "foo"
a # => [:foo, "foo", "bar", 2]
a = [:foo, 'bar', baz = 2]

If range.end is too large for the existing ary, does not extend ary:

a = [:foo, 'bar', baz = 2]
a[1..5] = 'foo' # => "foo"
a # => [:foo, "foo"]

Raises an exception if given a single argument that is not an Integer-convertible object or a Range:

a = [:foo, 'bar', baz = 2]
a[:nosuch] = 'two' # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if given two arguments that are not both Integer-convertible objects:

a = [:foo, 'bar', baz = 2]
a[:nosuch, 2] = 'two' # Raises TypeError (no implicit conversion of Symbol into Integer)
a[0, :nosuch] = 'two' # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if a negative index is out of range:

a = [:foo, 'bar', baz = 2]
a[-4] = 'two' # Raises IndexError (index -4 too small for array; minimum: -3)

Raises an exception if start is too small for ary:

a = [:foo, 'bar', baz = 2]
a[-5, 2] = 'foo' # Raises IndexError (index -5 too small for array; minimum: -3)

Raises an exception if length is negative:

a = [:foo, 'bar', baz = 2]
a[1, -1] = 'foo' # Raises IndexError (negative length (-1))

all?

ary.all? → true or false
ary.all? { |element| ... } → true or false
ary.all?(obj) → true or false

The argument, if given, must have instance method ===.

With no argument and no block, returns true if any contains no nil or false element, false otherwise:

[0, 1, :foo].all? # => true
[0, nil, 2].all? # => false
[].all? # => true

With no argument and a block, calls the block with each element in ary; returns true if the block returns no nil or false element, false otherwise:

[0, 1, 2].all? { |element| element < 3 } # => true
[0, 1, 2].all? { |element| element < 2 } # => false

Does not call the block if ary is empty:

[].all? { |element| fail 'Cannot happen' } # => true

If argument obj is given, returns true if obj.=== all elements, false otherwise:

['food', 'fool', 'foot'].all?(/foo/) # => true
['food', 'drink'].all?(/bar/) # => false
[].all?(/foo/) # => true
[0, 0, 0].all?(0) # => true
[0, 1, 2].all?(1) # => false

Issues a warniing ('warning: given block not used') if both an argument and a block given:

[0, 1, 2].all?(/foo/) { |element|} # => false

Raises an exception if the argument does not have instance method ===:

[0, 1, 2].all?(BasicObject.new) # Raises NoMethodError (undefined method `===' for #<BasicObject:>)

any?

ary.any? → true or false
ary.any? { |element| ... } → true or false
ary.any?(obj) → true or false

The argument, if given, must have instance method ===.

With no argument and no block, returns true if any has any truthy element, false otherwise:

[nil, 0, false].any? # => true
[nil, false].any? # => false
[].any? # => false

With no argument and a block, calls the block with each element in ary; returns true if the block returns any truthy value, false otherwise:

[0, 1, 2].any? { |element| element > 1 } # => true
[0, 1, 2].any? { |element| element > 2 } # => false

Does not call the block if ary is empty:

[].any? { |element| fail 'Cannot happen' } # => false

If argument obj is given, returns true if obj.=== any element, false otherwise:

['food', 'drink'].any?(/foo/) # => true
['food', 'drink'].any?(/bar/) # => false
[].any?(/foo/) # => false 
[0, 1, 2].any?(1) # => true
[0, 1, 2].any?(3) # => false

Issues a warniing ('(irb):161: warning: given block not used') if both an argument and a block given:

[0, 1, 2].any?(/foo/) { |element|} # => false

Raises an exception if the argument does not have instance method ===:

[0, 1, 2].any?(BasicObject.new) # Raises NoMethodError (undefined method `===' for #<BasicObject:>)

append

ary.append(*objects) → self

Appends the given *objects to ary; returns self:

a = [:foo, 'bar', baz = 2]
a1 = a.append(:bam, :bat)
a1 # => [:foo, "bar", 2, :bam, :bat]
a1.object_id == a.object_id # => true

assoc

ary.assoc(obj) → new_array or nil

Returns the the first element in ary that is an Array whose first element == >ary:

a = [[0, 1], [2, 4], [4, 5, 6], [4, 5]]
a.assoc(4) # => [4, 5, 6]

Returns nil if no such element is found:

a = [[0, 1], 7, {foo: 0}, [4, 5], [3, 4, 5]]
a.assoc(:nosuch) # => nil

at

ary.at(index) → obj

Returns the element in ary at offset index.

Argument index must be an Integer-convertible object, which will be converted to an Integer.

Returns the element at offset index:

a = [:foo, 'bar', baz = 2]
a.at(0) # => :foo
a.at(2) # => 2

Raises an exception if index is not an Integer-convertible object:

a = [:foo, 'bar', baz = 2]
a.at(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

bsearch

ary.bsearch { |element| ... } → obj
ary.bsearch → new_enumerator

Returns an element from ary selected by a binary search.

ary should be sorted, but this is not checked.

There are two search modes:

  • Find-minimum mode: the block should return true or false.
  • Find-any mode: the block should return a numeric value.

The block should not mix the modes by sometimes returning a numeric value and sometimes returning true or false, but this is not checked.

In find-minimum mode, the block always returns true or false. The further requirement (though not checked) is that there are no indexes i and j such that:

  • 0 <= i < j <= ary.size.
  • The block returns true for ary[i] and false for ary[j].

In find-minimum mode, method bsearch returns the first element for which the block returns true.

Examples:

a = [0, 4, 7, 10, 12]
a.bsearch { |x| x >= 4 } # => 4
a.bsearch { |x| x >= 6 } # => 7
a.bsearch { |x| x >= -1 } # => 0
a.bsearch { |x| x >= 100 } # => nil

Less formally: the block is such that all false-evaluating elements precede all true-evaluating elements.

These make sense as blocks for bsearch:

a = [0, 4, 7, 10, 12]
a.map { |x| x >= 4 } # => [false, true, true, true, true]
a.map { |x| x >= 6 } # => [false, false, true, true, true]
a.map { |x| x >= -1 } # => [true, true, true, true, true]
a.map { |x| x >= 100 } # => [false, false, false, false, false]

This would not make sense:

a = [0, 4, 7, 10, 12]
a.map {|x| x == 7 } # => [false, false, true, false, false]

In find-any mode, the block always returns a numeric value. The further requirement (though not checked) is that there are no indexes i and j such that:

  • 0 <= i < j <= ary.size.
  • The block returns a negative value for ary[i] and a positive value for ary[j].
  • The block returns a negative value for ary[i] and zero ary[j].
  • The block returns zero for ary[i] and a positive value for ary[j].

In find-any mode, method bsearch returns some element for which the block returns 0, or nil> if none.

Examples:

a = [0, 4, 7, 10, 12]
a.bsearch { |element| 7 <=> element } # => 7
a.bsearch { |element| -1 <=> element } # => nil
a.bsearch { |element| 5 <=> element } # => nil
a.bsearch { |element| 15 <=> element } # => nil

Less formally: the block is such that:

  • All positive-evaluating elements precede all zero-evaluating elements.
  • All positive-evaluating elements precede all negative-evaluating elements.
  • All zero-evaluating elements precede all negative-evaluating elements.

These make sense as blocks for bsearch:

a = [0, 4, 7, 10, 12]
a.map { |element| 7 <=> element } # => [1, 1, 0, -1, -1]
a.map { |element| -1 <=> element } # => [-1, -1, -1, -1, -1]
a.map { |element| 5 <=> element } # => [1, 1, -1, -1, -1]
a.map { |element| 15 <=> element } # => [1, 1, 1, 1, 1]

This would not make sense:

a = [0, 4, 7, 10, 12]
a.map { |element| element <=> 7 } # => [-1, -1, 0, 1, 1]

Returns an enumerator if no block given:

a = [0, 4, 7, 10, 12]
a.bsearch # => #<Enumerator: [0, 4, 7, 10, 12]:bsearch>

Raises an exception if the block returns an invalid value:

a = 'abcde'.split('').shuffle
a.bsearch { |element| :foo } # Raises TypeError (wrong argument type Symbol (must be numeric, true, false or nil))

bsearch_index

ary.bsearch_index { |element| ... } → integer or nil
ary.bsearch → new_enumerator

Searches ary as described at method bsearch, but returns the index of the found element instead of the element itself.

collect

ary.collect { |elemeent| ... } → new_array
ary.collect → new_enumerator

Returns a new Array whose elements are the return values from the block:

a = [:foo, 'bar', baz = 2]
a1 = a.collect { |element| element.class }
a1 # => [Symbol, String, Integer]

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2]
a1 = a.collect
a1 # => #<Enumerator: [:foo, "bar", 2]:collect>

collect!

ary.collect! { |elemeent| ... } → self
ary.collect → new_enumerator

Replaces each element the return value from the block:

a = [:foo, 'bar', baz = 2]
a1 = a.collect! { |element| element.class }
a1 # => [Symbol, String, Integer]
a1.object_id == a.object_id # => true

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2]
a1 = a.collect!
a1 # => #<Enumerator: [:foo, "bar", 2]:collect!>

combination

ary.combination(n) { |element| ... } → self
ary.combination(n) → new_enumerator

Calls the block with combinations of elements of ary; returns self. The order of combinations is indeterminate.

Argument n, if given, must be an Integer-convertible object.

When a block and a zero-valued argument n are given, calls the block once with a new empty Array:

a = [0, 1, 2]
a1 = a.combination(0) { |combination| p combination }
a1.equal?(a) # => true # Identity check.

Output:

[]

If 0 < n < ary.size, calls the block with all n-tuple combinations of ary:

a = [0, 1, 2]
a.combination(2) { |combination| p combination }

Output:

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

a = [0, 1, 2]
a.combination(3) { |combination| p combination }

Output:

[0, 1, 2]

If n >= ary.size, does not call the block:

a = [0, 1, 2]
a.combination(4) { |combination| fail 'Cannot happen' }

If n is negative, does not call the block:

a = [0, 1, 2]
a.combination(-1) { |combination| fail 'Cannot happen' }
a.combination(-2) { |combination| fail 'Cannot happen' }

Returns a new Enumerator if no block given:

a = [0, 1, 2]
a.combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>

Raises an exception if n is not an Integer-convertible object:

a.combination(:foo) { } # Raises TypeError (no implicit conversion of Symbol into Integer)

compact

ary.compact → self or nil

Returns a new Array containing all non-nil from ary:

a = [nil, 0, nil, 1, nil, 2, nil]
a.compact # => [0, 1, 2]

compact!

ary.compact! → self or nil

Removes all nil elements from ary.

Returns self if any elements removed:

a = [nil, 0, nil, 1, nil, 2, nil]
a.compact! # => [0, 1, 2]

Returns nil if no elements removed:

[0, 1, 2].compact! # => nil

concat

ary.concat(*other_arrays) → self

The given *other_arrays must be Array-convertible objects, which will be converted to Array objects.

Adds to ary all elements from each array in other_arrays; returns self:

a = [0, 1]
a1 = a.concat([2, 3], [4, 5])
a1 # => [0, 1, 2, 3, 4, 5]
a1.object_id == a.object_id # => true

Returns self unmodified if no arguments given:

a = [0, 1]
a.concat
a # => [0, 1]

Raises an exception if any argument is not an Array-convertible object:

[].concat([], :foo) # Raises TypeError (no implicit conversion of Symbol into Array)

count

ary.count → an_integer
ary.count(obj) → an_integer
ary.count { |element| ... } → an_integer

Returns a count of specified elements.

With no argument and no block, returns the count of all elements:

[0, 1, 2].count # => 3
[].count # => 0

With argument obj, returns the count of elements eql? to obj:

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

cycle

ary.cycle { |element| ... } → nil
ary.cycle(count) { |element| ... } → nil
ary.cycle → new_enumerator
ary.cycle(count) → new_enumerator

Argument count, if given, must be an Integer-convertible object.

When called with positive argument count and a block, calls the block with each element, then does so again, until it has done so count times returns nil:

[0, 1].cycle(2) { |element| puts element } # => nil

Output:

0
1
0
1

If count is zero or negative, does not call the block:

[0, 1].cycle(0) { |element| fail 'Cannot happen' } # => nil
[0, 1].cycle(-1) { |element| fail 'Cannot happen' } # => nil

When a block is given, but no argument, cycles forever (output omitted):

[0, 1].cycle { |element| puts element }

When a block is not given, returns a new Enumerator:

[0, 1].cycle(2) # => #<Enumerator: [0, 1]:cycle(2)>
[0, 1].cycle # => #<Enumerator: [0, 1]:cycle(2)> # => #<Enumerator: [0, 1]:cycle>

Raises an exception if count is not an Integer-convertible object:

[0, 1].cycle(:foo) { |element| } # Raises TypeError (no implicit conversion of Symbol into Integer)

delete

ary.delete(obj) → deleted_obj
ary.delete { |obj| ... } → deleted_obj or block_return

Removes zero or more elements from ary; returns self.

When no block given, removes from ary each element ele such that ele == obj; returns the last deleted element:

s1 = 'bar'; s2 = 'bar'
a = [:foo, s1, baz = 2, s2]
deleted_obj = a.delete('bar')
a # => [:foo, 2]
deleted_obj.object_id == s2.object_id # => true

Returns nil if nothing removed:

a = [:foo, 'bar', baz = 2]
a.delete(:nosuch) # => nil

When block given, removes from ary each element ele such that ele == obj; returns the last deleted element:

s1 = 'bar'; s2 = 'bar'
a = [:foo, s1, baz = 2, s2]
deleted_obj = a.delete('bar') { fail 'Cannot happen' }
a # => [:foo, 2]
deleted_obj.object_id == s2.object_id # => true

Returns block return value if nothing removed:

a = [:foo, 'bar', baz = 2]
a.delete(:nosuch) { |obj| "#{obj} not found" } # => "nosuch not found"

delete_at

ary.delete_at(index) → deleted_object or nil

Deletes an element from ary, per the given index.

The given index must be an Integer-convertible object.

When index is non-negative, deletes the element at offset index:

a = [:foo, 'bar', baz = 2]
a.delete_at(1) # => "bar"
a # => [:foo, 2]

If index is too large, returns nil:

a = [:foo, 'bar', baz = 2]
a.delete_at(5) # => nil

When index is negative, counts backward from the end of the array:

a = [:foo, 'bar', baz = 2]
a.delete_at(-2) # => "bar"
a # => [:foo, 2]

If index is too small, returns nil:

a = [:foo, 'bar', baz = 2]
a.delete_at(-5) # => nil

Raises an exception if index is not an Integer-convertible object:

a = [:foo, 'bar', baz = 2]
a.delete_at(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

delete_if

ary.delete_if { |element| ... } → self
ary.delete_if → Enumerator

Removes each element in ary for which the block returns a truthy value; returns self:

a = [:foo, 'bar', baz = 2, 'bat']
a1 = a.delete_if { |element| element.to_s.start_with?('b') }
a1 # => [:foo, 2]
a1.object_id == a.object_id # => true

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2]
a.delete_if # => #<Enumerator: [:foo, "bar", 2]:delete_if>

difference

ary.difference(*other_arrays) → new_array

Each argument in *other_arrays must be an Array-convertible object.

Returns a new Array containing only those elements from ary that are not eql? some element in any *other_arrays:

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

Returns self unmodified if no arguments given:

[0, 1].difference # => [0, 1]

Raises an exception if other_array is not an Array-convertible object:

[].difference(:foo) # Raises TypeError (no implicit conversion of Symbol into Array)

drop

ary.drop(n) → new_array

Argument n must be an Integer-convertible object.

Returns a new Array containing all but the first n element of ary; does not modify ary:

a = [0, 1, 2, 3, 4, 5]
a.drop(0) # => [0, 1, 2, 3, 4, 5]
a.drop(1) # => [1, 2, 3, 4, 5]
a.drop(2) # => [2, 3, 4, 5]
a.drop(50) # => []
a # => [0, 1, 2, 3, 4, 5]

Raises an exception if n is negative:

[0, 1].drop(-1) # Raises ArgumentError (attempt to drop negative size)

Argument n must be an Integer-convertible object:

[0, 1].drop(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

drop_while

ary.drop_while { |element| ... } → new_array
ary.drop_while → new_enumerator

With a block given, calls the block with each successive element; stops if the block returns nil or nil; returns a new Array omitting those elements for which the block returned a truthy value:

a = [0, 1, 2, 3, 4, 5]
a.drop_while { |element| element < 3 } # => [3, 4, 5]
a.drop_while { |element| true } # => []
a.drop_while { |element| false } # => [0, 1, 2, 3, 4, 5]

With no block given, returns a new Enumerator:

[0, 1].drop_while # => # => #<Enumerator: [0, 1]:drop_while>

each

ary.each { |element| ... } → self
ary.each → Enumerator

When a block given, passes each successive element in ary to the block; returns self:

a = [:foo, 'bar', baz = 2]
a1 = a.each { |element|  puts "#{element.class} #{element}" }
a1.object_id == a.object_id # => true

Output:

Symbol foo
String bar
Integer 2

Allows ary to be modified during the iteration:

a = [:foo, 'bar', baz = 2]
a.each { |element| puts element; a.clear if element.to_s.start_with?('b') }
a # => []

Output:

foo
bar

When no block given, returns a new Enumerator:

a = [:foo, 'bar', baz = 2]
e = a.each
e # => #<Enumerator: [:foo, "bar", 2]:each>
a1 = e.each { |element|  puts "#{element.class} #{element}" }
a1.object_id == a.object_id # => true

Output:

Symbol foo
String bar
Integer 2

each_index

ary.each_index { |index| ... } → self
ary.each_index → Enumerator

When a block given, passes each successive index in ary to the block, returns self:

a = [:foo, 'bar', baz = 2]
a1 = a.each_index { |index|  puts "#{index} #{a[index]}" }
a1.object_id == a.object_id # => true

Output:

0 foo
1 bar
2 2

Allows ary to be modified during the iteration:

a = [:foo, 'bar', baz = 2]
a.each_index { |index| puts index; a.clear if index > 0 }
a # => []

Output:

0
1

When no block given, returns a new Enumerator:

a = [:foo, 'bar', baz = 2]
e = a.each_index
e # => #<Enumerator: [:foo, "bar", 2]:each_index>
a1 = e.each { |index|  puts "#{index} #{a[index]}"}
a1.object_id == a.object_id # => true

Output:

0 foo
1 bar
2 2

empty?

ary.empty? → true or false

Returns true if the count of elements in ary is 0; false otherwise:

[].empty? # => true
[:foo, 'bar', baz = 2].empty? # => false

eql?

ary.eql other_array → true or false

Returns true if ary.size == other_array.size, and for each index i in ary, ary[i].eql? other_array[i]:

a = [0, 1, 2]
a.eql? [0, 1, 2] # => true
[].eql? [] # => true

Otherwise, returns false:

a = [0, 1, 2]
a.eql? [0, 1] # => false
a.eql? [0, 1, 3] # => false
a.eql? [0, 1, 3] # => false
[].eql? BasicObject.new # => false

fetch

ary.fetch(index) → obj
ary.fetch(index, default_value) → obj
ary.fetch(index) { |index| ... } → obj

Returns the element at index index.

The given index must be an Integer-convertible object.

With the single argument index, returns ary[index]:

a = [:foo, 'bar', baz = 2]
a.fetch(1) # => "bar"

If index < 0, counts from the end of ary:

a = [:foo, 'bar', baz = 2]
a.fetch(-1) # => 2

With arguments index and default_value, returns ary[index] if index is in range, otherwise default_value:

a = [:foo, 'bar', baz = 2]
a.fetch(1, nil) # => "bar"
a.fetch(50, nil) # => nil

With argument index and a block, returns ary[index] if index is in range (and the block is not called), otherwise calls the block with index and returns its return value:

a = [:foo, 'bar', baz = 2]
a.fetch(1) { |index| fail 'Cannot happen' } # => "bar"
a.fetch(50) { |index| "Value for #{index}" } # => "Value for 50"

Raises an exception if index is not an Integer-convertible object.

a = [:foo, 'bar', baz = 2]
a.fetch(:X) # Raises TypeError (no implicit conversion of String into Integer)

Raises an exception if index is out of range and neither default_value nor a block given:

a = [:foo, 'bar', baz = 2]
a.fetch(50) # Raises IndexError (index 50 outside of array bounds: -3...3)

fill

ary.fill(obj) → self
ary.fill(obj, start) → self
ary.fill(obj, start , length) → self
ary.fill(obj, range) → self
ary.fill { |index| ... } → self
ary.fill(start) { |index| ... } → self
ary.fill(start , length) { |index| ... } → self
ary.fill(range) { |index| ... } → self

Replaces specified elements in ary with specified objects; returns self.

Arguments start and length, if given, must be Integer-convertible objects.

Argument range, if given, must be a Range object.

With argument obj and no block given, replaces all elements with that one obj:

a = ['a', 'b', 'c', 'd']
a # => ["a", "b", "c", "d"]
a1 = a.fill(:X)
a1 # => [:X, :X, :X, :X]
a.first.object_id == a.last.object_id # => true

With arguments obj and start and no block given, replaces elements based on the given start.

If start is in range (0 <= start < ary.size), replaces all elements from offset start through the end:

a = ['a', 'b', 'c', 'd']
a.fill(:X, 2) # => ["a", "b", :X, :X]

If start >= ary.size, does nothing:

a = ['a', 'b', 'c', 'd']
a.fill(:X, 4) # => ["a", "b", "c", "d"]
a = ['a', 'b', 'c', 'd']
a.fill(:X, 5) # => ["a", "b", "c", "d"]

If start is negative, counts from the end (starting index is start + ary.size):

a = ['a', 'b', 'c', 'd']
a.fill(:X, -2) # => ["a", "b", :X, :X]

If start <= -ary.size, replaces all elements:

a = ['a', 'b', 'c', 'd']
a.fill(:X, -6) # => [:X, :X, :X, :X]
a = ['a', 'b', 'c', 'd']
a.fill(:X, -50) # => [:X, :X, :X, :X]

With arguments obj, start, and length, and no block given, replaces elements based on the given start and length.

If start is in range, replaces length elements beginning at offset start:

a = ['a', 'b', 'c', 'd']
a.fill(:X, 1, 1) # => ["a", :X, "c", "d"]

If start is negative, counts from the end:

a = ['a', 'b', 'c', 'd']
a.fill(:X, -2, 1) # => ["a", "b", :X, "d"]

If start >= ary.size, extends self with nil:

a = ['a', 'b', 'c', 'd']
a.fill(:X, 5, 0) # => ["a", "b", "c", "d", nil]
a = ['a', 'b', 'c', 'd']
a.fill(:X, 5, 2) # => ["a", "b", "c", "d", nil, :X, :X]

If length <= 0 replaces no elements:

a = ['a', 'b', 'c', 'd']
a.fill(:X, 1, 0) # => ["a", "b", "c", "d"]
a.fill(:X, 1, -1) # => ["a", "b", "c", "d"]

With arguments obj and range and no block given replaces elements based on the given range.

If the range is positive and ascending ( 0 <= range.begin <= range.end, replaces elements from (tt>range.begin to range.end:

a = ['a', 'b', 'c', 'd']
a.fill(:X, (1..1)) # => ["a", :X, "c", "d"]

If range.first is negative, replaces no elements:

a = ['a', 'b', 'c', 'd']
a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"]

If range.last is negative, counts from the end of the array:

a = ['a', 'b', 'c', 'd']
a.fill(:X, (0..-2)) # => [:X, :X, :X, "d"]
a = ['a', 'b', 'c', 'd']
a.fill(:X, (1..-2)) # => ["a", :X, :X, "d"]

If range.last and range.last are both negative, both count from the end of the array:

a = ['a', 'b', 'c', 'd']
a.fill(:X, (-1..-1)) # => ["a", "b", "c", :X]
a = ['a', 'b', 'c', 'd']
a.fill(:X, (-2..-2)) # => ["a", "b", :X, "d"]

With no argument and block given, calls the block with each index and replaces self[index] with the block's return value:

a = ['a', 'b', 'c', 'd']
a.fill { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]

With argument start and block given, calls the block with each index from start to the end, replacing the corresponding element with the block's return value:

If start is in range (0 <= start < ary.size),

a = ['a', 'b', 'c', 'd']
a.fill(1) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "new_3"]

If start >= ary.size, does nothing:

a = ['a', 'b', 'c', 'd']
a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
a = ['a', 'b', 'c', 'd']
a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]

If start is negative, counts from the end (starting index is start + ary.size):

a = ['a', 'b', 'c', 'd']
a.fill(-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "new_3"]

If start <= -ary.size, replaces all elements:

a = ['a', 'b', 'c', 'd']
a.fill(-6) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
a = ['a', 'b', 'c', 'd']
a.fill(-50) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]

With arguments start and length, and block given, calls the block for each index specified by start length; replaces the element at offset index with the block's return value.

If start is in range, replaces length elements beginning at offset start:

a = ['a', 'b', 'c', 'd']
a.fill(1, 1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]

If start is negative, counts from the end:

a = ['a', 'b', 'c', 'd']
a.fill(-2, 1) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]

If start >= ary.size, extends self with nil:

a = ['a', 'b', 'c', 'd']
a.fill(5, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil]
a = ['a', 'b', 'c', 'd']
a.fill(5, 2) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil, "new_5", "new_6"]

If length <= 0 replaces no elements:

a = ['a', 'b', 'c', 'd']
a.fill(1, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
a.fill(1, -1) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]

With arguments obj and range and block given calls the block with each index in the given range, replaces the element at offset index with the block's return value.

If the range is positive and ascending ( 0 <= range.begin <= range.end, replaces elements from (tt>range.begin to range.end:

a = ['a', 'b', 'c', 'd']
a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]

If range.first is negative, does not call the block, replaces no elements:

a = ['a', 'b', 'c', 'd']
a.fill(-1..1) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]

If range.last is negative, counts from the end of the array:

a = ['a', 'b', 'c', 'd']
a.fill(0..-2) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "d"] 
a = ['a', 'b', 'c', 'd']
a.fill(1..-2) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "d"]

If range.last and range.last are both negative, both count from the end of the array:

a = ['a', 'b', 'c', 'd']
a.fill(-1..-1) { |index| "new_#{index}" } # => ["a", "b", "c", "new_3"]
a = ['a', 'b', 'c', 'd']
a.fill(-2..-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]

Raises an exception if no block given, two arguments given, second argument is not a Range or an Integer-convertible object:

[].fill(:X, :x) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if no block given, three arguments given, second or third argument not an Integer-convertible object:

[].fill(:X, :x, 1) # Raises TypeError (no implicit conversion of Symbol into Integer)
[].fill(:X, 1, :x) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if block given, one argument given, argument is not a Range or an Integer-convertible object:

[].fill(:x) { } # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if block given, two arguments given, either argument is not an Integer-convertible object:

[].fill(:x, 1) { } # Raises TypeError (no implicit conversion of Symbol into Integer)
[].fill(1, :x) { } # Raises TypeError (no implicit conversion of Symbol into Integer)

filter

ary.filter { |element| ... } → new_array
ary.filter → new_enumeration

Returns a new Array containing those elements of ary for which the block returns a truthy value:

a = [:foo, 'bar', baz = 2, :bam]
a1 = a.filter { |element| element.to_s.start_with?('b') }
a1 # => ["bar", :bam]

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2, :bam]
a.filter # => #<Enumerator: [:foo, "bar", 2, :bam]:filter>

filter!

ary.filter! { |element| ... } → new_array
ary.filter! → new_enumeration

Removes from ary those elements for which the block returns false or nil; returns self:

a = [:foo, 'bar', baz = 2, :bam]
a1 = a.filter! { |element| element.to_s.start_with?('b') }
a1 # => ["bar", :bam]
a1.object_id == a.object_id

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2, :bam]
a.filter! # => #<Enumerator: [:foo, "bar", 2, :bam]:filter!>

find_index

ary.find_index(obj) → Integer or nil
ary.find_index { |element| ... } → Integer or nil
ary.find_index → new_enumerator

When argument obj is given, returns the index of the first element element for which obj == element:

a = [:foo, 'bar', baz = 2, 'bar']
a.find_index('bar') # => 1

Returns nil if no such object found:

a = [:foo, 'bar', baz = 2]
a.find_index(:nosuch) # => nil

When a block is given, calls the block with each successive element element, returning the index of the first element for which the block returns a truthy value:

a = [:foo, 'bar', baz = 2, 'bar']
a.find_index { |element| element == 'bar' } # => 1

Returns nil if the block never returns a truthy value:

a = [:foo, 'bar', baz = 2]
a.find_index { |element| element == :X } # => nil

When neither an argument nor a block is given, returns a new Enumerator:

a = [:foo, 'bar', baz = 2]
e = a.find_index
e # => #<Enumerator: [:foo, "bar", 2]:find_index>
e.each { |element| element == 'bar' } # => 1

When both an argument and a block given, gives a warning (warning: given block not used) and ignores the block:

a = [:foo, 'bar', baz = 2, 'bar']
index = a.find_index('bar') { fail 'Cannot happen' }
index # => 1

first

ary.first → obj or nil
ary.first(n) → new_array

Returns elements from ary.

Argument n, if given, must be an Integer-convertible object, which will be converted to an Integer.

When no argument is given, returns the first element:

a = [:foo, 'bar', baz = 2]
a.first # => :foo
a # => [:foo, "bar", 2]

If ary> is empty, returns nil:

[].first # => nil

When argument n is given, returns the first n elements in a new Array:

a = [:foo, 'bar', baz = 2]
a.first(2) # => [:foo, "bar"]

When n >= ary.size, returns all elements:

a = [:foo, 'bar', baz = 2]
a.first(50) # => [:foo, "bar", 2]

When n == 0, returns an empty Array:

a = [:foo, 'bar', baz = 2]
a.first(0) # []

Raises an exception if n < 0:

a = [:foo, 'bar', baz = 2]
a.first(-1) # Raises ArgumentError (negative array size)

Raises an exception if n is not an Integer-convertible object:

a = [:foo, 'bar', baz = 2]
a.first(:X) # Raises TypeError (no implicit conversion of String into Integer)

flatten

ary.flatten → self or nil
ary.flatten(level) → self or nil

Replaces each Array object in ary with the elements from that object; returns self if any changes, nil otherwise.

Argument level, if given must be an Integer-convertible object.

With no argument, flattens all levels:

a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a1 = a.flatten
a1 # => [0, 1, 2, 3, 4, 5]
a1.equal?(a) # => true # Identity check
[0, 1, 2].flatten # => nil

With non-negative argument level, flattens recursively through level levels:

a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(0) # => nil
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(1) # => [0, 1, [2, 3], 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(2) # => [0, 1, 2, 3, 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(3) # => [0, 1, 2, 3, 4, 5]
[0, 1, 2].flatten(1) # => nil

With negative argument level, flattens all levels:

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

Raises an exception if level is not an Integer-convertible object:

[].flatten(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if ary contains a circular reference:

a = []
a.push([a, a])
a.flatten # Raises ArgumentError (tried to flatten recursive array)

Raises an exception if flatten reentered:

require 'continuation'
o = Object.new
def o.to_ary() callcc {|k| @cont = k; [1,2,3]} end
[10, 20, o, 30, o, 40].flatten
o.instance_eval {@cont}.call # Raises RuntimeError (flatten reentered)

flatten!

ary.flatten! → self or nil
ary.flatten!(level) → self or nil

Replaces each Array object in ary with the elements from that object; returns self if any changes, nil otherwise.

Argument level, if given must be an Integer-convertible object.

With no argument, flattens all levels:

a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a1 = a.flatten!
a1 # => [0, 1, 2, 3, 4, 5]
a1.equal?(a) # => true # Identity check
[0, 1, 2].flatten! # => nil

With non-negative argument level, flattens recursively through level levels:

a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(0) # => nil
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(1) # => [0, 1, [2, 3], 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(2) # => [0, 1, 2, 3, 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(3) # => [0, 1, 2, 3, 4, 5]
[0, 1, 2].flatten!(1) # => nil

With negative argument level, flattens all levels:

a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
[0, 1, 2].flatten!(-1) # => nil

Raises an exception if level is not an Integer-convertible object:

[].flatten!(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if ary contains a circular reference:

a = []
a.push([a, a])
a.flatten! # Raises ArgumentError (tried to flatten recursive array)

Raises an exception if flatten reentered:

require 'continuation'
o = Object.new
def o.to_ary() callcc {|k| @cont = k; [1,2,3]} end
[10, 20, o, 30, o, 40].flatten!
o.instance_eval {@cont}.call # Raises RuntimeError (flatten reentered)

freeze

ary.freeze → self

Freezes ary, returns self:

a = [:foo, 'bar', baz = 2]
a.frozen? # => false
a1 = a.freeze 
a1.object_id == a.object_id # => true

Raises an exception for an attempt to modify a frozen Array:

a = [:foo, 'bar', baz = 2]
a.freeze
a[3] = :bat # Raises FrozenError (can't modify frozen Array: [:foo, "bar", 2])

hash

ary.hash → integer

Returns the integer hash value for ary:

[].hash.class # => Integer

Two arrays have the same hash value if and only if they have the same content:

[0, 1, 2].hash == [0, 1, 2].hash # => true
[0, 1, 2].hash == [0, 1, ].hash # => false

include?

ary.include?(obj) → true or false

Returns true if obj == ary[n] for some index n:

[0, 1, 2].include?(2) # => true
[0, 1, 2].include?(3) # => false

index

ary.index(obj) → Integer or nil
ary.index { |element| ... } → Integer or nil
ary.index → new_enumerator

When argument obj is given, returns the index of the first element element for which obj == element:

a = [:foo, 'bar', baz = 2, 'bar']
a.index('bar') # => 1

Returns nil if no such object found:

a = [:foo, 'bar', baz = 2]
a.index(:nosuch) # => nil

When a block is given, calls the block with each successive element element, returning the index of the first element for which the block returns a truthy value:

a = [:foo, 'bar', baz = 2, 'bar']
a.index { |element| element == 'bar' } # => 1

Returns nil if the block never returns a truthy value:

a = [:foo, 'bar', baz = 2]
a.index { |element| element == :X } # => nil

When neither an argument nor a block is given, returns a new Enumerator:

a = [:foo, 'bar', baz = 2]
e = a.index
e # => #<Enumerator: [:foo, "bar", 2]:index>
e.each { |element| element == 'bar' } # => 1

When both an argument and a block given, gives a warning (warning: given block not used) and ignores the block:

a = [:foo, 'bar', baz = 2, 'bar']
index = a.index('bar') { fail 'Cannot happen' }
index # => 1

insert

ary.insert(index, *objects) → self

Inserts *objects before or after the element at offset index; returns self.

Argument index must be an Integer-convertible object, which will be converted to an Integer.

When index is non-negative, inserts *objects before the element at offset index:

a = [:foo, 'bar', baz = 2]
a1 = a.insert(1, :bat, :bam)
a # => [:foo, :bat, :bam, "bar", 2]
a1.object_id == a.object_id # => true

If index >= ary.length, extends ary:

a = [:foo, 'bar', baz = 2]
a.insert(5, :bat, :bam)
a # => [:foo, "bar", 2, nil, nil, :bat, :bam]

Does nothing if no *objects given:

a = [:foo, 'bar', baz = 2]
a.insert(1)
a.insert(50)
a.insert(-50)
a # => [:foo, "bar", 2]

When index is negative, inserts *objects after the element at offset index + ary.length:

a = [:foo, 'bar', baz = 2]
a.insert(-2, :bat, :bam)
a # => [:foo, "bar", :bat, :bam, 2]

Raises an exception if index is not an Integer-convertible object:

a = [:foo, 'bar', baz = 2, 'bar']
a.insert(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if index is too small:

a = [:foo, 'bar', baz = 2]
a.insert(-5, :bat, :bam) # Raises IndexError (index -5 too small for array; minimum: -4)

inspect

ary.inspect → new_string

Returns a new String formed by calling method inspect on each element in ary:

a = [:foo, 'bar', baz = 2]
a.inspect  # => "[:foo, \"bar\", 2]"

Raises an exception if any element lacks instance method inspect:

a = [:foo, 'bar', baz = 2, BasicObject.new]
a.inspect  # Raises NoMethodError (undefined method `inspect' for #<BasicObject:0x0000000006b69d28>)

intersection

ary.intersection(*other_arrays) → new_array

Each object in *other_arrays must be an Array-convertible object, which will be converted to an Array.

Returns a new Array containing each element found in both in ary and in all of the given *other_arrays; duplicates are omitted; comparisons use eql?:

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

Preserves order from ary:

[0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]

Raises an exception if any of the given *other_arrays is not an Array-convertible object:

[].intersection([0, 1], :foo) # Raises TypeError (no implicit conversion of Symbol into Array)

join

ary.join → new_string
ary.join(separator) → new_string

Returns a new String formed by joining the elements of ary.

Argument separator, if given, must be a String-convertible object:

With no argument, joins using the output field separator, $,:

a = [:foo, 'bar', baz = 2]
$, # => nil
a.join # => "foobar2"

With argument separator, joins using that separator:

a = [:foo, 'bar', baz = 2]
a.join("\n") # => "foo\nbar\n2"

Raises an exception if separator is not a String-convertible object:

a = [:foo, 'bar', baz = 2]
a.join(:foo) # Raises TypeError (no implicit conversion of Symbol into String)

Raises an exception if any element lacks instance method to_s:

a = [:foo, 'bar', baz = 2, BasicObject.new]
a.join # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)

keep_if

ary.keep_if { |element| ... } → new_array
ary.keep_if → new_enumeration

Removes from ary those elements for which the block returns false or nil; returns self:

a = [:foo, 'bar', baz = 2, :bam]
a1 = a.keep_if { |element| element.to_s.start_with?('b') }
a1 # => ["bar", :bam]
a1.object_id == a.object_id

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2, :bam]
a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if>

last

ary.last → obj or nil
ary.last(n) → new_array

Returns elements from ary.

Argument n, if given, must be an Integer-convertible object, which will be converted to an Integer.

When no argument is given, returns the last element:

a = [:foo, 'bar', baz = 2]
a.last # => 2
a # => [:foo, "bar", 2]

If ary is empty, returns nil:

[].last # => nil

When argument n is given, returns the last n elements in a new Array:

a = [:foo, 'bar', baz = 2]
a.last(2) # => ["bar", 2]

When n >= ary.size, returns all elements:

a = [:foo, 'bar', baz = 2]
a.last(50) # => [:foo, "bar", 2]

When n == 0, returns an empty Array:

a = [:foo, 'bar', baz = 2]
a.last(0) # []

Raises an exception if n < 0:

a = [:foo, 'bar', baz = 2]
a.last(-1) # Raises ArgumentError (negative array size)

Raises an exception if n is not an Integer-convertible object:

a = [:foo, 'bar', baz = 2]
a.last(:X) # Raises TypeError (no implicit conversion of String into Integer)

length

ary.length → int

Returns the count of elements in ary:

a = [:foo, 'bar', baz = 2]
a.length # => 3
[].length # => 0

map

ary.map { |elemeent| ... } → new_array
ary.map → new_enumerator

Returns a new Array whose elements are the return values from the block:

a = [:foo, 'bar', baz = 2]
a1 = a.map { |element| element.class }
a1 # => [Symbol, String, Integer]

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2]
a1 = a.map
a1 # => #<Enumerator: [:foo, "bar", 2]:map>

map!

ary.map! { |elemeent| ... } → self
ary.map → new_enumerator

Replaces each element the return value from the block:

a = [:foo, 'bar', baz = 2]
a1 = a.map! { |element| element.class }
a1 # => [Symbol, String, Integer]
a1.object_id == a.object_id # => true

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2]
a1 = a.map!
a1 # => #<Enumerator: [:foo, "bar", 2]:map!>

max

ary.max → obj
ary.max { |a, b| ... } → obj
ary.max(n) → new_array
ary.max(n) { |a, b| ... } → new_array

If no block given, each element in ary must respond to method <=> with an Integer-convertible object.

Argument n, if given, must be an Integer-convertible object, and may not be negative.

The block, if given, must return an Integer-convertible object.

With no argument and no block, returns the element in ary having the maximum value per <=>:

[0, 1, 2].max # => 2

With an argument n and no block, returns a new Array with at most n elements:

[0, 1, 2, 3].max(3) # => [3, 2, 1]
[0, 1, 2, 3].max(6) # => [3, 2, 1]
[0, 1, 2, 3].max(0) # => []

With a block and no argument, calls the block ary.size-1 times to compare elements; returns the element having the maximum value per the block.

['0', '00', '000'].max { |a, b| a.size <=> b.size } # => "000"

With an argument n and a block, returns a new Array with at most n elements:

['0', '00', '000'].max(2) { |a, b| a.size <=> b.size } # => ["000", "00"]
['0', '00', '000'].max(0) { |a, b| a.size <=> b.size } # => []

Raises an exception on encountering elements that are not comparable:

[0, 1, :foo].max # Raises ArgumentError (comparison of Symbol with 1 failed)

Raises an exception if argument n is not an Integer-convertible object:

[0, 1].max(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if argument n is negative:

[0, 1].max(-1) # Raises ArgumentError (negative size (-1))

Raises an exception if the block returns an object that is not an Integer-convertible object:

[0, 1, 2].max { |a, b| :foo } # Raises ArgumentError (comparison of Symbol with 0 failed)

min

ary.min → obj
ary.min { |a, b| ... } → obj
ary.min(n) → new_array
ary.min(n) { |a, b| ... } → new_array

If no block given, each element in ary must respond to method <=> with an Integer-convertible object.

Argument n, if given, must be an Integer-convertible object, and may not be negative.

The block, if given, must return an Integer-convertible object.

With no argument and no block, returns the element in ary having the minimum value per <=>:

[0, 1, 2].min # => 0

With an argument n and no block, returns a new Array with at most n elements:

[0, 1, 2, 3].min(3) # => [0, 1, 2]
[0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
[0, 1, 2, 3].min(0) # => []

With a block and no argument, calls the block ary.size-1 times to compare elements; returns the element having the minimum value per the block.

['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0"

With an argument n and a block, returns a new Array with at most n elements:

['0', '00', '000'].min(2) { |a, b| a.size <=> b.size } # => ["0", "00"]
['0', '00', '000'].min(0) { |a, b| a.size <=> b.size } # => []

Raises an exception on encountering elements that are not comparable:

[0, 1, :foo].min # Raises ArgumentError (comparison of Symbol with 1 failed)

Raises an exception if argument n is not an Integer-convertible object:

[0, 1].min(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if argument n is negative:

[0, 1].min(-1) # Raises ArgumentError (negative size (-1))

Raises an exception if the block returns an object that is not an Integer-convertible object:

[0, 1, 2].max { |a, b| :foo } # Raises ArgumentError (comparison of Symbol with 0 failed)

minmax

ary.minmax → [min_val, max_val]
ary.min { |a, b| ... } → [min_val, max_val]

If no block given, each element in ary must respond to method <=> with an Integer-convertible object](../../../doc/convertibles.md#integer-convertible-objects).

The block, if given, must return an Integer-convertible object.

With no block, returns the elements in ary having the minimum and maximum values per <=>:

[0, 1, 2].min_max # => [0, 2]

With a block, calls the block ary.size-1 times to compare elements; returns the elements in ary having the minimum and maximum values per <=>:

['0', '00', '000'].min_max { |a, b| a.size <=> b.size } # => ["0", "000"]

Raises an exception on encountering elements that are not comparable:

[0, 1, :foo].min # Raises ArgumentError (comparison of Symbol with 1 failed)

Raises an exception if argument n is not an Integer-convertible object:

[0, 1].min(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if argument n is negative:

[0, 1].min(-1) # Raises ArgumentError (negative size (-1))

Raises an exception if the block returns an object that is not an Integer-convertible object:

[0, 1, 2].max { |a, b| :foo } # Raises ArgumentError (comparison of Symbol with 0 failed)

none?

ary.none? → true or false
ary.none? { |element| ... } → true or false
ary.none?(obj) → true or false

The argument, if given, must have instance method ===.

With no argument and no block, returns true if any has no truthy elements, false otherwise:

[nil, false].none? # => true
[nil, 0, false].none? # => false
[].none? # => true

With no argument and a block, calls the block with each element in ary; returns true if the block returns no truthy value, false otherwise:

[0, 1, 2].none? { |element| element > 3 } # => true
[0, 1, 2].none? { |element| element > 1 } # => false

Does not call the block if ary is empty:

[].none? { |element| fail 'Cannot happen' } # => true

If argument obj is given, returns true unless obj.=== any element, false otherwise:

['food', 'drink'].none?(/bar/) # => true
['food', 'drink'].none?(/foo/) # => false
[].none?(/foo/) # => true
[0, 1, 2].none?(3) # => true
[0, 1, 2].none?(1) # => false

Issues a warniing ('(irb):161: warning: given block not used') if both an argument and a block given:

[0, 1, 2].none?(/foo/) { |element| } # => true

Raises an exception if the argument does not have instance method ===:

[0, 1, 2].none?(BasicObject.new) # Raises NoMethodError (undefined method `===' for #<BasicObject:>)

permutation

ary.permutation { |element| ... } → self
ary.permutation(n) { |element| ... } → self
ary.permutation → new_enumerator
ary.permutation(n) → new_enumerator

Calls the block with permutations of elements of ary; returns self. The order of permutations is indeterminate.

Argument n, if given, must be an Integer-convertible object.

When a block and a zero-valued argument n are given, calls the block once with a new empty Array:

a = [0, 1, 2]
a1 = a.permutation(0) { |permutation| p permutation }
a1.equal?(a) # => true # Identity check.

Output:

[]

If 0 < n < ary.size, calls the block with all n-tuple permutations of ary:

a = [0, 1, 2]
a.permutation(2) { |permutation| p permutation }

Output:

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

a = [0, 1, 2]
a.permutation(3) { |permutation| p permutation }

Output:

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

If n >= ary.size, does not call the block:

a = [0, 1, 2]
a.permutation(4) { |permutation| fail 'Cannot happen' }

If n is negative, does not call the block:

a = [0, 1, 2]
a.permutation(-1) { |permutation| fail 'Cannot happen' }
a.permutation(-2) { |permutation| fail 'Cannot happen' }

When a block given but no argument, behaves the same as a.permutation(a.size):

a = [0, 1, 2]
a.permutation { |permutation| p permutation }

Output:

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

Returns a new Enumerator if no block given:

a = [0, 1, 2]
a.permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>

Raises an exception if n is not an Integer-convertible object:

a.permutation(:foo) { } # Raises TypeError (no implicit conversion of Symbol into Integer)

pop

ary.pop → obj or nil
ary.pop(n) → new_array

Removes and returns trailing elements from ary.

Argument n, if given, must be an Integer-convertible object, which will be converted to an Integer.

If no argument is given and ary is empty, returns nil:

a = []
a.pop # => nil

If no argument is given and ary is not empty, removes and returns the last element in ary:

a = [:foo, 'bar', baz = 2]
a.pop # => 2
a # => [:foo, "bar"]

If argument n is given and ary is empty, returns a new empty Array:

a = []
a.pop(1) # => []
a.pop(2) # => []

If argument n is given and ary is not empty, removes and returns the last n elements in ary:

a = [:foo, 'bar', baz = 2]
a1 = a.pop(2)
a1 # => ["bar", 2]
a # => [:foo]

If n is greater than ary.size, removes and returns all elements in ary:

a = [:foo, 'bar', baz = 2]
a1 = a.pop(50)
a1 # => [:foo, "bar", 2]
a # => []

Returns a new empty Array if n is 0:

a = [:foo, 'bar', baz = 2]
a1 = a.pop(0)
a1 # => []
a # => [:foo, "bar", 2]

Raises an exception if n is negative:

a = [:foo, 'bar', baz = 2]
a1 = a.pop(-1) # Raises ArgumentError (negative array size)

prepend

ary.prepend(*objects) → self

Prepends the given *objects to ary, returns self:

a = [:foo, 'bar', baz = 2]
a1 = a.prepend(:bam, :bat)
a1 # => [:bam, :bat, :foo, "bar", 2]
a1.object_id == a.object_id # => true

product

ary.product(*other_arrays) → new_array
ary.product(*other_arrays) { |combination| ... } → self

Each argument must be an Array-convertible object.

Returns a new Array of all combinations of elements from all arrays, ary and *other_arrays:

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

The size of the new Array is the product of the lengths of all arrays:

[0, 1].product([2, 3, 4], [5, 6, 7, 8]).size # => 24

The size of each nested Array is the count of all arrays, ary and *other_arrays:

[0, 1].product([2, 3, 4], [5, 6, 7, 8]).first.size # => 3

If a block given, calls the block with each combination; returns self:

a = [0, 1]
a1 = a.product([2, 3]) { |combination| p combination }
a. equal?(a) # => true # Identity check

Output:

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

Raises an exception if any argument is not an Array-convertible object:

[0, 1].product(:foo) # Raises TypeError (no implicit conversion of Symbol into Array)

push

ary.push(*objects) → self

Appends the given *objects to ary; returns self:

a = [:foo, 'bar', baz = 2]
a1 = a.push(:bam, :bat)
a1 # => [:foo, "bar", 2, :bam, :bat]
a1.object_id == a.object_id # => true

rassoc

ary.assoc(obj) → new_array or nil

Returns the the first element in ary that is an Array whose second element == >ary:

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

Returns nil if no such element is found:

a = [[0, 1], 7, {foo: 0}, [4, 5]]
a.rassoc(:nosuch) # => nil

reject

ary.reject { |element| ... } → new_array
ary.reject → new_enumerator

Returns a new Array whose elements are all those from ary for which the block returns false or nil:

a = [:foo, 'bar', baz = 2, 'bat']
a1 = a.reject { |element| element.to_s.start_with?('b') }
a1 # => [:foo, 2]

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2]
a.reject # => #<Enumerator: [:foo, "bar", 2]:reject>

reject!

ary.reject! { |element| ... } → self or nil
ary.reject! → new_enumerator

Removes each element for which the block returns a truthy value.

Returns self if any elements removed:

a = [:foo, 'bar', baz = 2, 'bat']
a1 = a.reject! { |element| element.to_s.start_with?('b') }
a1 # => [:foo, 2]
a1.object_id == a.object_id # => true

Returns nil if no elements removed:

a = [:foo, 'bar', baz = 2]
a.reject! { |element| false } # => nil

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2]
a.reject! # => #<Enumerator: [:foo, "bar", 2]:reject!>

repeated_combination

ary.repeated_combination(n) { |element| ... } → self
ary.repeated_combination(n) → new_enumerator

Calls the block with repeated combinations of length n of the elements of ary; returns self. The order of repeated combinations is indeterminate.

Argument n, if given, must be an Integer-convertible object.

When a block and a zero-valued argument n are given, calls the block once with a new empty Array:

a = [0, 1, 2]
a1 = a.repeated_combination(0) { |combination| p combination }
a1.equal?(a) # => true # Identity check.

Output:

[]

If 0 < n < ary.size, calls the block with all n-tuple repeated combinations of ary:

a = [0, 1, 2]
a.repeated_combination(2) { |combination| p combination }

Output:

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

a = [0, 1, 2]
a.repeated_combination(3) { |combination| p combination }

Output:

[0, 0, 0]
[0, 0, 1]
[0, 0, 2]
[0, 1, 1]
[0, 1, 2]
[0, 2, 2]
[1, 1, 1]
[1, 1, 2]
[1, 2, 2]
[2, 2, 2]```

If <tt>n</tt> is negative, does not call the block:

```ruby
a = [0, 1, 2]
a.repeated_combination(-1) { |combination| fail 'Cannot happen' }
a.repeated_combination(-2) { |combination| fail 'Cannot happen' }

Returns a new Enumerator if no block given:

a = [0, 1, 2]
a.repeated_combination(2) # => #<Enumerator: [0, 1, 2]:repeated_combination(2)>

Raises an exception if n is not an Integer-convertible object:

a.repeated_combination(:foo) { } # Raises TypeError (no implicit conversion of Symbol into Integer)

repeated_permutation

ary.repeated_permutation(n) { |element| ... } → self
ary.repeated_permutation(n) → new_enumerator

Calls the block with repeated permutations of length n of the elements of ary; returns self. The order of repeated permutations is indeterminate.

Argument n, if given, must be an Integer-convertible object.

When a block and a zero-valued argument n are given, calls the block once with a new empty Array:

a = [0, 1, 2]
a1 = a.repeated_permutation(0) { |permutation| p permutation }
a1.equal?(a) # => true # Identity check.

Output:

[]

If 0 < n < ary.size, calls the block with all n-tuple repeated permutations of ary:

a = [0, 1, 2]
a.repeated_permutation(2) { |permutation| p permutation }

Output:

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

a = [0, 1, 2]
a.repeated_permutation(3) { |permutation| p permutation }

Output:

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

If n is negative, does not call the block:

a = [0, 1, 2]
a.repeated_permutation(-1) { |permutation| fail 'Cannot happen' }
a.repeated_permutation(-2) { |permutation| fail 'Cannot happen' }

Returns a new Enumerator if no block given:

a = [0, 1, 2]
a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:repeated_permutation(2)>

Raises an exception if n is not an Integer-convertible object:

a.repeated_permutation(:foo) { } # Raises TypeError (no implicit conversion of Symbol into Integer)

replace

ary.replace(other_array) → self

Replaces the content of ary with the content of other_array; returns self.

Argument other_array must be an Array-convertible object, which will be converted to an Array.

Replaces the content of ary with the content of other_array:

a = [:foo, 'bar', baz = 2]
a1 = a.replace(['foo', :bar, 3])
a1 # => ["foo", :bar, 3]
a1.object_id == a.object_id # => true

Ignores the size of ary:

a = [:foo, 'bar', baz = 2]
a.replace([]) # => []
a.replace([:foo, 'bar', baz = 2]) # => [:foo, "bar", 2]

Raises an exception if other_array is not an Array-convertible object:

a = [:foo, 'bar', baz = 2]
a.replace(:foo) # Raises TypeError (no implicit conversion of Symbol into Array)

reverse

ary.reverse → new_array

Returns a new Array whose elements are in reverse order from ary:

a = [:foo, 'bar', baz = 2]
a1 = a.reverse
a1 # => [2, "bar", :foo]

reverse!

ary.reverse → self

Returns self with elements in reverse order:

a = [:foo, 'bar', baz = 2]
a1 = a.reverse!
a1 # => [2, "bar", :foo]
a1.object_id == a.object_id # => true

reverse_each

ary.reverse_each { |element| ... } → self
ary.reverse_each → Enumerator

When a block given, passes reverse_each successive element in ary to the block in reverse order; returns self:

a = [:foo, 'bar', baz = 2]
a1 = a.reverse_each { |element|  puts "#{element.class} #{element}" }
a1.object_id == a.object_id # => true

Output:

Integer 2
String bar
Symbol foo

Allows ary to be modified during the iteration:

a = [:foo, 'bar', baz = 2]
a.reverse_each { |element| puts element; a.clear if element.to_s.start_with?('b') }
a # => []

Output:

2
bar

When no block given, returns a new Enumerator:

a = [:foo, 'bar', baz = 2]
e = a.reverse_each
e # => #<Enumerator: [:foo, "bar", 2]:reverse_each>
a1 = e.each { |element|  puts "#{element.class} #{element}" }
a1.object_id == a.object_id # => true

Output:

Integer 2
String bar
Symbol foo

rindex

ary.rindex(obj) → Integer or nil
ary.rindex { |element| ... } → Integer or nil
ary.rindex → new_enumerator

When argument obj is given, returns the index of the last element element for which obj == element:

a = [:foo, 'bar', baz = 2, 'bar']
a.rindex('bar') # => 3

Returns nil if no such object found:

a = [:foo, 'bar', baz = 2]
a.rindex(:nosuch) # => nil

When a block is given, calls the block with each successive element element, returning the index of the last element for which the block returns a truthy value:

a = [:foo, 'bar', baz = 2, 'bar']
a.rindex { |element| element == 'bar' } # => 3

Returns nil if the block never returns a truthy value:

a = [:foo, 'bar', baz = 2]
a.rindex { |element| element == :X } # => nil

When neither an argument nor a block is given, returns a new Enumerator:

a = [:foo, 'bar', baz = 2, 'bar']
e = a.rindex
e # => #<Enumerator: [:foo, "bar", 2, "bar"]:rindex>
e.each { |element| element == 'bar' } # => 3

When both an argument and a block given, gives a warning (warning: given block not used) and ignores the block:

a = [:foo, 'bar', baz = 2, 'bar']
index = a.rindex('bar') { fail 'Cannot happen' }
index # => 3

rotate

ary.rotate → new_ary
ary.rotate(count) → new_ary

Returns a new Array formed from ary by rotating elements from one end to the other.

Argument count, if given, must be an Integer-convertible object.

When no argument given, returns a new Array that is like ary, except that the first element has been rotated to the last position:

a = [:foo, 'bar', baz = 2, 'bar']
a1 = a.rotate
a1 # => ["bar", 2, "bar", :foo]

When given a non-negative argument count, returns a new Array with count elements rotated from the beginning to the end:

a = [:foo, 'bar', baz = 2]
a1 = a.rotate(2)
a1 # => [2, :foo, "bar"]

If count is large, uses count % ary.size as the count:

a = [:foo, 'bar', baz = 2]
a1 = a.rotate(20)
a1 # => [2, :foo, "bar"]

If count is 0, returns an unmodified copy of ary:

a = [:foo, 'bar', baz = 2]
a1 = a.rotate(0)
a1 # => [:foo, "bar", 2]

When given a negative argument count, rotates in the opposite direction, from end to beginning:

a = [:foo, 'bar', baz = 2]
a1 = a.rotate(-2)
a1 # => ["bar", 2, :foo]

If count is small, uses count % ary.size< as the count:

a = [:foo, 'bar', baz = 2]
a1 = a.rotate(-5)
a1 # => ["bar", 2, :foo]

Raises an exception if count is not an Integer-convertible object:

a = [:foo, 'bar', baz = 2]
a1 = a.rotate(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

rotate!

ary.rotate! → self
ary.rotate(count) → self

Rotates ary by moving elements from one end to the other; returns self.

Argument count, if given, must be an Integer-convertible object.

When no argument given, rotates the first element to the last position:

a = [:foo, 'bar', baz = 2, 'bar']
a1 = a.rotate!
a1 # => ["bar", 2, "bar", :foo]
a1.object_id == a.object_id # => true

When given a non-negative argument count, rotates count elements from the beginning to the end:

a = [:foo, 'bar', baz = 2]
a.rotate!(2)
a # => [2, :foo, "bar"]

If count is large, uses count % ary.size as the count:

a = [:foo, 'bar', baz = 2]
a.rotate!(20)
a # => [2, :foo, "bar"]

If count is 0, returns self unmodified:

a = [:foo, 'bar', baz = 2]
a.rotate!(0)
a # => [:foo, "bar", 2]

When given a negative argument count, rotates in the opposite direction, from end to beginning:

a = [:foo, 'bar', baz = 2]
a.rotate!(-2)
a # => ["bar", 2, :foo]

If count is small, uses count % ary.size< as the count:

a = [:foo, 'bar', baz = 2]
a.rotate!(-5)
a # => ["bar", 2, :foo]

Raises an exception if count is not an Integer-convertible object:

a = [:foo, 'bar', baz = 2]
a1 = a.rotate!(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

select

ary.select { |element| ... } → new_array
ary.select → new_enumeration

Returns a new Array containing those elements of ary for which the block returns a truthy value:

a = [:foo, 'bar', baz = 2, :bam]
a1 = a.select { |element| element.to_s.start_with?('b') }
a1 # => ["bar", :bam]

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2, :bam]
a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>

select!

ary.select! { |element| ... } → new_array
ary.select! → new_enumeration

Removes from ary those elements for which the block returns false or nil; returns self:

a = [:foo, 'bar', baz = 2, :bam]
a1 = a.select! { |element| element.to_s.start_with?('b') }
a1 # => ["bar", :bam]
a1.object_id == a.object_id

Returns a new Enumerator if no block given:

a = [:foo, 'bar', baz = 2, :bam]
a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>

shift

ary.shift → obj or nil
ary.shift(n) → new_array

Removes and returns leading elements in ary.

The argument n, if given, must be an Integer-convertible object, which will be converted to an Integer.

If no argument is given and ary is empty returns nil:

a = []
a.shift # => nil

If no argument is given and ary is not empty, removes and returns the first element in ary:

a = [:foo, 'bar', baz = 2]
a.shift # => :foo
a # => ["bar", 2]

If argument n is given and ary is empty, returns a new empty Array:

a = []
a.shift(1) # => []
a.shift(2) # => []

If argument is given and ary is not empty, removes and returns the first n elements in ary:

a = [:foo, 'bar', baz = 2]
a1 = a.shift(2)
a1 # => [:foo, "bar"]
a # => [2]

If n is greater than ary.size, removes and returns all elements in ary:

a = [:foo, 'bar', baz = 2]
a1 = a.shift(50)
a1 # => [:foo, "bar", 2]
a # => []

If n is 0, returns an empty Array and ary is unmodified:

a = [:foo, 'bar', baz = 2]
a1 = a.shift(0)
a1 # => []
a # => [:foo, "bar", 2]

Raises an exception if n is negative:

a = [:foo, 'bar', baz = 2]
a1 = a.shift(-1) # Raises ArgumentError (negative array size)

slice

ary.slice(n) → obj or nil
ary.slice(start, length) → new_array or nil
ary.slice(range) → new_array or nil

Returns elements from ary.

When the only argument is an Integer n, returns the nth element in ary:

a = [:foo, 'bar', baz = 2]
a.slice(0) # => :foo
a.slice(2) # => 2
a # => [:foo, "bar", 2]

If n is negative, counts relative to the end of ary:

a = [:foo, 'bar', baz = 2]
a.slice(-1) # => 2
a.slice(-2) # => "bar"

If n is out of range, returns nil:

a = [:foo, 'bar', baz = 2]
a.slice(50) # => nil
a.slice(-50) # => nil

When the only arguments are Integers start and length, returns a new array of size length containing elements of ary beginning at index start:

a = [:foo, 'bar', baz = 2]
a.slice(0, 2) # => [:foo, "bar"]
a.slice(1, 2) # => ["bar", 2]

If start + length > ary.length, returns ary.size - start elements:

a = [:foo, 'bar', baz = 2]
a.slice(0, 50) # => [:foo, "bar", 2]
a.slice(1, 50) # => ["bar", 2]

If start == a.size and length >= 0, returns a new empty Array:

a = [:foo, 'bar', baz = 2]
a.slice(a.size, 0) # => []
a.slice(a.size, 50) # => []

If length is negative, returns nil:

a = [:foo, 'bar', baz = 2]
a.slice(2, -1) # => nil
a.slice(1, -2) # => nil

When the only argument is a Range object , treats rng.min as start above and rng.size as length above:

a = [:foo, 'bar', baz = 2]
a.slice(0..1) # => [:foo, "bar"]
a.slice(1..2) # => ["bar", 2]

If rng.start == a.size, returns a new empty Array:

a = [:foo, 'bar', baz = 2]
a.slice(a.size..0) # => []
a.slice(a.size..50) # => []
a.slice(a.size..-1) # => []
a.slice(a.size..-50) # => []

If rng.end is negative, calculates the end index from the end of ary:

a = [:foo, 'bar', baz = 2]
a.slice(0..-1) # => [:foo, "bar", 2] 
a.slice(0..-2) # => [:foo, "bar"]
a.slice(0..-3) # => [:foo]
a.slice(0..-4) # => []

If rng.start is negative, calculates the start index from the end of ary:

a = [:foo, 'bar', baz = 2]
a.slice(-1..2) # => [2] 
a.slice(-2..2) # => ["bar", 2]
a.slice(-3..2) # => [:foo, "bar", 2]

Raises an exception if given a single argument that is not an Integer or a Range:

a = [:foo, 'bar', baz = 2]
a.slice(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if given two arguments that are not both Integers:

a = [:foo, 'bar', baz = 2]
a.slice(:foo, 3) # Raises TypeError (no implicit conversion of Symbol into Integer)
a.slice(1, :bar) # Raises TypeError (no implicit conversion of Symbol into Integer)

slice!

ary.slice!(n) → obj or nil
ary.slice!(start, length) → new_array or nil
ary.slice!(range) → new_array or nil

Removes and returns elements from ary.

When the only argument is an Integer n, removes and returns the nth element in ary:

a = [:foo, 'bar', baz = 2]
a.slice!(1) # => "bar"
a # => [:foo, 2]

If n is negative, counts relative to the end of ary:

a = [:foo, 'bar', baz = 2]
a.slice!(-1) # => 2
a # => [:foo, "bar"]

If n is out of range, returns nil:

a = [:foo, 'bar', baz = 2]
a.slice!(50) # => nil
a.slice!(-50) # => nil
a # => [:foo, "bar", 2]

When the only arguments are Integers start and length, removes length elements from ary beginning at index start; returns the deleted objects in a new array:

a = [:foo, 'bar', baz = 2]
a.slice!(0, 2) # => [:foo, "bar"]
a # => [2]

If start + length > ary.length, removes and returns ary.size - start elements:

a = [:foo, 'bar', baz = 2]
a.slice!(1, 50) # => ["bar", 2]
a # => [:foo]

If start == a.size and length >= 0, returns a new empty Array:

a = [:foo, 'bar', baz = 2]
a.slice!(a.size, 0) # => []
a.slice!(a.size, 50) # => []
a # => [:foo, "bar", 2]

If length is negative, returns nil:

a = [:foo, 'bar', baz = 2]
a.slice!(2, -1) # => nil
a.slice!(1, -2) # => nil
a # => [:foo, "bar", 2]

When the only argument is a Range object , treats rng.min as start above and rng.size as length above:

a = [:foo, 'bar', baz = 2]
a.slice!(1..2) # => ["bar", 2]
a # => [:foo]

If rng.start == a.size, returns a new empty Array:

a = [:foo, 'bar', baz = 2]
a.slice!(a.size..0) # => []
a.slice!(a.size..50) # => []
a.slice!(a.size..-1) # => []
a.slice!(a.size..-50) # => []
a # => [:foo, "bar", 2]

If rng.end is negative, calculates the end index from the end of ary:

a = [:foo, 'bar', baz = 2]
a.slice!(0..-2) # => [:foo, "bar"]
a # => [2]

If rng.start is negative, calculates the start index from the end of ary:

a = [:foo, 'bar', baz = 2]
a.slice!(-2..2) # => ["bar", 2]
a # => [:foo]

Raises an exception if given a single argument that is not an Integer or a Range:

a = [:foo, 'bar', baz = 2]
a.slice!(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

Raises an exception if given two arguments that are not both Integers:

a = [:foo, 'bar', baz = 2]
a.slice!(:foo, 3) # Raises TypeError (no implicit conversion of Symbol into Integer)
a.slice!(1, :bar) # Raises TypeError (no implicit conversion of Symbol into Integer)

sort

ary.sort → new_array
ary.sort { |a, b| ... } → new_array

Returns a new Array whose elements are those from ary, sorted.

With no block, compares elements using operator <=>:

a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort
a1 # => ["a", "b", "c", "d", "e"]

With a block, compares elements using the block's return value.

For each element pair a and b, the block should return an integer:

  • Negative when b is to follow a.
  • Zero when a and b are equivalent.
  • Positive when a is to follow b.
a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort { |a, b| a <=> b }
a1 # => ["a", "b", "c", "d", "e"]
a2 = a.sort { |a, b| b <=> a }
a2 # => ["e", "d", "c", "b", "a"]

When the block returns 0, the order for a and b is indeterminate, and may be unstable:

a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort { |a, b| 0 }
a1 # => ["c", "e", "b", "d", "a"]

Raises an exception if the block returns a non-Integer:

a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort { |a, b| :foo } # Raises ArgumentError (comparison of Symbol with 0 failed)

sort!

ary.sort! → self
ary.sort! { |a, b| ... } → self

Returns self with its elements sorted.

With no block, compares elements using operator <=>:

a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a.sort!
a # => ["a", "b", "c", "d", "e"]

With a block, compares elements using the block's return value.

For each element pair a and b, the block should return an integer:

  • Negative when b is to follow a.
  • Zero when a and b are equivalent.
  • Positive when a is to follow b.
a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a.sort! { |a, b| a <=> b }
a # => ["a", "b", "c", "d", "e"]
a.sort! { |a, b| b <=> a }
a # => ["e", "d", "c", "b", "a"]

When the block returns 0, the order for a and b is indeterminate, and may be unstable:

a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a.sort! { |a, b| 0 }
a # => ["d", "e", "c", "a", "b"]

Raises an exception if the block returns a non-Integer:

a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort! { |a, b| :foo } # Raises ArgumentError (comparison of Symbol with 0 failed)

sort_by!

ary.sort_by! { |element| ... } → self
ary.sort_by! → new_enumerator

Sorts ary using an ordering determined by the block; returns self.

Calls the block with each successive element; sorts elements based on the collection of values returned from the block.

For duplicates returned by the block, the ordering is indeterminate, and may be unstable.

This example sorts strings based on their sizes:

a = ['aaaa', 'bbb', 'cc', 'd']
a.sort_by! { |element| element.size }
a # => ["d", "cc", "bbb", "aaaa"]

Returns a new Enumerator if no block given:

a = ['aaaa', 'bbb', 'cc', 'd']
a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>

take

ary.take(n) → new_array

Argument n must be an Integer-convertible object.

Returns a new Array containing the first n element of ary; does not modify ary:

a = [0, 1, 2, 3, 4, 5]
a.take(0) # => []
a.take(1) # => [0]
a.take(2) # => [0, 1]
a.take(50) # => [0, 1, 2, 3, 4, 5]
a # => [0, 1, 2, 3, 4, 5]

Raises an exception if n is negative:

[0, 1].take(-1) # Raises ArgumentError (attempt to take negative size)

Argument n must be an Integer-convertible object:

[0, 1].take(:foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

take_while

ary.take_while { |element| ... } → new_array
ary.take_while → new_enumerator

With a block given, calls the block with each successive element; stops if the block returns nil or nil; returns a new Array containing those elements for which the block returned a truthy value:

a = [0, 1, 2, 3, 4, 5]
a.take_while { |element| element < 3 } # => [0, 1, 2]
a.take_while { |element| true } # => [0, 1, 2, 3, 4, 5]
a.take_while { |element| false } # => []

With no block given, returns a new Enumerator:

[0, 1].take_while # => #<Enumerator: [0, 1]:take_while>

to_a

ary.to_a → self or new_array

When ary is an Array, returns self:

a = [:foo, 'bar', baz = 2]
a1 = a.to_a
a1.object_id == a.object_id # => true

When ary is a subclass of Array, returns a new Array containing the elements of ary:

class SubArray < Array; end
a = SubArray.new([:foo, 'bar', baz = 2])
a1 = a.to_a
a1.class # => Array
a1 == a # => true

to_ary


ary.to_ary → self or new_array

When ary is an Array, returns self:

a = [:foo, 'bar', baz = 2]
a1 = a.to_ary
a1.object_id == a.object_id # => true

When ary is a subclass of Array, returns a new Array containing the elements of ary:

class SubArray < Array; end
a = SubArray.new([:foo, 'bar', baz = 2])
a1 = a.to_ary
a1.class # => Array
a1 == a # => true

to_h

ary.to_h → new_hash
ary.to_h {|element| ... }  → new_hash

Returns a new Hash formed from ary.

When no block given, returns a new Hash wherein each 2-element Array object in ary becomes a key-value pair in the returned Hash:

[].to_h # => {}
a = [[:foo, 0], [:bar, 1], [:baz, 2]]
h = a.to_h
h # => {:foo=>0, :bar=>1, :baz=>2}

Raises an exception if any element is not an Array:

[:foo].to_h # Raises TypeError (wrong element type Symbol at 0 (expected array))

Raises an exception if any element is an Array not of size 2:

[[:foo]].to_h # Raises ArgumentError (wrong array length at 0 (expected 2, was 1))

Raises an exception if any ary[n].first would be an invalid hash key:

[[BasicObject.new, 0]].to_h # Raises NoMethodError (undefined method `hash' for #<BasicObject:>)

to_s

ary.to_s → new_string

Returns a new String formed by calling method inspect on each element in ary:

a = [:foo, 'bar', baz = 2]
a.to_s  # => "[:foo, \"bar\", 2]"

Raises an exception if any element lacks instance method inspect:

a = [:foo, 'bar', baz = 2, BasicObject.new]
a.to_s  # Raises NoMethodError (undefined method `inspect' for #<BasicObject:0x0000000006b69d28>)

transpose

ary.transpose → new_array

Transposes the rows and columns in an array of arrays.

Each element in ary must be an Array-convertible object, which will be converted to an Array.

a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]

Raises an exception if an element in ary is not an Array-convertible object:

a = [[:a0, :a1], [:b0, :b1], :foo]
a.transpose # Raises TypeError (no implicit conversion of Symbol into Array)

Raises an exception if the sizes of the sub-arrays differ:

a = [[:a0, :a1], [:b0, :b1], [:c0, :c1, :c2]]
a.transpose # Raises IndexError (element size differs (3 should be 2))

union

ary.union(*other_arrays) → new_array

Each argument must be an Array-convertible object.

Returns a new Array that is the union of ary and all arguments, with duplicates removed and order preserved; compares using eql?:

[0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
[0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
[0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3]

Raises an exeption if any argument is not an Array-convertible object:

[].union([], :foo) # Raises TypeError (no implicit conversion of Symbol into Array)

uniq

ary.uniq → new_array
ary.uniq { |element| ... } → new_array

Returns a new Array containing those elements from ary that are not duplicates, the first occurrence always being retained.

With no block, identifies duplicates by comparing elements with eql?:

a = [0, 0, 1, 1, 2, 2]
a.uniq # => [0, 1, 2]

With a block, calls the block for each element; identifies duplicates by comparing block return values with eql?:

a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
a.uniq { |element| element.size } # => ["a", "aa", "aaa"]

Raises an exception if any element does not respond to instance method hash:

[BasicObject.new, BasicObject.new].uniq # Raises NoMethodError (undefined method `hash' for #<BasicObject:>)

Raises an exception if the block returns an element that does not respond to method hash:

[0, 1].uniq { |x| BasicObject.new } # Raises NoMethodError (undefined method `hash' for #<BasicObject:0x0000000006baaf08>)

uniq!

ary.uniq! → self or nil
ary.uniq! { |element| ... } → self or nil

Removes duplicate elements from ary, the first occurrence always being retained. Returns self if any elements removed, nil otherwise.

With no block, removes duplicate elements identified by comparing elements with eql?:

a = [0, 0, 1, 1, 2, 2]
a1 = a.uniq!
a1 # => [0, 1, 2]
a1.equal?(a) # => true # Identity check
[0, 1, 2].uniq! # => nil

With a block, calls the block for each element; removes duplicate elements identified by comparing block return values with eql?:

a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
a.uniq! { |element| element.size } # => ["a", "aa", "aaa"]
a = ['a', 'aa', 'aaa']
a.uniq! { |element| element.size } # => nil

Raises an exception if any element does not respond to instance method hash:

[BasicObject.new, BasicObject.new].uniq! # Raises NoMethodError (undefined method `hash' for #<BasicObject:>)

Raises an exception if the block returns an element that does not respond to method hash:

[0, 1].uniq! { |x| BasicObject.new } # Raises NoMethodError (undefined method `hash' for #<BasicObject:0x0000000006baaf08>)

unshift

ary.unshift(*objects) → self

Prepends the given *objects to ary:

a = [:foo, 'bar', baz = 2]
a1 = a.unshift(:bam, :bat)
a1 # => [:bam, :bat, :foo, "bar", 2]
a1.object_id == a.object_id # => true

values_at

ary.values_at(*indexes) → new_array

Returns a new Array whose elements are the ary elements at the given indexes.

Each index given in *indexes must be an Integer-convertible object.

For each positive index index, returns the element at offset index:

a = [:foo, 'bar', baz = 2]
a.values_at(0, 2) # => [:foo, 2]

The given *indexes may be in any order, and may repeat:

a = [:foo, 'bar', baz = 2]
a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]

Assigns nil> for an index that is too large:

a = [:foo, 'bar', baz = 2]
a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]

For each negative index, counts backward from the end of ary:

a = [:foo, 'bar', baz = 2]
a.values_at(-1, -3) # => [:foo, 2] # => [2, :foo]

The given *indexes may have a mixture of signs:

a = [:foo, 'bar', baz = 2]
a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]

Assigns nil for an index that is too small:

a = [:foo, 'bar', baz = 2]
a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]

Raises an exception if any index is not an Integer-convertible object:

a = [:foo, 'bar', baz = 2]
a.values_at(0, :foo) # Raises TypeError (no implicit conversion of Symbol into Integer)

zip

ary.zip(*other_arrays) → new_array
ary.zip(*other_arrays) { |other_array| ... } → nil

Each object in *other_arrays must be an Array-convertible object, which will be converted to an Array.

With no block, returns a new Array of size ary.size whose elements are Arrays.

Each nested array new_array[n] is of size other_arrays.size+1, and contains:

  • The nth element of ary.
  • The nth element of each of the *other_arrays.

If all the arrays are the same size:

a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3]
c = [:c0, :c1, :c2, :c3]
d = a.zip(b, c)
d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]

If any array in other_arrays is smaller than ary, fills to ary.size with nil:

a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2]
c = [:c0, :c1]
d = a.zip(b, c)
d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]

If any array in other_arrays is larger than ary, its trailing elements are ignored:

a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3, :b4]
c = [:c0, :c1, :c2, :c3, :c4, :c5]
d = a.zip(b, c)
d

When a block given, calls the block with each of the sub-arrays (formed as above); returns nil

a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3]
c = [:c0, :c1, :c2, :c3]
a.zip(b, c) { |sub_array| p sub_array} # => nil

Output:

[:a0, :b0, :c0]
[:a1, :b1, :c1]
[:a2, :b2, :c2]
[:a3, :b3, :c3]

Raises an exception if any of the given *other_arrays is not an Array-convertible object:

a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3]
c = [:c0, :c1, :c2, :c3]
d = a.zip(b, c, :foo) # Raises TypeError (wrong argument type Symbol (must respond to :each))

| (Union)

ary | other_array → new_array

Argument other_array must be an Array-convertible object.

Returns the union of ary and other_array, with duplicates removed and order preserved:

[0, 1] | [2, 3] # => [0, 1, 2, 3]
[0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
[0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]

Raises an exception if other_array is not an Array-convertible object:

[] | :foo # Raises TypeError (no implicit conversion of Symbol into Array)