class Array[out T]

include Enumerable[T]

An ordered, immutable sequence of Ts: [1, 2, 3], %w[a b], Array[Int].new.

Methods that "change" an array, #push, #pop, #set, #delete and the others, return a new one and leave the receiver as it was. An update assigned back to the same variable, xs = xs.push(v), happens in place without copying when nothing else refers to the array, so a loop that builds an array this way is linear. Array::Builder is the mutable array, and Array.build fills one and hands over the result.

An index counts from 0; a negative index counts from the end, -1 being the last element. xs[i] raises IndexError out of range, while xs[i]? and #at return nil, and #fetch a default. #pop and #shift return the array without its last or first element, not the element: read it with #last or #first.

xs = [1, 2, 3]
ys = xs.push(4)
xs        # => [1, 2, 3]
ys        # => [1, 2, 3, 4]
xs[-1]    # => 3
xs[5]?    # => nil
xs[5]     # raises IndexError
xs.pop    # => [1, 2]

<prelude>:3814

Classes and modules

Class methods

def self.new -> Array[T]

An empty array: Array[Int].new.

<prelude>:3819

def self.new(size: Int, &: (Int) -> T) -> Array[T]

An array of size elements, the block's result for each index from 0. Empty when size is 0 or negative.

Array.new(4) { |i| i * i }   # => [0, 1, 4, 9]

<prelude>:3826

def self.build(&: (Array::Builder[T]) -> Void) -> Array[T]

The array a block fills: the block receives an Array::Builder, whose contents become the result without copying.

Array.build { |b| 3.times { |i| b << i * 2 } }   # => [0, 2, 4]

<prelude>:3833

Methods

def each(&: (T) -> Void) -> Void

Calls the block with each element in order.

<prelude>:3836

def each_index(&: (Int) -> Void) -> Void

Calls the block with each index, from 0.

<prelude>:3838

def reverse_each(&: (T) -> Void) -> Void

Calls the block with each element, last first.

<prelude>:3840

def [](index: Int) -> T

The element at index; a negative index counts from the end.

Raises

IndexError when index is out of range (not in -size...size): use #[]? or #fetch to get nil or a default instead.

xs = [10, 20, 30]
xs[0]    # => 10
xs[-1]   # => 30
xs[3]    # raises IndexError

<prelude>:3854

def [](range: Range[Int]) -> Array[T]

The elements in range. A negative bound counts from the end, an end past the last element is cut there, and a range that ends before it starts gives []; endless and beginless ranges reach the end and the start.

Raises

IndexError when the start is past the end of the array (a start of exactly size gives []), or is negative and before its first element.

xs = [10, 20, 30]
xs[1..]      # => [20, 30]
xs[0...-1]   # => [10, 20]
xs[1..10]    # => [20, 30]
xs[3..]      # => []
xs[4..]      # raises IndexError

<prelude>:3874

def []?(index: Int) -> T?

The element at index, or nil when it is out of range; a negative index counts from the end.

[10, 20][-1]?   # => 20
[10, 20][2]?    # => nil

<prelude>:3882

def at(index: Int) -> T?

The element at index, or nil when it is out of range: #[]?.

<prelude>:3884

def fetch[U >: T](index: Int, default: U) -> U

The element at index, or default when it is out of range; a negative index counts from the end.

[10, 20].fetch(5, 0)   # => 0

<prelude>:3891

def first -> T?

The first element, or nil when the array is empty.

<prelude>:3893

def first? -> T?

The first element, or nil when the array is empty: #first.

<prelude>:3895

def first(n: Int) -> Array[T]

The first n elements, or all of them when there are fewer; [] when n is 0.

Raises

ArgumentError for a negative n.

<prelude>:3902

def last -> T?

The last element, or nil when the array is empty.

<prelude>:3904

def last? -> T?

The last element, or nil when the array is empty: #last.

<prelude>:3906

def last(n: Int) -> Array[T]

The last n elements, or all of them when there are fewer; [] when n is 0.

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

Raises

ArgumentError for a negative n.

<prelude>:3917

def size -> Int

The number of elements.

<prelude>:3919

def length -> Int

The number of elements: #size.

<prelude>:3921

def empty? -> Bool

Whether the array has no element.

<prelude>:3923

def push[U >: T](value: U) -> Array[U]

The array with value appended. The element type widens to take value's ([1].push("a") is an Array[Int | String]).

xs = xs.push(v) appends in place when nothing else refers to xs; otherwise the elements are copied once and xs's other holders keep the old array.

xs = [1, 2]
xs.push(3)   # => [1, 2, 3]
xs           # => [1, 2]

<prelude>:3936

def pop -> Array[T]

The array without its last element ([] for an empty array). Unlike Ruby's, it returns the array, not the element: read that with #last first.

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

<prelude>:3944

def shift -> Array[T]

The array without its first element ([] for an empty array), not the element: read that with #first first.

<prelude>:3947

def unshift[U >: T](value: U) -> Array[U]

The array with value in front.

<prelude>:3949

def insert[U >: T](index: Int, value: U) -> Array[U]

The array with value inserted before the element at index. index may be size (appends); a negative index counts from the end and inserts after that element, so -1 appends.

Raises

IndexError when index is not in -(size + 1)..size.

[1, 2].insert(1, 9)    # => [1, 9, 2]
[1, 2].insert(-1, 9)   # => [1, 2, 9]
[1, 2].insert(3, 9)    # raises IndexError

<prelude>:3963

def set[U >: T](index: Int, value: U) -> Array[U]

The array with the element at index replaced by value: the immutable []=. A negative index counts from the end.

Raises

IndexError when index is out of range: set does not extend the array.

[1, 2, 3].set(-1, 0)   # => [1, 2, 0]
[1, 2, 3].set(3, 0)    # raises IndexError

<prelude>:3976

def delete(value: Object) -> Array[T]

The array without the elements == to value (all of them); the same elements when there is none.

<prelude>:3979

def delete_at(index: Int) -> Array[T]

The array without the element at index (negative counts from the end); the same elements when index is out of range.

<prelude>:3982

def concat[U >: T](other: Array[U]) -> Array[U]

The array followed by other's elements.

<prelude>:3984

def +[U >: T](other: Array[U]) -> Array[U]

The array followed by other's elements: #concat.

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

<prelude>:3990

def -(other: Array[Object]) -> Array[T]

The elements that are not == to an element of other, in order (duplicates included).

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

<prelude>:3997

def *(count: Int) -> Array[T]

The elements repeated count times; [] when count is 0 or negative.

[1, 2] * 2   # => [1, 2, 1, 2]

<prelude>:4004

def &(other: Array[Object]) -> Array[T]

The elements also in other, without duplicates, in the receiver's order.

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

<prelude>:4011

def |[U >: T](other: Array[U]) -> Array[U]

The elements of both arrays without duplicates: the receiver's first, then other's new ones.

[1, 2] | [2, 3]   # => [1, 2, 3]

<prelude>:4018

def reverse -> Array[T]

The elements in reverse order.

<prelude>:4020

def rotate(count: Int = …) -> Array[T]

The elements rotated left by count: the element at count comes first. A negative count rotates right, and count may exceed the size.

[1, 2, 3].rotate       # => [2, 3, 1]
[1, 2, 3].rotate(-1)   # => [3, 1, 2]

<prelude>:4028

def index(value: Object) -> Int?

The index of the first element == to value, or nil.

<prelude>:4030

def rindex(value: Object) -> Int?

The index of the last element == to value, or nil.

<prelude>:4032

def include?(value: Object) -> Bool

Whether an element is == to value.

<prelude>:4034

def join(separator: String = …) -> String

The elements' to_s joined with separator between them. A nil element gives an empty string, and a nested array its inspect (Ruby joins nested arrays recursively).

[1, 2, 3].join("-")      # => "1-2-3"
[1, nil, "a"].join(",")  # => "1,,a"

<prelude>:4043

def sample -> T?

A random element, or nil when the array is empty.

<prelude>:4045

def shuffle -> Array[T]

The elements in a random order.

<prelude>:4047

def flatten -> Array[Object]

The elements with nested arrays replaced by their elements, at every depth.

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

<prelude>:4054

def compact -> Array[T]

The elements that are not nil.

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

<prelude>:4060

def to_a -> Array[T]

The array itself.

<prelude>:4062

def to_s -> String

The elements' inspect in brackets: #inspect.

<prelude>:4064

def inspect -> String

The elements' inspect in brackets.

["a", 1].inspect   # => "[\"a\", 1]"

<prelude>:4070

def ==(other: Object) -> Bool

Whether other is an array of the same size whose elements are == to these, position by position ([1] == [1.0] holds).

<prelude>:4073

def hash -> Int

A hash code: arrays that are == have the same one.

<prelude>:4075

def map[U](&: (T) -> U) -> Array[U]

The block's results for each element, in order.

<prelude>:4077

def select(&: (T) -> Object) -> Array[T]

The elements for which the block is truthy, in order.

<prelude>:4079

def each -> Enumerator[T]

An enumerator over the elements.

e = [1, 2].each
e.next   # => 1

<prelude>:4086

def fetch[U >: T](index: Int, &: (Int) -> U) -> U

The element at index, or the block's result for index when it is out of range; a negative index counts from the end.

[10, 20].fetch(5) { |i| i * 100 }   # => 500

<prelude>:4093

def slice(start: Int, length: Int) -> Array[T]

The length elements from start (fewer at the end); a negative start counts from the end. [] when start is out of range or length is negative.

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

<prelude>:4102

def take(n: Int) -> Array[T]

The first n elements, or all of them when there are fewer.

Raises

ArgumentError when n is negative.

<prelude>:4108

def drop(n: Int) -> Array[T]

The elements after the first n; [] when there are no more than n.

Raises

ArgumentError when n is negative.

<prelude>:4114

def values_at(*indices: Int) -> Array[T?]

The elements at indices, in their order; nil for an index out of range. Negative indices count from the end.

[10, 20, 30].values_at(0, -1, 5)   # => [10, 30, nil]

<prelude>:4121

def index(&: (T) -> Object) -> Int?

The index of the first element for which the block is truthy, or nil.

<prelude>:4123

def rindex(&: (T) -> Object) -> Int?

The index of the last element for which the block is truthy, or nil.

<prelude>:4125

def push[U >: T](*values: U) -> Array[U]

The array with values appended, in order.

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

<prelude>:4131

def fill[U >: T](value: U) -> Array[U]

The array with every element replaced by value.

<prelude>:4133

def fill[U >: T](value: U, start: Int, length: Int) -> Array[U]

The array with the length elements from start replaced by value; a negative start counts from the end. The array grows when start + length passes its end, and a start equal to the size appends. IndexError when start is past the end (where Ruby fills the gap with nil).

[1, 2, 3].fill(0, 1, 1)   # => [1, 0, 3]
[1, 2].fill(0, 1, 3)      # => [1, 0, 0, 0]
[1, 2].fill(0, 2, 2)      # => [1, 2, 0, 0]
[1, 2].fill(0, 3, 1)      # raises IndexError

<prelude>:4146

def flatten(depth: Int) -> Array[Object]

The elements with nested arrays replaced by their elements, depth levels deep; every level when depth is negative.

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

<prelude>:4153

def sample(n: Int) -> Array[T]

n elements at distinct random positions, or all of them shuffled when there are fewer; [] when n is 0.

Raises

ArgumentError for a negative n.

<prelude>:4160

def *(separator: String) -> String

The elements joined with separator: #join.

[1, 2] * ", "   # => "1, 2"

<prelude>:4166

def product[U](other: Array[U]) -> Array[[T, U]]

Every pair of an element and an element of other, the receiver's order outermost.

[1, 2].product(["a", "b"])
# => [[1, "a"], [1, "b"], [2, "a"], [2, "b"]]

<prelude>:4174

def combination(n: Int) -> Array[Array[T]]

Every combination of n elements, in the order of their positions: [[]] when n is 0, [] when n exceeds the size.

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

<prelude>:4181

def permutation(n: Int) -> Array[Array[T]]

Every ordered arrangement of n elements: [[]] when n is 0, [] when n exceeds the size.

<prelude>:4184

def permutation -> Array[Array[T]]

Every ordering of all the elements.

[1, 2].permutation   # => [[1, 2], [2, 1]]

<prelude>:4190

def bsearch(&: (T) -> Bool) -> T?

Binary search over a sorted array: the block is false for a prefix and true from some element on; that element is returned.

nil when the block is false for every element; the array must be sorted for the block's answers to make sense.

[1, 3, 5, 7].bsearch { |x| x >= 4 }   # => 5
[1, 3, 5, 7].bsearch { |x| x >= 9 }   # => nil

<prelude>:4201

def delete_if(&: (T) -> Object) -> Array[T]

The elements for which the block is falsy: #reject.

<prelude>:4203

def keep_if(&: (T) -> Object) -> Array[T]

The elements for which the block is truthy: #select.

<prelude>:4205

def union[U >: T](other: Array[U]) -> Array[U]

The elements of both arrays without duplicates: #|.

<prelude>:4207

def intersection(other: Array[Object]) -> Array[T]

The elements also in other, without duplicates: #&.

<prelude>:4209

def difference(other: Array[Object]) -> Array[T]

The elements not in other: #-.

<prelude>:4211

def intersect?(other: Array[Object]) -> Bool

Whether the arrays have an element in common.

[1, 2].intersect?([2, 3])   # => true

<prelude>:4217

def <=>(other: Array[T]) -> Int

Compares element by element: the first pair that differs decides, and when one array is a prefix of the other, the shorter is smaller.

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

<prelude>:4425