class Array::Builder[T]

include Enumerable[T]

A mutable array: Ruby's destructive Array API, for building an array step by step. Its methods change it in place and most return the builder itself, so calls chain (b << 1 << 2).

#to_a (or #freeze) hands the contents over as an immutable Array without copying and leaves the builder empty, ready to be filled again; #snapshot copies them and leaves the builder as it was. A builder is not Shareable: it stays in the task that made it. Array.build is the usual way to use one.

Indices follow Array's: a negative one counts from the end, b[i] raises IndexError out of range and b[i]? returns nil. #pop, #shift and #delete_at return the element removed, or nil.

b = Array::Builder[Int].new
b << 3 << 1 << 2
b.sort!
b.pop       # => 3
b[-1]       # => 2
xs = b.to_a
xs          # => [1, 2]
b.empty?    # => true

<prelude>:4243

Class methods

def self.new -> Array::Builder[T]

An empty builder: Array::Builder[Int].new.

<prelude>:4248

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

A builder holding size copies of fill; empty when size is 0 or negative.

<prelude>:4251

Methods

def <<(value: T) -> Self

Appends value, and returns the builder.

<prelude>:4253

def push(value: T) -> Self

Appends value, and returns the builder: #<<.

<prelude>:4255

def pop -> T?

Removes the last element and returns it, or nil when there is none.

<prelude>:4257

def shift -> T?

Removes the first element and returns it, or nil when there is none.

<prelude>:4259

def unshift(value: T) -> Self

Puts value in front, and returns the builder.

<prelude>:4261

def insert(index: Int, value: T) -> Self

Inserts value before the element at index, and returns the builder. index may be size (appends); a negative index counts from the end and inserts after that element, so -1 appends.

Raises

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

<prelude>:4269

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

Appends other's elements, and returns the builder.

<prelude>:4271

def [](index: Int) -> T

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

Raises

IndexError when index is out of range: use #[]? for nil.

<prelude>:4277

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

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

<prelude>:4280

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

Replaces the element at index with value, and returns value. A negative index counts from the end; an index equal to size appends.

Raises

IndexError when index is past the end (where Ruby fills the gap with nil) or, negative, before the start.

b = Array::Builder[Int].new.push(1, 2)
b[-1] = 5
b[2] = 6
b.to_a   # => [1, 5, 6]
b[4] = 7   # raises IndexError

<prelude>:4297

def first -> T?

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

<prelude>:4299

def last -> T?

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

<prelude>:4301

def size -> Int

The number of elements.

<prelude>:4303

def length -> Int

The number of elements: #size.

<prelude>:4305

def empty? -> Bool

Whether the builder has no element.

<prelude>:4307

def include?(value: Object) -> Bool

Whether an element is == to value.

<prelude>:4309

def delete(value: T) -> Self

Removes every element == to value, and returns the builder.

<prelude>:4311

def delete_at(index: Int) -> T?

Removes the element at index (negative counts from the end) and returns it, or nil when index is out of range.

<prelude>:4314

def clear -> Self

Removes every element, and returns the builder.

<prelude>:4316

def reverse! -> Self

Reverses the elements in place, and returns the builder.

<prelude>:4318

def sort! -> Self

Sorts the elements in ascending order (by <=>), and returns the builder.

<prelude>:4320

def map!(&: (T) -> T) -> Self

Replaces each element with the block's result for it, and returns the builder.

<prelude>:4322

def select!(&: (T) -> Object) -> Self

Keeps the elements for which the block is truthy, and returns the builder.

<prelude>:4324

def reject!(&: (T) -> Object) -> Self

Removes the elements for which the block is truthy, and returns the builder.

<prelude>:4326

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

Calls the block with each element in order.

<prelude>:4328

def each_with_index(&: (T, Int) -> Void) -> Void

Calls the block with each element and its index, from 0.

<prelude>:4330

def push(*values: T) -> Self

Appends values in order, and returns the builder.

<prelude>:4332

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

The elements in range, as an immutable array (a copy). A negative bound counts from the end. Unlike Array#[], it raises nothing: a start past the end gives [], and one before the start is cut there.

<prelude>:4336

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

The first n elements (all of them when there are fewer), as an immutable array; ArgumentError for a negative n.

<prelude>:4339

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

The last n elements (all of them when there are fewer), as an immutable array; ArgumentError for a negative n.

<prelude>:4342

def index(value: T) -> Int?

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

<prelude>:4344

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

The elements' to_s joined with separator: Array#join.

<prelude>:4346

def sort!(&: (T, T) -> Int) -> Self

Sorts the elements by the comparator block (negative, zero or positive, as <=>), and returns the builder.

<prelude>:4349

def sort_by![U <: Comparable[U]](&: (T) -> U) -> Self

Sorts the elements by the block's result (stable), and returns the builder.

<prelude>:4352

def uniq! -> Self

Removes duplicate elements, keeping the first of each, and returns the builder.

<prelude>:4354

def compact! -> Self

Removes the nil elements, and returns the builder.

<prelude>:4356

def shuffle! -> Self

Puts the elements in a random order, and returns the builder.

<prelude>:4358

def rotate!(count: Int = …) -> Self

Rotates the elements left by count (right when negative), and returns the builder.

<prelude>:4361

def fill(value: T) -> Self

Replaces every element with value, and returns the builder.

<prelude>:4363

def fill(value: T, start: Int, length: Int) -> Self

Replaces the length elements from start with value, growing the builder when start + length passes its end; a negative start counts from the end, and a start equal to the size appends. Returns the builder. IndexError when start is past the end, as in Array#fill.

<prelude>:4369

def replace(other: Array[T]) -> Self

Replaces the contents with other's elements, and returns the builder.

<prelude>:4371

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

Removes the length elements from start (fewer at the end) and returns them; a negative start counts from the end. [] when start is out of range.

b = Array::Builder[Int].new.push(1, 2, 3, 4)
b.slice!(1, 2)   # => [2, 3]
b.to_a           # => [1, 4]

<prelude>:4381

def delete_if(&: (T) -> Object) -> Self

Removes the elements for which the block is truthy, and returns the builder.

<prelude>:4383

def keep_if(&: (T) -> Object) -> Self

Keeps the elements for which the block is truthy, and returns the builder.

<prelude>:4385

def freeze -> Array[T]

The contents as an immutable array, leaving the builder empty: #to_a.

<prelude>:4387

def to_a -> Array[T]

The contents as an immutable array, without copying; the builder is left empty and can be filled again. Use #snapshot to keep its contents.

b = Array::Builder[Int].new.push(1, 2)
b.to_a   # => [1, 2]
b.size   # => 0

<prelude>:4397

def snapshot -> Array[T]

A copy of the contents as an immutable array; the builder keeps them.

b = Array::Builder[Int].new.push(1, 2)
b.snapshot   # => [1, 2]
b.size       # => 2

<prelude>:4405

def to_s -> String

The elements' inspect in brackets, as Array#to_s.

<prelude>:4407

def inspect -> String

The elements' inspect in brackets, as Array#inspect.

<prelude>:4409