Sequence

A sequence that returns values through its iterator. The values are evaluated lazily, and the sequence is potentially infinite.

Sequences can be iterated multiple times, however some sequence implementations might constrain themselves to be iterated only once. That is mentioned specifically in their documentation (e.g. generateSequence overload). The latter sequences throw an exception on an attempt to iterate them the second time.

Sequence operations, like Sequence.map, Sequence.filter etc, generally preserve that property of a sequence, and again it's documented for an operation if it doesn't.

Since Kotlin

1.0

Parameters

the type of elements in the sequence.

Inheritors

FileTreeWalk

Functions

all

inline fun <T> Sequence<T>.all(predicate: (T) -> Boolean): Boolean

Returns true if all elements match the given predicate.

Since Kotlin 1.0

any

fun <T> Sequence<T>.any(): Boolean

Returns true if sequence has at least one element.

Since Kotlin 1.0

inline fun <T> Sequence<T>.any(predicate: (T) -> Boolean): Boolean

Returns true if at least one element matches the given predicate.

Since Kotlin 1.0

asIterable

fun <T> Sequence<T>.asIterable(): Iterable<T>

Creates an Iterable instance that wraps the original sequence returning its elements when being iterated.

Since Kotlin 1.0

asSequence

inline fun <T> Sequence<T>.asSequence(): Sequence<T>

Returns this sequence as a Sequence.

Since Kotlin 1.0

associate

inline fun <T, K, V> Sequence<T>.associate(transform: (T) -> Pair<K, V>): Map<K, V>

Returns a Map containing key-value pairs provided by transform function applied to elements of the given sequence.

Since Kotlin 1.0

associateBy

inline fun <T, K> Sequence<T>.associateBy(keySelector: (T) -> K): Map<K, T>

Returns a Map containing the elements from the given sequence indexed by the key returned from keySelector function applied to each element.

Since Kotlin 1.0

inline fun <T, K, V> Sequence<T>.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, V>

Returns a Map containing the values provided by valueTransform and indexed by keySelector functions applied to elements of the given sequence.

Since Kotlin 1.0

associateByTo

inline fun <T, K, M : MutableMap<in K, in T>> Sequence<T>.associateByTo(destination: M, keySelector: (T) -> K): M

Populates and returns the destination mutable map with key-value pairs, where key is provided by the keySelector function applied to each element of the given sequence and value is the element itself.

Since Kotlin 1.0

inline fun <T, K, V, M : MutableMap<in K, in V>> Sequence<T>.associateByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M

Populates and returns the destination mutable map with key-value pairs, where key is provided by the keySelector function and and value is provided by the valueTransform function applied to elements of the given sequence.

Since Kotlin 1.0

associateTo

inline fun <T, K, V, M : MutableMap<in K, in V>> Sequence<T>.associateTo(destination: M, transform: (T) -> Pair<K, V>): M

Populates and returns the destination mutable map with key-value pairs provided by transform function applied to each element of the given sequence.

Since Kotlin 1.0

associateWith

inline fun <K, V> Sequence<K>.associateWith(valueSelector: (K) -> V): Map<K, V>

Returns a Map where keys are elements from the given sequence and values are produced by the valueSelector function applied to each element.

Since Kotlin 1.3

associateWithTo

inline fun <K, V, M : MutableMap<in K, in V>> Sequence<K>.associateWithTo(destination: M, valueSelector: (K) -> V): M

Populates and returns the destination mutable map with key-value pairs for each element of the given sequence, where key is the element itself and value is provided by the valueSelector function applied to that key.

Since Kotlin 1.3

asStream

fun <T> Sequence<T>.asStream(): Stream<T>

Creates a sequential Stream instance that produces elements from the original sequence.

Since Kotlin 1.2

average

@JvmName(name = "averageOfByte")

fun Sequence<Byte>.average(): Double

@JvmName(name = "averageOfDouble")

fun Sequence<Double>.average(): Double

@JvmName(name = "averageOfFloat")

fun Sequence<Float>.average(): Double

@JvmName(name = "averageOfInt")

fun Sequence<Int>.average(): Double

@JvmName(name = "averageOfLong")

fun Sequence<Long>.average(): Double

@JvmName(name = "averageOfShort")

fun Sequence<Short>.average(): Double

Returns an average value of elements in the sequence.

Since Kotlin 1.0

chunked

fun <T> Sequence<T>.chunked(size: Int): Sequence<List<T>>

Splits this sequence into a sequence of lists each not exceeding the given size.

Since Kotlin 1.2

fun <T, R> Sequence<T>.chunked(size: Int, transform: (List<T>) -> R): Sequence<R>

Splits this sequence into several lists each not exceeding the given size and applies the given transform function to an each.

Since Kotlin 1.2

constrainOnce

fun <T> Sequence<T>.constrainOnce(): Sequence<T>

Returns a wrapper sequence that provides values of this sequence, but ensures it can be iterated only one time.

Since Kotlin 1.0

contains

operator fun <T> Sequence<T>.contains(element: T): Boolean

Returns true if element is found in the sequence.

Since Kotlin 1.0

count

fun <T> Sequence<T>.count(): Int

Returns the number of elements in this sequence.

Since Kotlin 1.0

inline fun <T> Sequence<T>.count(predicate: (T) -> Boolean): Int

Returns the number of elements matching the given predicate.

Since Kotlin 1.0

distinct

fun <T> Sequence<T>.distinct(): Sequence<T>

Returns a sequence containing only distinct elements from the given sequence.

Since Kotlin 1.0

distinctBy

fun <T, K> Sequence<T>.distinctBy(selector: (T) -> K): Sequence<T>

Returns a sequence containing only elements from the given sequence having distinct keys returned by the given selector function.

Since Kotlin 1.0

drop

fun <T> Sequence<T>.drop(n: Int): Sequence<T>

Returns a sequence containing all elements except first n elements.

Since Kotlin 1.0

dropWhile

fun <T> Sequence<T>.dropWhile(predicate: (T) -> Boolean): Sequence<T>

Returns a sequence containing all elements except first elements that satisfy the given predicate.

Since Kotlin 1.0

elementAt

fun <T> Sequence<T>.elementAt(index: Int): T

Returns an element at the given index or throws an IndexOutOfBoundsException if the index is out of bounds of this sequence.

Since Kotlin 1.0

elementAtOrElse

fun <T> Sequence<T>.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T

Returns an element at the given index or the result of calling the defaultValue function if the index is out of bounds of this sequence.

Since Kotlin 1.0

elementAtOrNull

fun <T> Sequence<T>.elementAtOrNull(index: Int): T?

Returns an element at the given index or null if the index is out of bounds of this sequence.

Since Kotlin 1.0

filter

fun <T> Sequence<T>.filter(predicate: (T) -> Boolean): Sequence<T>

Returns a sequence containing only elements matching the given predicate.

Since Kotlin 1.0

filterIndexed

fun <T> Sequence<T>.filterIndexed(predicate: (index: Int, T) -> Boolean): Sequence<T>

Returns a sequence containing only elements matching the given predicate.

Since Kotlin 1.0

filterIndexedTo

inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterIndexedTo(destination: C, predicate: (index: Int, T) -> Boolean): C

Appends all elements matching the given predicate to the given destination.

Since Kotlin 1.0

filterIsInstance

inline fun <R> Sequence<*>.filterIsInstance(): Sequence<R>

Returns a sequence containing all elements that are instances of specified type parameter R.

Since Kotlin 1.0

fun <R> Sequence<*>.filterIsInstance(klass: Class<R>): Sequence<R>

Returns a sequence containing all elements that are instances of specified class.

Since Kotlin 1.0

filterIsInstanceTo

inline fun <R, C : MutableCollection<in R>> Sequence<*>.filterIsInstanceTo(destination: C): C

Appends all elements that are instances of specified type parameter R to the given destination.

Since Kotlin 1.0

fun <C : MutableCollection<in R>, R> Sequence<*>.filterIsInstanceTo(destination: C, klass: Class<R>): C

Appends all elements that are instances of specified class to the given destination.

Since Kotlin 1.0

filterNot

fun <T> Sequence<T>.filterNot(predicate: (T) -> Boolean): Sequence<T>

Returns a sequence containing all elements not matching the given predicate.

Since Kotlin 1.0

filterNotNull

fun <T : Any> Sequence<T?>.filterNotNull(): Sequence<T>

Returns a sequence containing all elements that are not null.

Since Kotlin 1.0

filterNotNullTo

fun <C : MutableCollection<in T>, T : Any> Sequence<T?>.filterNotNullTo(destination: C): C

Appends all elements that are not null to the given destination.

Since Kotlin 1.0

filterNotTo

inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterNotTo(destination: C, predicate: (T) -> Boolean): C

Appends all elements not matching the given predicate to the given destination.

Since Kotlin 1.0

filterTo

inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterTo(destination: C, predicate: (T) -> Boolean): C

Appends all elements matching the given predicate to the given destination.

Since Kotlin 1.0

find

inline fun <T> Sequence<T>.find(predicate: (T) -> Boolean): T?

Returns the first element matching the given predicate, or null if no such element was found.

Since Kotlin 1.0

findLast

inline fun <T> Sequence<T>.findLast(predicate: (T) -> Boolean): T?

Returns the last element matching the given predicate, or null if no such element was found.

Since Kotlin 1.0

first

fun <T> Sequence<T>.first(): T

Returns the first element.

Since Kotlin 1.0

inline fun <T> Sequence<T>.first(predicate: (T) -> Boolean): T

Returns the first element matching the given predicate.

Since Kotlin 1.0

firstNotNullOf

inline fun <T, R : Any> Sequence<T>.firstNotNullOf(transform: (T) -> R?): R

Returns the first non-null value produced by transform function being applied to elements of this sequence in iteration order, or throws NoSuchElementException if no non-null value was produced.

Since Kotlin 1.5

firstNotNullOfOrNull

inline fun <T, R : Any> Sequence<T>.firstNotNullOfOrNull(transform: (T) -> R?): R?

Returns the first non-null value produced by transform function being applied to elements of this sequence in iteration order, or null if no non-null value was produced.

Since Kotlin 1.5

firstOrNull

fun <T> Sequence<T>.firstOrNull(): T?

Returns the first element, or null if the sequence is empty.

Since Kotlin 1.0

inline fun <T> Sequence<T>.firstOrNull(predicate: (T) -> Boolean): T?

Returns the first element matching the given predicate, or null if element was not found.

Since Kotlin 1.0

flatMap

@JvmName(name = "flatMapIterable")

fun <T, R> Sequence<T>.flatMap(transform: (T) -> Iterable<R>): Sequence<R>

Returns a single sequence of all elements from results of transform function being invoked on each element of original sequence.

Since Kotlin 1.4

fun <T, R> Sequence<T>.flatMap(transform: (