Array

Returns a new array populated with the given objects.

Array.[]( 1, 'a', /^A/)  # => [1, "a", /^A/]
Array[ 1, 'a', /^A/ ]    # => [1, "a", /^A/]
[ 1, 'a', /^A/ ]         # => [1, "a", /^A/]

Returns a new Array.

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

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

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

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

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

With a block and 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"]

Raises ArgumentError if size is negative.

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

If object is an Array object, returns object.

Otherwise if object responds to :to_ary, calls object.to_ary and returns the result.

Returns nil if object does not respond to :to_ary

Raises an exception unless object.to_ary returns an Array object.

Returns a new Array containing each element found in both array and Array other_array; duplicates are omitted; items are compared using eql?:

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

Preserves order from array:

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

Related: Array#intersection.

When non-negative argument Integer n is given, returns a new Array built by concatenating the n copies of self:

a = ['x', 'y']
a * 3 # => ["x", "y", "x", "y", "x", "y"]

When String argument string_separator is given, equivalent to array.join(string_separator):

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

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

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

Related: concat.

Returns a new Array containing only those elements from array that are not found in Array other_array; items are compared using eql?; the order from array is preserved:

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

Related: Array#difference.

Appends object to self; returns self:

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

Appends object as one element, even if it is another Array:

a = [:foo, 'bar', 2]
a1 = a << [3, 4]
a1 # => [:foo, "bar", 2, [3, 4]]

Returns -1, 0, or 1 as self is less than, equal to, or greater than other_array. For each index i in self, evaluates result = self[i] <=> other_array[i].

Returns -1 if any result is -1:

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

Returns 1 if any result is 1:

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

When all results are zero:

• Returns -1 if array is smaller than other_array:

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

• Returns 1 if array is larger than other_array:

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

• Returns 0 if array and other_array are the same size:

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

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

a0 = [:foo, 'bar', 2]
a1 = [:foo, 'bar', 2.0]
a1 == a0 # => true
[] == [] # => true

Otherwise, returns false.

This method is different from method Array#eql?, which compares elements using Object#eql?.

Returns elements from self; does not modify self.

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

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

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

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

If index is out of range, returns nil.

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

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

If start + length is greater than self.length, returns all elements from offset start to the end:

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

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

If length is negative, returns nil.

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

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

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

If range.end is negative, calculates the end index from the end:

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

If range.start is negative, calculates the start index from the end:

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

If range.start is larger than the array size, returns nil.

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

When a single Enumerator::ArithmeticSequence argument aseq is given, returns an Array of elements corresponding to the indexes produced by the sequence.

a = ['--', 'data1', '--', 'data2', '--', 'data3']
a[(1..).step(2)] # => ["data1", "data2", "data3"]

Unlike slicing with range, if the start or the end of the arithmetic sequence is larger than array size, throws RangeError.

a = ['--', 'data1', '--', 'data2', '--', 'data3']
a[(1..11).step(2)]
# RangeError (((1..11).step(2)) out of range)
a[(7..).step(2)]
# RangeError (((7..).step(2)) out of range)

If given a single argument, and its type is not one of the listed, tries to convert it to Integer, and raises if it is impossible:

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

Array#slice is an alias for Array#[].

Assigns elements in self; returns the given object.

When Integer argument index is given, assigns object to an element in self.

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

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

If index is greater than self.length, extends the array:

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

If index is negative, counts backwards from the end of the array:

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

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

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

If start is negative, counts backwards from the end of the array:

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

If start is non-negative and outside the array ( >= self.size), extends the array with nil, assigns object at offset start, and ignores length:

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

If length is zero, shifts elements at and following offset start and assigns object at offset start:

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

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

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

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

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

if range.begin is negative, counts backwards from the end of the array:

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

If the array length is less than range.begin, assigns object at offset range.begin, and ignores length:

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

If range.end is zero, shifts elements at and following offset start and assigns object at offset start:

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

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

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

If range.end is too large for the existing array, replaces array elements, but does not extend the array with nil values:

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

Calculates the set of unambiguous abbreviations for the strings in self.

require 'abbrev'
%w{ car cone }.abbrev
#=> {"car"=>"car", "ca"=>"car", "cone"=>"cone", "con"=>"cone", "co"=>"cone"}

The optional pattern parameter is a pattern or a string. Only input strings that match the pattern or start with the string are included in the output hash.

%w{ fast boat day }.abbrev(/^.a/)
#=> {"fast"=>"fast", "fas"=>"fast", "fa"=>"fast", "day"=>"day", "da"=>"day"}

Abbrev.abbrev(%w{car box cone}, "ca")
#=> {"car"=>"car", "ca"=>"car"}

See also Abbrev.abbrev

Returns true if all elements of self meet a given criterion.

With no block given and no argument, returns true if self contains only truthy elements, false otherwise:

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

With a block given and no argument, calls the block with each element in self; returns true if the block returns only truthy values, false otherwise:

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

If argument obj is given, returns true if obj.=== every element, 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

Related: Enumerable#all?

Returns true if any element of self meets a given criterion.

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

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

With a block given and no argument, calls the block with each element in self; 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

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

Related: Enumerable#any?

Returns the first element in self that is an Array whose first element == obj:

a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
a.assoc(4) # => [4, 5, 6]

Returns nil if no such element is found.

Related: rassoc.

Returns the element at Integer offset index; does not modify self.

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

Returns an element from self selected by a binary search. self should be sorted, but this is not checked.

By using binary search, finds a value from this array which meets the given condition in O(log n) where n is the size of the array.

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 and sometimes returning true or false and sometimes returning a numeric value, but this is not checked.

Find-Minimum Mode

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 <= self.size.

• The block returns true for self[i] and false for self[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 in find-minimum mode:

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]

Find-Any Mode

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 <= self.size.

• The block returns a negative value for self[i] and a positive value for self[j].

• The block returns a negative value for self[i] and zero self[j].

• The block returns zero for self[i] and a positive value for self[j].

In find-any mode, method bsearch returns some element for which the block returns zero, or nil if no such element is found.

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 in find-any mode:

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>

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

Removes all elements from self:

a = [:foo, 'bar', 2]
a.clear # => []

Calls the block, if given, with each element of self; returns a new Array whose elements are the return values from the block:

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

Returns a new Enumerator if no block given:

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

Array#collect is an alias for Array#map.

Calls the block, if given, with each element; replaces the element with the block’s return value:

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

Returns a new Enumerator if no block given:

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

Array#collect! is an alias for Array#map!.

Calls the block, if given, with combinations of elements of self; returns self. The order of combinations is indeterminate.

When a block and an in-range positive Integer argument n (0 < n <= self.size) are given, calls the block with all n-tuple combinations of self.

Example:

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

Output:

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

Another example:

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

Output:

[0, 1, 2]

When n is zero, calls the block once with a new empty Array:

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

Output:

[]

When n is out of range (negative or larger than self.size), does not call the block:

a = [0, 1, 2]
a.combination(-1) {|combination| fail 'Cannot happen' }
a.combination(4) {|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)>

Returns a new Array containing all non-nil elements from self:

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

Removes all nil elements from self.

Returns self if any elements removed, otherwise nil.

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

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

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

With no argument and a block given, calls the block with each element; returns the count of elements for which the block returns a truthy value:

[0, 1, 2, 3].count {|element| element > 1} # => 2

With argument obj and a block given, issues a warning, ignores the block, and returns the count of elements eql? to obj:

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

output = []
[0, 1].cycle(2) {|element| output.push(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, and argument is omitted or nil, cycles forever:

# Prints 0 and 1 forever.
[0, 1].cycle {|element| puts element }
[0, 1].cycle(nil) {|element| puts element }

When no block is given, returns a new Enumerator:

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

Removes zero or more elements from self; returns self.

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

s1 = 'bar'; s2 = 'bar'
a = [:foo, s1, 2, s2]
a.delete('bar') # => "bar"
a # => [:foo, 2]

Returns nil if no elements removed.

When a block is given, removes from self each element ele such that ele == obj.

If any such elements are found, ignores the block and returns the last deleted element:

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

If no such elements are found, returns the block’s return value:

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

Deletes an element from self, per the given Integer index.

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

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

If index is too large, returns nil.

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

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

If index is too small (far from zero), returns nil.

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

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

Returns a new Enumerator if no block given:

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

Returns a new Array containing only those elements from self that are not found in any of the Arrays other_arrays; items are compared using eql?; order from self is preserved:

[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 a copy of self if no arguments given.

Related: Array#-.

Finds and returns the object in nested objects that is specified by index and identifiers. The nested objects may be instances of various classes. See Dig Methods.

Examples:

a = [:foo, [:bar, :baz, [:bat, :bam]]]
a.dig(1) # => [:bar, :baz, [:bat, :bam]]
a.dig(1, 2) # => [:bat, :bam]
a.dig(1, 2, 0) # => :bat
a.dig(1, 2, 3) # => nil

Returns a new Array containing all but the first n element of self, where n is a non-negative Integer; does not modify self.

Examples:

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]

Returns a new Array containing zero or more trailing elements of self; does not modify self.

With a block given, calls the block with each successive element of self; stops if the block returns false 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]

With no block given, returns a new Enumerator:

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

Iterates over array elements.

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

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

Output:

Symbol foo
String bar
Integer 2

Allows the array to be modified during iteration:

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

Output:

foo
bar

When no block given, returns a new Enumerator:

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

Output:

Symbol foo
String bar
Integer 2

Related: each_index, reverse_each.