Skip to main content

interface List.Builder<T>

A mutable builder to create immutable List instances in a more efficient way. See the List documentation and the List.Builder API documentation

Implemented by: GenBuilder<T>

Type parameters

NameDescription
Tthe value type
example
const b = List.builder<T>();
b.append(1);
b.prepend(2);
b.insert(1, 3);
b.build().toArray();
// => [2, 3, 1]

Properties

isEmpty

Returns true if there are no values in the builder.

Definition

readonly isEmpty: boolean;

example
List.of(1, 2, 3).toBuilder().isEmpty
// => false

length

Returns the amount of values in the builder.

Definition

readonly length: number;

example
List.of(1, 2, 3).toBuilder().size
// => 3

Methods

append

Adds the given value to the end of the builder values.

Definition

append(value: T): void;

Parameters

NameTypeDescription
valueTthe value to append
example
const m = List.of(1, 2, 3).toBuilder()
m.append(10)
m.build().toArray()
// => [1, 2, 3, 10]
note

O(logB(N)) for block size B - mosly o(1)

appendAll

Adds all given values at the end of the builder values

Definition

appendAll(values: StreamSource<T>): void;

Parameters

NameTypeDescription
valuesStreamSource<T>a StreamSource containing values to add
example
const m = List.of(1, 2, 3).toBuilder()
m.appendAll([10, 11])
m.build().toArray()
// => [1, 2, 3, 10, 11]

build

Returns an immutable instance containing the values in this builder.

Definition

build(): List<T>;

example
const m = List.of(1, 2, 3).toBuilder()
const m2: List<number> = m.build()
m.toArray()
// => [1, 2, 3]

buildMap

Returns an immutable instance containing the result of applying given mapFun to each value in the builder.

Definition

buildMap<T2 = T>(mapFun: (value: T) => T2): List<T2>;

Type parameters

NameDefaultDescription
T2T

Parameters

NameTypeDescription
mapFun(value: T) => T2
example
const m = List.of(1, 2, 3).toBuilder()
const m2: List<number> = m.buildMap(v => String(v))
m.toArray()
// => ['1', '2', '3']

forEach

Performs given function f for each value of the List builder.

Definition

forEach(f: (value: T, index: number, halt: () => void) => void, state?: TraverseState): void;

Parameters

NameTypeDescription
f(value: T, index: number, halt: () => void) => voidthe function to perform for each element, receiving
- value: the next value
- index: the index of the value
- halt: a function that, if called, ensures that no new elements are passed
stateTraverseState
throws

RibuError.ModifiedBuilderWhileLoopingOverItError if the builder is modified while looping over it

example
List.of(0, 1, 2, 3).toBuilder().forEach((value, i, halt) => {
console.log(value * 2);
if (i >= 1) halt();
})
// => logs 0 2
note

O(N)

get

Returns the value in the List builder at the given index.

Definitions

get(index: number): T | undefined;

get<O>(index: number, otherwise: OptLazy<O>): T | O;

Parameters

NameTypeDescription
indexnumberthe element index
note

a negative index will be treated as follows:
- -1: the last value in the list
- -2: the second-last value in the list
- ...etc

example
const m = List.of(0, 1, 2).toBuilder()
m.get(5) // => undefined
m.get(5, 'other') // => 'other'
m.get(1, 'other') // => 1
m.get(-1) // => 2
note

O(logB(N)) for block size B

insert

Inserts the given value at the given index in the builder.

Definition

insert(index: number, value: T): void;

Parameters

NameTypeDescription
indexnumberthe index at which to insert the value
valueTthe value to insert
note

a negative index will be treated as follows:
- -1: the last value in the list
- -2: the second-last value in the list
- ...etc

example
const m = List.of(1, 2, 3).toBuilder()
m.insert(1, 10)
m.build().toArray()
// => [1, 10, 2, 3]

prepend

Adds the given value to the start of the builder values.

Definition

prepend(value: T): void;

Parameters

NameTypeDescription
valueTthe value to prepend
example
const m = List.of(1, 2, 3).toBuilder()
m.prepend(10)
m.build().toArray()
// => [10, 1, 2, 3]
note

O(logB(N)) for block size B - mosly o(1)

remove

Removes the value at the given index in the builder.

Definitions

remove(index: number): T | undefined;

remove<O>(index: number, otherwise: OptLazy<O>): T | O;

Parameters

NameTypeDescription
indexnumberthe index at which to remove a value
example
const m = List.of(1, 2, 3).toBuilder()
m.remove(10) // => undefined
m.remove(10, 'a') // => 'a'
m.remove(1) // => 2
m.remove(0, 'a') // => 1

set

Sets the element at the given index to the given value.

Definitions

set(index: number, value: T): T | undefined;

set<O>(index: number, value: T, otherwise: OptLazy<O>): T | O;

Parameters

NameTypeDescription
indexnumberthe index of the element to set.
valueTthe new value to set.
note

a negative index will be treated as follows:
- -1: the last element in the list
- -2: the second-last element in the list
- ...etc

example
const m = List.of(1, 2, 3).toBuilder()
m.set(0, 10) // => 1
m.set(1, 10, 'a') // => 2
m.set(10, 0) // => undefined
m.set(10, 0, 'a') // => 'a'
note

O(logB(N)) for block size B

updateAt

Updates the element at the given index with the given update value or function.

Definitions

updateAt(index: number, update: Update<T>): T | undefined;

updateAt<O>(index: number, update: Update<T>, otherwise: OptLazy<O>): T | O;

Parameters

NameTypeDescription
indexnumberthe index of the element to update
updateUpdate<T>the new value or function taking the current value and returning a new value
note

a negative index will be treated as follows:
- -1: the last element in the list
- -2: the second-last element in the list
- ...etc

example
const m = List.of(1, 2, 3).toBuilder()
m.updateAt(0, 10) // => 1
m.updateAt(1, 10, 'a') // => 2
m.updateAt(10, 0) // => undefined
m.updateAt(10, 0, 'a') // => 'a'
note

O(logB(N)) for block size B