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

Type parameters

Name	Description
T	the 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

Name	Type	Description
value	T	the 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 - mostly o(1)

appendAll

Adds all given values at the end of the builder values

Definition

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

Parameters

Name	Type	Description
values	StreamSource<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

Name	Default	Description
T2	T

Parameters

Name	Type	Description
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, options?: {
      reversed?: boolean;
      state?: TraverseState;
    }): void;

Parameters

Name	Type	Description
f	(value: T, index: number, halt: () => void) => void	the 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
options	{       reversed?: boolean;       state?: TraverseState;     }	(optional) an object containing the following properties: - state: (optional) the traversal state

throws

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

Name	Type	Description
index	number	the 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

Name	Type	Description
index	number	the index at which to insert the value
value	T	the 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

Name	Type	Description
value	T	the 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 - mostly 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

Name	Type	Description
index	number	the 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

Name	Type	Description
index	number	the index of the element to set.
value	T	the 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

Name	Type	Description
index	number	the index of the element to update
update	Update<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