Collection0.26.3

Overview
Properties
Methods

abstract external class Collection<out Element> extends Any

Common base class for List and Set.

Known subtypes:
Known usages:
All versions:

The following operators are supported for all collections:

coll1 + coll2  // concatenation; result type is `Set` if `coll1` is a set and `List` otherwise

Additionally, the following operators are supported for Lists:

coll[3]    // subscript

Properties

link

abstract
length: Int

The number of elements in this collection.

Also known as:

size, count
Facts:
```
List(1, 2, 3).length == 3
List().length == 0
```
link

abstract
isEmpty: Boolean

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

abstract
first: Element

The first element in this collection.

Also known as:

head
Throws if this collection is empty.

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

abstract

firstOrNull: Element?

Same as first but returns null if this collection is empty.

Also known as:

head
link

abstract
rest: Collection<Element>

The tail of this collection.

Also known as:

tail
Throws if this collection is empty.

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

abstract

restOrNull: Collection<Element>?

Same as rest but returns null if this collection is empty.

Also known as:

tail
link

abstract
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

abstract

lastOrNull: Element?

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

abstract
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

abstract

singleOrNull: Element?

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

abstract

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

abstract

minOrNull: Element?

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

abstract

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

abstract

maxOrNull: Element

Same as max but returns null if this collection empty.

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

abstract function
contains(element: Element): 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

abstract 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

abstract 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

abstract function

split(index: Int): Pair<Collection<Element>, Collection<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

abstract function

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

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

abstract function

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

abstract 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

abstract function

indexOfOrNull(element: Any): Int?

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

abstract 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

abstract function

lastIndexOfOrNull(element: Any): Int?

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

abstract 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

abstract function

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

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

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

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

abstract function

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

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

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

The index of the first element for which predicate returns true.

Also known as:

indexWhere
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

abstract function

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

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

Also known as:

indexWhere
link

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

The index of the last element for which predicate returns true.

Also known as:

lastIndexWhere
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

abstract function

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

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

Also known as:

lastIndexWhere
link

abstract 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

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

Tests whether predicate holds for every element in this collection.

Also known as:

all, forall
Facts:
```
List(1, 3, 3).every((n) -> n.isOdd)
List().every((n) -> n.isOdd)
!List(1, 2, 3).every((n) -> n.isOdd)
```
link

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

Tests whether predicate holds for at least one element in this collection.

Also known as:

exists
Facts:
```
List(1, 2, 3).any((n) -> n.isEven)
!List(1, 2, 3).any((n) -> n.isEven)
!List().any((n) -> n.isEven)
```
link

abstract function
filter(predicate: (Element) -> Boolean): Collection<Element>

Retains elements for which predicate holds.

Also known as:

findAll, where
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

abstract function

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

Retains non-null elements.

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

link

abstract function

filterIndexed(predicate: (Int, Element) -> Boolean): Collection<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

abstract function
filterIsInstance<Type>(clazz: Class): Collection<Type>

Retains elements whose class is a subclass of clazz.

Also known as:

whereType
Shorthand for filter((it) -> it is X).

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

abstract function
map<Result>(transform: (Element) -> Result): Collection<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

abstract function
mapIndexed<Result>(transform: (Int, Element) -> Result): Collection<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

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

Transforms this collection by applying transform to each element and removing resulting null elements.

Also known as:

filterMap
Equivalent to map(transform).filterNonNull().

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

abstract function

flatMap<Result>(transform: (Element) -> Collection<Result>): Collection<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

abstract function

flatMapIndexed<Result>(transform: (Int, Element) -> Collection<Result>): Collection<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

abstract function

flatten(): Collection

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

Throws if any element is not a collection.
link

abstract function

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

Adds element to this collection.

For List, element is appended.
link

abstract function

take(n: Int): Collection<Element>

Returns the first n elements in this collection.

Also known as:

limit
link

abstract function

takeLast(n: Int): Collection<Element>

Returns the last n elements in this collection.
link

abstract function

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

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

abstract function

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

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

abstract function

drop(n: Int): Collection<Element>

Removes the first n elements in this collection.

Also known as:

skip
link

abstract function

dropLast(n: Int): Collection<Element>

Removes the last n elements in this collection.

Also known as:

skipLast
link

abstract function

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

Removes the longest prefix of this collection that satisfies predicate.

Also known as:

skipWhile
link

abstract function

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

Removes the longest suffix of this collection that satisfies predicate.

Also known as:

skipLastWhile
link

abstract function

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

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

abstract function

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

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

Also known as:

foldRight
link

abstract 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

abstract 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

abstract function

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

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

abstract function

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

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

abstract function

repeat(n: UInt): Collection<Element>

Concatenates this collection n times.
link

abstract 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

abstract function

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

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

abstract 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

abstract function

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

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

abstract 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

abstract function

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

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

abstract function

maxWith(comparator: (Element, Element) -> (Boolean|Int)): 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

abstract function

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

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

abstract 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

abstract function

sortBy(selector: (Element) -> Comparable): Collection<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

abstract function
sortWith(comparator: (Element, Element) -> (Boolean|Int)): Collection<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

abstract function

reverse(): Collection<Element>

Reverses the order of elements in this collection.
link

abstract function
zip<Other>(coll: Collection<Other>): Collection<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

transpose(): Collection

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

abstract function

join(separator: String): String

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

abstract function

toList(): List<Element>

Converts this collection to a list.

Returns this collection if it already is a list.
link

abstract function

toSet(): Set<Element>

Converts this collection to a set.

Returns this collection if it already is a set.
link

abstract 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

abstract function

toListing(): Listing<Element>

Converts this collection to a Listing.
link

abstract function

toDynamic(): Dynamic

Converts this collection to a Dynamic object.