Array

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

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-

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

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

Creates a new empty Array.

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

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.

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

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

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]

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]

Append. Alias for #push.

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

Combined comparison operator. Returns 0 if self equals other, 1 if self is greater than other and -1 if self is smaller 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

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

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 starting index 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"]

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 starting index is out of range-

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

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]

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]

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

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]

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]

Removes all elements from self.

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

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

Returns a copy of self with all nil elements removed.

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

Removes all nil elements from self.

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

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

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

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

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

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

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

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

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

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

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-

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.

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

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.

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

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]

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]

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]

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]

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]

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

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

Returns the first n elements of the array.

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

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]

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

Returns the last n elements of the array.

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

Optimized version of Enumerable#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]

Optimized version of Enumerable#map_with_index.

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

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"

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

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

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

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

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]

Modifies self, deleting the elements in the collection for which the passed block returns true. Returns nil if no changes were made.

See also: Array#reject.

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

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

Reverses in-place all the elements of self.

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]

Modifies self, keeping only the elements in the collection for which the passed block returns true. Returns nil if no changes were made.

See also: Array#select.

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

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

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

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

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

Returns the number of elements in the array.

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

Returns an array with all elements in the collection sorted.

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

Optionally, a block may be given that must implement a comparison, either with the comparison operator #<=> or a comparison between a and b, where a < b yields -1, a == b yields 0, and a > b yields 1.

Modifies self by sorting the elements in the collection.

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

Optionally, a block may be given that must implement a comparison, either with the comparison operator #<=> or a comparison between a and b, where a < b yields -1, a == b yields 0, and a > b yields 1.

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

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

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

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

Removes duplicate elements from self. Returns self.

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

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

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

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

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.