Returns anArray of all ordered combinations of elements taken from each of theindexables asArrays. Traversal of elements starts from the lastIndexable. Ifindexables is empty, the returned product contains exactly one emptyArray.

#cartesian_product is preferred over this class method when the quantity ofindexables is known in advance.

Indexable.cartesian_product([[1, 2, 3], [4, 5]]) # => [[1, 4], [1, 5], [2, 4], [2, 5], [3, 4], [3, 5]]

Yields each ordered combination of the elements taken from each of the indexables asArrays. Traversal of elements starts from the lastIndexable. Ifindexables is empty, yields an emptyArray exactly once.

#each_cartesian is preferred over this class method when the quantity of indexables is known in advance.

Indexable.each_cartesian([%w[Alice Bob Carol], [1, 2]]) do |name, n|
  puts "#{n}. #{name}"
end

Prints

1. Alice
2. Alice
1. Bob
2. Bob
1. Carol
2. Carol

By default, a newArray is created and yielded for each combination.

• Ifreuse is anArray, it will be reused
• Ifreuse is truthy, the method will create a newArray and reuse it
• Ifreuse is falsey, noArrays will be reused.

This can be used to prevent many memory allocations when each combination of interest is to be used in a read-only fashion.

Returns an iterator that enumerates the ordered combinations of elements taken from theindexables asArrays. Traversal of elements starts from the lastIndexable. Ifindexables is empty, the returned iterator produces one emptyArray, then stops.

#each_cartesian is preferred over this class method when the quantity of indexables is known in advance.

iter = Indexable.each_cartesian([%w[N S], %w[E W]])
iter.next # => ["N", "E"]
iter.next # => ["N", "W"]
iter.next # => ["S", "E"]
iter.next # => ["S", "W"]
iter.next # => Iterator::Stop::INSTANCE

By default, a newArray is created and returned for each combination.

• Ifreuse is anArray, it will be reused
• Ifreuse is truthy, the method will create a newArray and reuse it
• Ifreuse is falsey, noArrays will be reused.

This can be used to prevent many memory allocations when each combination of interest is to be used in a read-only fashion.

Returns the element at the givenindex.

Negative indices can be used to start counting from the end of the array. RaisesIndexError if trying to access an element outside the array's range.

ary = ['a', 'b', 'c']
ary[0]  # => 'a'
ary[2]  # => 'c'
ary[-1] # => 'c'
ary[-2] # => 'b'

ary[3]  # raises IndexError
ary[-4] # raises IndexError

Returns the element at the givenindex.

Negative indices can be used to start counting from the end of the array. Returnsnil if trying to access an element outside the array's range.

ary = ['a', 'b', 'c']
ary[0]?  # => 'a'
ary[2]?  # => 'c'
ary[-1]? # => 'c'
ary[-2]? # => 'b'

ary[3]?  # => nil
ary[-4]? # => nil

By using binary search, returns the first element for which the passed block returns a truthy value.

If the block returns a falsey value, the element to be found lies behind. If the block returns a truthy value, the element to be found is itself or lies in front.

Binary search needs the collection to be sorted in regards to the search criterion.

Returnsnil if the block didn't return a truthy value for any element.

[2, 5, 7, 10].bsearch { |x| x >= 4 } # => 5
[2, 5, 7, 10].bsearch { |x| x > 10 } # => nil

By using binary search, returns the index of the first element for which the passed block returns a truthy value.

If the block returns a falsey value, the element to be found lies behind. If the block returns a truthy value, the element to be found is itself or lies in front.

Binary search needs the collection to be sorted in regards to the search criterion.

Returnsnil if the block didn't return a truthy value for any element.

[2, 5, 7, 10].bsearch_index { |x, i| x >= 4 } # => 1
[2, 5, 7, 10].bsearch_index { |x, i| x > 10 } # => nil

Returns anArray of all ordered combinations of elements taken from each ofself andothers asTuples. Traversal of elements starts from the lastIndexable argument.

[1, 2, 3].cartesian_product({'a', 'b'})                     # => [{1, 'a'}, {1, 'b'}, {2, 'a'}, {2, 'b'}, {3, 'a'}, {3, 'b'}]
['a', 'b'].cartesian_product({1, 2}, {'c', 'd'}).map &.join # => ["a1c", "a1d", "a2c", "a2d", "b1c", "b1d", "b2c", "b2d"]

Returns anArray with all possible combinations ofsize ofself.

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

Traverses the depth of a structure and returns the value, otherwise raisesIndexError.

ary = [{1, 2, 3, {4, 5, 6}}]
ary.dig(0, 3, 2) # => 6
ary.dig(0, 3, 3) # raises IndexError

Traverses the depth of a structure and returns the value. Returnsnil if not found.

ary = [{1, 2, 3, {4, 5, 6}}]
ary.dig?(0, 3, 2) # => 6
ary.dig?(0, 3, 3) # => nil

Calls the given block once for each element inself, passing that element as a parameter.

a = ["a", "b", "c"]
a.each { |x| print x, " -- " }

produces:

a -- b -- c --

Returns anIterator for the elements ofself.

a = ["a", "b", "c"]
iter = a.each
iter.next # => "a"
iter.next # => "b"

The returned iterator keeps a reference toself: if the array changes, the returned values of the iterator change as well.

Calls the given block once forcount number of elements inself starting from indexstart, passing each element as a parameter.

Negative indices count backward from the end of the array. (-1 is the last element).

RaisesIndexError if the starting index is out of range. RaisesArgumentError ifcount is a negative number.

array = ["a", "b", "c", "d", "e"]
array.each(start: 1, count: 3) { |x| print x, " -- " }

produces:

b -- c -- d --

Calls the given block once for all elements at indices within the given range, passing each element as a parameter.

RaisesIndexError if the starting index is out of range.

array = ["a", "b", "c", "d", "e"]
array.each(within: 1..3) { |x| print x, " -- " }

produces:

b -- c -- d --

Yields each ordered combination of the elements taken from each ofself andothers as aTuple. Traversal of elements starts from the lastIndexable argument.

["Alice", "Bob"].each_cartesian({1, 2, 3}) do |name, n|
  puts "#{n}. #{name}"
end

Prints

1. Alice
2. Alice
3. Alice
1. Bob
2. Bob
3. Bob

Returns an iterator that enumerates the ordered combinations of elements taken from each ofself andothers asTuples. Traversal of elements starts from the lastIndexable argument.

iter = {1, 2, 3}.each_cartesian({'a', 'b'})
iter.next # => {1, 'a'}
iter.next # => {1, 'b'}
iter.next # => {2, 'a'}
iter.next # => {2, 'b'}
iter.next # => {3, 'a'}
iter.next # => {3, 'b'}
iter.next # => Iterator::Stop::INSTANCE

Yields each possible combination ofsize ofself.

a = [1, 2, 3]
sums = [] of Int32
a.each_combination(2) { |p| sums << p.sum } # => nil
sums                                        # => [3, 4, 5]

By default, a new array is created and yielded for each combination. Ifreuse is given, the array can be reused: ifreuse is anArray, this array will be reused; ifreuse if truthy, the method will create a new array and reuse it. This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion.

Returns anIterator over each possible combination ofsize ofself.

iter = [1, 2, 3, 4].each_combination(3)
iter.next # => [1, 2, 3]
iter.next # => [1, 2, 4]
iter.next # => [1, 3, 4]
iter.next # => [2, 3, 4]
iter.next # => #<Iterator::Stop>

By default, a new array is created and returned for each combination. Ifreuse is given, the array can be reused: ifreuse is anArray, this array will be reused; ifreuse if truthy, the method will create a new array and reuse it. This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion.

Calls the given block once for each index inself, passing that index as a parameter.

a = ["a", "b", "c"]
a.each_index { |x| print x, " -- " }

produces:

0 -- 1 -- 2 --

Returns anIterator for each index inself.

a = ["a", "b", "c"]
iter = a.each_index
iter.next # => 0
iter.next # => 1

The returned iterator keeps a reference toself. If the array changes, the returned values of the iterator will change as well.

Calls the given block once forcount number of indices inself starting from indexstart, passing each index as a parameter.

Negative indices count backward from the end of the array. (-1 is the last element).

RaisesIndexError if the starting index is out of range. RaisesArgumentError ifcount is a negative number.

array = ["a", "b", "c", "d", "e"]
array.each_index(start: -3, count: 2) { |x| print x, " -- " }

produces:

2 -- 3 --

Yields each possible permutation ofsize ofself.

a = [1, 2, 3]
sums = [] of Int32
a.each_permutation(2) { |p| sums << p.sum } # => nil
sums                                        # => [3, 4, 3, 5, 4, 5]

By default, a new array is created and yielded for each permutation. Ifreuse is given, the array can be reused: ifreuse is anArray, this array will be reused; ifreuse if truthy, the method will create a new array and reuse it. This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion.

Returns anIterator over each possible permutation ofsize ofself.

iter = [1, 2, 3].each_permutation
iter.next # => [1, 2, 3]
iter.next # => [1, 3, 2]
iter.next # => [2, 1, 3]
iter.next # => [2, 3, 1]
iter.next # => [3, 1, 2]
iter.next # => [3, 2, 1]
iter.next # => #<Iterator::Stop>

By default, a new array is created and returned for each permutation. Ifreuse is given, the array can be reused: ifreuse is anArray, this array will be reused; ifreuse if truthy, the method will create a new array and reuse it. This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion.

Yields each possible combination with repeated elements ofsize of self.

a = [1, 2, 3]
sums = [] of Int32
a.each_repeated_combination(2) { |p| sums << p.sum } # => nil
sums                                                 # => [2, 3, 4, 4, 5, 6]

By default, a new array is created and yielded for each combination. Ifreuse is given, the array can be reused: ifreuse is anArray, this array will be reused; ifreuse if truthy, the method will create a new array and reuse it. This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion.

Returns anIterator over each possible combination with repeated elements ofsize ofself.

iter = [1, 2, 3].each_repeated_combination(2)
iter.next # => [1, 1]
iter.next # => [1, 2]
iter.next # => [1, 3]
iter.next # => [2, 2]
iter.next # => [2, 3]
iter.next # => [3, 3]
iter.next # => #<Iterator::Stop>

By default, a new array is created and returned for each combination. Ifreuse is given, the array can be reused: ifreuse is anArray, this array will be reused; ifreuse if truthy, the method will create a new array and reuse it. This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion.

Returnstrue ifself is empty,false otherwise.

([] of Int32).empty? # => true
([1]).empty?         # => false

Optimized version of#equals? used whenother is also anIndexable.

Determines ifself equalsother according to a comparison done by the given block.

Ifself's size is the same asother's size, this method yields elements fromself andother in tandem: if the block returns true for all of them, this method returnstrue. Otherwise it returnsfalse.

a = [1, 2, 3]
b = ["a", "ab", "abc"]
a.equals?(b) { |x, y| x == y.size } # => true
a.equals?(b) { |x, y| x == y }      # => false

Returns the element at the givenindex, if in bounds, otherwise executes the given block with the index and returns its value.

a = [:foo, :bar]
a.fetch(0) { :default_value }    # => :foo
a.fetch(2) { :default_value }    # => :default_value
a.fetch(2) { |index| index * 3 } # => 6

Returns the value at the index given byindex, or when not found the value given bydefault.

a = [:foo, :bar]
a.fetch(0, :default_value) # => :foo
a.fetch(2, :default_value) # => :default_value

Returns the first element in the indexable for which the passed block is truthy, starting from the givenoffset.

Accepts an optional parameterif_none, to set what gets returned if no element is found (defaults tonil).

[1, 2, 3, 4].find { |i| i > 2 }        # => 3
[1, 2, 3, 4].find(-1) { |i| i > 8 }    # => -1
[1, 2, 3, 4].find(-1, 2) { |i| i < 2 } # => -1

Returns the first element in the indexable for which the passed block is truthy, starting from the givenoffset.

Accepts an optional parameterif_none, to set what gets returned if no element is found (defaults tonil).

[1, 2, 3, 4].find { |i| i > 2 }        # => 3
[1, 2, 3, 4].find(-1) { |i| i > 8 }    # => -1
[1, 2, 3, 4].find(-1, 2) { |i| i < 2 } # => -1

Returns the first element in the indexable for which the passed block is truthy, starting from the givenoffset. RaisesEnumerable::NotFoundError if there is no element for which the block is truthy.

[1, 2, 3, 4].find! { |i| i > 2 }     # => 3
[1, 2, 3, 4].find!(3) { |i| i > 2 }  # => 4
[1, 2, 3, 4].find! { |i| i > 8 }     # => raises Enumerable::NotFoundError
[1, 2, 3, 4].find!(-5) { |i| i > 2 } # => raises Enumerable::NotFoundError

Returns the first element in the collection, If the collection is empty, calls the block and returns its value.

([1, 2, 3]).first { 4 }   # => 1
([] of Int32).first { 4 } # => 4

SeeObject#hash(hasher)

Returns the index of the first appearance ofobject inself starting from the givenoffset, ornil ifobject is not inself.

[1, 2, 3, 1, 2, 3].index(2, offset: 2) # => 4

Returns the index of the first object inself for which the block is truthy, starting from the givenoffset, ornil if no match is found.

[1, 2, 3, 1, 2, 3].index(offset: 2) { |x| x < 2 } # => 3

Returns the index of the first appearance ofobj inself starting from the givenoffset. RaisesEnumerable::NotFoundError if obj is not inself.

[1, 2, 3, 1, 2, 3].index!(2, offset: 2) # => 4

Returns the index of the first object inself for which the block is truthy, starting from the givenoffset. Raises Enumerable::NotFoundError if no match is found.

[1, 2, 3, 1, 2, 3].index!(offset: 2) { |x| x < 2 } # => 3

Optimized version ofEnumerable#join that performs better when all of the elements in this indexable are strings: the total string bytesize to return can be computed before creating the final string, which performs better because there's no need to do reallocations.

Returns the last element ofself if it's not empty, or raisesIndexError.

([1, 2, 3]).last   # => 3
([] of Int32).last # raises IndexError

Returns the last element ofself if it's not empty, or the given block's value.

([1, 2, 3]).last { 4 }   # => 3
([] of Int32).last { 4 } # => 4

Returns the last element ofself if it's not empty, ornil.

([1, 2, 3]).last?   # => 3
([] of Int32).last? # => nil

Returns anArray with all possible permutations ofsize ofself.

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

Returns anArray with all possible combinations with repeated elements of size ofself.

a = [1, 2, 3]

pp a.repeated_combinations
pp a.repeated_combinations(2)

produces:

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

Same as#each, but works in reverse.

Returns anIterator over the elements ofself in reverse order.

Returns the index of the last appearance ofvalue inself, or nil if the value is not inself.

Ifoffset is given, it defines the position toend the search (elements beyond this point are ignored).

[1, 2, 3, 2, 3].rindex(2)            # => 3
[1, 2, 3, 2, 3].rindex(2, offset: 2) # => 1

Returns the index of the first object inself for which the block is truthy, starting from the last object, ornil if no match is found.

Ifoffset is given, the search starts from that index towards the first elements inself.

[1, 2, 3, 2, 3].rindex { |x| x < 3 }            # => 3
[1, 2, 3, 2, 3].rindex(offset: 2) { |x| x < 3 } # => 1

Returns the index of the last appearance ofvalue inself, or nil if the value is not inself.

Ifoffset is given, it defines the position toend the search (elements beyond this point are ignored).

[1, 2, 3, 2, 3].rindex(2)            # => 3
[1, 2, 3, 2, 3].rindex(2, offset: 2) # => 1

RaisesEnumerable::NotFoundError ifvalue is not inself.

Returns the index of the first object inself for which the block is truthy, starting from the last object, ornil if no match is found.

Ifoffset is given, the search starts from that index towards the first elements inself.

[1, 2, 3, 2, 3].rindex { |x| x < 3 }            # => 3
[1, 2, 3, 2, 3].rindex(offset: 2) { |x| x < 3 } # => 1

RaisesEnumerable::NotFoundError if no match is found.

Returns anArray ofn random elements fromself. All elements have equal probability of being drawn. Sampling is done without replacement; if n is larger than the size of this collection, the returnedArray has the same size asself.

RaisesArgumentError ifn is negative.

[1, 2, 3, 4, 5].sample(2) # => [3, 5]
{1, 2, 3, 4, 5}.sample(2) # => [3, 4]

Uses therandom instance when provided if the randomness needs to be controlled or to follow some traits. For example the following calls use a custom seed or a secure random source:

{1, 2, 3, 4, 5}.sample(2, Random.new(1))  # => [1, 5]
{1, 2, 3, 4, 5}.sample(2, Random::Secure) # => [2, 5]

Ifself is not empty andn is equal to 1, calls#sample(random) exactly once. Thus,random will be left in a different state compared to the implementation inEnumerable.

Optimized version ofEnumerable#sample that runs in O(1) time.

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

Uses therandom instance when provided if the randomness needs to be controlled or to follow some traits. For example the following sample will always return the same value:

a = [1, 2, 3]
a.sample(Random.new(1)) # => 2
a.sample(Random.new(1)) # => 2

Returns the number of elements in this container.

Returns anArray with the results of runningblock against each element of the collection.

{1, 2, 3}.to_a { |i| i * 2 } # => [2, 4, 6]

Returns the element at the givenindex, without doing any bounds check.

Indexable makes sure to invoke this method withindex in0...size, so converting negative indices to positive ones is not needed here.

Clients never invoke this method directly. Instead, they access elements with#[](index) and#[]?(index).

This method should only be directly invoked if you are absolutely sure the index is in bounds, to avoid a bounds check for a small boost of performance.

Returns aTuple populated with the elements at the given indexes. RaisesIndexError if any index is invalid.

["a", "b", "c", "d"].values_at(0, 2) # => {"a", "c"}