class Array(T)
inherits Reference

An Array is an ordered, integer-indexed collection of objects of type T.

Array indexing starts at 0. A negative index is assumed to be relative to the end of the array: -1 indicates the last element, -2 is the next to last element, and so on.

An Array can be created using the usual new method (several are provided), or with an array literal:

Array(Int32).new  # => []
[1, 2, 3]         # Array(Int32)
[1, "hello", 'x'] # Array(Int32 | String | Char)

An Array can have mixed types, meaning T will be a union of types, but these are determined when the array is created, either by specifying T or by using an array literal. In the latter case, T will be set to the union of the array literal elements' types.

When creating an empty array you must always specify T:

[] of Int32 # same as Array(Int32)
[]          # syntax error

An Array is implemented using an internal buffer of some capacity and is reallocated when elements are pushed to it when more capacity is needed. This is normally known as a dynamic array.

You can use a special array literal syntax with other types too, as long as they define an argless new method and a << method. Set is one such type:

set = Set{1, 2, 3} # => Set{1, 2, 3}
set.class          # => Set(Int32)

The above is the same as this:

set = Set(typeof(1, 2, 3)).new
set << 1
set << 2
set << 3

Included modules

Comparable Indexable

Class methods

.each_product(arrays : Array(Array), reuse = false

View source

.each_product(*arrays : Array, reuse = false

View source

.from_json(string_or_io, &) : Nil

Parses a String or IO denoting a JSON array, yielding each of its elements to the given block. This is useful for decoding an array and processing its elements without creating an Array in memory, which might be expensive.

require "json"

Array(Int32).from_json("[1, 2, 3]") do |element|
  puts element
end

Output:

1
2
3

To parse and get an Array, use the block-less overload.

View source

.from_yaml(string_or_io : String | IO

View source

.product(arrays)

View source

.product(*arrays : Array)

View source

.additive_identity : self

Returns the additive identity of this type.

This is an empty array.

View source

.build(capacity : Int, &) : self

Creates a new Array, allocating an internal buffer with the given capacity, and yielding that buffer. The given block must return the desired size of the array.

This method is unsafe, but is usually used to initialize the buffer by passing it to a C function.

Array.build(3) do |buffer|
  LibSome.fill_buffer_and_return_number_of_elements_filled(buffer)
end

View source

.new(size : Int, value : T)

Creates a new Array of the given size filled with the same value in each position.

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

ary = Array.new(3, [1])
ary # => [[1], [1], [1]]
ary[0][0] = 2
ary # => [[2], [2], [2]]

View source

.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)

View source

.new(initial_capacity : Int)

Creates a new empty Array backed by a buffer that is initially initial_capacity big.

The initial_capacity is useful to avoid unnecessary reallocations of the internal buffer in case of growth. If you have an estimate of the maximum number of elements an array will hold, the array should be initialized with that capacity for improved performance.

ary = Array(Int32).new(5)
ary.size # => 0

View source

.new(pull : JSON::PullParser)

View source

.new

Creates a new empty Array.

View source

.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node

View source

.new(size : Int, &block : Int32 -> T)

Creates a new Array of the given size and invokes the given block once for each index of self, assigning the block's value in that index.

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

ary = Array.new(3) { [1] }
ary # => [[1], [1], [1]]
ary[0][0] = 2
ary # => [[2], [1], [1]]

View source

.new(pull : JSON::PullParser

View source

Methods

#&(other : Array(U)) forall U

Set intersection: returns a new Array containing elements common to self and other, excluding any duplicates. The order is preserved from self.

[1, 1, 3, 5] & [1, 2, 3]               # => [ 1, 3 ]
['a', 'b', 'b', 'z'] & ['a', 'b', 'c'] # => [ 'a', 'b' ]

See also: #uniq.

View source

#*(times : Int)

Repetition: Returns a new Array built by concatenating times copies of self.

["a", "b", "c"] * 2 # => [ "a", "b", "c", "a", "b", "c" ]

View source

#+(other : Array(U)) forall U

Concatenation. Returns a new Array built by concatenating self and other. The type of the new array is the union of the types of both the original arrays.

[1, 2] + ["a"]  # => [1,2,"a"] of (Int32 | String)
[1, 2] + [2, 3] # => [1,2,2,3]

View source

#-(other : Array(U)) forall U

Difference. Returns a new Array that is a copy of self, removing any items that appear in other. The order of self is preserved.

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

View source

#<<(value : T)

Append. Alias for push.

a = [1, 2]
a << 3 # => [1,2,3]

View source

#<=>(other : Array)

Combined comparison operator.

Returns -1, 0 or 1 depending on whether self is less than other, equals other or is greater than other.

It compares the elements of both arrays in the same position using the <=> operator. As soon as one of such comparisons returns a non-zero value, that result is the return value of the comparison.

If all elements are equal, the comparison is based on the size of the arrays.

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

View source

#==(other : Array)

Equality. Returns true if each element in self is equal to each corresponding element in other.

ary = [1, 2, 3]
ary == [1, 2, 3] # => true
ary == [2, 3]    # => false

View source

#==(other : JSON::Any)

View source

#==(other : YAML::Any)

View source

#[](start : Int, count : Int)

Returns count or less (if there aren't enough) elements starting at the given start index.

Negative indices count backward from the end of the array (-1 is the last element). Additionally, an empty array is returned when the starting index for an element range is at the end of the array.

Raises IndexError if the start index is out of range.

Raises ArgumentError if count is negative.

a = ["a", "b", "c", "d", "e"]
a[-3, 3] # => ["c", "d", "e"]
a[1, 2]  # => ["b", "c"]
a[5, 1]  # => []
a[6, 1]  # raises IndexError

View source

#[](range : Range)

Returns all elements that are within the given range.

Negative indices count backward from the end of the array (-1 is the last element). Additionally, an empty array is returned when the starting index for an element range is at the end of the array.

Raises IndexError if the range's start is out of range.

a = ["a", "b", "c", "d", "e"]
a[1..3]    # => ["b", "c", "d"]
a[4..7]    # => ["e"]
a[6..10]   # raise IndexError
a[5..10]   # => []
a[-2...-1] # => ["d"]
a[2..]     # => ["c", "d", "e"]

View source

#[]=(index : Int, count : Int, values : Array(T))

Replaces a subrange with the elements of the given array.

a = [1, 2, 3, 4, 5]
a[1, 3] = [6, 7, 8]
a # => [1, 6, 7, 8, 5]

a = [1, 2, 3, 4, 5]
a[1, 3] = [6, 7]
a # => [1, 6, 7, 5]

a = [1, 2, 3, 4, 5]
a[1, 3] = [6, 7, 8, 9, 10]
a # => [1, 6, 7, 8, 9, 10, 5]

View source

#[]=(index : Int, count : Int, value : T)

Replaces a subrange with a single value. All elements in the range index...index+count are removed and replaced by a single element value.

If count is zero, value is inserted at index.

Negative values of index count from the end of the array.

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

a = [1, 2, 3, 4, 5]
a[1, 0] = 6
a # => [1, 6, 2, 3, 4, 5]

View source

#[]=(index : Int, value : T)

Sets the given value at the given index.

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

ary = [1, 2, 3]
ary[0] = 5
p ary # => [5,2,3]

ary[3] = 5 # raises IndexError

View source

#[]=(range : Range, values : Array(T))

Replaces a subrange with the elements of the given array.

a = [1, 2, 3, 4, 5]
a[1..3] = [6, 7, 8]
a # => [1, 6, 7, 8, 5]

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

a = [1, 2, 3, 4, 5]
a[1..3] = [6, 7, 8, 9, 10]
a # => [1, 6, 7, 8, 9, 10, 5]

a = [1, 2, 3, 4, 5]
a[2..] = [6, 7, 8, 9, 10]
a # => [1, 2, 6, 7, 8, 9, 10]

View source

#[]=(range : Range, value : T)

Replaces a subrange with a single value.

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

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

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

View source

#[]?(range : Range)

Like #[Range], but returns nil if the range's start is out of range.

a = ["a", "b", "c", "d", "e"]
a[6..10]? # => nil
a[6..]?   # => nil

View source

#[]?(start : Int, count : Int)

Like #[Int, Int] but returns nil if the start index is out of range.

View source

#clear

Removes all elements from self.

a = ["a", "b", "c", "d", "e"]
a.clear # => []

View source

#clone

Returns a new Array that has self's elements cloned. That is, it returns a deep copy of self.

Use #dup if you want a shallow copy.

ary = [[1, 2], [3, 4]]
ary2 = ary.clone
ary[0][0] = 5
ary  # => [[5, 2], [3, 4]]
ary2 # => [[1, 2], [3, 4]]

ary2 << [7, 8]
ary  # => [[5, 2], [3, 4]]
ary2 # => [[1, 2], [3, 4], [7, 8]]

View source

#compact

Returns a copy of self with all nil elements removed.

["a", nil, "b", nil, "c", nil].compact # => ["a", "b", "c"]

View source

#compact!

Removes all nil elements from self and returns self.

ary = ["a", nil, "b", nil, "c"]
ary.compact!
ary # => ["a", "b", "c"]

View source

#concat(other : Array)

Appends the elements of other to self, and returns self.

ary = ["a", "b"]
ary.concat(["c", "d"])
ary # => ["a", "b", "c", "d"]

View source

#concat(other : Enumerable)

Appends the elements of other to self, and returns self.

ary = ["a", "b"]
ary.concat(["c", "d"])
ary # => ["a", "b", "c", "d"]

View source

#delete(obj)

Removes all items from self that are equal to obj.

Returns the last found element that was equal to obj, if any, or nil if not found.

a = ["a", "b", "b", "b", "c"]
a.delete("b") # => "b"
a             # => ["a", "c"]

a.delete("x") # => nil
a             # => ["a", "c"]

View source

#delete_at(index : Int, count : Int)

Removes count elements from self starting at index. If the size of self is less than count, removes values to the end of the array without error. Returns an array of the removed elements with the original order of self preserved. Raises IndexError if index is out of range.

a = ["ant", "bat", "cat", "dog"]
a.delete_at(1, 2)  # => ["bat", "cat"]
a                  # => ["ant", "dog"]
a.delete_at(99, 1) # raises IndexError

View source

#delete_at(index : Int)

Removes the element at index, returning that element. Raises IndexError if index is out of range.

a = ["ant", "bat", "cat", "dog"]
a.delete_at(2)  # => "cat"
a               # => ["ant", "bat", "dog"]
a.delete_at(99) # raises IndexError

View source

#delete_at(range : Range)

Removes all elements within the given range. Returns an array of the removed elements with the original order of self preserved. Raises IndexError if the index is out of range.

a = ["ant", "bat", "cat", "dog"]
a.delete_at(1..2)    # => ["bat", "cat"]
a                    # => ["ant", "dog"]
a.delete_at(99..100) # raises IndexError

View source

#dup

Returns a new Array that has exactly self's elements. That is, it returns a shallow copy of self.

Use #clone if you want a deep copy.

ary = [[1, 2], [3, 4]]
ary2 = ary.dup
ary[0][0] = 5
ary  # => [[5, 2], [3, 4]]
ary2 # => [[5, 2], [3, 4]]

ary2 << [7, 8]
ary  # => [[5, 2], [3, 4]]
ary2 # => [[5, 2], [3, 4], [7, 8]]

View source

#each_repeated_permutation(size : Int = self.size, reuse = false, &) : Nil

View source

#fill(value : T)

Replaces every element in self with the given value. Returns self.

a = [1, 2, 3]
a.fill(9) # => [9, 9, 9]

View source

#fill(value : T, range : Range)

Replaces every element in range with value. Returns self.

Negative values of from count from the end of the array.

a = [1, 2, 3, 4, 5]
a.fill(9, 2..3) # => [1, 2, 9, 9, 5]

View source

#fill(value : T, from : Int)

Replaces every element in self, starting at from, with the given value. Returns self.

Negative values of from count from the end of the array.

a = [1, 2, 3, 4, 5]
a.fill(9, 2) # => [1, 2, 9, 9, 9]

View source

#fill

Yields each index of self to the given block and then assigns the block's value in that position. Returns self.

a = [1, 2, 3, 4]
a.fill { |i| i * i } # => [0, 1, 4, 9]

View source

#fill(range : Range

Yields each index of self, in the given range, to the given block and then assigns the block's value in that position. Returns self.

a = [1, 2, 3, 4, 5, 6]
a.fill(2..3) { |i| i * i } # => [1, 2, 4, 9, 5, 6]

View source

#fill(from : Int

Yields each index of self, starting at from, to the given block and then assigns the block's value in that position. Returns self.

Negative values of from count from the end of the array.

Raises IndexError if from is outside the array range.

a = [1, 2, 3, 4]
a.fill(2) { |i| i * i } # => [1, 2, 4, 9]

View source

#fill(from : Int, count : Int

Yields each index of self, starting at from and just count times, to the given block and then assigns the block's value in that position. Returns self.

Negative values of from count from the end of the array.

Raises IndexError if from is outside the array range.

Has no effect if count is zero or negative.

a = [1, 2, 3, 4, 5, 6]
a.fill(2, 2) { |i| i * i } # => [1, 2, 4, 9, 5, 6]

View source

#fill(value : T, from : Int, count : Int)

Replaces every element in self, starting at from and only count times, with the given value. Returns self.

Negative values of from count from the end of the array.

a = [1, 2, 3, 4, 5]
a.fill(9, 2, 2) # => [1, 2, 9, 9, 5]

View source

#first(n : Int)

Returns the first n elements of the array.

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

View source

#flatten

Returns a new Array that is a one-dimensional flattening of self (recursively).

That is, for every element that is an array or an iterator, extract its elements into the new array.

s = [1, 2, 3]          # => [1, 2, 3]
t = [4, 5, 6, [7, 8]]  # => [4, 5, 6, [7, 8]]
u = [9, [10, 11].each] # => [9, #<Indexable::ItemIterator>]
a = [s, t, u, 12, 13]  # => [[1, 2, 3], [4, 5, 6, [7, 8]], 9, #<Indexable::ItemIterator>, 12, 13]
a.flatten              # => [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]

View source

#insert(index : Int, object : T)

Insert object before the element at index and shifting successive elements, if any. Returns self.

Negative values of index count from the end of the array.

a = ["a", "b", "c"]
a.insert(0, "x")  # => ["x", "a", "b", "c"]
a.insert(2, "y")  # => ["x", "a", "y", "b", "c"]
a.insert(-1, "z") # => ["x", "a", "y", "b", "c", "z"]

View source

#last(n : Int)

Returns the last n elements of the array.

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

View source

#map(&block : T -> U) forall U

Optimized version of Enumerable#map.

View source

#map!

Invokes the given block for each element of self, replacing the element with the value returned by the block. Returns self.

a = [1, 2, 3]
a.map! { |x| x * x }
a # => [1, 4, 9]

View source

#map_with_index(offset = 0, &block : T, Int32 -> U) forall U

Optimized version of Enumerable#map_with_index.

Accepts an optional offset parameter, which tells it to start counting from there.

gems = ["crystal", "pearl", "diamond"]
results = gems.map_with_index { |gem, i| "#{i}: #{gem}" }
results # => ["0: crystal", "1: pearl", "2: diamond"]

View source

#map_with_index!(offset = 0, &block : T, Int32 -> T)

Like map_with_index, but mutates self instead of allocating a new object.

Accepts an optional offset parameter, which tells it to start counting from there.

gems = ["crystal", "pearl", "diamond"]
gems.map_with_index! { |gem, i| "#{i}: #{gem}" }
gems # => ["0: crystal", "1: pearl", "2: diamond"]

View source

#pop

Removes the last value from self. If the array is empty, the given block is called.

a = [1]
a.pop { "Testing" } # => 1
a.pop { "Testing" } # => "Testing"

See also: #truncate.

View source

#pop

Removes the last value from self, at index size - 1. This method returns the removed value. Raises IndexError if array is of 0 size.

a = ["a", "b", "c"]
a.pop # => "c"
a     # => ["a", "b"]

See also: #truncate.

View source

#pop(n : Int)

Removes the last n values from self, at index size - 1. This method returns an array of the removed values, with the original order preserved.

If n is greater than the size of self, all values will be removed from self without raising an error.

a = ["a", "b", "c"]
a.pop(2) # => ["b", "c"]
a        # => ["a"]

a = ["a", "b", "c"]
a.pop(4) # => ["a", "b", "c"]
a        # => []

See also: #truncate.

View source

#pop?

Like pop, but returns nil if self is empty.

See also: #truncate.

View source

#pretty_print(pp) : Nil

View source

#product(ary : Array(U)) forall U

View source

#product(enumerable : Enumerable

View source

#push(*values : T)

Append multiple values. The same as push, but takes an arbitrary number of values to push into self. Returns self.

a = ["a"]
a.push("b", "c") # => ["a", "b", "c"]

View source

#push(value : T)

Append. Pushes one value to the end of self, given that the type of the value is T (which might be a single type or a union of types). This method returns self, so several calls can be chained. See pop for the opposite effect.

a = ["a", "b"]
a.push("c") # => ["a", "b", "c"]
a.push(1)   # Errors, because the array only accepts String.

a = ["a", "b"] of (Int32 | String)
a.push("c") # => ["a", "b", "c"]
a.push(1)   # => ["a", "b", "c", 1]

View source

#reject!(pattern)

Modifies self, deleting the elements in the collection for which pattern === element.

ary = [1, 6, 2, 4, 8]
ary.reject!(3..7)
ary # => [1, 2, 8]

See also: Array#select!.

View source

#reject!

Modifies self, deleting the elements in the collection for which the passed block returns true. Returns self.

ary = [1, 6, 2, 4, 8]
ary.reject! { |x| x > 3 }
ary # => [1, 2]

See also: Array#reject.

View source

#remaining_capacity

View source

#repeated_permutations(size : Int = self.size)

View source

#replace(other : Array)

View source

#reverse

Returns an array with all the elements in the collection reversed.

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

View source

#reverse!

Reverses in-place all the elements of self.

View source

#rotate(n = 1)

Returns an array with all the elements shifted n times.

a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
a.rotate    # => [1, 2, 3, 4, 5, 6, 7, 8, 9, 0]
a.rotate(1) # => [1, 2, 3, 4, 5, 6, 7, 8, 9, 0]
a.rotate(3) # => [3, 4, 5, 6, 7, 8, 9, 0, 1, 2]
a           # => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

View source

#rotate!(n = 1)

Returns self with all the elements shifted n times.

a1 = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
a2 = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
a3 = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

a1.rotate!
a2.rotate!(1)
a3.rotate!(3)

a1 # => [1, 2, 3, 4, 5, 6, 7, 8, 9, 0]
a2 # => [1, 2, 3, 4, 5, 6, 7, 8, 9, 0]
a3 # => [3, 4, 5, 6, 7, 8, 9, 0, 1, 2]

View source

#select!(pattern)

Modifies self, keeping only the elements in the collection for which pattern === element.

ary = [1, 6, 2, 4, 8]
ary.select!(3..7)
ary # => [6, 4]

See also: Array#reject!.

View source

#select!

Modifies self, keeping only the elements in the collection for which the passed block returns true. Returns self.

ary = [1, 6, 2, 4, 8]
ary.select! { |x| x > 3 }
ary # => [6, 4, 8]

See also: Array#select.

View source

#shift

Removes the first value of self, at index 0. This method returns the removed value. If the array is empty, it raises IndexError.

a = ["a", "b", "c"]
a.shift # => "a"
a       # => ["b", "c"]

See also: #truncate.

View source

#shift

Removes the first value of self, at index 0, or otherwise invokes the given block. This method returns the removed value. If the array is empty, it invokes the given block and returns its value.

a = ["a"]
a.shift { "empty!" } # => "a"
a                    # => []
a.shift { "empty!" } # => "empty!"
a                    # => []

See also: #truncate.

View source

#shift(n : Int)

Removes the first n values of self, starting at index 0. This method returns an array of the removed values.

If n is greater than the size of self, all values will be removed from self without raising an error.

a = ["a", "b", "c"]
a.shift # => "a"
a       # => ["b", "c"]

a = ["a", "b", "c"]
a.shift(4) # => ["a", "b", "c"]
a          # => []

See also: #truncate.

View source

#shift?

Removes the first value of self, at index 0. This method returns the removed value. If the array is empty, it returns nil without raising any error.

a = ["a", "b"]
a.shift? # => "a"
a        # => ["b"]
a.shift? # => "b"
a        # => []
a.shift? # => nil
a        # => []

See also: #truncate.

View source

#shuffle(random = Random::DEFAULT)

Returns an array with all the elements in the collection randomized using the given random number generator.

View source

#shuffle!(random = Random::DEFAULT)

Modifies self by randomizing the order of elements in the collection using the given random number generator. Returns self.

View source

#size : Int32

Returns the number of elements in the array.

[:foo, :bar].size # => 2

View source

#skip(count : Int) : Array(T)

Returns an Array with the first count elements removed from the original array.

If count is bigger than the number of elements in the array, returns an empty array.

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

View source

#sort : Array(T)

Returns a new array with all elements sorted based on the return value of their comparison method #<=>

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

View source

#sort(&block : T, T -> U) : Array(T) forall U

Returns a new array with all elements sorted based on the comparator in the given block.

The block must implement a comparison between two elements a and b, where a < b returns -1, a == b returns 0, and a > b returns 1. The comparison operator <=> can be used for this.

a = [3, 1, 2]
b = a.sort { |a, b| b <=> a }

b # => [3, 2, 1]
a # => [3, 1, 2]

View source

#sort! : Array(T)

Modifies self by sorting all elements based on the return value of their comparison method #<=>

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

View source

#sort!(&block : T, T -> U) : Array(T) forall U

Modifies self by sorting all elements based on the comparator in the given block.

The given block must implement a comparison between two elements a and b, where a < b returns -1, a == b returns 0, and a > b returns 1. The comparison operator <=> can be used for this.

a = [3, 1, 2]
a.sort! { |a, b| b <=> a }
a # => [3, 2, 1]

View source

#sort_by(&block : T -> _) : Array(T)

Returns a new array with all elements sorted. The given block is called for each element, then the comparison method #<=> is called on the object returned from the block to determine sort order.

a = %w(apple pear fig)
b = a.sort_by { |word| word.size }
b # => ["fig", "pear", "apple"]
a # => ["apple", "pear", "fig"]

View source

#sort_by!(&block : T -> _) : Array(T)

Modifies self by sorting all elements. The given block is called for each element, then the comparison method #<=> is called on the object returned from the block to determine sort order.

a = %w(apple pear fig)
a.sort_by! { |word| word.size }
a # => ["fig", "pear", "apple"]

View source

#swap(index0, index1) : Array(T)

Swaps the elements at index0 and index1 and returns self. Raises an IndexError if either index is out of bounds.

a = ["first", "second", "third"]
a.swap(1, 2)  # => ["first", "third", "second"]
a             # => ["first", "third", "second"]
a.swap(0, -1) # => ["second", "third", "first"]
a             # => ["second", "third", "first"]
a.swap(2, 3)  # => raises "Index out of bounds (IndexError)"

View source

#to_a

Returns an Array with all the elements in the collection.

{1, 2, 3}.to_a # => [1, 2, 3]

View source

#to_json(json : JSON::Builder)

View source

#to_s(io : IO) : Nil

Appends a short String representation of this object which includes its class name and its object address.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>

View source

#to_unsafe : Pointer(T)

Returns a pointer to the internal buffer where self's elements are stored.

This method is unsafe because it returns a pointer, and the pointed might eventually not be that of self if the array grows and its internal buffer is reallocated.

ary = [1, 2, 3]
ary.to_unsafe[0] # => 1

View source

#to_yaml(yaml : YAML::Nodes::Builder)

View source

#transpose

Assumes that self is an array of arrays and transposes the rows and columns.

a = [[:a, :b], [:c, :d], [:e, :f]]
a.transpose # => [[:a, :c, :e], [:b, :d, :f]]
a           # => [[:a, :b], [:c, :d], [:e, :f]]

View source

#truncate(start : Int, count : Int) : self

Removes all elements except the count or less (if there aren't enough) elements starting at the given start index. Returns self.

Negative values of start count from the end of the array.

Raises IndexError if the start index is out of range.

Raises ArgumentError if count is negative.

a = [0, 1, 4, 9, 16, 25]
a.truncate(2, 3) # => [4, 9, 16]
a                # => [4, 9, 16]

See also: #pop, #shift.

View source

#truncate(range : Range) : self

Removes all elements except those within the given range. Returns self.

a = [0, 1, 4, 9, 16, 25]
a.truncate(1..-3) # => [1, 4, 9]
a                 # => [1, 4, 9]

View source

#uniq

Returns a new Array by removing duplicate values in self.

a = ["a", "a", "b", "b", "c"]
a.uniq # => ["a", "b", "c"]
a      # => [ "a", "a", "b", "b", "c" ]

View source

#uniq(&block : T -> _)

Returns a new Array by removing duplicate values in self, using the block's value for comparison.

a = [{"student", "sam"}, {"student", "george"}, {"teacher", "matz"}]
a.uniq { |s| s[0] } # => [{"student", "sam"}, {"teacher", "matz"}]
a                   # => [{"student", "sam"}, {"student", "george"}, {"teacher", "matz"}]

View source

#uniq!

Removes duplicate elements from self. Returns self.

a = ["a", "a", "b", "b", "c"]
a.uniq! # => ["a", "b", "c"]
a       # => ["a", "b", "c"]

View source

#uniq!

Removes duplicate elements from self, using the block's value for comparison. Returns self.

a = [{"student", "sam"}, {"student", "george"}, {"teacher", "matz"}]
a.uniq! { |s| s[0] } # => [{"student", "sam"}, {"teacher", "matz"}]
a                    # => [{"student", "sam"}, {"teacher", "matz"}]

View source

#unsafe_fetch(index : Int)

Returns the element at the given index, without doing any bounds check.

Indexable makes sure to invoke this method with index in 0...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.

View source

#unshift(object : T)

Prepend. Adds object to the beginning of self, given that the type of the value is T (which might be a single type or a union of types). This method returns self, so several calls can be chained. See shift for the opposite effect.

a = ["a", "b"]
a.unshift("c") # => ["c", "a", "b"]
a.unshift(1)   # Errors, because the array only accepts String.

a = ["a", "b"] of (Int32 | String)
a.unshift("c") # => ["c", "a", "b"]
a.unshift(1)   # => [1, "c", "a", "b"]

View source

#unshift(*values : T)

Prepend multiple values. The same as unshift, but takes an arbitrary number of values to add to the array. Returns self.

View source

#update(index : Int

View source

#|(other : Array(U)) forall U

Set union: returns a new Array by joining self with other, excluding any duplicates, and preserving the order from self.

["a", "b", "c"] | ["c", "d", "a"] # => [ "a", "b", "c", "d" ]

See also: #uniq.

View source