List<T>

Show usages

Default implementation of IList<T>.

Inheritance Hierarchy

List

Implemented Interfaces

Remarks

This implementation provides fast random indexed access. However, removing or adding elements from the beginning or in the middle of the list will be slower.

Type Parameters

T: The type of the list's elements.

Type Details

yFiles module: core

Constructors

List

()

Creates a new instance.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

items - T[]: An array of items which are added to this list. Each item will be added via the add method.

List

(enumerable: IEnumerable<T>, mapFunction?: function(T, number, IEnumerable<T>):T)

Creates a new instance and fills it with the elements of the given enumerable.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

enumerable - IEnumerable<T>

The enumerable to fill the list with.

mapFunction - function(T, number, IEnumerable<T>):T

The optional function to call for each element to map the generate the elements in the newly created list. The first argument is the element, the second one the index and the third one is the enumerable itself (after possible conversion).

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : T

The selector to use for the IEnumerable<T>.

A function which returns a result of type TResult for each element.

Parameters

element - T: The current element create a result for.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

T: A result of type TResult created from the element.

Properties

isReadOnly

: boolean

Whether this collection is read-only.

Implements

ICollection

size

: number

The number of elements in this collection.

Overrides

IEnumerable.size

Methods

add

(item: T)

Adds the given item to the collection.

Implements

ICollection

addRange

(enumerable: IEnumerable<T>)

Adds the elements of the given collection to this list.

Parameters

options - Object
A map of options to pass to the method.

enumerable - IEnumerable<T>: The collection to add.

append

(items: T…) : IEnumerable<T>

Creates a wrapped enumerable that has one or several elements appended to it.

Remarks

In contrast to concat, this method will not treat the items any special if they are array-like or enumerable-like.

Parameters

options - Object
A map of options to pass to the method.

items - T: The item(s) to prepend to the enumeration

Returns

↪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]

Overrides

IEnumerable.append

at

(index: number) : T

Returns the element at the given index in this enumerable.

Remarks

This is modeled after the Array.prototype.at function, with the important difference, that null will be returned instead of undefined in the case of an invalid index.

Parameters

options - Object
A map of options to pass to the method.

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.

Returns

↪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')

Overrides

IEnumerable.at

clear

()

Removes all items from this collection.

Implements

ICollection

concat

(elements: any…) : IEnumerable<T>

Concatenates this enumerable with the given other elements in a new dynamic IEnumerable<T>.

Remarks

The returned enumerable is dynamic, in other words, if elements are added or removed from one of the original enumerables, the returned enumerable changes, too. If you want to store the current state of the concatenation, create a list or array of it.

Parameters

options - Object
A map of options to pass to the method.

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

Returns

↪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]

The returned enumerable is dynamic

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]

Overrides

IEnumerable.concat

copyTo

(array: T[], arrayIndex: number)

Copies all elements of this collection into the given array.

Parameters

options - Object
A map of options to pass to the method.

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.

Implements

ICollection

copyWithin

(target: number, begin?: number, end?: number) : List<T>

Shallow copies part of this list to another location in the same list and returns it.

Remarks

This function mimics the JavaScript Array.copyWithin() function, but returns a List<T> instead of an array.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

target - number: Index at which to copy the sequence to. If negative target will be counted from the end.
begin - number: Index at which to start copying from, 0 if omitted. If negative begin will be counted from the end.
end - number: The index of the element after the last element at which to end copying elements from. Defaults to the length of this list. If negative end will be counted from the end.

Returns

↪List<T>: A new, shallow, independent copy of this list.

distinct

(keySelector?: function(T):any) : IEnumerable<T>

Creates a wrapped enumerable that yields each element only once.

Remarks

To determine equality between objects that implement a yFiles type, equals and hashCode methods are used if present.

Parameters

options - Object
A map of options to pass to the method.

keySelector - function(T):any

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

Signature Details

function(element: T) : any

A function which creates a key for the given element.

Parameters

element - T: The element to get the key for.

Returns

any: The key for the element.

Returns

↪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]

Overrides

IEnumerable.distinct

drop

(amount: number) : IEnumerable<T>

Creates a wrapped view of an enumerable which drops the given amount of elements.

Parameters

options - Object
A map of options to pass to the method.

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

Returns

↪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]

Overrides

IEnumerable.drop

dropWhile

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

Creates a wrapped view of an enumerable which skips a number of elements at the beginning while the given predicate yields true.

Remarks

While the predicate yields true for the elements of the original enumerable, the elements are skipped. The new enumeration will start with the first element for which the predicate yields false. All subsequent elements will be yielded.

Parameters

options - Object
A map of options to pass to the method.

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.

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

Returns

↪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"]

Overrides

IEnumerable.dropWhile

every

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

Determines whether every element of the enumerable matches the given predicate.

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

↪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

Overrides

IEnumerable.every

fill

(value: T, start?: number, end?: number) : List<T>

Fills the elements in this list from the start to the end index with value.

Remarks

This function mimics the JavaScript Array.fill() function and returns this.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

value - T: The value to fill the elements with
start - number: The index of the first cell in the list to fill with the value. 0 if not provided and size+start if negative.
end - number: The index after the last cell in the list to fill with the value. size-1 if not provided and size+end if negative.

Returns

↪List<T>: The list itself for method chaining.

filter

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

Returns a dynamic IEnumerable<T> of the elements of this enumerable which match the given predicate.

Remarks

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

↪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]

The returned enumerable is dynamic

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]

Overrides

IEnumerable.filter(yfiles.collections.ElementPredicate,any)

filter

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

Returns a dynamic IEnumerable<T> of the elements of this enumerable which match the given type guard.

Remarks

Type Parameters

TResult: The type of the elements of the returned enumerable. Is equivalent to the type of the type predicate

Parameters

options - Object
A map of options to pass to the method.

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
}

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

↪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"

Defined in

IEnumerable

filter

<TResult>(predicate: function(T, number, IEnumerable<T>):boolean, thisArg?: any) : IEnumerable<T & TResult>

Returns a dynamic IEnumerable<T> of the elements of this enumerable which match the given type guard.

Remarks

Type Parameters

TResult: The type of the elements of the returned enumerable. Is equivalent to the type of the type predicate

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

↪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"

Defined in

IEnumerable

find

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

Returns the first element of the enumerable that matches a given predicate or null if there is no such element.

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

↪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

Overrides

IEnumerable.find

findIndex

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

Searches the enumerable for the first item for which predicate returns true and returns its index.

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

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

Overrides

IEnumerable.findIndex

findLast

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

Returns the last element of the enumerable that matches a given predicate or null if there is no such element.

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

↪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

Overrides

IEnumerable.findLast

findLastIndex

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

Searches the enumerable for the last item for which predicate returns true and returns its index.

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

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

Overrides

IEnumerable.findLastIndex

first

() : T

Returns the first element of this enumerable.

Returns

↪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

Overrides

IEnumerable.first

flatMap

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

Returns a flattened dynamic IEnumerable<T> of this enumerable using the given selector function which returns an enumerable for each element of this enumerable.

Remarks

Type Parameters

TResult: The type of the elements of the result enumerable.

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : IEnumerable<TResult>

The selector to use for the IEnumerable<T>.

A function which returns a result of type IEnumerable<T> for each element.

Parameters

element - T: The current element create a result for.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

IEnumerable<TResult>: A result of type of TResult created from the element.

thisArg - any

The optional object to use for this in the function.

Returns

↪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]

The returned enumerable is dynamic

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]

Overrides

IEnumerable.flatMap

forEach

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

Iterates this enumerable and invokes the given function for each element with the element, its index, and this enumerable as arguments.

Parameters

options - Object
A map of options to pass to the method.

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

The function to call for each element.

Signature Details

function(element: T, index: number, source: IEnumerable<T>)

An action to execute for each element of an IEnumerable<T>.

Parameters

element - T: The current element.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

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}`),
)

Overrides

IEnumerable.forEach

get

(index: number) : T

Gets the item at the given index.

Parameters

options - Object
A map of options to pass to the method.

index - number: The index of the item to access.

Returns

↪T: The item at the given index.

Throws

Exception({ name: 'ArgumentError' }): index is not a valid index in this enumerable.

Implements

IListEnumerable

getEnumerator

() : IEnumerator<T>

Gets an IEnumerator<T> which can be used to enumerate the items this instance represents.

Remarks

This is the low-level API that needs to be implemented by all enumerables. Clients will only have to use this API, rarely, as iteration is more conveniently handled by the forEach method or using the iterable (for(let item of enumerable){}) protocol.

Returns

↪IEnumerator<T>: The IEnumerator<T> which can be used to iterate over the items in this instance

Implements

IEnumerable

groupBy

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

Groups the elements in the enumerable according to the equality of a key.

Remarks

For each element in the original enumerable the keySelector will be used to retrieve a key. All elements with the same key will be provided to the optional resultCreator function that receives both the key, and an IEnumerable<T> of the elements that match that key to create a resulting object that will be yielded by this enumerable. Note that the resulting enumerable does not necessarily preserve the order of the (first) appearance of their elements in the original sequence. The elements of each group passed to the resultCreator are in the order of their original appearance.

Type Parameters

TKey: The type of the key elements.
TResult: The type of the created elements.

Parameters

options - Object
A map of options to pass to the method.

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

A function which selects from each element the key.

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : TKey

A function which creates a key for the given element.

Parameters

element - T: The element to get the key for.
index - number: The index of the element in the underlying .
source - IEnumerable<T>: The underlying

Returns

TKey

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.

Signature Details

function(key: TKey, group: IEnumerable<T>, index: number) : TResult

A function which transforms a group of elements and their common key into a resulting object.

Parameters

key - TKey: The key of the provided group.
group - IEnumerable<T>: The group of elements with the given key.
index - number: The index of the group.

Returns

TResult: A resulting object for the given group with the given key.

Returns

↪IEnumerable<TResult>: An enumeration of groups of the original enumerable.

Examples

A simple groupBy example

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

groupBy with index

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]]
// ]

Using groupBy to create an object

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}]
// }

This implementation differs from the TC39 proposal for array grouping. See the example "Using groupBy to create an object" to mimic the proposal's groupBy behavior.

Overrides

IEnumerable.groupBy

includes

(item: T) : boolean

Whether the given item is contained in this collection.

Parameters

options - Object
A map of options to pass to the method.

item - T: The item to search for.

Returns

↪boolean: true if the given item is contained in this collection.

Overrides

IEnumerable.includes

indexOf

(item: T, fromIndex?: number) : number

The index of the given item in the enumerable.

Parameters

options - Object
A map of options to pass to the method.

item - T: The item to search for.
fromIndex - number: An optional start index for the search.

Returns

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

Overrides

IEnumerable.indexOf

insert

(index: number, item: T)

Inserts the given item at the given index.

Parameters

options - Object
A map of options to pass to the method.

index - number: The index to insert the item at.
item - T: The item to insert.

Implements

IList

last

() : T

Returns the last element of this enumerable.

Returns

↪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

Overrides

IEnumerable.last

map

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

Returns a dynamic IEnumerable<T> of this enumerable using the given selector function which returns a new object for each element of this enumerable.

Remarks

Type Parameters

TResult: The type of the mapped elements.

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : TResult

The selector to use for the IEnumerable<T>.

A function which returns a result of type TResult for each element.

Parameters

element - T: The current element create a result for.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

TResult: A result of type TResult created from the element.

thisArg - any

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

Returns

↪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"]

The returned enumerable is dynamic

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]

Overrides

IEnumerable.map

ofType

(resultType: typeof Number) : IEnumerable<number>

Converts this untyped enumerable into an enumerable with the given type.

Remarks

The source enumerable may contain elements which are not of the given type. Those elements will not be contained in the returned enumerable.

Parameters

options - Object
A map of options to pass to the method.

resultType - typeof Number: The type of the elements of the result enumerable.

Returns

↪IEnumerable<number>: A typed enumerable.

Overrides

IEnumerable.ofType(number)

ofType

(resultType: typeof String) : IEnumerable<string>

Converts this untyped enumerable into an enumerable with the given type.

Remarks

The source enumerable may contain elements which are not of the given type. Those elements will not be contained in the returned enumerable.

Parameters

options - Object
A map of options to pass to the method.

resultType - typeof String: The type of the elements of the result enumerable.

Returns

↪IEnumerable<string>: A typed enumerable.

Overrides

IEnumerable.ofType(string)

ofType

(resultType: typeof Boolean) : IEnumerable<boolean>

Converts this untyped enumerable into an enumerable with the given type.

Remarks

The source enumerable may contain elements which are not of the given type. Those elements will not be contained in the returned enumerable.

Parameters

options - Object
A map of options to pass to the method.

resultType - typeof Boolean: The type of the elements of the result enumerable.

Returns

↪IEnumerable<boolean>: A typed enumerable.

Overrides

IEnumerable.ofType(boolean)

ofType

<TResult>(resultType: Constructor<TResult>) : IEnumerable<TResult>

Converts this untyped enumerable into an enumerable with the given type.

Remarks

The source enumerable may contain elements which are not of the given type. Those elements will not be contained in the returned enumerable.

Type Parameters

TResult: The type of the elements of the result enumerable.

Parameters

options - Object
A map of options to pass to the method.

resultType - Constructor<TResult>: The type of the elements of the result enumerable.

Returns

↪IEnumerable<TResult>: A typed enumerable.

Overrides

IEnumerable.ofType(Constructor)

pop

() : T

Removes and returns the last value in this list.

Remarks

This function mimics the JavaScript Array.pop() function and returns undefined if the list is empty.

Returns

↪T: The removed value. undefined if the list was empty.

Defined in

IList

prepend

(items: T…) : IEnumerable<T>

Creates a wrapped enumerable that has on or several elements prepended to it.

Parameters

options - Object
A map of options to pass to the method.

items - T: The item(s) to prepend to the enumeration

Returns

↪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]

Overrides

IEnumerable.prepend

push

(values: T…) : number

Adds one or more elements to this list and returns the new length.

Remarks

This function mimics the JavaScript Array.push() function.

Parameters

options - Object
A map of options to pass to the method.

values - T: The values to append to the list.

Returns

↪number: The new length of the list.

Defined in

IList

reduce

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

Applies the accumulator function to this elements of this enumerable.

Type Parameters

TAccumulate: The type of the accumulated value.

Parameters

options - Object
A map of options to pass to the method.

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.

Signature Details

function(total: TAccumulate, element: T, index: number, source: IEnumerable<T>) : TAccumulate

The accumulator to use for the IEnumerable<T>.

A function which returns a result of type TAccumulate as an accumulation of total and element.

Parameters

total - TAccumulate: The previously returned value of the function.
element - T: The current element to accumulate.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

TAccumulate: A result of type TAccumulate created from the element.

initialValue - TAccumulate

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

Returns

↪TAccumulate: The result of the accumulation.

Examples

The returned enumerable is dynamic

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

Overrides

IEnumerable.reduce(yfiles.collections.Accumulator,TAccumulate)

reduce

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

Applies the accumulator function to this elements of this enumerable.

Parameters

options - Object
A map of options to pass to the method.

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.

Signature Details

function(total: T, element: T, index: number, source: IEnumerable<T>) : T

The accumulator to use for the IEnumerable<T>.

A function which returns a result of type TAccumulate as an accumulation of total and element.

Parameters

total - T: The previously returned value of the function.
element - T: The current element to accumulate.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

T: A result of type TAccumulate created from the element.

Returns

↪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

Overrides

IEnumerable.reduce(yfiles.collections.Accumulator)

reduceRight

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

Applies the accumulator function to this elements of this enumerable in reverse order.

Type Parameters

TAccumulate: The type of the accumulated value.

Parameters

options - Object
A map of options to pass to the method.

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.

Signature Details

function(total: TAccumulate, element: T, index: number, source: IEnumerable<T>) : TAccumulate

The accumulator to use for the IEnumerable<T>.

A function which returns a result of type TAccumulate as an accumulation of total and element.

Parameters

total - TAccumulate: The previously returned value of the function.
element - T: The current element to accumulate.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

TAccumulate: A result of type TAccumulate created from the element.

initialValue - TAccumulate

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

Returns

↪TAccumulate: The final value of the accumulation.

Examples

The returned enumerable is dynamic

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

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

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

Overrides

IEnumerable.reduceRight(yfiles.collections.Accumulator,TAccumulate)

reduceRight

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

Applies the accumulator function to this elements of this enumerable in reverse order.

Parameters

options - Object
A map of options to pass to the method.

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.

Signature Details

function(total: T, element: T, index: number, source: IEnumerable<T>) : T

The accumulator to use for the IEnumerable<T>.

A function which returns a result of type TAccumulate as an accumulation of total and element.

Parameters

total - T: The previously returned value of the function.
element - T: The current element to accumulate.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

T: A result of type TAccumulate created from the element.

Returns

↪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]

Overrides

IEnumerable.reduceRight(yfiles.collections.Accumulator)

remove

(item: T) : boolean

Removes the given item from this collection.

Parameters

options - Object
A map of options to pass to the method.

item - T: The item to remove.

Returns

↪boolean: Whether the item was removed from the collection.

Implements

ICollection

removeAll

(match: function(T):boolean) : number

Removes all elements for which match returns true.

Parameters

options - Object
A map of options to pass to the method.

match - function(T):boolean

A predicate function with the signature function(o:object):boolean which returns true if o matches the conditions of the element to search for.

Signature Details

function(obj: T) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - T: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

Returns

↪number: The number of elements which were removed.

removeAt

(index: number)

Removes the item at the given index from the list.

Parameters

options - Object
A map of options to pass to the method.

index - number: The index of the item to remove.

Implements

IList

removeRange

(index: number, count: number)

Removes a given count of elements starting from the given index .

Parameters

options - Object
A map of options to pass to the method.

index - number: The index of the first element to remove.
count - number: The number of elements to remove.

reverse

()

Reverses the order of the elements in this list.

set

(index: number, value: T)

Sets the item at the given index.

Parameters

options - Object
A map of options to pass to the method.

index - number: The index of the item to access.
value - T: The item at the given index.

Implements

IList

shift

() : T

Removes and returns the first value in this list.

Remarks

This function mimics the JavaScript Array.shift() function and returns undefined if the list is empty.

Returns

↪T: The removed value. undefined if the list was empty.

Defined in

IList

slice

(begin?: number, end?: number) : List<T>

Returns a shallow copy of a portion of this list in the form of a new and independent list.

Remarks

This function mimics the JavaScript Array.slice() function, but returns a List<T> instead of an array.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

begin - number: The start index for the copy, 0 if omitted
end - number: The index of the element after the last element that will be copied. If omitted, the

Returns

↪List<T>: A new, shallow, independent copy of this list.

some

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

Determines whether this enumerable contains any elements matching the given predicate.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

thisArg - any

The optional object to use for this in the function.

Returns

↪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

Overrides

IEnumerable.some

sort

(comparator?: function(T, T):number)

Sorts all elements in the list using an optional comparator function.

Parameters

options - Object
A map of options to pass to the method.

comparator - function(T, T):number

The optional comparison function to use. If no comparison function is provided, the elements are sorted by their natural order. Always provide a comparison function for lists containing a mixture of primitive values and other objects. Otherwise, the behavior is undefined.

Signature Details

function(value1: T, value2: T) : number

Compares the given values.

Parameters

value1 - T: The first value to compare.
value2 - T: The second value to compare.

Returns

number: A value less than 0 if value 1 is smaller than value2, 0 if both values are equal, greater than 0 otherwise.

splice

(start: number, deleteCount?: number, items: T…) : List<T>

Alters the contents of this list like JavaScript's Array.splice() method.

Remarks

This function mimics the JavaScript Array.splice() function, but returns a List<T> instead of an array.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

start - number: The index into the list at which elements should be removed and inserted.
deleteCount - number: The number of items to remove starting at start. If omitted all elements after start will be removed.
items - T: The items to insert. If omitted, no items will be added.

Returns

↪List<T>: The elements that have been removed in the form of a List<T>.

sum

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

Calculates the sum of the elements of this enumerable.

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : number

The selector to use for the IEnumerable<T>.

A function which returns a result of type TResult for each element.

Parameters

element - T: The current element create a result for.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

number: A result of type TResult created from the element.

Returns

↪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

Overrides

IEnumerable.sum

take

(count: number) : IEnumerable<T>

Creates a dynamic view of this enumerable with the given number of elements taken from the start or end of this enumerable.

Parameters

options - Object
A map of options to pass to the method.

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.

Returns

↪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]

Overrides

IEnumerable.take

takeWhile

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

Returns a dynamic IEnumerable<T> that contains the elements from this enumerable as long as the given predicate is true.

Remarks

Parameters

options - Object
A map of options to pass to the method.

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

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

Signature Details

function(element: T, index: number, source: IEnumerable<T>) : boolean

The predicate to use for IEnumerable<T>.

Parameters

element - T: The current element to test.
index - number: The element's index in the
source - IEnumerable<T>: The enumerable this function is called upon.

Returns

boolean: true if the item matches the condition.

Returns

↪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]

Overrides

IEnumerable.takeWhile

toArray

() : T

Creates an array with the elements of this enumerable.

Returns

↪T[]: An array with the elements of this enumerable.

Overrides

IEnumerable.toArray

toList

() : List<T>

Creates a List<T> with the values of this enumerable.

Returns

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

Overrides

IEnumerable.toList

toReversed

() : IEnumerable<T>

Returns an dynamic enumerable which contains the elements of this enumerable in reverse order.

Remarks

Returns

↪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]

The returned enumerable is dynamic

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]

Overrides

IEnumerable.toReversed

toSorted

(comparator?: function(T, T):number) : IEnumerable<T>

Yields an ordered enumerable of the elements given an optional comparison function.

Remarks

The sorting will happen each time the enumerable is enumerated.

Parameters

options - Object
A map of options to pass to the method.

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

Signature Details

function(value1: T, value2: T) : number

Compares the given values.

Parameters

value1 - T: The first value to compare.
value2 - T: The second value to compare.

Returns

number: A value less than 0 if value 1 is smaller than value2, 0 if both values are equal, greater than 0 otherwise.

Returns

↪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 }]

Overrides

IEnumerable.toSorted

unshift

(values: T…) : number

Adds one or more elements to the beginning of this list and returns the new length.

Remarks

This function mimics the JavaScript Array.unshift() function.

Parameters

options - Object
A map of options to pass to the method.

values - T: The values to prepend to this list. The first argument will become the new first element in the list

Returns

↪number: The new length of the list.

Defined in

IList

Static Methods

from

<TSource,T>(enumerable: IEnumerable<TSource>, mapFunction?: function(TSource, number, IEnumerable<TSource>):T, thisArg?: any) : List<T>

Creates a new list similar in behavior to Array.from().

Type Parameters

TSource
T: The type of the list's elements.

Parameters

options - Object
A map of options to pass to the method.

enumerable - IEnumerable<TSource>

The enumerable to fill the list with.

mapFunction - function(TSource, number, IEnumerable<TSource>):T

The optional function to call for each element to map the generate the elements in the newly created list

Signature Details

function(element: TSource, index: number, source: IEnumerable<TSource>) : T

The selector to use for the IEnumerable<T>.

A function which returns a result of type TResult for each element.

Parameters

element - TSource: The current element create a result for.
index - number: The element's index in the
source - IEnumerable<TSource>: The enumerable this function is called upon.

Returns

T: A result of type TResult created from the element.

thisArg - any

The optional object to use for this in the function.

Returns

↪List<T>: A new List<T> initialized with the values of the given enumerable.

fromArray

<T>(array: T[]) : List<T>

Creates a new list with the given array used as the live backing store.

Remarks

Modifying the list or the array will modify both instances.

Type Parameters

T: The type of the list's elements.

Parameters

options - Object
A map of options to pass to the method.

array - T[]: The array to create a list view over from.

Returns

↪List<T>: A list backed by the given array.

List<T>

Remarks

Type Parameters

Type Details

Constructors

List

ParametersOptions Overload

List

ParametersOptions Overload

Signature Details

Parameters

Returns

Properties

isReadOnly

Implements

size

Overrides

Methods

add

Implements

addRange

Parameters

append

Remarks

Parameters

Returns

Examples

See Also

Overrides

at

Remarks

Parameters

Returns

Examples

Overrides

clear

Implements

concat

Remarks

Parameters

Returns

Examples

See Also

Overrides

copyTo

Parameters

Implements

copyWithin

Remarks

ParametersOptions Overload

Returns

distinct

Remarks

Parameters

Signature Details

Parameters

Returns

Returns

Examples

See Also

Overrides

drop

Parameters

Returns

Examples

See Also

Overrides

dropWhile

Remarks

Parameters

Signature Details

Parameters

Returns

Returns

Examples

See Also

Overrides

every

Parameters

Signature Details