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 |
const l = List.of(1, 3, 2)
Properties
context
The list context that acts as a factory for all related list instances.
context
isEmpty
Returns false since this collection is known to be non-empty.
isEmpty
length
Returns the number of values in the collection
length
Methods
[Symbol.iterator]
Returns a FastIterator
instance used to iterate over the values of this Iterable
.
[Symbol.iterator]
FastIterator
instance used to iterate over the values of this Iterable
.append
Returns the List with the given value
added to the end.
append
value
added to the end.Definition
append(value: T):
List.NonEmpty
<T>;
Parameters
Name | Type | Description |
---|---|---|
value | T | the value to append. |
List.of(0, 1, 2).append(-10) // => List(0, 1, 2, -10)
O(logB(N)) for block size B - mostly o(1)
Overrides
asNormal
Returns this collection typed as a 'possibly empty' collection.
asNormal
assumeNonEmpty
Returns a self reference since this collection is known to be non-empty.
assumeNonEmpty
collect
Returns a List containing the values resulting from applying given collectFun
to each value in this List.
collect
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 |
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
concat
Returns the non-empty List succeeded by the values from all given StreamSource
instances given in sources
.
concat
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 |
this operation is most efficient when the given sources are instances of List from the same context.
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)
O(logB(N)) for block size B
Overrides
drop
Returns a List skipping the first given amount
elements of this List.
drop
amount
elements of this List.Definition
drop(amount: number):
List
<T>;
Parameters
Name | Type | Description |
---|---|---|
amount | number | the desired amount of values of to include |
a negative index
will be treated as follows:
- -1: the last element in the list
- -2: the second-last element in the list
- ...etc
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)
O(logB(N)) for block size B
Overrides
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.
filter
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 |
if the predicate is a type guard, the return type is automatically inferred
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
first
Returns the first value of the List.
first
flatMap
Returns a List containing the joined results of applying given flatMapFun
to each value in this List.
flatMap
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 |
List.of(1, 2, 3).flatMap(v => [v, v + 1]).toArray()
// => [1, 2, 2, 3, 3, 4]
Overrides
forEach
Performs given function f
for each value of the List.
forEach
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 |
List.of(0, 1, 2, 3).forEach((value, i, halt) => {
console.log(value * 2);
if (i >= 1) halt();
})
// => logs 0 2
O(N)
Overrides
get
Returns the value in the List at the given index
.
get
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 |
a negative index
will be treated as follows:
- -1: the last value in the list
- -2: the second-last value in the list
- ...etc
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
O(logB(N)) for block size B
Overrides
insert
Returns the non-empty List with the given values
inserted at the given index
.
insert
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 |
a negative index
will be treated as follows:
- -1: the last element in the list
- -2: the second-last element in the list
- ...etc
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)
O(logB(N)) for block size B
Overrides
last
Returns the last value of the 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.
map
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 |
List.of(1, 2, 3).map(v => `value: ${v + 2}`).toArray()
// => ['value 2', 'value 3', 'value 3']
Overrides
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.
mapPure
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 |
The given mapFun
is expected to be side-effect free, so that structural sharing can be kept in place.
List.of(1, 2, 3).mapPure(v => `value: ${v + 2}`).toArray()
// => ['value 2', 'value 3', 'value 3']
Overrides
nonEmpty
Returns true since this collection is known to be non-empty
nonEmpty
Definition
nonEmpty(): this is
List.NonEmpty
<T>;
List.of(0, 1, 2).nonEmpty() // => true
Overrides
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
.
padTo
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 |
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)
O(logB(N)) for block size B
Overrides
prepend
Returns the List with the given value
added to the start.
prepend
value
added to the start.Definition
prepend(value: T):
List.NonEmpty
<T>;
Parameters
Name | Type | Description |
---|---|---|
value | T | the value to prepend |
List.of(0, 1, 2).prepend(-10) // => List(-10, 0, 1, 2)
O(logB(N)) for block size B - mostly o(1)
Overrides
remove
Returns the List with the given amount
of values removed at the given index
.
remove
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 |
a negative index
will be treated as follows:
- -1: the last element in the list
- -2: the second-last element in the list
- ...etc
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)
O(logB(N)) for block size B
Overrides
repeat
Returns a non-empty List that contains this List the given amount
of times.
repeat
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 |
if the given amount <= 1, the List itself is returned
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)
O(logB(N)) for block size B
Overrides
reversed
Returns the non-empty List in reversed order.
reversed
Definition
reversed():
List.NonEmpty
<T>;
List.of(0, 1, 2).reversed() // -> List(2, 1, 0)
O(logB(n)) for block size B
Overrides
rotate
Returns the non-empty List where the first given shiftAmount
of values are removed from this List, and are appended at the end.
rotate
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 |
if the shiftAmount
is negative, the last shiftAmount
values will be removed from the List and will be prepended.
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)
O(logB(N)) for block size B
Overrides
slice
Returns the List containing the values within the given index range
, potentially reversed in order if reversed
is true.
slice
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 |
a negative index
will be treated as follows:
- -1: the last element in the list
- -2: the second-last element in the list
- ...etc
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)
O(logB(N)) for block size B
Overrides
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.
sort
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
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
.
splice
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 |
a negative index
will be treated as follows: - -1: the last element in the list - -2: the second-last element in the list - ...etc
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)
O(logB(N)) for block size B
Overrides
stream
Returns a non-empty Stream containing the values in order of the List, or in reverse order if reversed
is true.
stream
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 |
List.of(0, 1, 2).stream().toArray() // => [0, 1, 2]
List.of(0, 1, 2).stream(true).toArray() // => [2, 1, 0]
Overrides
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.
streamRange
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: - range: (optional) the index range to include from the list - reversed: (default: false) if true reverses the order of the included elements |
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]
Overrides
take
Returns a List containing the first (or last) given amount
values of this List.
take
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 of to include |
a negative index
will be treated as follows:
- -1: the last element in the list
- -2: the second-last element in the list
- ...etc
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)
O(logB(N)) for block size B
Overrides
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.
toArray
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 |
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]
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
toBuilder
Returns a builder object containing the values of this collection.
toBuilder
Definition
toBuilder():
List.Builder
<T>;
const builder: List.Builder<number> = List.of(0, 1, 2, 3).toBuilder()
Overrides
toJSON
Returns a JSON representation of this collection.
toJSON
toString
Returns a string representation of this collection.
toString
updateAt
Returns the non-empty List where at the given index
the value is replaced or updated by the given update
.
updateAt
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 |
a negative index
will be treated as follows:
- -1: the last element in the list
- -2: the second-last element in the list
- ...etc
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)
O(logB(N)) for block size B