List0.27.0

Overview
Properties
Methods

external class List<out Element> extends Collection<Element>

An indexed sequence of elements.

Known subtypes:
Known usages:
All versions:

The following operators are supported for lists:

list[3]       // subscript
list1 + list2 // concatenation

Properties(show inherited)

link
length: Int

The number of elements in this collection.
Facts:
```
List(1, 2, 3).length == 3
List().length == 0
```
link
isEmpty: Boolean

Tells whether this collection is empty.
Facts:
```
!List(1, 2, 3).isEmpty
List().isEmpty
```
link
first: Element

The first element in this collection.
Throws if this collection is empty.

Facts:
```
List(1, 2, 3).first == 1
import("pkl:test").catch(() -> List().first)
```
link

firstOrNull: Element?

Same as first but returns null if this collection is empty.
link
rest: List<Element>

The tail of this collection.
Throws if this collection is empty.

Facts:
```
List(1, 2, 3).rest == List(2, 3)
import("pkl:test").catch(() -> List().rest)
```
link

restOrNull: List<Element>?

Same as rest but returns null if this collection is empty.
link
last: Element

The last element in this collection.
Throws if this collection is empty.

Facts:
```
List(1, 2, 3).last == 3
import("pkl:test").catch(() -> List().last)
```
link

lastOrNull: Element?

Same as last but returns null if this collection is empty.
link
single: Element

The single element in this collection.
Throws if this collection has zero or more than one element.

Facts:
```
List(1).single == 1
throws(() -> List().single)
throws(() -> List(1, 2, 3).single)
```
link

singleOrNull: Element?

Same as single but returns null if this collection is empty or has more than one element.
link

min: Element

Returns the first element in this collection that is less than or equal to any other element.

Shorthand for minWith((a, b) -> a < b).

Throws if this collection is empty, or if any two elements cannot be compared with <.
link

minOrNull: Element

Same as min but returns null if this collection is empty.
link

max: Element

Returns the first element in this collection that is greater than or equal to any other element.

Shorthand for maxWith((a, b) -> a < b).

Throws if this collection is empty, or if any two elements cannot be compared with <.
link

maxOrNull: Element?

Same as max but returns null if this collection empty.
link

lastIndex: Int

The index of the last element in this list (same as length - 1).

Returns -1 for an empty list.
link
isDistinct: Boolean

Tells whether this list contains no duplicate elements.

Also known as:

isUnique
Equivalent to length == toSet().length.

Facts:
```
List(1, 2, 3).isDistinct
!List(1, 2, 1).isDistinct
```
link
distinct: List<Element>

Removes duplicate elements from this list, preserving the first occurrence of each element.

Also known as:

unique
Equivalent to toSet().toList().

Facts:
```
List(1, 2, 3).distinct == List(1, 2, 3)
List(1, 2, 1).distinct == List(1, 2)
```

Methods(show inherited)

link

function

Any.getClass(): Class (pkl.base)

Returns the class of this.
link

function

Any.toString(): String (pkl.base)

Returns a string representation of this.

This method is used to convert the values of string interpolation expressions to strings.
link

function

Any.ifNonNull<Result>(transform: (NonNull) -> Result): Result? (pkl.base)

Returns this |> transform if this is non-null, and null otherwise.

This method is the complement of the ?? operator and the equivalent of an Option type's map and flatMap methods.

link

function

contains(element: Any): Boolean

Tests if element is contained in this collection.

Facts:

List(1, 2, 3).contains(1)
List(1, 2, 3).contains(2)
List(1, 2, 3).contains(3)
!List(1, 2, 3).contains(4)

link

function
startsWith(coll: Collection<Any>): Boolean

Tests if this collection starts with the elements in coll.
Facts:
```
List(1, 2, 3).startsWith(List(1, 2))
List(1, 2, 3).startsWith(List())
!List(1, 2, 3).startsWith(List(2, 3))
```
link

function
endsWith(coll: Collection<Any>): Boolean

Tests if this collection ends with the elements in coll.
Facts:
```
List(1, 2, 3).endsWith(List(2, 3))
List(1, 2, 3).endsWith(List())
!List(1, 2, 3).endsWith(List(1, 2))
```
link

function

split(index: Int): Pair<List<Element>, List<Element>>

Splits this collection into two at split point index.

If index is zero or length, one of the two collections is empty. Throws if index is outside range 0..length.
link

function

splitOrNull(index: Int): Pair<List<Element>, List<Element>>?

Same as split() but returns null if index is outside range 0..length.
link

function

partition(predicate: (Element) -> Boolean): Pair<List<Element>, List<Element>>
link

function
indexOf(element: Any): Int

The zero-based index of the first occurrence of element in this collection.
Throws if this collection does not contains element.

Facts:
```
List(1, 2, 3).indexOf(2) == 1
List(1, 2, 2).indexOf(2) == 1
import("pkl:test").catch(() -> List(1, 2, 3).indexOf(4))
```
link

function

indexOfOrNull(element: Any): Int?

Same as indexOf() but returns null if this collection does not contain element.
link

function
lastIndexOf(element: Any): Int

The zero-based index of the last occurrence of element in this collection.
Throws if this collection does not contain element.

Facts:
```
List(1, 2, 3).lastIndexOf(2) == 1
List(1, 2, 2).lastIndexOf(2) == 2
import("pkl:test").catch(() -> List(1, 2, 3).lastIndexOf(4))
```
link

function

lastIndexOfOrNull(element: Any): Int?

Same as lastIndexOf() but returns null if this collection does not contain element.
link

function
find(predicate: (Element) -> Boolean): Element

The first element for which predicate returns true.
Throws if predicate does not hold for any element in this collection.

Facts:
```
List(5, 6, 7).find((n) -> n.isEven) == 6
List(4, 6, 7).find((n) -> n.isEven) == 4
import("pkl:test").catch(() -> List(5, 7, 9).find((n) -> n.isEven))
```
link

function

findOrNull(predicate: (Element) -> Boolean): Element?

Same as find() but returns null if predicate does not hold for any element in this collection.
link

function
findLast(predicate: (Element) -> Boolean): Element

The last element for which predicate returns true.
Throws if predicate does not hold for any element in this collection.

Facts:
```
List(5, 6, 7).findLast((n) -> n.isEven) == 6
List(4, 6, 8).findLast((n) -> n.isEven) == 8
List(5, 7, 9).findLast((n) -> n.isEven) == null
```
link

function

findLastOrNull(predicate: (Element) -> Boolean): Element?

Same as findLast() but returns null if predicate does not hold for any element in this collection.
link

function
findIndex(predicate: (Element) -> Boolean): Int

The index of the first element for which predicate returns true.
Throws if predicate does not hold for any element in this collection.

Facts:
```
List(5, 6, 7).findIndex((n) -> n.isEven) == 1
List(4, 6, 8).findIndex((n) -> n.isEven) == 0
import("pkl:test").catch(() -> List(5, 7, 9).findLast((n) -> n.isEven))
```
link

function

findIndexOrNull(predicate: (Element) -> Boolean): Int?

Same as findIndex() but returns null if predicate does not hold for any element in this collection.
link

function
findLastIndex(predicate: (Element) -> Boolean): Int

The index of the last element for which predicate returns true.
Throws if predicate does not hold for any element in this collection.

Facts:
```
List(5, 6, 7).findLastIndex((n) -> n.isEven) == 1
List(4, 6, 8).findLastIndex((n) -> n.isEven) == 2
import("pkl:test").catch(() -> List(5, 7, 9).findLastIndex((n) -> n.isEven))
```
link

function

findLastIndexOrNull(predicate: (Element) -> Boolean): Int?

Same as findLastIndex() but returns null if predicate does not hold for any element in this collection.

link

function

count(predicate: (Element) -> Boolean): Int

The number of elements for which predicate returns true.

Facts:

List(1, 2, 3).count((n) -> n.isEven) == 1
List(1, 2, 3).count((n) -> n.isOdd) == 2
List(1, 2, 3).count((n) -> n > 9) == 0

link

function
every(predicate: (Element) -> Boolean): Boolean

Tests whether predicate holds for every element in this collection.
Facts:
```
List(1, 3, 3).every((n) -> n.isOdd)
List().every((n) -> n.isOdd)
!List(1, 2, 3).every((n) -> n.isOdd)
```
link

function
any(predicate: (Element) -> Boolean): Boolean

Tests whether predicate holds for at least one element in this collection.
Facts:
```
List(1, 2, 3).any((n) -> n.isEven)
!List(1, 2, 3).any((n) -> n.isEven)
!List().any((n) -> n.isEven)
```

link

function

filter(predicate: (Element) -> Boolean): List<Element>

Retains elements for which predicate holds.

Facts:

List(1, 2, 3).filter((n) -> n.isOdd) == List(1, 3)
List(1, 2, 3).filter((n) -> n.isEven) == List(2)
List(1, 2, 3).filter((n) -> n > 9) == List()

link

function

filterNonNull(): List<Element(this != null)>

Retains non-null elements.

Shorthand for filter((it) -> it != null).

link

function

filterIndexed(predicate: (Int, Element) -> Boolean): List<Element>

Retains elements for which predicate holds.

predicate takes two arguments: the index of the element, and the element itself.

Facts:

List(1, 2, 3).filterIndexed((i, n) -> i.isOdd) == List(2)
List(1, 2, 3).filterIndexed((i, n) -> i.isEven) == List(1, 3)
List(1, 2, 3).filterIndexed((i, n) -> i.isOdd && n > 2) == List()
List(1, 2, 3).filterIndexed((i, n) -> i.isEven && n > 2) == List(3)

link

function
filterIsInstance<Type>(clazz: Class): List<Type>

Retains elements whose class is a subclass of clazz.
Shorthand for filter((it) -> it is X).

Facts:
```
List(42, "Pigeon", true, "Parrot").filterIsInstance(String) == List("Pigeon", "Parrot")
```
link

function
map<Result>(transform: (Element) -> Result): List<Result>

Transforms this collection by applying transform to each element.
Facts:
```
List(1, 2, 3).map((n) -> n * 2) == List(2, 4, 6)
List(1, 2, 3).map((n) -> n.isEven) == List(false, true, false)
```
link

function
mapIndexed<Result>(transform: (Int, Element) -> Result): List<Result>

Transforms this collection by applying transform to each element.
transform takes two arguments: the index of the element, and the element itself.

Facts:
```
List(1, 2, 3).mapIndexed((i, n) -> n * i) == List(0, 2, 6)
List(1, 2, 3).mapIndexed((i, n) -> i.isOdd && n.isEven) == List(false, true, false)
```
link

function
mapNonNull<Result>(transform: (Element) -> Result): List<Result(this != null)>

Transforms this collection by applying transform to each element and removing resulting null elements.
Equivalent to map(transform).filterNonNull().

Facts:
```
List(1, 2, 3).mapNonNull((n) -> if (n.isOdd) null else n + 2) == List(4)
```
link

function

flatMap<Result>(transform: (Element) -> Collection<Result>): List<Result>

Applies a collection-generating transform to each element in this collection and concatenates the resulting collections.

Throws if transform produces a non-collection value.
link

function

flatMapIndexed<Result>(transform: (Int, Element) -> Collection<Result>): List<Result>

Applies a collection-generating transform to each element in this collection and concatenates the resulting collections.

transform takes two arguments: the index of the element, and the element itself.

Throws if transform produces a non-collection value.
link

function

flatten(): List

Concatenates the elements in this collection, each of which must itself be a collection.

Throws if any element is not a collection.
link

function

add<Other>(element: Other): List<(Element|Other)>

Adds element to this collection.

For List, element is appended.
link

function

take(n: Int): List<Element>

Returns the first n elements in this collection.
link

function

takeLast(n: Int): List<Element>

Returns the last n elements in this collection.
link

function

takeWhile(predicate: (Element) -> Boolean): List<Element>

Returns the longest prefix of this collection that satisfies predicate.
link

function

takeLastWhile(predicate: (Element) -> Boolean): List<Element>

Returns the longest suffix of this collection that satisfies predicate.
link

function

drop(n: Int): List<Element>

Removes the first n elements in this collection.
link

function

dropLast(n: Int): List<Element>

Removes the last n elements in this collection.
link

function

dropWhile(predicate: (Element) -> Boolean): List<Element>

Removes the longest prefix of this collection that satisfies predicate.
link

function

dropLastWhile(predicate: (Element) -> Boolean): List<Element>

Removes the longest suffix of this collection that satisfies predicate.
link

function

fold<Result>(initial: Result, operator: (Result, Element) -> Result): Result

Folds this collection in iteration order using operator, starting with initial.
link

function

foldBack<Result>(initial: Result, operator: (Element, Result) -> Result): Result

Folds this collection in reverse iteration order using operator, starting with initial.
link

function

foldIndexed<Result>(initial: Result, operator: (Int, Result, Element) -> Result): Result

Folds this collection in iteration order using operator, starting with initial.

The first parameter of operator is the zero-based index of the current element.
link

function

reduce<Result>(operator: ((Element|Result), Element) -> Result): Result

Folds this collection in iteration order using operator, starting with the first element.

Throws if this collection is empty.
link

function

reduceOrNull<Result>(operator: ((Element|Result), Element) -> Result): Result?

Same as reduce() but returns null if this collection is empty.
link

function

groupBy<Key>(selector: (Element) -> Key): Map<Key, List<Element>>

Groups the elements in this collection according to keys returned by selector.
link

function

repeat(n: Int): List<Element>

Concatenates this collection n times.
link

function

minBy(selector: (Element) -> Comparable): Element

Returns the first element in this collection that is less than or equal to any other element after applying selector.

Shorthand for minWith((a, b) -> selector.apply(a) < selector.apply(b)).

Throws if this collection is empty or if any two elements cannot be compared with <.
link

function

minByOrNull(selector: (Element) -> Comparable): Element?

Same as minBy() but returns null if this collection is empty.
link

function

minWith(comparator: (Element, Element) -> Boolean): Element

Returns the first element in this collection that is less than or equal to any other element according to comparator.

comparator should return true if its first argument is less than its second argument, and false otherwise.

Throws if this collection is empty.
link

function

minWithOrNull(comparator: (Element, Element) -> Boolean): Element?

Same as minWith() but returns null if this collection is empty.
link

function

maxBy(selector: (Element) -> Comparable): Element

Returns the first element in this collection that is greater than or equal to any other element after applying selector.

Shorthand for maxWith((a, b) -> selector.apply(a) < selector.apply(b)).

Throws if this collection is empty, or if any two elements cannot be compared with < after applying selector.
link

function

maxByOrNull(selector: (Element) -> Comparable): Element?

Same as maxBy() but returns null if this collection is empty.
link

function

maxWith(comparator: (Element, Element) -> Boolean): Element

Returns the first element in this collection that is greater than or equal to any other element according to comparator.

comparator should return true if its first argument is less than its second argument, and false otherwise.

Throws if this collection is empty.
link

function

maxWithOrNull(comparator: (Element, Element) -> Boolean): Element?

Same as maxWith() but returns null if this collection is empty.
link

function

sort(): List<Element>

Sorts this collection of Comparable elements in ascending order.

Shorthand for sortWith((a, b) -> a < b).

Throws if any two elements in this collection cannot be compared with <.
link

function

sortBy(selector: (Element) -> Comparable): List<Element>

Sorts this collection in ascending order after applying selector.

Shorthand for sortWith((a, b) -> selector.apply(a) < selector.apply(b)).

Throws if any two elements in this collection cannot be compared with < after applying selector.
link

function
sortWith(comparator: (Element, Element) -> Boolean): List<Element>

Sorts this collection according to comparator.
comparator should return true if its first argument comes before its second argument in the sort order, and false otherwise.

Facts:
```
List(1, 2, 3).sortWith((a, b) -> a > b)) == List(3, 2, 1)
```
link

function

reverse(): List<Element>

Reverses the order of elements in this collection.
link

function
zip<Other>(coll: Collection<Other>): List<Pair<Element, Other>>

Returns a collection that combines corresponding elements of this and coll in pairs.
The returned collection's length is the minimum of this.length and coll.length.

Facts:
```
List(1, 2, 3).zip(List(4, 5, 6)) == List(Pair(1, 4), Pair(2, 5), Pair(3, 6))
List(1, 2, 3).zip(List(4, 5, 6, 7, 8)) == List(Pair(1, 4), Pair(2, 5), Pair(3, 6))
```
link

abstract function

Collection.transpose(): Collection (pkl.base)

Transposes this two-dimensional collection of collections.

The nth row of the resulting collection corresponds to the nth column of this collection. Throws if an element of this collection is not itself a collection.
link

function

join(separator: String): String

Converts the elements of this collection to strings and concatenates them inserting separator between elements.
link

function

toList(): List<Element>

Converts this collection to a list.

Returns this collection if it already is a list.
link

function

toSet(): Set<Element>

Converts this collection to a set.

Returns this collection if it already is a set.
link

function

toMap<Key, Value>(keyExtractor: (Element) -> Key, valueExtractor: (Element) -> Value): Map<Key, Value>

Converts this collection to a map by extracting a key and value from each element using the given functions.
link

function

toListing(): Listing<Element>

Converts this collection to a Listing.
link

function

toDynamic(): Dynamic

Converts this collection to a Dynamic object.

link

function

getOrNull(index: Int): Element?

Returns the element at index.

Returns null if index is outside the bounds of this list.

Facts:

List(3, 9, 6).getOrNull(0) == 3
List(3, 9, 6).getOrNull(1) == 9
List(3, 9, 6).getOrNull(2) == 6
List(3, 9, 6).getOrNull(-1) == null
List(3, 9, 6).getOrNull(3) == null
List(3, 9, 6).getOrNull(99) == null

link

function

sublist(start: Int, exclusiveEnd: Int): List<Element>

Returns the sublist from start until exclusiveEnd.

Throws if start is outside range 0..length or exclusiveEnd is outside range start..length.

Facts:

List(3, 9, 6).sublist(0, 1) == List(3)
List(3, 9, 6).sublist(0, 2) == List(3, 9)
List(3, 9, 6).sublist(1, 3) == List(9, 6)
List(3, 9, 6).sublist(0, 3) == List(3, 9, 6)
List(3, 9, 6).sublist(-1, 2) // error
List(3, 9, 6).sublist(1, 4)  // error
List(3, 9, 6).sublist(9, 99) // error

link

function

sublistOrNull(start: Int, exclusiveEnd: Int): List<Element>?

Returns the sublist from start until exclusiveEnd.

Returns null if start is outside range 0..length or exclusiveEnd is outside range start..length.

Facts:

List(3, 9, 6).sublistOrNull(0, 1) == List(3)
List(3, 9, 6).sublistOrNull(0, 2) == List(3, 9)
List(3, 9, 6).sublistOrNull(1, 3) == List(9, 6)
List(3, 9, 6).sublistOrNull(0, 3) == List(3, 9, 6)
List(3, 9, 6).sublistOrNull(-1, 2) == null
List(3, 9, 6).sublistOrNull(1, 4) == null
List(3, 9, 6).sublistOrNull(9, 99) == null

link

function
isDistinctBy(selector: (Element) -> Any): Boolean

Tells whether this list contains no duplicate elements after applying selector.

Also known as:

isUniqueBy
Facts:
```
List("a", "b", "abc").isDistinctBy((it) -> it.length)
!List("a", "ab", "c").isDistinctBy((it) -> it.length)
```
link

function
distinctBy(selector: (Element) -> Any): List<Element>

Removes elements that are duplicates after applying selector from this list, preserving the first occurrence.

Also known as:

uniqueBy
Facts:
```
List("a", "b", "abc").distinctBy((it) -> it.length) == List("a", "b", "abc")
List("a", "ab", "c").distinctBy((it) -> it.length) == List("a", "ab")
```
link

function

replace<Other>(index: Int, replacement: Other): List<(Element|Other)>

Replaces the element at index with replacement.

Throws if index is outside the bounds of this list.
link

function

replaceOrNull<Other>(index: Int, replacement: Other): List<(Element|Other)>?

Replaces the element at index with replacement.

Returns null if index is outside the bounds of this list.
link

function

replaceRange<Other>(start: Int, exclusiveEnd: Int, replacement: Collection<Other>): List<(Element|Other)>

Replaces the elements between indices range and exclusiveEnd with replacement.

Throws if range or exclusiveEnd is outside the bounds of this list.
link

function

replaceRangeOrNull<Other>(start: Int, exclusiveEnd: Int, replacement: Collection<Other>): List<(Element|Other)>?

Replaces the elements between indices range and exclusiveEnd with replacement.

Returns null if range or exclusiveEnd is outside the bounds of this list.