Skip to main content

interface List<T>

A random accessible immutable sequence of values of type T. See the List documentation and the List API documentation

Companion namespace: List

Extends: FastIterable<T>

Implemented by: Empty<T>, List.NonEmpty<T>

Type parameters

NameDescription
Tthe value type
example
const l1 = List.empty<string>()
const l2 = List.of(1, 3, 2)

Properties

context

The list context that acts as a factory for all related list instances.

Definition

readonly context: List.Context;

isEmpty

Returns true if the collection is empty

Definition

readonly isEmpty: boolean;

example
List.empty().isEmpty      // => true
List.of(0, 1, 2).isEmpty // => false

length

Returns the number of values in the collection

Definition

readonly length: number;

example
List.empty().length      // => 0
List.of(0, 1, 2).length // => 3

Methods

[Symbol.iterator]

Returns a FastIterator instance used to iterate over the values of this Iterable.

Definition

[Symbol.iterator](): FastIterator<T>;

Overrides

FastIterable.[Symbol.iterator]

append

Returns the List with the given value added to the end.

Definition

append(value: T): List.NonEmpty<T>;

Parameters

NameTypeDescription
valueTthe value to append.
example
List.of(0, 1, 2).append(-10)  // => List(0, 1, 2, -10)
note

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

assumeNonEmpty

Returns the same collection typed as non-empty.

Definition

assumeNonEmpty(): List.NonEmpty<T>;

throws

RimbuError.EmptyCollectionAssumedNonEmptyError if the collection is empty

example
List.empty().assumeNonEmpty()           // => throws RimbuError.EmptyCollectionAssumedNonEmptyError
List.from([0, 1, 2]).assumeNonEmpty() // => List.NonEmpty(0, 1, 2)

collect

Returns a List containing the values resulting from applying given collectFun to each value in this List.

Definition

collect<T2>(collectFun: CollectFun<T, T2>, options?: {
    range?: IndexRange;
    reversed?: boolean;
  }): List<T2>;

Type parameters

NameDescription
T2the result element type

Parameters

NameTypeDescription
collectFunCollectFun<T, T2>a function receiving
- value: the next value
- index: the value index
- skip: a token that, when returned, will not add a value to the resulting collection
- halt: a function that, when called, ensures no next elements are passed
options{
    range?: IndexRange;
    reversed?: boolean;
  }
(optional) an object containing the following properties:
- range: (optional) the range of the list to include in the filtering process
- reversed: (default: false) if true reverses the elements within the given range
example
List.of(0, 1, 2, 3).collect(v => v > 1)
// => List(false, false, true, true)
List.of(0, 1, 2, 3).collect((v, i, skip) => v === 1 ? skip : v * 2)
// => List(0, 4, 6)
List.of(0, 1, 2, 3).collect((v, i, skip, halt) => {
if (v > 1) halt()
return v * 2
})
// => List(0, 2)

concat

Returns the List succeeded by the values from all given StreamSource instances given in sources.

Definitions

concat<T2 = T>(...sources: ArrayNonEmpty<StreamSource.NonEmpty<T2>>): List.NonEmpty<T | T2>;

concat<T2 = T>(...sources: ArrayNonEmpty<StreamSource<T2>>): List<T | T2>;

Type parameters

NameDefaultDescription
T2Tthe type of the source elements to add

Parameters

NameTypeDescription
sourcesArrayNonEmpty<StreamSource.NonEmpty<T2>>an array of StreamSource instances containing values to be added to the list
note

this operation is most efficient when the given sources are instances of List from the same context.

example
List.of(0, 1, 2).concat([10, 11])                      // -> List(0, 1, 2, 10, 11)
List.of(0, 1, 2).concat([10, 11], new Set([12, 13])) // -> List(0, 1, 2, 10, 11, 12, 13)
note

O(logB(N)) for block size B

drop

Returns a List skipping the first given amount elements of this List.

Definition

drop(amount: number): List<T>;

Parameters

NameTypeDescription
amountnumberthe desired amount of values of to include
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
List.of(0, 1, 2, 3).drop(2)    // => List(2, 3)
List.of(0, 1, 2, 3).drop(10) // => List()
List.of(0, 1, 2, 3).drop(-2) // => List(0, 1)
note

O(logB(N)) for block size B

filter

Returns a List containing only those values within optionally given range that satisfy given pred predicate. If reversed is true, the order of the values is reversed.

Definitions

filter<TF extends T>(pred: (value: T, index: number, halt: () => void) => value is TF, options?: {
    range?: IndexRange;
    reversed?: boolean;
    negate?: false | undefined;
  }): List<TF>;

filter<TF extends T>(pred: (value: T, index: number, halt: () => void) => value is TF, options: {
    range?: IndexRange;
    reversed?: boolean;
    negate: true;
  }): List<Exclude<T, TF>>;

filter(pred: (value: T, index: number, halt: () => void) => boolean, options?: {
    range?: IndexRange;
    reversed?: boolean;
    negate?: boolean;
  }): List<T>;

Type parameters

NameConstraintsDescription
TFT

Parameters

NameTypeDescription
pred(value: T, index: number, halt: () => void) => value is TFa predicate function receiving
- value: the next value
- index: the value index
- halt: a function that, when called, ensures no next elements are passed
options{
    range?: IndexRange;
    reversed?: boolean;
    negate?: false | undefined;
  }
(optional) an object containing the following properties:
- range: (optional) the range of the list to include in the filtering process
- reversed: (default: false) if true reverses the elements within the given range
note

if the predicate is a type guard, the return type is automatically inferred

example
List.of(0, 1, 2, 3).filter(v => v < 2)           // -> List(0, 1)
List.of(0, 1, 2, 3).filter((v, _, halt) => {
if (v > 1) halt();
return v;
}) // -> List(0, 1, 2)
List.of(0, 1, 2, 3)
.filter((_, i) => i > 1, undefined, true) // -> List(1, 0)

first

Returns the first value of the List, or the otherwise value if the list is empty.

Definitions

first(): T | undefined;

first<O>(otherwise: OptLazy<O>): T | O;

example
List.empty().first()                  // => undefined
List.empty().first('other') // => 'other'
List.from([0, 1, 2]).first('other') // => 0
note

O(1)

flatMap

Returns a List containing the joined results of applying given flatMapFun to each value in this List.

Definition

flatMap<T2>(flatMapFun: (value: T, index: number) => StreamSource<T2>, options?: {
    range?: IndexRange;
    reversed?: boolean;
  }): List<T2>;

Type parameters

NameDescription
T2the result element type

Parameters

NameTypeDescription
flatMapFun(value: T, index: number) => StreamSource<T2>a function taking the next value and its index, and returning a StreamSource of value to include in the resulting collection
options{
    range?: IndexRange;
    reversed?: boolean;
  }
(optional) an object containing the following properties:
- range: (optional) the range of the list to include in the filtering process
- reversed: (default: false) if true reverses the elements within the given range
example
List.of(1, 2, 3).flatMap(v => [v, v + 1]).toArray()
// => [1, 2, 2, 3, 3, 4]

forEach

Performs given function f for each value of the List.

Definition

forEach(f: (value: T, index: number, halt: () => void) => void, options?: {
    reversed?: boolean;
    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
options{
    reversed?: boolean;
    state?: TraverseState;
  }
(optional) an object containing the following properties:
- reversed: (default: false) when true will reverse the element order - state: (optional) the traversal state
example
List.of(0, 1, 2, 3).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 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
List.of(0, 1, 2).get(5)             // => undefined
List.of(0, 1, 2).get(5, 'other') // => 'other'
List.of(0, 1, 2).get(1, 'other') // => 1
List.of(0, 1, 2).get(-1) // => 2
note

O(logB(N)) for block size B

insert

Returns the List with the given values inserted at the given index.

Definitions

insert(index: number, values: StreamSource.NonEmpty<T>): List.NonEmpty<T>;

insert(index: number, values: StreamSource<T>): List<T>;

Parameters

NameTypeDescription
indexnumberthe index at which to insert the values
valuesStreamSource.NonEmpty<T>a StreamSource of values to insert
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
List.of(0, 1, 2, 3).insert(2, [10, 11])   // -> List(0, 1, 10, 11, 2, 3)
List.of(0, 1, 2, 3).insert(-1, [10, 11]) // -> List(0, 1, 2, 1, 11, 3)
note

O(logB(N)) for block size B

last

Returns the last value of the List, or the otherwise value if the list is empty.

Definitions

last(): T | undefined;

last<O>(otherwise: OptLazy<O>): T | O;

example
List.empty().last()                  // => undefined
List.empty().last('other') // => 'other'
List.from([0, 1, 2]).last('other') // => 2
note

O(1)

map

Returns a List containing the result of applying given mapFun to each value in this List. If reversed is true, the order of the values is reversed.

Definition

map<T2>(mapFun: (value: T, index: number) => T2, options?: {
    reversed?: boolean;
  }): List<T2>;

Type parameters

NameDescription
T2the result element type

Parameters

NameTypeDescription
mapFun(value: T, index: number) => T2a function receiving a value and its index, and returning a new value
options{
    reversed?: boolean;
  }
(optional) an object containing the following properties:
- reversed: (default: false) if true, reverses the order of the values
example
List.of(1, 2, 3).map(v => `value: ${v + 2}`).toArray()
// => ['value 2', 'value 3', 'value 3']

mapPure

Returns a List containing the result of applying given mapFun to each value in this List. If reversed is true, the order of the values is reversed.

Definition

mapPure<T2>(mapFun: (value: T) => T2, options?: {
    reversed?: boolean;
  }): List<T2>;

Type parameters

NameDescription
T2the result element type

Parameters

NameTypeDescription
mapFun(value: T) => T2a function receiving a value, and returning a new value
options{
    reversed?: boolean;
  }
(optional) an object containing the following properties:
- reversed: (default: false) if true, reverses the order of the values
note

The given mapFun is expected to be side-effect free, so that structural sharing can be kept in place.

example
List.of(1, 2, 3).mapPure(v => `value: ${v + 2}`).toArray()
// => ['value 2', 'value 3', 'value 3']

nonEmpty

Returns true if there is at least one value in the collection, and instructs the compiler to treat the collection as a .NonEmpty type.

Definition

nonEmpty(): this is List.NonEmpty<T>;

example
const m: List<number> = List.of(1, 2, 2)
m.stream().first(0) // compiler allows fallback value since the Stream may be empty
if (m.nonEmpty()) {
m.stream().first(0) // compiler error: fallback value not allowed since Stream is not empty
}

padTo

Returns the List where, if given length is larger than the List length, the given fill value is added to the start and/or end of the List according to the positionPercentage such that the result length is equal to length.

Definition

padTo(length: number, fill: T, options?: {
    positionPercentage?: number;
  }): List<T>;

Parameters

NameTypeDescription
lengthnumberthe target length of the resulting list
fillTthe element used to fill up empty space in the resulting List
options{
    positionPercentage?: number;
  }
(optional) an object containing the following properties:
- positionPercentage: (default: 0) a percentage indicating how much of the filling elements should be to the right side of the current List
example
List.of(0, 1).padTo(4, 10)       // -> List(0, 1, 10, 10)
List.of(0, 1).padTo(4, 10, 50) // -> List(10, 0, 1, 10)
List.of(0, 1).padTo(4, 10, 100) // -> List(0, 1, 10, 10)
List.of(0, 1, 2).padTo(2, 10) // -> List(0, 1, 2)
note

O(logB(N)) for block size B

prepend

Returns the List with the given value added to the start.

Definition

prepend(value: T): List.NonEmpty<T>;

Parameters

NameTypeDescription
valueTthe value to prepend
example
List.of(0, 1, 2).prepend(-10)  // => List(-10, 0, 1, 2)
note

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

remove

Returns the List with the given amount of values removed at the given index.

Definition

remove(index: number, options?: {
    amount?: number;
  }): List<T>;

Parameters

NameTypeDescription
indexnumberthe index at which to remove values
options{
    amount?: number;
  }
object containing the following
- amount: (default: 1) the amount of elements to remove
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
List.of(0, 1, 2, 3).remove(1, 2)  // -> List(0, 3)
List.of(0, 1, 2, 3).remove(-2, 1) // -> List(0, 1, 3)
note

O(logB(N)) for block size B

repeat

Returns a List that contains this List the given amount of times.

Definition

repeat(amount: number): List<T>;

Parameters

NameTypeDescription
amountnumberthe amount of times to repeat the values in this List
note

if the given amount <= -1, the reverse List is repeated @note if the given amount is 0 or 1, the List itself is returned

example
List.of(0, 1, 2).repeat(2)   // -> List(0, 1, 2, 0, 1, 2)
List.of(0, 1, 2).repeat(0) // -> List(0, 1, 2)
note

O(logB(N)) for block size B

reversed

Returns the List in reversed order.

Definition

reversed(): List<T>;

example
List.of(0, 1, 2).reversed()  // -> List(2, 1, 0)
note

O(logB(n)) for block size B

rotate

Returns the List where the elements are shifted to right by shiftRoundAmount position, and the elements at the end are placed at the beginning.

Definition

rotate(shiftRightAmount: number): List<T>;

Parameters

NameTypeDescription
shiftRightAmountnumberthe amount of values to shift the elements to the right
note

if the shiftRightAmount is negative, the elements will be shifted to the left.

example
List.of(0, 1, 2, 3).rotate(2)   // -> List(2, 3, 0, 1)
List.of(0, 1, 2, 3).rotate(-1) // -> List(1, 2, 3, 0)
note

O(logB(N)) for block size B

slice

Returns the List containing the values within the given index range, potentially reversed in order if reversed is true.

Definition

slice(range: IndexRange, options?: {
    reversed?: boolean;
  }): List<T>;

Parameters

NameTypeDescription
rangeIndexRangethe index range to include
options{
    reversed?: boolean;
  }
(optional) an object containing the following properties:
- reversed: (default: false) if true reverses the order of the elements
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
List.of(0, 1, 2, 3).slice({ start: 1, amount: 2 })        // -> List(1, 2)
List.of(0, 1, 2, 3).slice({ start: -2, amount: 2 }, true) // -> List(3, 2)
note

O(logB(N)) for block size B

sort

Returns the values sorted according to the given, optional Comp. Performance warning: this method is not designed for frequent calls; should you need to keep in order a collection with potentially duplicate values, please consider SortedMultiSet instead.

Definition

sort(comp?: Comp<T>, options?: {
    inverse?: boolean;
  }): List<T>;

Parameters

NameTypeDescription
compComp<T>The comparison logic to use; if missing, the default JavaScript sorting algorithm is applied
options{
    inverse?: boolean;
  }

splice

Returns the List, where at the given index the remove amount of values are replaced by the values from the optionally given insert StreamSource.

Definitions

splice(options: {
    index: number;
    remove?: number;
    insert: StreamSource.NonEmpty<T>;
  }): List.NonEmpty<T>;

splice(options: {
    index: number;
    remove?: number;
    insert?: StreamSource<T>;
  }): List<T>;

Parameters

NameTypeDescription
options{
    index: number;
    remove?: number;
    insert: StreamSource.NonEmpty<T>;
  }
object containing the following
- index: the index at which to replace values
- remove: (default: 0) the amount of values to remove
- insert: (default: []) a StreamSource of values to insert
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
List.of(0, 1, 2, 3).splice({ index: 2, remove: 1 })                    // -> List(0, 1, 3)
List.of(0, 1, 2, 3).splice({ index: 1, remove: 2, insert: [10, 11] }) // -> List(0, 10, 11, 3)
note

O(logB(N)) for block size B

stream

Returns a Stream containing the values in order of the List, or in reverse order if reversed is true.

Definition

stream(options?: {
    reversed?: boolean;
  }): Stream<T>;

Parameters

NameTypeDescription
options{
    reversed?: boolean;
  }
(optional) an object containing the following properties:
- reversed: (default: false) if true reverses the order of the elements
example
List.of(0, 1, 2).stream().toArray()      // => [0, 1, 2]
List.of(0, 1, 2).stream(true).toArray() // => [2, 1, 0]

streamRange

Returns a Stream containing the values contained in the given index range, in order of the List, or in reverse order if reversed is true.

Definition

streamRange(range: IndexRange, options?: {
    reversed?: boolean;
  }): Stream<T>;

Parameters

NameTypeDescription
rangeIndexRange
options{
    reversed?: boolean;
  }
(optional) an object containing the following properties:
- range: (optional) the index range to include from the list
- reversed: (default: false) if true reverses the order of the included elements
example
List.of(0, 1, 2, 3, 4).streamRange({ start: 1, end: 2 }).toArray()             // => [0, 1, 2]
List.of(0, 1, 2, 3, 4).streamRange({ start: 1, amount: 2 }, true).toArray() // => [2, 1]

take

Returns a List containing the first (or last) given amount values of this List.

Definition

take(amount: number): List<T>;

Parameters

NameTypeDescription
amountnumberthe desired amount of values of to include
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
List.of(0, 1, 2, 3).take(2)    // => List(0, 1)
List.of(0, 1, 2, 3).take(10) // => List(0, 1, 2, 3)
List.of(0, 1, 2, 3).take(-2) // => List(2, 3)
note

O(logB(N)) for block size B

toArray

Returns an array containing the values within given range (default: all) in this collection. If reversed is true, reverses the order of the values.

Definition

toArray(options?: {
    range?: IndexRange;
    reversed?: boolean;
  }): T[];

Parameters

NameTypeDescription
options{
    range?: IndexRange;
    reversed?: boolean;
  }
(optional) an object containing the following properties:
- range: (optional) the range of the list to include in the filtering process
- reversed: (default: false) if true reverses the elements within the given range
example
List.of(0, 1, 2, 3).toArray()                      // => [0, 1, 2, 3]
List.of(0, 1, 2, 3).toArray({ amount: 2 }) // => [0, 1]
List.of(0, 1, 2, 3).toArray({ amount: 2 }, true) // => [1, 0]
note

O(logB(N)) for block size B @note it is safe to mutate the returned array, however, the array elements are not copied, thus should be treated as read-only

toBuilder

Returns a builder object containing the values of this collection.

Definition

toBuilder(): List.Builder<T>;

example
const builder: List.Builder<number> = List.of(0, 1, 2, 3).toBuilder()

toJSON

Returns a JSON representation of this collection.

Definition

toJSON(): ToJSON<T[], this['context']['typeTag']>;

example
List.of(0, 1, 2, 3).toJSON()   // => { dataType: 'List', value: [0, 1, 2, 3] }

toString

Returns a string representation of this collection.

Definition

toString(): string;

example
List.of(0, 1, 2, 3).toString()   // => List(0, 1, 2, 3)

updateAt

Returns the List where at the given index the value is replaced or updated by the given update.

Definition

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

Parameters

NameTypeDescription
indexnumberthe index at which to update the value
updateUpdate<T>a 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
List.of(0, 1, 2).updateAt(1, 10)            // -> List(0, 10, 2)
List.of(0, 1, 2).updateAt(1, v => v + 1) // -> List(0, 2, 2)
List.of(0, 1, 2).updateAt(-1, 10) // -> List(0, 1, 10)
note

O(logB(N)) for block size B