List

filter

<function> Returns a copy of the list of elements filtered according to the predicate.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

predicate - (T) -> Boolean - the filter function applied to each element of the list

Returns

List<T> - a copy of the list containing those elements of the list for which the filter function returns true. The returned values retain their order.

Usage

listOf<Number>().filter(function(x: Number) -> x < 3) == listOf<Number>()

listOf(4, 3, 2, 1).filter(function(x: Number) -> x < 3) == listOf(2, 1)

findFirstOrNone

<function> Returns the first element of the list for which the predicate returns true. Returns an empty optional None if no such element exists.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

predicate - (T) -> Boolean - the filter function applied to each element of the list

Returns

Optional<T> - the first element for which the predicate is true, or an empty optional None if no such element exists

Usage

listOf(6, 3, 2, -2, 10).findFirstOrNone(function(x: Number) -> x < 3) == optionalOf<Number>(2)

listOf(5, 6, 7).findFirstOrNone(function(x: Number) -> x < 3) == optionalOf<Number>()

firstOrNone

<function> Returns an optional of the first element of the list, if any.

Receiver

List<T>

Type Arguments

T - the element type

Returns

Optional<T> - an optional of the first item on the list, or an empty optional None if the list is empty.

Usage

listOf(1, 2).firstOrNone() == optionalOf<Number>(1)

listOf<Number>().firstOrNone() == optionalOf<Number>()

get

<function> Returns the element at index in the list, the first element having index 0. If index is negative or greater than or equal to the list size, a run-time error is thrown.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

index - Number

Returns

T - the element at the index

Usage

listOf(4, 3, 2, 1).get(3) == 1

head

<function> Returns a copy of the list without its last element. The head of an empty list is an empty list. This method does not modify the original list.

Receiver

List<T>

Type Arguments

T - the element type

Returns

List<T> - a copy of the list with the last element removed

Usage

listOf<Number>().head() == listOf<Number>()

listOf(4, 3, 2, 1).head() == listOf(4, 3, 2)

listOf(4, 3, 2, 1).head() == listOf(4, 3, 2, 1).withoutAt(3)

indexOfOrNone

<function> Returns the index of the first occurrence of element in the list. The index of the first element is 0. If the list does not contain element, it returns an empty optional None.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

element - T

Returns

Optional<Number> - index of the first occurrence of element in the array, or empty optional None if the list doesn't contain the element

Usage

listOf(4, 3, 2, 1).indexOfOrNone(3).getOrElse(-1) == 1

listOf(4, 3, 2, 1).indexOfOrNone(5).isPresent() == false

lastOrNone

<function> Returns an Optional<T> of the last item on the list, or an empty optional None if the list is empty.

Receiver

List<T>

Type Arguments

T - the element type

Returns

Optional<T> - the last element of the list, or an empty optional None if the list is empty

Usage

listOf(1, 2).lastOrNone() == optionalOf<Number>(2)

listOf<Number>().lastOrNone() == optionalOf<Number>()

plus

<function> Creates and returns a new List which is a copy of the original one concatenated with the provided list. This method does not modify the original list.

Receiver

List<T>

Type Arguments

T - the elemnt type

Arguments

other - List<T> - the list to concatenate to this one

Returns

List<T> - a new list which contains the concatenation of other to this

Usage

This method also has an infix operator, +.

listOf<Number>() + listOf(4, 3, 2, 1) == listOf(4, 3, 2, 1)

listOf<Number>().plus(listOf(4, 3, 2, 1)) == listOf(4, 3, 2, 1)

listOf(4, 3, 2, 1) + listOf<Number>() == listOf(4, 3, 2, 1)

listOf(4, 3, 2, 1) + listOf(5, 6) + listOf(3, 3) == listOf(4, 3, 2, 1, 5, 6, 3, 3)

reverse

<function> Returns a reversed copy of the list. This method does not modify the original list.

Receiver

List<T>

Type Arguments

T - the element type

Returns

List<T> - a reversed copy of the list

Usage

listOf<Number>().reverse() == listOf<Number>()

listOf(4, 2, 3, 1).reverse() == listOf(1, 3, 2, 4)

takeFirst

<function> Takes the first n items of this List. If n is larger than the List's size, then the entire collection is returned. Otherwise, the first n elements are returned.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

n - Number - the number of items to take, must be greater than or equal to 0

Returns

List<T> - the first n values in the List, sorted by their original insertion order.

Usage

listOf(2, 3, 1).takeFirst(2)

takeLast

<function> Takes the last n items of this List. If n is larger than the List's size, then the entire collection is returned. Otherwise, the last n elements are returned.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

n - Number - the number of items to take, must be greater than or equal to 0

Returns

List<T> - the last n values in the List, sorted by their original insertion order.

Usage

listOf(2, 3, 1).takeLast(2)

sort

<function>

Receiver

List<Number>

Returns

List<Number>

Usage

sort() returns a List<Type> that sorts the list of List<Type> according to its natural ordering (available for List<Text> and List<Number>).

listOf<Number>().sort() == listOf<Number>()

listOf(1, 3, 2).sort() == listOf(1, 2, 3)

sortBy

<function> Returns a copy of the list sorted according to the comparator function. This method does not modify the original list.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

comparator - (T, T) -> Number

Returns

List<T> - a copy of the list sorted according to the comparator

Usage

listOf<Number>().sortBy(function(a: Number, b: Number) -> if (a < b) -1 else if (a > b) 1 else 0)
== listOf<Number>()

listOf(4, 3, 2, 1).sortBy(function(a: Number, b: Number) -> if (a < b) -1 else if (a > b) 1 else 0)
== listOf(1, 2, 3, 4)

tail

<function> Returns a copy of the list without its first element. The tail of an empty list is an empty list. This method does not modify the original list.

Receiver

List<T>

Type Arguments

T - the element type

Returns

List<T> - a copy of the list with the first element removed

Usage

listOf<Number>().tail() == listOf<Number>()

listOf(4, 3, 2, 1).tail() == listOf(3, 2, 1)

listOf(4, 3, 2, 1).tail() == listOf(4, 3, 2, 1).withoutAt(0)

toSet

<function> Converts a list into a set of the same type with the same values and removed duplicates.

Receiver

List<T>

Type Arguments

T - the element type

Returns

Set<T> - a set containing all elements of the list

Usage

listOf(1, 2, 3, 2, 4).toSet() == setOf(1, 2, 3, 4)

toMap

<function> Converts a List of Pairs into a Map of the same types.

Receiver

List<Pair<S, T>>

Type Arguments

S - , T the element types of the Pairs

T

Returns

Map<S, T> - a Map with key S and value T containing all pair elements of the List.

Usage

listOf(Pair("1", 1), Pair("2", 2)).toMap() == mapOf(Pair("1", 1), Pair("2", 2))

with

<function> Creates and returns a new List which is a copy of the original one with the provided element inserted at the end of the list. This method does not modify the original list.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

element - T - the element to be added

Returns

List<T> - a copy of the list with element added to the end

Usage

listOf(4, 3, 2, 1).with(5) == listOf(4, 3, 2, 1, 5)

listOf<Number>().with(7) == listOf(7)

withAt

<function> Creates and returns a new List which is a copy of the original one with the provided element inserted at a particular position in the list. This method does not modify the original list. A run-time error is thrown if index is greater than or equal to the size of the list.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

element - T - the element to be added

index - Number - the position where the element is to be added

Returns

List<T> - a copy of the list where element is inserted at position index of the list.

Usage

A run-time error is thrown if index is greater than or equal to the size of the list.

listOf(4, 3, 2, 1).withAt(5, 1) == listOf(4, 5, 3, 2, 1)

withIndex

<function> Creates and returns a new List which wraps each element of the original list into an IndexedElement containing the index of that element and the element itself. Ordering of list elements is preserved, the index of the first element is 0. This method does not modify the original list.

Receiver

List<T>

Type Arguments

T - the element type

Returns

List<IndexedElement<T>> - a copy of the list, providing sequential index with the element.

Usage

listOf("a", "b", "c").withIndex()
== listOf(
    IndexedElement<Text>(0, "a"),
    IndexedElement<Text>(1, "b"),
    IndexedElement<Text>(2, "c")
)

without

<function> Creates and returns a new List which is a copy of the original one with the first occurrence of the provided element removed. This method does not modify the original list. If the list doesn't contain the element, it returns the original list.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

element - T - to be removed

Returns

List<T> - a copy of the list where the first occurrence of element, if any, is removed from the list.

Usage

listOf(4, 3, 2, 1).without(5) == listOf(4, 3, 2, 1)

listOf(4, 3, 2, 1, 4).without(4) == listOf(3, 2, 1, 4)

withoutAt

<function> Creates and returns a new List which is a copy of the original one with the element in a particular index removed from the list. This method does not modify the original list. A run-time error is thrown if index is greater than or equal to the size of the list.

Receiver

List<T>

Type Arguments

T - the element type

Arguments

index - Number - the position of the element to be removed

Returns

List<T> - a copy of the list where the element at index index is removed.

Usage

listOf(4, 3, 2, 1).withoutAt(1) == listOf(4, 2, 1)

zipOrFail

<function> Creates and returns a new List formed from the original list and the other list by combining corresponding elements in pairs. This method does not modify the original list. The length of the other list must match the receiver lists length, otherwise a run-time error is thrown.

Receiver

List<T>

Type Arguments

T - the element type of the receiver list

U - the element type of the other list

Arguments

other - List<U> - the list providing the second half of each result pair

Returns

List<Pair<T, U>> - a new list containing pairs consisting of corresponding elements of this list and other list.

Usage

listOf(1, 2).zipOrFail(listOf("odd", "even"))
== listOf(Pair(1, "odd"), Pair(2, "even"))

allMatch

<function> Determines whether the predicate is true for all elements in the collection. allMatch on an empty collection returns true.

Receiver

Collection<T>

Type Arguments

T - the element type

Arguments

predicate - (T) -> Boolean - The predicate tested on the elements of the collection

Returns

Boolean - true if predicate returns true for all elements in the collection, false otherwise

Usage

listOf<Number>().allMatch(function(x: Number) -> x < 3) == true

listOf(4, 3, 2, 1).allMatch(function(x: Number) -> x < 3) == false

listOf(2, 1).allMatch(function(x: Number) -> x < 3) == true

anyMatch

<function> Determines whether the predicate is true for at least one element in the collection. anyMatch on an empty collection returns false.

Receiver

Collection<T>

Type Arguments

T - the element type

Arguments

predicate - (T) -> Boolean - The predicate tested on the elements of the collection

Returns

Boolean - true if predicate returns true for any element in the collection, false otherwise

Usage

listOf<Number>().anyMatch(function(x: Number) -> x < 3) == false

listOf(4, 3, 2, 1).anyMatch(function(x: Number) -> x < 3) == true

listOf(4, 3).anyMatch(function(x: Number) -> x < 3) == false

asList

<function> Converts a collection into a list with the same values, if needed. It creates a new List when the collection is a Set. It is a no-op when the collection is a List.

Receiver

Collection<T>

Type Arguments

T - the element type

Returns

List<T> - a list of the values in the collection, sorted by their original insertion order.

Usage

listOf(2, 3, 1).asList() == listOf(2, 3, 1)

contains

<function> Determines whether the collection contains the given element.

Receiver

Collection<T>

Type Arguments

T - the element type

Arguments

element - T - The element to be searched in the collection.

Returns

Boolean - true if element is in the collection, false otherwise

Usage

listOf<Text>().contains("abc") == false

listOf(4, 3, 2, 1).contains(3) == true

listOf(4, 3, 2, 1).contains(5) == false

flatMap

<function> Applies the given function to each element of the original collection, producing a collection of U for each, and then build a result list of U from the elements of these collections. Note that, irrespective of whether the function passed to flatMap returns a set or a list, the result of flatMap is always a list.

Receiver

Collection<T>

Type Arguments

T - the element type

U - the result type

Arguments

transformer - (T) -> Collection<U> - A function transforming each element of the original collection into a collection of results.

Returns

List<U> - a list of all elements returned by the transformer function

Usage

listOf(1, 2, 3).flatMap(function(x: Number) -> listOf(x, x * x))
== listOf(1, 1, 2, 4, 3, 9)

listOf(1, 2, 3).flatMap(function(x: Number) -> setOf(x, x * x))
== listOf(1, 2, 4, 3, 9)

flatten

<function> When applied to a collection whose elements are themselves collections, returns a list where the elements are the elements of those collections. Attempting to apply flatten() to a collection whose elements are not collections will result in a compile time error.

Receiver

Collection<Collection<T>>

Type Arguments

T - the element type

Returns

List<T> - list of all elements contained in elements of the original collection

Usage

listOf(listOf(1, 2), listOf(3, 4, 5)).flatten() == listOf(1, 2, 3, 4, 5)

listOf(setOf(1, 2), setOf(3, 4, 5)).flatten() == listOf(1, 2, 3, 4, 5)

fold

<function> Folds collection items into an accumulated value, starting with the initial value as its accumulator. It requires a lambda with two inputs, the first of which matches the type of the initial, and the second matches the type of the collection elements.

Receiver

Collection<T>

Type Arguments

T - the element type

U - the result type

Arguments

initval - U - the initial value of the accumulator

transformer - (U, T) -> U - the transforming function that updates the accumulator with a new value.

Returns

U - the value of accumulator after applying the transformer to each element of the collection

Usage

listOf(9, 10, 1).fold(0, function(acc: Number, elem: Number) -> acc + elem)
== 20 // equivalent to sum()

listOf(9, 10, 1).fold("", function(acc: Text, elem: Number) returns Text -> acc + elem.toText())
== "9101"

forEach

<function> Applies a function to each element of a collection in the collection's order. Ignores the return value of the action.

Receiver

Collection<T>

Type Arguments

T - the element type

U - the result type (ignored)

Arguments

action - (T) -> U - the function to call on each element

Usage

protocol[p] ForEachProtocol() {
    var localList: List<Number> = listOf<Number>();

    permission[p] forEachPerm(inputs: List<Number>)  {
        inputs.forEach(function(n: Number) returns Unit -> {
            localList = localList.with(n * 2);
        });
    };
};

isEmpty

<function> Determines if the collection contains no elements.

Receiver

Collection<T>

Type Arguments

T - the element type

Returns

Boolean - true if the size of the collection is 0, otherwise returns false.

Usage

listOf(4, 3, 2, 1).isEmpty() == false

listOf<Number>().isEmpty() == true

isNotEmpty

<function> Determines if the collection contains any elements.

Receiver

Collection<T>

Type Arguments

T - the element type

Returns

Boolean - false if the size of the collection is 0, otherwise returns true.

Usage

listOf(4, 3, 2, 1).isNotEmpty() == true

listOf<Number>().isNotEmpty() == false

map

<function> Applies a transformation function on each element of the collection and returns a list of results.

Receiver

Collection<T>

Type Arguments

T - the element type

U - the return type of the transformer

Arguments

transformer - (T) -> U - the transformation function applied to each element

Returns

List<U> - a list where the elements of the original collection are converted using transformer

Usage

listOf<Number>().map(function(x: Number) -> (2*x - 0.5).roundTo(0))
== listOf<Number>()

listOf(4.0, 3.5, 2, 1).map(function(x: Number) -> (2*x - 0.5).roundTo(0))
== listOf(8, 7, 4, 2)

noneMatch

<function> Determines whether the predicate is false for all elements in the collection. noneMatch on an empty collection returns true.

Receiver

Collection<T>

Type Arguments

T - the element type

Arguments

predicate - (T) -> Boolean - The predicate tested on the elements of the collection

Returns

Boolean - true if predicate returns false for all elements in the collection, false otherwise

Usage

listOf<Number>().noneMatch(function(x: Number) -> x < 3) == true

listOf(5, 4).noneMatch(function(x: Number) -> x < 3) == true

listOf(2, 1).noneMatch(function(x: Number) -> x < 3) == false

size

<function> Gets the size of the collection.

Receiver

Collection<T>

Type Arguments

T - the element type

Returns

Number - the number of elements in the collection

Usage

listOf<Number>().size() == 0

listOf(5, 2, 3, 8).size() == 4

sum

<function> Returns the sum of all numbers in the collection. sum() applied to an empty collection returns 0.

Receiver

Collection<Number>

Returns

Number - the total of all numbers in the collection

Usage

listOf<Number>().sum() == 0

listOf(4, 3, 2, 1).sum() == 10

listOf(4.0, 3.0, 2.0, 1.1).sum() == 10.1