YList<T>

c: IEnumerable<T>

The enumerable collection of elements to initialize the list with.

collection: IEnumerable<T>

The collection of elements to be appended to the list.

Return Value

boolean

Whether there have been elements appended.

index: number

Index at which the first element of the specified collection is placed

c: IEnumerable<T>

The collection that contains the elements to be added

Return Value

boolean

true if this list was changed, false otherwise

Throws

Exception ({ name: 'IndexOutOfRangeError' })

If the index is out of range, that is, negative or larger than the size of this list

element: T

The element to be inserted at the head of the list.

Return Value

ListCell<T>

The newly created ListCell<T> that stores the given element.

cell: ListCell<T>

A list cell which is not part of any list.

element: T

The element to be inserted at the tail of the list.

Return Value

ListCell<T>

The newly created ListCell<T> that stores the given element.

cell: ListCell<T>

A list cell which is not part of any list.

items: T

The item(s) to prepend to the enumeration

Return Value

IEnumerable<T>

A new live view over the original enumerable that has each of the items appended to it.

Examples

const list = List.fromArray([1, 2, 3, 4])

const appendedEnumerable = list.append(5, 6)
console.log(appendedEnumerable.toArray()) // yields [1,2,3,4,5,6]

// show live updates
list.add(4.5)

console.log(appendedEnumerable.toArray()) // yields [1,2,3,4,4.5,5,6]

See Also

API

prepend, concat

index: number

The index of the element to return. Supports relative indexing from the end of the enumerable when passed a negative index. In other words, if a negative number is used, the returned element will be found by counting back from the end of the enumerable.

Return Value

T

The element at the given index, or null if the index is not within the valid range of this enumerable.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4])
console.log(enumerable.at(0)) // yields 1
console.log(enumerable.at(-1)) // yields 4
console.log(enumerable.at(5)) // yields null!

// using ?? for default values
console.log(enumerable.at(10) ?? 0) // yields 0
// use ! when you know that this is valid
console.log(enumerable.at(0)!.toFixed())
// use optional chaining when you are unsure whether the index is valid
console.log(enumerable.at(20)?.toFixed())
// combine optional chaining and null-coalescing operator when you are unsure
console.log(enumerable.at(30)?.toLocaleString() ?? 'no value')

elements: any

Rest arguments to be appended. In case the elements are enumerable-like, too, they will be will be enumerated after the others have been enumerated. But this can also be simple objects of type T in which case they will be appended to the enumerable just like with append

Return Value

IEnumerable<T>

A dynamic composite enumerable.

Examples

const enumerable1 = IEnumerable.from([1, 2])
const enumerable2 = IEnumerable.from([3, 4])

console.log(enumerable1.concat(enumerable2).toArray()) // yields [1,2,3,4]

// single values can be used, too
console.log(enumerable1.concat(3, 4).toArray()) // yields [1,2,3,4]

// arrays are flattened
console.log(enumerable1.concat([5, 6], [7, 8]).toArray()) // now contains [1,2,5,6,7,8]

// works with arrays and array-like collections, too
console.log(enumerable1.concat([3, 4]).toArray()) // yields [1,2,3,4]

const list1 = List.fromArray([1, 2])
const list2 = List.fromArray([3, 4])

const result = list1.concat(list2)

console.log(result.toArray()) // yields [1,2,3,4]

list1.add(2.5)

// result changed also
console.log(result.toArray()) // yields [1,2,2.5,3,4]

list2.add(5)

// result changed also
console.log(result.toArray()) // yields [1,2,2.5,3,4,5]

See Also

API

append

array: T[]

The array to copy the elements to.

arrayIndex: number

The index in the given array where the first element should be copied to.

keySelector?: function(T): any

The optional function that determines the key to determine distinctness of the elements. If omitted, the element itself is used.

Function Details

Return Value

IEnumerable<T>

A new live view over the original enumerable that yields each element with a given key at most once.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 3, 4])

const result = enumerable.distinct()

console.log(result.toArray()) // yields [1,2,3,4]

See Also

API

HashMap

amount: number

The number of elements to drop from the beginning. If negative, the elements will be skipped from the end of the enumeration.

Return Value

IEnumerable<T>

A new live view over the original enumerable that drops amount elements.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4, 5, 6, 7])

const result = enumerable.drop(3)

console.log(result.toArray()) // yields [4,5,6,7]

See Also

API

dropWhile

predicate: function(T, number, IEnumerable<T>): boolean

The predicate function that determines what elements should be skipped. While the predicate yields true for the provided item, the element will not be yielded.

Function Details

Return Value

IEnumerable<T>

A new live view over the original enumerable that discards elements at the beginnging of the original enumeration while the predicate yields true.

Examples

const enumerable = IEnumerable.from([
  'a',
  'b',
  'c',
  'd',
  'a',
  'b',
  'c',
  'd',
])

const result = enumerable.dropWhile(
  (element) => element.charCodeAt(0) < 'c'.charCodeAt(0),
)

console.log(result.toArray()) // yields ["c", "d", "a", "b", "c", "d"]

See Also

API

take, takeWhile

predicate: function(T, number, IEnumerable<T>): boolean

A predicate function which returns true if the element matches a condition.

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

boolean

true if all elements of the enumerable match the given predicate, false otherwise.

Throws

Exception ({ name: 'ArgumentError' })

predicate is null.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4])

console.log(enumerable.every((item) => item < 5)) // true

console.log(enumerable.every((item) => item < 4)) // false

predicate: function(T, number, IEnumerable<T>): boolean

A predicate function which returns true if the given element should be included in the resulting enumerable.

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

IEnumerable<T>

A dynamic enumerable of the elements which match the given predicate.

Examples

const enumerable = IEnumerable.from([10, 2, 30, 4, 5, 6])

const result = enumerable.filter((item) => item < 5)

console.log(result.toArray()) // yields [2,4]

const list = List.fromArray([10, 2, 30, 4, 5, 6])

const result = list.filter((item) => item < 5)

list.add(1)

// result changed also
console.log(result.toArray()) // yields [2,4,1]

predicate: function(T, number, IEnumerable<T>): boolean

A type predicate function which returns true if the given element is of the desired type and should be included in the resulting enumerable. The signature of the predicate must include a type guard, for example

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined
}

Copy

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

IEnumerable<TResult>

A dynamic enumerable of the elements which match the given type guard.

Examples

const list = List.fromArray([1, 'a', 'b'])

list
  .filter(
    (item: string | number): item is string => typeof item === 'string',
  )
  .forEach((item: string) => console.log(item.toUpperCase())) // logs "A B"

predicate: function(T, number, IEnumerable<T>): boolean

A type predicate function which returns true if the given element is of the desired type and should be included in the resulting enumerable. The signature of the predicate must include a type guard, for example

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined
}

Copy

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

IEnumerable<T & TResult>

A dynamic enumerable of the elements which match the given type guard.

Examples

const list = List.fromArray([1, 'a', 'b'])

list
  .filter(
    (item: string | number): item is string => typeof item === 'string',
  )
  .forEach((item: string) => console.log(item.toUpperCase())) // logs "A B"

predicate: function(T, number, IEnumerable<T>): boolean

A predicate function which returns true if the given element should be returned.

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

T

The first element of this enumerable that matches the predicate or null if there is no such element.

Examples

const enumerable = IEnumerable.from([10, 2, 3, 9, 5, 6])

console.log(enumerable.find((item) => item < 5)) // yields 2

// no matches with the given predicate
console.log(enumerable.find((item) => item < 2)) // yields null

element: T

The element to search for in the list.

Return Value

ListCell<T>

the ListCell<T> that contains the element or null if no such ListCell<T> was found

predicate: function(T): boolean

The predicate used to evaluate each element in the list.

Function Details

Return Value

ListCell<T>

The ListCell<T> that contains the element or null if no such ListCell<T> was found

predicate: function(T, number, IEnumerable<T>): boolean

A predicate function which returns true if an item matches the search conditions.

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

number

The index of the first item for which predicate returns true or -1 if there is no such item in the enumerable.

predicate: function(T, number, IEnumerable<T>): boolean

A predicate function which returns true if the given element should be returned.

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

T

The last element of this enumerable that matches the predicate or null if there is no such element.

Examples

const enumerable = IEnumerable.from([10, 2, 3, 9, 5, 6])

console.log(enumerable.findLast((item) => item < 5)) // yields 3

// no matches with the given predicate
console.log(enumerable.findLast((item) => item < 2)) // yields null

predicate: function(T, number, IEnumerable<T>): boolean

A predicate function which returns true if an item matches the search conditions.

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

number

The index of the last item for which predicate returns true or -1 if there is no such item in the enumerable.

Return Value

T

The first matching element of this enumerable or null if nothing was found.

Examples

const enumerable = IEnumerable.from([10, 2, 3, 9, 5, 6])

console.log(enumerable.first()) // yields 10

// returns null for empty enumerable
const empty = IEnumerable.from([])
console.log(empty.first()) // yields null

See Also

API

at

selector: function(T, number, IEnumerable<T>): IEnumerable<TResult>

A function which returns an enumerable for each element of this enumerable.

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

IEnumerable<TResult>

A flattened dynamic enumerable of the enumerables provided for each element of this enumerable.

Examples

const enumerable = IEnumerable.from<number>([1, 2, 3])

const result = enumerable.flatMap((item) =>
  IEnumerable.from<number>([item, item * 2]),
)

console.log(result.toArray()) // yields [1,2,2,4,3,6]

const list = List.fromArray<number[]>([[1], [2], [3]])

const result = list.flatMap((item) =>
  IEnumerable.from<number>([item[0] * 2]),
)

list.add([4])

// result changed also
console.log(result.toArray()) // yields [2,4,6,8]

action: function(T, number, IEnumerable<T>): void

The function to call for each element.

Function Details

thisArg?: any

The optional object to use for this in the function.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4])

enumerable.forEach((item) => console.log(item)) // 1 2 3 4

// accessing the index
enumerable.forEach((item, index) =>
  console.log(`Item #${index} is ${item}`),
)

index: number

The zero-based index of the element to get or set.

Return Value

T

The element at the specified index.

See Also

API

set

index: number

The zero-based index of the cell in this list.

Return Value

ListCell<T>

The cell.

Throws

Exception ({ name: 'IndexOutOfRangeError' })

If the index is negative or greater or equal than the size

Return Value

ICursor<T>

A "cursor" for enumerating this list.

Return Value

IEnumerator<T>

An IEnumerator<T> that can be used to iterate through this collection.

keySelector: function(T, number, IEnumerable<T>): TKey

A function which selects from each element the key.

Function Details

resultCreator?: function(TKey, IEnumerable<T>, number): TResult

An optional function which transforms each group of elements and their common key into a resulting object. If omitted, the default implementation will create arrays of length 2 where the first element is the key and the second element is an IEnumerable<TSource> of the elements with the corresponding key.

Function Details

Return Value

IEnumerable<TResult>

An enumeration of groups of the original enumerable.

Examples

const enumerable = IEnumerable.from([
  { type: 'A', amount: 1 },
  { type: 'A', amount: 2 },
  { type: 'B', amount: 4 },
])

// without result creator
const groups1 = enumerable.groupBy<string, string>(
  (element) => element.type,
)

for (const g of groups1) {
  console.log(`Type is ${g[0]} and has ${g[1].length} members.`)
}
// Type is A and has 2 members.
// Type is B and has 1 members.

// with result creator
const groups2 = enumerable.groupBy(
  (element) => element.type,
  (type, elements) => ({
    type,
    amount: elements.sum((item) => item.amount),
  }),
)

console.log(groups2.toArray()) // yields [{"type":"A","amount":4},{"type":"B","amount":4}]

const val = IEnumerable.ofRange(1, 10)
  .groupBy(
    (value, index) => index % 2,
    (key, items, index) => [`key ${index % 2}`, items.toArray()],
  )
  .toArray()

// [
//   ["key 0",[1,3,5,7,9]],
//   ["key 1",[2,4,6,8,10]]
// ]

const enumerable: IEnumerable<{ value: number; key: string }> =
  IEnumerable.from([
    { value: 0, key: 'a' },
    { value: 1, key: 'b' },
    { value: 2, key: 'b' },
    { value: 3, key: 'a' },
  ])

const obj = Object.fromEntries(
  enumerable.groupBy(
    (item) => item.key,
    (key, items) => [key, items.toArray()],
  ) as Iterable<[unknown, unknown]>,
)

// {
//   a: [{value:0, key:a}, {value:3, key:a}],
//   b: [{value:1, key:b}, {value:2, key:b}]
// }

element: T

The element to locate in this list.

Return Value

boolean

true if the list contains the given element, false otherwise.

item: T

The item to search for.

fromIndex?: number

An optional start index for the search.

Return Value

number

The index of the given item in the enumerable. -1 if the item is not in the enumerable.

cell: ListCell<T>

The ListCell<T> whose index is to be found.

Return Value

number

The zero-based index of the given cell in this list, or -1 if the cell is not in the list.

index: number

The index that specifies the insertion position.

element: T

The element to insert.

element: T

The element to be inserted.

refCell: ListCell<T>

The list cell used to reference the position.

Return Value

ListCell<T>

The newly created ListCell{T} that stores the element.

element: T

The element to be inserted.

refCell: ListCell<T>

The list cell used to reference the position.

Return Value

ListCell<T>

The newly created ListCell<T> that stores the element.

cellToInsert: ListCell<T>

A list cell which is not part of any list.

refCell: ListCell<T>

The list cell used to reference the position.

cellToInsert: ListCell<T>

A list cell which is not part of any list.

refCell: ListCell<T>

The list cell used to reference the position.

Return Value

T

The last element of this enumerable, or null if the enumerable is empty.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4])
console.log(enumerable.last()) // yields 4

// if the enumerable is empty null will be returned
const empty = IEnumerable.from([])
console.log(empty.last()) // yields null

See Also

API

at

selector: function(T, number, IEnumerable<T>): TResult

A function which converts each element into a new element of the type TResult.

Function Details

thisArg?: any

The optional value to use as this when executing the selector.

Return Value

IEnumerable<TResult>

A dynamic enumerable of the results of the provided function.

Examples

const enumerable = IEnumerable.from([1, 2, 3])

const result = enumerable.map((item) => item * 2)

console.log(result.toArray()) // yields [2, 4, 6]

// with index
const result2 = enumerable.map((item, index) => item * index)

console.log(result2.toArray()) // yields [0, 2, 6]

// with index and enumerable
const result3 = enumerable.map(
  (item, index, enumerable) =>
    `Item no ${index} of ${enumerable.size} is ${item}`,
)

console.log(result3.toArray())
// ["Item no 0 of 3 is 1","Item no 1 of 3 is 2","Item no 2 of 3 is 3"]

const list = List.fromArray([1, 2, 3])

const result = list.map((item) => item * 2)

list.add(4)

// result changed also
console.log(result.toArray()) // yields [2,4,6,8]

resultType: typeof Number

The type of the elements of the result enumerable.

Return Value

IEnumerable<number>

A typed enumerable.

resultType: typeof String

The type of the elements of the result enumerable.

Return Value

IEnumerable<string>

A typed enumerable.

resultType: typeof Boolean

The type of the elements of the result enumerable.

Return Value

IEnumerable<boolean>

A typed enumerable.

resultType: Constructor<TResult>

The type of the elements of the result enumerable.

Return Value

IEnumerable<TResult>

A typed enumerable.

Return Value

T

The removed value. undefined if the list was empty.

items: T

The item(s) to prepend to the enumeration

Return Value

IEnumerable<T>

A new live view over the original enumerable that has items prepended to it.

Examples

const enumerable1 = IEnumerable.from([1, 2, 3, 4])
console.log(enumerable1.prepend(0).toArray()) // yields [0,1,2,3,4]

// more than one value can be used too
const enumerable2 = IEnumerable.from([3, 4, 5, 6])
console.log(enumerable2.prepend(1, 2).toArray()) // yields [1,2,3,4,5,6]

See Also

API

append

values: T

The values to append to the list.

Return Value

number

The new length of the list.

accumulator: function(T, T, number, IEnumerable<T>): T

A function which "adds" (accumulates) a value depending on the element and index to the initial value and returns the result.

Function Details

Return Value

T

The result of the accumulation.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4, 5])

const result = enumerable.reduce(
  (accumulator, currentValue) => accumulator + currentValue,
)

console.log(result) // expected output: 15

See Also

API

reduce, reduceRight

accumulator: function(TAccumulate, T, number, IEnumerable<T>): TAccumulate

A function which "adds" (accumulates) a value depending on the element and index to the initial value and returns the result.

Function Details

initialValue: TAccumulate

The initial value for the accumulator. Omit/use the reduce overload if you don't want to specify an initial value.

Return Value

TAccumulate

The result of the accumulation.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4, 5])

const result = enumerable.reduce(
  (accumulator, currentValue) => Math.max(accumulator, currentValue),
  0,
)

console.log(result) // expected output: 5

See Also

API

reduceRight

accumulator: function(T, T, number, IEnumerable<T>): T

A function which "adds" (accumulates) a value depending on the element and index to the seed value and returns the result.

Function Details

Return Value

T

The result of the accumulation.

Examples

const enumerable = IEnumerable.from([
  [0, 1],
  [2, 3],
  [4, 5],
])

const result = enumerable.reduceRight((accumulator, currentValue) =>
  accumulator.concat(currentValue),
)

console.log(result) // yields [4,5,2,3,0,1]

See Also

API

reduceRight, reduce

accumulator: function(TAccumulate, T, number, IEnumerable<T>): TAccumulate

A function which "adds" (accumulates) a value depending on the element and index to the seed value and returns the result.

Function Details

initialValue: TAccumulate

The initial value for the accumulator. Omit/use the reduceRight overload if you don't want to specify an initial value.

Return Value

TAccumulate

The final value of the accumulation.

Examples

const enumerable = IEnumerable.from(['a', 'b', 'c', 'd'])

const result = enumerable.reduceRight(
  (accumulator, currentValue) => currentValue + accumulator,
  '.',
)

console.log(result) // yields 'abcd.'

See Also

API

reduceRight, reduce

element: T

The element to be removed from the list.

Return Value

boolean

true if the element was found and removed; false if the element was not found in the list.

Complexity

collection: IEnumerable<T>

The collection of objects to be removed from the list.

Return Value

boolean

Whether there have been elements removed.

removeItemPredicate: function(T): boolean

The predicate used to determine which items to remove from the list.

Function Details

Return Value

boolean

Whether there have been elements removed.

index: number

The index of the item to remove.

c: ListCell<T>

The list cell to be removed.

Return Value

T

The element that is stored in the removed cell.

Complexity

removeItemPredicate?: function(T): boolean

The predicate used to determine which element to remove from the list. If null, the first element will be removed.

Function Details

Return Value

boolean

Whether there have been elements removed.

index: number

The zero-based index of the element to get or set.

value: T

The element at the specified index.

See Also

API

get

Return Value

T

The removed value. undefined if the list was empty.

predicate?: function(T, number, IEnumerable<T>): boolean

A function which returns true if the element matches a condition.

Function Details

thisArg?: any

The optional object to use for this in the function.

Return Value

boolean

Whether this enumerable contains any elements matching the given predicate.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4, 5, 6, 7])

const result = enumerable.some((item) => item % 2 === 0)

console.log(result) // true

comparator?: function(T, T): number

The comparison function to use for sorting the elements.

Function Details

Complexity

list: YList<T>

The list to transfer elements from.

Complexity

selector: function(T, number, IEnumerable<T>): number

A function which returns a numeric value for the given element.

Function Details

Return Value

number

The sum of the elements of the enumerable.

Examples

const enumerable = IEnumerable.from([
  { type: 'A', amount: 3 },
  { type: 'B', amount: 2 },
  { type: 'C', amount: 2 },
  { type: 'D', amount: 5 },
])

const result = enumerable.sum((element) => element.amount)

console.log(result) // yields 12

count: number

The number of elements in the created enumerable. If the number is positive, the elements are taken from the beginning, otherwise, the elements are taken from the end.

Return Value

IEnumerable<T>

A dynamic iew of this enumerable with the given number of elements.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4, 5, 6, 7])

// positive parameter means taking elements from the beginning of the enumerable
console.log(enumerable.take(2).toArray()) // yields [1,2]

// negative parameter means taking elements from the end of the enumerable
console.log(enumerable.take(-2).toArray()) // yields [6,7]

See Also

API

takeWhile, drop

predicate: function(T, number, IEnumerable<T>): boolean

A function which returns true as long as the elements should be added to the returned enumerable.

Function Details

Return Value

IEnumerable<T>

A dynamic enumerable that is a subset of the original enumerable.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 30, 4, 5])

const result = enumerable.takeWhile((item) => item < 5)

console.log(result.toArray()) // yields [1,2,3]

Return Value

T

An array with the elements of this enumerable.

Return Value

List<T>

A List<T> of the elements of this enumerable.

Return Value

IEnumerable<T>

A dynamic enumerable which contains the elements of the original enumerable in reverse order.

Examples

const enumerable = IEnumerable.from([1, 2, 3, 4, 5])

const result = enumerable.toReversed()

console.log(result.toArray()) // yields [5,4,3,2,1]

const list = List.fromArray([1, 2, 3, 4, 5])

const result = list.toReversed()

list.add(0)

// result changed also
console.log(result.toArray()) // yields [0,5,4,3,2,1]

comparator?: function(T, T): number

A function with the signature (a, b) => number which is used for the sort operation to compare the elements in the enumerable. May be omitted. If omitted, the elements are sorted by converting them to strings first. Numbers are sorted as numbers without converting them to strings (this is different to the EcmaScript implementation).

Function Details

Return Value

IEnumerable<T>

A sorted enumeration of the original enumerable.

Examples

const enumerable = IEnumerable.from([
  { type: 'name-6', rank: 8 },
  { type: 'name-23', rank: 4 },
  { type: 'name-3', rank: 5 },
])

// order by the elements' rank
const sortedEnumerable1 = enumerable.toSorted(
  (entryA, entryB) => entryA.rank - entryB.rank,
)

console.log(sortedEnumerable1.toArray())
// [{ "type": "name-23", "rank": 4 }, { "type": "name-3", "rank": 5 }, { "type": "name-6", "rank": 8 }]

// order by the elements' type using numeric collation to get a more "natural" order, with a comparer function
const collator = new Intl.Collator(undefined, {
  numeric: true,
  sensitivity: 'base',
})
const sortedEnumerable2 = enumerable.toSorted((entryA, entryB) =>
  collator.compare(entryA.type, entryB.type),
)

console.log(sortedEnumerable2.toArray())
// [{ "type": "name-3", "rank": 5 }, { "type": "name-6", "rank": 8 },{ "type": "name-23", "rank": 4 }]