Indexable::Mutable(T)

Sets the given value at the given index. Returns value.

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

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

ary[3] = 5 # raises IndexError

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

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

Raises IndexError if the start index is out of range.

Raises ArgumentError if count is negative.

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

Replaces the elements within the given range with value. Returns self.

Negative indices count backward from the end of the container.

Raises IndexError if the starting index is out of range.

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

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

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

Yields each index of self, starting at start and for count times (or less if there aren't enough elements), to the given block and then assigns the block's value in that position. Returns self.

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

Has no effect if count is zero or negative.

Raises IndexError if start is outside the array range.

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

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.

Negative indices count backward from the end of the container.

Raises IndexError if the starting index is out of range.

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

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

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

array = [2, 1, 1, 1]
array.fill { |i| i * i }            # => [0, 1, 4, 9]
array                               # => [0, 1, 4, 9]
array.fill(offset: 3) { |i| i * i } # => [9, 16, 25, 36]
array                               # => [9, 16, 25, 36]

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]

Like #map!, but the block gets passed both the element and its index.

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

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

Shifts all elements of self to the left n times. Returns self.

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]

Modifies self by randomizing the order of elements in the collection. Returns self.

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

Uses the random instance when provided if the randomness needs to be controlled or to follow some traits. For example the following shuffle will always result in the same order:

a = [1, 2, 3, 4, 5]
a.shuffle!(Random.new(42)) # => [3, 2, 4, 5, 1]
a.shuffle!(Random.new(42)) # => [3, 2, 4, 5, 1]
a                          # => [3, 2, 4, 5, 1]

Sorts all elements in self based on the return value of the comparison method T#<=> (see Comparable#<=>), using a stable sort algorithm.

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

This sort operation modifies self. See #sort for a non-modifying option that allocates a new instance.

See Slice#sort! for details on the implementation.

Raises ArgumentError if the comparison between any two elements returns nil.

Sorts all elements in self based on the comparator in the given block, using a stable sort algorithm.

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]
# This is a reverse sort (forward sort would be `a <=> b`)
a.sort! { |a, b| b <=> a }
a # => [3, 2, 1]

This sort operation modifies self. See #sort(&block : T, T -> U) for a non-modifying option that allocates a new instance.

See Slice#sort!(&block : T, T -> U) for details on the implementation.

Raises ArgumentError if for any two elements the block returns nil.

Sorts all elements in self by the output value of the block. The output values are compared via the comparison method #<=> (see Comparable#<=>), using a stable sort algorithm.

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

This sort operation modifies self. See #sort_by(&block : T -> _) for a non-modifying option that allocates a new instance.

If stability is expendable, #unstable_sort_by!(&block : T -> _) provides a performance advantage over stable sort.

See #sort!(&block : T -> _) for details on the sorting mechanism.

Raises ArgumentError if the comparison between any two comparison values returns nil.

Swaps the elements at index0 and index1. Returns self.

Negative indices can be used to start counting from the end of the container. Raises 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 IndexError

Sets the element at the given index to value, without doing any bounds check.

Indexable::Mutable 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 modify elements with #[]=(index, value).

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.

Sorts all elements in self based on the return value of the comparison method T#<=> (see Comparable#<=>), using an unstable sort algorithm.

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

This sort operation modifies self. See #unstable_sort for a non-modifying option that allocates a new instance.

See Slice#unstable_sort! for details on the implementation.

Raises ArgumentError if the comparison between any two elements returns nil.

Sorts all elements in self based on the comparator in the given block, using an unstable sort algorithm.

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]
# This is a reverse sort (forward sort would be `a <=> b`)
a.unstable_sort! { |a, b| b <=> a }
a # => [3, 2, 1]

This sort operation modifies self. See #unstable_sort(&block : T, T -> U) for a non-modifying option that allocates a new instance.

See Slice#unstable_sort!(&block : T, T -> U) for details on the implementation.

Raises ArgumentError if for any two elements the block returns nil.

Sorts all elements in self by the output value of the block. The output values are compared via the comparison method #<=> (see Comparable#<=>), using an unstable sort algorithm.

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

This sort operation modifies self. See #unstable_sort_by(&block : T -> _) for a non-modifying option that allocates a new instance.

If stability is necessary, use #sort_by!(&block : T -> _) instead.

See #unstable_sort!(&block : T -> _) for details on the sorting mechanism.

Raises ArgumentError if the comparison between any two comparison values returns nil.

Yields the current element at the given index and updates the value at that index with the block's value. Returns the new value.

Raises IndexError if trying to set an element outside the container's range.

array = [1, 2, 3]
array.update(1) { |x| x * 2 } # => 4
array                         # => [1, 4, 3]
array.update(5) { |x| x * 2 } # raises IndexError