interface List.NonEmpty<T>

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

Extends: Streamable.NonEmpty<T>, List<T>

Type parameters

Name	Description
T	the value type

example

const l = 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;

Overrides

List.context

isEmpty

Returns false since this collection is known to be non-empty.

Definition

readonly isEmpty: false;

example

List(0, 1, 2).isEmpty   // => false

Overrides

List.isEmpty

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

Overrides

List.length

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

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

Overrides

List.append

asNormal

Returns this collection typed as a 'possibly empty' collection.

Definition

asNormal(): List<T>;

example

List.of(0, 1, 2).asNormal();  // type: List<number>

assumeNonEmpty

Returns a self reference since this collection is known to be non-empty.

Definition

assumeNonEmpty(): this;

example

const m = List.of(0, 1, 2);
m === m.assumeNonEmpty()  // => true

Overrides

List.assumeNonEmpty

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

Name	Description
T2	the result element type

Parameters

Name	Type	Description
collectFun	CollectFun<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)

Overrides

List.collect

concat

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

Definition

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

Type parameters

Name	Default	Description
T2	T	the type of the source elements to add

Parameters

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

Overrides

List.concat

drop

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

Definition

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

Parameters

Name	Type	Description
amount	number	the desired amount of values 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

Overrides

List.drop

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

Name	Constraints	Description
TF	T

Parameters

Name	Type	Description
pred	(value: T, index: number, halt: () => void) => value is TF	a 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)

Overrides

List.filter

first

Returns the first value of the List.

Definition

first(): T;

example

List.of(0, 1, 2).first()   // => 0

note

O(1)

Overrides

List.first

flatMap

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

Definitions

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

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

Type parameters

Name	Description
T2	the result element type

Parameters

Name	Type	Description
flatMapFun	(value: T, index: number) => StreamSource.NonEmpty<T2>	a function taking the next value and its index, and returning a StreamSource of value to include in the resulting collection
options	{       range?: undefined;       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]

Overrides

List.flatMap

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

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: - 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)

Overrides

List.forEach

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

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

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

Overrides

List.get

insert

Returns the non-empty List with the given values inserted at the given index.

Definition

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

Parameters

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

Overrides

List.insert

last

Returns the last value of the List.

Definition

last(): T;

example

List.of(0, 1, 2).last()   // => 2

note

O(1)

Overrides

List.last

map

Returns a non-empty 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.NonEmpty<T2>;

Type parameters

Name	Description
T2

Parameters

Name	Type	Description
mapFun	(value: T, index: number) => T2	a 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: 3', 'value: 4', 'value: 5']

Overrides

List.map

mapPure

Returns a non-empty 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.NonEmpty<T2>;

Type parameters

Name	Description
T2	the result element type

Parameters

Name	Type	Description
mapFun	(value: T) => T2	a 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: 3', 'value: 4', 'value: 5']

Overrides

List.mapPure

nonEmpty

Returns true since this collection is known to be non-empty

Definition

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

example

List.of(0, 1, 2).nonEmpty()   // => true

Overrides

List.nonEmpty

padTo

Returns the non-empty 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.NonEmpty<T>;

Parameters

Name	Type	Description
length	number	the target length of the resulting list
fill	T	the 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

Overrides

List.padTo

prepend

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

Definition

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

Parameters

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

Overrides

List.prepend

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

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

Overrides

List.remove

repeat

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

Definition

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

Parameters

Name	Type	Description
amount	number	the amount of times to repeat the values in this List

note

if the given amount <= 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

Overrides

List.repeat

reversed

Returns the non-empty List in reversed order.

Definition

reversed(): List.NonEmpty<T>;

example

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

note

O(logB(n)) for block size B

Overrides

List.reversed

rotate

Returns the non-empty List where the first given shiftAmount of values are removed from this List, and are appended at the end.

Definition

rotate(shiftAmount: number): List.NonEmpty<T>;

Parameters

Name	Type	Description
shiftAmount	number	the amount of values to rotate

note

if the shiftAmount is negative, the last shiftAmount values will be removed from the List and will be prepended.

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

Overrides

List.rotate

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

Name	Type	Description
range	IndexRange	the 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 }, { reversed: true }) // -> List(3, 2)

note

O(logB(N)) for block size B

Overrides

List.slice

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.NonEmpty<T>;

Parameters

Name	Type	Description
comp	Comp<T>	The comparison logic to use; if missing, the default JavaScript sorting algorithm is applied
options	{       inverse?: boolean;     }

Overrides

List.sort

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

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

Overrides

List.splice

stream

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

Definition

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

Parameters

Name	Type	Description
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({ reversed: true }).toArray()     // => [2, 1, 0]

Overrides

NonEmpty.stream, List.stream

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

Name	Type	Description
range	IndexRange
options	{     reversed?: boolean;   }	(optional) an object containing the following properties: - reversed: (default: false) if true reverses the order of the included elements

example

List.of(0, 1, 2, 3, 4).streamRange({ start: 1, amount: 2 }).toArray()                      // => [1, 2]
List.of(0, 1, 2, 3, 4).streamRange({ start: 1, amount: 2 }, { reversed: true }).toArray() // => [2, 1]

Overrides

List.streamRange

take

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

Definition

take<N extends number>(amount: N): 0 extends N ? List<T> : List.NonEmpty<T>;

Type parameters

Name	Constraints	Description
N	number	the literal numeric type of amount

Parameters

Name	Type	Description
amount	N	the desired amount of values 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

Overrides

List.take

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.

Definitions

toArray(options?: {
      range?: undefined;
      reversed?: boolean;
    }): ArrayNonEmpty<T>;

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

Parameters

Name	Type	Description
options	{       range?: undefined;       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({ range: { amount: 2 } })                 // => [0, 1]
List.of(0, 1, 2, 3).toArray({ range: { amount: 2 }, reversed: 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

Overrides

List.toArray

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()

Overrides

List.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] }

Overrides

List.toJSON

toString

Returns a string representation of this collection.

Definition

toString(): string;

example

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

Overrides

List.toString

updateAt

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

Definition

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

Parameters

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

Overrides

List.updateAt