Array(T) - Crystal 0.35.1

# class Array(T)

- Array(T)
- Reference
- Object

##
Overview

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(Array(T))
- Indexable(T)

##
Defined in:

##
Constructors

- .build(capacity : Int, &) : self

  Creates a new `Array`, allocating an internal buffer with the given capacity, and yielding that buffer.

- .new(size : Int, value : T)

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

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

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

- .new(pull : JSON::PullParser)
- .new

  Creates a new empty `Array`.

- .new(ctx : YAML::ParseContext, node : YAML::Nodes::Node, &)
- .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.

- .new(pull : JSON::PullParser, &)

##
Class Method Summary

- .each_product(arrays : Array(Array), reuse = false, &)
- .each_product(*arrays : Array, reuse = false, &)
- .from_json(string_or_io, &) : Nil

  Parses a `String` or `IO` denoting a JSON array, yielding each of its elements to the given block.

- .from_yaml(string_or_io : String | IO, &)
- .product(arrays)
- .product(*arrays : Array)

##
Instance Method Summary

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

  Set intersection: returns a new `Array` containing elements common to `self` and other, excluding any duplicates.

- #*(times : Int)

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

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

  Concatenation.

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

  Difference.

- #<<(value : T)

  Append.

- #<=>(other : Array)

  Combined comparison operator.

- #==(other : Array)

  Equality.

- #==(other : JSON::Any)
- #==(other : YAML::Any)
- #[](start : Int, count : Int)

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

- #[](range : Range)

  Returns all elements that are within the given range.

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

  Replaces a subrange with a single value.

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

  Replaces a subrange with the elements of the given array.

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

  Sets the given value at the given index.

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

  Replaces a subrange with a single value.

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

  Replaces a subrange with the elements of the given array.

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

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

- #[]?(range : Range)

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

- #clear

  Removes all elements from self.

- #clone

  Returns a new `Array` that has `self`'s elements cloned.

- #combinations(size : Int = self.size)
- #compact

  Returns a copy of `self` with all `nil` elements removed.

- #compact!

  Removes all `nil` elements from `self` and returns `self`.

- #concat(other : Array)

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

- #concat(other : Enumerable)

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

- #delete(obj)

  Removes all items from `self` that are equal to obj.

- #delete_at(index : Int, count : Int)

  Removes count elements from `self` starting at index.

- #delete_at(index : Int)

  Removes the element at index, returning that element.

- #delete_at(range : Range)

  Removes all elements within the given range.

- #dup

  Returns a new `Array` that has exactly `self`'s elements.

- #each_combination(size : Int = self.size, reuse = false, &) : Nil
- #each_combination(size : Int = self.size, reuse = false)
- #each_permutation(size : Int = self.size, reuse = false)

  Returns an `Iterator` over each possible permutation of size of `self`.

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

  Yields each possible permutation of size of `self`.

- #each_repeated_combination(size : Int = self.size, reuse = false, &) : Nil
- #each_repeated_combination(size : Int = self.size, reuse = false)
- #each_repeated_permutation(size : Int = self.size, reuse = false, &) : Nil
- #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.

- #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.

- #fill(&)

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

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

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

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

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

- #fill(value : T, range : Range)

  Replaces every element in range with value.

- #fill(value : T)

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

- #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.

- #first(n : Int)

  Returns the first n elements of the array.

- #flatten

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

- #insert(index : Int, object : T)

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

- #last(n : Int)

  Returns the last n elements of the array.

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

  Optimized version of `Enumerable#map`.

- #map!(&)

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

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

  Optimized version of `Enumerable#map_with_index`.

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

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

- #permutations(size : Int = self.size)

  Returns an `Array` with all possible permutations of size.

- #pop

  Removes the last value from `self`, at index size - 1.

- #pop(&)

  Removes the last value from `self`.

- #pop(n : Int)

  Removes the last n values from `self`, at index size - 1.

- #pop?

  Like `#pop`, but returns `nil` if `self` is empty.

- #pretty_print(pp) : Nil
- #product(ary : Array(U)) forall U
- #product(enumerable : Enumerable, &)
- #push(value : T)

  Append.

- #push(*values : T)

  Append multiple values.

- #reject!(&)

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

- #reject!(pattern)

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

- #repeated_combinations(size : Int = self.size)
- #repeated_permutations(size : Int = self.size)
- #replace(other : Array)
- #reverse

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

- #reverse!

  Reverses in-place all the elements of `self`.

- #rotate(n = 1)
- #rotate!(n = 1)
- #sample(n : Int, random = Random::DEFAULT)

  Returns n number of random elements from `self`, using the given random number generator.

- #select!(pattern)

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

- #select!(&)

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

- #shift

  Removes the first value of `self`, at index 0.

- #shift(n : Int)

  Removes the first n values of `self`, starting at index 0.

- #shift(&)
- #shift?

  Removes the first value of `self`, at index 0.

- #shuffle(random = Random::DEFAULT)

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

- #shuffle!(random = Random::DEFAULT)

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

- #size : Int32

  Returns the number of elements in the array.

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

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

- #sort : Array(T)

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

- #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.

- #sort! : Array(T)

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

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

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

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

  Returns a new array with all elements sorted.

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

  Modifies `self` by sorting all elements.

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

  Swaps the elements at index0 and index1 and returns `self`.

- #to_a

  Returns an `Array` with all the elements in the collection.

- #to_json(json : JSON::Builder)
- #to_s(io : IO) : Nil

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

- #to_unsafe : Pointer(T)

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

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

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

- #uniq

  Returns a new `Array` by removing duplicate values in `self`.

- #uniq(&block : T -> _)

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

- #uniq!

  Removes duplicate elements from `self`.

- #uniq!(&)

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

- #unsafe_fetch(index : Int)

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

- #unshift(obj : T)

  Prepend.

- #unshift(*values : T)

  Prepend multiple values.

- #update(index : Int, &)
- #|(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`.

### Instance methods inherited from module `Comparable(Array(T))`

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Indexable(T)`

[](index : Int) [], []?(index : Int) []?, bsearch(&block : T -> Bool) bsearch, bsearch_index(&block : T, Int32 -> Bool) bsearch_index, dig(index : Int, *subindexes) dig, dig?(index : Int, *subindexes) dig?, each
each(*, within range : Range, &)
each(&)
each(*, start : Int, count : Int, &) each, each_index(*, start : Int, count : Int, &)
each_index(&) : Nil
each_index each_index, empty? empty?, equals?(other : Indexable, &)
equals?(other, &) equals?, fetch(index, default)
fetch(index : Int, &) fetch, first(&) first, hash(hasher) hash, index(object, offset : Int = 0)
index(offset : Int = 0, &) index, join(separator = "") join, last
last(&) last, last? last?, reverse_each(&) : Nil
reverse_each reverse_each, rindex(value, offset = size - 1)
rindex(offset = size - 1, &) rindex, sample(random = Random::DEFAULT) sample, size size, to_a to_a, unsafe_fetch(index : Int) unsafe_fetch, values_at(*indexes : Int) values_at

### Instance methods inherited from module `Enumerable(T)`

all?(&)
all?(pattern)
all? all?, any?(&)
any?(pattern)
any? any?, chunks(&block : T -> U) forall U chunks, compact_map(&) compact_map, count(&)
count(item) count, cycle(&)
cycle(n, &) cycle, each(&block : T -> _) each, each_cons(count : Int, reuse = false, &) each_cons, each_cons_pair(& : T, T -> _) : Nil each_cons_pair, each_slice(count : Int, reuse = false, &) each_slice, each_with_index(offset = 0, &) each_with_index, each_with_object(obj, &) each_with_object, empty? empty?, find(if_none = nil, &) find, first(&)
first(count : Int)
first first, first? first?, flat_map(&block : T -> Array(U) | Iterator(U) | U) forall U flat_map, grep(pattern) grep, group_by(&block : T -> U) forall U group_by, in_groups_of(size : Int, filled_up_with : U = nil) forall U
in_groups_of(size : Int, filled_up_with : U = nil, reuse = false, &) forall U in_groups_of, includes?(obj) includes?, index(&)
index(obj) index, index_by(&block : T -> U) forall U index_by, join(separator = "", & : T -> )
join(separator, io : IO, &)
join(io : IO, separator = "", & : T, IO -> )
join(separator = "")
join(separator, io : IO)
join(io : IO, separator = "") join, map(&block : T -> U) forall U map, map_with_index(offset = 0, &block : T, Int32 -> U) forall U map_with_index, max max, max? max?, max_by(&block : T -> U) forall U max_by, max_by?(&block : T -> U) forall U max_by?, max_of(&block : T -> U) forall U max_of, max_of?(&block : T -> U) forall U max_of?, min min, min? min?, min_by(&block : T -> U) forall U min_by, min_by?(&block : T -> U) forall U min_by?, min_of(&block : T -> U) forall U min_of, min_of?(&block : T -> U) forall U min_of?, minmax minmax, minmax? minmax?, minmax_by(&block : T -> U) forall U minmax_by, minmax_by?(&block : T -> U) forall U minmax_by?, minmax_of(&block : T -> U) forall U minmax_of, minmax_of?(&block : T -> U) forall U minmax_of?, none?
none?(pattern)
none?(&) none?, one?(&)
one?(pattern)
one? one?, partition(&) partition, product
product(initial : Number)
product(initial : Number, &)
product(&) product, reduce(memo, &)
reduce(&) reduce, reduce?(&) reduce?, reject(pattern)
reject(type : U.class) forall U
reject(&block : T -> ) reject, select(pattern)
select(type : U.class) forall U
select(&block : T -> ) select, size size, skip(count : Int) skip, skip_while(&) skip_while, sum(initial)
sum
sum(initial, &)
sum(&) sum, take_while(&) take_while, tally : Hash(T, Int32) tally, to_a to_a, to_h
to_h(&block : T -> Tuple(K, V)) forall K, V to_h, to_set to_set, zip(*others : Indexable | Iterable | Iterator, &)
zip(*others : Indexable | Iterable | Iterator) zip, zip?(*others : Indexable | Iterable | Iterator, &)
zip?(*others : Indexable | Iterable | Iterator) zip?

### Instance methods inherited from module `Iterable(T)`

chunk(reuse = false, &block : T -> U) forall U chunk, chunk_while(reuse : Bool | Array(T) = false, &block : T, T -> B) forall B chunk_while, cycle(n)
cycle cycle, each each, each_cons(count : Int, reuse = false) each_cons, each_slice(count : Int, reuse = false) each_slice, each_with_index(offset = 0) each_with_index, each_with_object(obj) each_with_object, slice_after(reuse : Bool | Array(T) = false, &block : T -> B) forall B
slice_after(pattern, reuse : Bool | Array(T) = false) slice_after, slice_before(reuse : Bool | Array(T) = false, &block : T -> B) forall B
slice_before(pattern, reuse : Bool | Array(T) = false) slice_before, slice_when(reuse : Bool | Array(T) = false, &block : T, T -> B) forall B slice_when

### Instance methods inherited from class `Reference`

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

### Constructor methods inherited from class `Reference`

new new

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(*values : Object) : Bool
in?(collection) : Bool in?, inspect : String
inspect(io : IO) : Nil inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO)
to_json to_json, to_pretty_json(io : IO, indent : String = " ")
to_pretty_json(indent : String = " ") to_pretty_json, to_s : String
to_s(io : IO) : Nil to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

##
Constructor Detail

def self.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

def self.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]]

def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node) #
def self.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

def self.new(pull : JSON::PullParser) #
def self.new #

Creates a new empty `Array`.

def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node, &) #
def self.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]]

def self.new(pull : JSON::PullParser, &) #

##
Class Method Detail

def self.each_product(arrays : Array(Array), reuse = false, &) #
def self.each_product(*arrays : Array, reuse = false, &) #
def self.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.

def self.from_yaml(string_or_io : String | IO, &) #
def self.product(arrays) #
def self.product(*arrays : Array) #

##
Instance Method Detail

def &(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`.

def *(times : Int) #

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

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

def +(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]

def -(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]

def <<(value : T) #

Append. Alias for `#push`.

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

def <=>(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

def ==(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

def ==(other : JSON::Any) #
def ==(other : YAML::Any) #
def [](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

def [](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"]

def []=(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]

def []=(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]

def []=(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

def []=(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]

def []=(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]

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

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

def []?(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

def clear #

Removes all elements from self.

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

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

def combinations(size : Int = self.size) #
def compact #

Returns a copy of `self` with all `nil` elements removed.

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

def compact! #

Removes all `nil` elements from `self` and returns `self`.

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

def 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"]

def 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"]

def 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"]

def 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

def 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

def 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

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

def each_combination(size : Int = self.size, reuse = false, &) : Nil #
def each_combination(size : Int = self.size, reuse = false) #
def each_permutation(size : Int = self.size, reuse = false) #

Returns an `Iterator` over each possible permutation of size of `self`.

    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. If reuse is given, the array can be reused: if reuse is an `Array`, this array will be reused; if reuse 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.

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

Yields each possible permutation of size of `self`.

    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. If reuse is given, the array can be reused: if reuse is an `Array`, this array will be reused; if reuse 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.

def each_repeated_combination(size : Int = self.size, reuse = false, &) : Nil #
def each_repeated_combination(size : Int = self.size, reuse = false) #
def each_repeated_permutation(size : Int = self.size, reuse = false, &) : Nil #
def 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]

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

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

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

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

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

def fill(value : T) #

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

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

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

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

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

def 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"]

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

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

Optimized version of `Enumerable#map`.

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

def 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.

def 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.

def permutations(size : Int = self.size) #

Returns an `Array` with all possible permutations of size.

    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) # => []

def 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"]

def 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"

def 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        # => []

def pop? #

Like `#pop`, but returns `nil` if `self` is empty.

def pretty_print(pp) : Nil #
def product(ary : Array(U)) forall U #
def product(enumerable : Enumerable, &) #
def 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]

def 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"]

def 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`.

def 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!`.

def repeated_combinations(size : Int = self.size) #
def repeated_permutations(size : Int = self.size) #
def replace(other : Array) #
def reverse #

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

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

def reverse! #

Reverses in-place all the elements of `self`.

def rotate(n = 1) #
def rotate!(n = 1) #
def sample(n : Int, random = Random::DEFAULT) #

Returns n number of random elements from `self`, using the given random number generator. Raises IndexError if `self` is empty.

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

def 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!`.

def 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`.

def 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"]

def 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          # => []

def shift(&) #
def 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        # => []

def shuffle(random = Random::DEFAULT) #

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

def shuffle!(random = Random::DEFAULT) #

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

def size : Int32 #

Returns the number of elements in the array.

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

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

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

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

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

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

def 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"]

def 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"]

def 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)"

def to_a #
Description copied from module Indexable(T)

Returns an `Array` with all the elements in the collection.

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

def to_json(json : JSON::Builder) #
def to_s(io : IO) : Nil #
Description copied from class Reference

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>

def 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

def to_yaml(yaml : YAML::Nodes::Builder) #
def 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]]

def 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" ]

def 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"}]

def uniq! #

Removes duplicate elements from `self`. Returns `self`.

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

def 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"}]

def unsafe_fetch(index : Int) #
Description copied from module Indexable(T)

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.

def unshift(obj : T) #

Prepend. Adds obj 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"]

def unshift(*values : T) #

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

def update(index : Int, &) #
def |(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`.