commonMain.generated._Sequences.kt Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of kotlin-stdlib Show documentation
Show all versions of kotlin-stdlib Show documentation
Kotlin Standard Library for JVM
/*
* Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
* Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
*/
@file:kotlin.jvm.JvmMultifileClass
@file:kotlin.jvm.JvmName("SequencesKt")
package kotlin.sequences
//
// NOTE: THIS FILE IS AUTO-GENERATED by the GenerateStandardLib.kt
// See: https://github.com/JetBrains/kotlin/tree/master/libraries/stdlib
//
import kotlin.contracts.*
import kotlin.random.*
/**
* Returns `true` if [element] is found in the sequence.
*
* The operation is _terminal_.
*/
public operator fun <@kotlin.internal.OnlyInputTypes T> Sequence.contains(element: T): Boolean {
return indexOf(element) >= 0
}
/**
* Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this sequence.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Elements.elementAt
*/
public fun Sequence.elementAt(index: Int): T {
return elementAtOrElse(index) { throw IndexOutOfBoundsException("Sequence doesn't contain element at index $index.") }
}
/**
* 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.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Elements.elementAtOrElse
*/
public fun Sequence.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T {
contract {
callsInPlace(defaultValue, InvocationKind.AT_MOST_ONCE)
}
if (index < 0)
return defaultValue(index)
val iterator = iterator()
var count = 0
while (iterator.hasNext()) {
val element = iterator.next()
if (index == count++)
return element
}
return defaultValue(index)
}
/**
* Returns an element at the given [index] or `null` if the [index] is out of bounds of this sequence.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Elements.elementAtOrNull
*/
public fun Sequence.elementAtOrNull(index: Int): T? {
if (index < 0)
return null
val iterator = iterator()
var count = 0
while (iterator.hasNext()) {
val element = iterator.next()
if (index == count++)
return element
}
return null
}
/**
* Returns the first element matching the given [predicate], or `null` if no such element was found.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Elements.find
*/
@kotlin.internal.InlineOnly
public inline fun Sequence.find(predicate: (T) -> Boolean): T? {
return firstOrNull(predicate)
}
/**
* Returns the last element matching the given [predicate], or `null` if no such element was found.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Elements.find
*/
@kotlin.internal.InlineOnly
public inline fun Sequence.findLast(predicate: (T) -> Boolean): T? {
return lastOrNull(predicate)
}
/**
* Returns the first element.
*
* The operation is _terminal_.
*
* @throws NoSuchElementException if the sequence is empty.
*/
public fun Sequence.first(): T {
val iterator = iterator()
if (!iterator.hasNext())
throw NoSuchElementException("Sequence is empty.")
return iterator.next()
}
/**
* Returns the first element matching the given [predicate].
* @throws [NoSuchElementException] if no such element is found.
*
* The operation is _terminal_.
*/
public inline fun Sequence.first(predicate: (T) -> Boolean): T {
for (element in this) if (predicate(element)) return element
throw NoSuchElementException("Sequence contains no element matching the predicate.")
}
/**
* 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.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.firstNotNullOf
*/
@SinceKotlin("1.5")
@kotlin.internal.InlineOnly
public inline fun Sequence.firstNotNullOf(transform: (T) -> R?): R {
return firstNotNullOfOrNull(transform) ?: throw NoSuchElementException("No element of the sequence was transformed to a non-null value.")
}
/**
* 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.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.firstNotNullOf
*/
@SinceKotlin("1.5")
@kotlin.internal.InlineOnly
public inline fun Sequence.firstNotNullOfOrNull(transform: (T) -> R?): R? {
for (element in this) {
val result = transform(element)
if (result != null) {
return result
}
}
return null
}
/**
* Returns the first element, or `null` if the sequence is empty.
*
* The operation is _terminal_.
*/
public fun Sequence.firstOrNull(): T? {
val iterator = iterator()
if (!iterator.hasNext())
return null
return iterator.next()
}
/**
* Returns the first element matching the given [predicate], or `null` if element was not found.
*
* The operation is _terminal_.
*/
public inline fun Sequence.firstOrNull(predicate: (T) -> Boolean): T? {
for (element in this) if (predicate(element)) return element
return null
}
/**
* Returns first index of [element], or -1 if the sequence does not contain element.
*
* The operation is _terminal_.
*/
public fun <@kotlin.internal.OnlyInputTypes T> Sequence.indexOf(element: T): Int {
var index = 0
for (item in this) {
checkIndexOverflow(index)
if (element == item)
return index
index++
}
return -1
}
/**
* Returns index of the first element matching the given [predicate], or -1 if the sequence does not contain such element.
*
* The operation is _terminal_.
*/
public inline fun Sequence.indexOfFirst(predicate: (T) -> Boolean): Int {
var index = 0
for (item in this) {
checkIndexOverflow(index)
if (predicate(item))
return index
index++
}
return -1
}
/**
* Returns index of the last element matching the given [predicate], or -1 if the sequence does not contain such element.
*
* The operation is _terminal_.
*/
public inline fun Sequence.indexOfLast(predicate: (T) -> Boolean): Int {
var lastIndex = -1
var index = 0
for (item in this) {
checkIndexOverflow(index)
if (predicate(item))
lastIndex = index
index++
}
return lastIndex
}
/**
* Returns the last element.
*
* The operation is _terminal_.
*
* @throws NoSuchElementException if the sequence is empty.
*
* @sample samples.collections.Collections.Elements.last
*/
public fun Sequence.last(): T {
val iterator = iterator()
if (!iterator.hasNext())
throw NoSuchElementException("Sequence is empty.")
var last = iterator.next()
while (iterator.hasNext())
last = iterator.next()
return last
}
/**
* Returns the last element matching the given [predicate].
*
* The operation is _terminal_.
*
* @throws NoSuchElementException if no such element is found.
*
* @sample samples.collections.Collections.Elements.last
*/
public inline fun Sequence.last(predicate: (T) -> Boolean): T {
var last: T? = null
var found = false
for (element in this) {
if (predicate(element)) {
last = element
found = true
}
}
if (!found) throw NoSuchElementException("Sequence contains no element matching the predicate.")
@Suppress("UNCHECKED_CAST")
return last as T
}
/**
* Returns last index of [element], or -1 if the sequence does not contain element.
*
* The operation is _terminal_.
*/
public fun <@kotlin.internal.OnlyInputTypes T> Sequence.lastIndexOf(element: T): Int {
var lastIndex = -1
var index = 0
for (item in this) {
checkIndexOverflow(index)
if (element == item)
lastIndex = index
index++
}
return lastIndex
}
/**
* Returns the last element, or `null` if the sequence is empty.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Elements.last
*/
public fun Sequence.lastOrNull(): T? {
val iterator = iterator()
if (!iterator.hasNext())
return null
var last = iterator.next()
while (iterator.hasNext())
last = iterator.next()
return last
}
/**
* Returns the last element matching the given [predicate], or `null` if no such element was found.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Elements.last
*/
public inline fun Sequence.lastOrNull(predicate: (T) -> Boolean): T? {
var last: T? = null
for (element in this) {
if (predicate(element)) {
last = element
}
}
return last
}
/**
* Returns the single element, or throws an exception if the sequence is empty or has more than one element.
*
* The operation is _terminal_.
*/
public fun Sequence.single(): T {
val iterator = iterator()
if (!iterator.hasNext())
throw NoSuchElementException("Sequence is empty.")
val single = iterator.next()
if (iterator.hasNext())
throw IllegalArgumentException("Sequence has more than one element.")
return single
}
/**
* Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element.
*
* The operation is _terminal_.
*/
public inline fun Sequence.single(predicate: (T) -> Boolean): T {
var single: T? = null
var found = false
for (element in this) {
if (predicate(element)) {
if (found) throw IllegalArgumentException("Sequence contains more than one matching element.")
single = element
found = true
}
}
if (!found) throw NoSuchElementException("Sequence contains no element matching the predicate.")
@Suppress("UNCHECKED_CAST")
return single as T
}
/**
* Returns single element, or `null` if the sequence is empty or has more than one element.
*
* The operation is _terminal_.
*/
public fun Sequence.singleOrNull(): T? {
val iterator = iterator()
if (!iterator.hasNext())
return null
val single = iterator.next()
if (iterator.hasNext())
return null
return single
}
/**
* Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found.
*
* The operation is _terminal_.
*/
public inline fun Sequence.singleOrNull(predicate: (T) -> Boolean): T? {
var single: T? = null
var found = false
for (element in this) {
if (predicate(element)) {
if (found) return null
single = element
found = true
}
}
if (!found) return null
return single
}
/**
* Returns a sequence containing all elements except first [n] elements.
*
* The operation is _intermediate_ and _stateless_.
*
* @throws IllegalArgumentException if [n] is negative.
*
* @sample samples.collections.Collections.Transformations.drop
*/
public fun Sequence.drop(n: Int): Sequence {
require(n >= 0) { "Requested element count $n is less than zero." }
return when {
n == 0 -> this
this is DropTakeSequence -> this.drop(n)
else -> DropSequence(this, n)
}
}
/**
* Returns a sequence containing all elements except first elements that satisfy the given [predicate].
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Transformations.drop
*/
public fun Sequence.dropWhile(predicate: (T) -> Boolean): Sequence {
return DropWhileSequence(this, predicate)
}
/**
* Returns a sequence containing only elements matching the given [predicate].
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Filtering.filter
*/
public fun Sequence.filter(predicate: (T) -> Boolean): Sequence {
return FilteringSequence(this, true, predicate)
}
/**
* Returns a sequence containing only elements matching the given [predicate].
* @param [predicate] function that takes the index of an element and the element itself
* and returns the result of predicate evaluation on the element.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Filtering.filterIndexed
*/
public fun Sequence.filterIndexed(predicate: (index: Int, T) -> Boolean): Sequence {
// TODO: Rewrite with generalized MapFilterIndexingSequence
return TransformingSequence(FilteringSequence(IndexingSequence(this), true, { predicate(it.index, it.value) }), { it.value })
}
/**
* Appends all elements matching the given [predicate] to the given [destination].
* @param [predicate] function that takes the index of an element and the element itself
* and returns the result of predicate evaluation on the element.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Filtering.filterIndexedTo
*/
public inline fun > Sequence.filterIndexedTo(destination: C, predicate: (index: Int, T) -> Boolean): C {
forEachIndexed { index, element ->
if (predicate(index, element)) destination.add(element)
}
return destination
}
/**
* Returns a sequence containing all elements that are instances of specified type parameter R.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Filtering.filterIsInstance
*/
public inline fun Sequence<*>.filterIsInstance(): Sequence<@kotlin.internal.NoInfer R> {
@Suppress("UNCHECKED_CAST")
return filter { it is R } as Sequence
}
/**
* Appends all elements that are instances of specified type parameter R to the given [destination].
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Filtering.filterIsInstanceTo
*/
public inline fun > Sequence<*>.filterIsInstanceTo(destination: C): C {
for (element in this) if (element is R) destination.add(element)
return destination
}
/**
* Returns a sequence containing all elements not matching the given [predicate].
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Filtering.filter
*/
public fun Sequence.filterNot(predicate: (T) -> Boolean): Sequence {
return FilteringSequence(this, false, predicate)
}
/**
* Returns a sequence containing all elements that are not `null`.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Filtering.filterNotNull
*/
public fun Sequence.filterNotNull(): Sequence {
@Suppress("UNCHECKED_CAST")
return filterNot { it == null } as Sequence
}
/**
* Appends all elements that are not `null` to the given [destination].
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Filtering.filterNotNullTo
*/
public fun , T : Any> Sequence.filterNotNullTo(destination: C): C {
for (element in this) if (element != null) destination.add(element)
return destination
}
/**
* Appends all elements not matching the given [predicate] to the given [destination].
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Filtering.filterTo
*/
public inline fun > Sequence.filterNotTo(destination: C, predicate: (T) -> Boolean): C {
for (element in this) if (!predicate(element)) destination.add(element)
return destination
}
/**
* Appends all elements matching the given [predicate] to the given [destination].
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Filtering.filterTo
*/
public inline fun > Sequence.filterTo(destination: C, predicate: (T) -> Boolean): C {
for (element in this) if (predicate(element)) destination.add(element)
return destination
}
/**
* Returns a sequence containing first [n] elements.
*
* The operation is _intermediate_ and _stateless_.
*
* @throws IllegalArgumentException if [n] is negative.
*
* @sample samples.collections.Collections.Transformations.take
*/
public fun Sequence.take(n: Int): Sequence {
require(n >= 0) { "Requested element count $n is less than zero." }
return when {
n == 0 -> emptySequence()
this is DropTakeSequence -> this.take(n)
else -> TakeSequence(this, n)
}
}
/**
* Returns a sequence containing first elements satisfying the given [predicate].
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Transformations.take
*/
public fun Sequence.takeWhile(predicate: (T) -> Boolean): Sequence {
return TakeWhileSequence(this, predicate)
}
/**
* Returns a sequence that yields elements of this sequence sorted according to their natural sort order.
*
* The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
*
* The operation is _intermediate_ and _stateful_.
*/
public fun > Sequence.sorted(): Sequence {
return object : Sequence {
override fun iterator(): Iterator {
val sortedList = [email protected]()
sortedList.sort()
return sortedList.iterator()
}
}
}
/**
* Returns a sequence that yields elements of this sequence sorted according to natural sort order of the value returned by specified [selector] function.
*
* The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
*
* The operation is _intermediate_ and _stateful_.
*
* @sample samples.collections.Collections.Sorting.sortedBy
*/
public inline fun > Sequence.sortedBy(crossinline selector: (T) -> R?): Sequence {
return sortedWith(compareBy(selector))
}
/**
* Returns a sequence that yields elements of this sequence sorted descending according to natural sort order of the value returned by specified [selector] function.
*
* The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
*
* The operation is _intermediate_ and _stateful_.
*/
public inline fun > Sequence.sortedByDescending(crossinline selector: (T) -> R?): Sequence {
return sortedWith(compareByDescending(selector))
}
/**
* Returns a sequence that yields elements of this sequence sorted descending according to their natural sort order.
*
* The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
*
* The operation is _intermediate_ and _stateful_.
*/
public fun > Sequence.sortedDescending(): Sequence {
return sortedWith(reverseOrder())
}
/**
* Returns a sequence that yields elements of this sequence sorted according to the specified [comparator].
*
* The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
*
* The operation is _intermediate_ and _stateful_.
*/
public fun Sequence.sortedWith(comparator: Comparator): Sequence {
return object : Sequence {
override fun iterator(): Iterator {
val sortedList = [email protected]()
sortedList.sortWith(comparator)
return sortedList.iterator()
}
}
}
/**
* Returns a [Map] containing key-value pairs provided by [transform] function
* applied to elements of the given sequence.
*
* If any of two pairs would have the same key the last one gets added to the map.
*
* The returned map preserves the entry iteration order of the original sequence.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.associate
*/
public inline fun Sequence.associate(transform: (T) -> Pair): Map {
return associateTo(LinkedHashMap(), transform)
}
/**
* Returns a [Map] containing the elements from the given sequence indexed by the key
* returned from [keySelector] function applied to each element.
*
* If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
*
* The returned map preserves the entry iteration order of the original sequence.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.associateBy
*/
public inline fun Sequence.associateBy(keySelector: (T) -> K): Map {
return associateByTo(LinkedHashMap(), keySelector)
}
/**
* Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given sequence.
*
* If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
*
* The returned map preserves the entry iteration order of the original sequence.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.associateByWithValueTransform
*/
public inline fun Sequence.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map {
return associateByTo(LinkedHashMap(), keySelector, valueTransform)
}
/**
* 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.
*
* If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.associateByTo
*/
public inline fun > Sequence.associateByTo(destination: M, keySelector: (T) -> K): M {
for (element in this) {
destination.put(keySelector(element), element)
}
return destination
}
/**
* 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.
*
* If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.associateByToWithValueTransform
*/
public inline fun > Sequence.associateByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M {
for (element in this) {
destination.put(keySelector(element), valueTransform(element))
}
return destination
}
/**
* Populates and returns the [destination] mutable map with key-value pairs
* provided by [transform] function applied to each element of the given sequence.
*
* If any of two pairs would have the same key the last one gets added to the map.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.associateTo
*/
public inline fun > Sequence.associateTo(destination: M, transform: (T) -> Pair): M {
for (element in this) {
destination += transform(element)
}
return destination
}
/**
* Returns a [Map] where keys are elements from the given sequence and values are
* produced by the [valueSelector] function applied to each element.
*
* If any two elements are equal, the last one gets added to the map.
*
* The returned map preserves the entry iteration order of the original sequence.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.associateWith
*/
@SinceKotlin("1.3")
public inline fun Sequence.associateWith(valueSelector: (K) -> V): Map {
val result = LinkedHashMap()
return associateWithTo(result, valueSelector)
}
/**
* 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.
*
* If any two elements are equal, the last one overwrites the former value in the map.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.associateWithTo
*/
@SinceKotlin("1.3")
public inline fun > Sequence.associateWithTo(destination: M, valueSelector: (K) -> V): M {
for (element in this) {
destination.put(element, valueSelector(element))
}
return destination
}
/**
* Appends all elements to the given [destination] collection.
*
* The operation is _terminal_.
*/
public fun > Sequence.toCollection(destination: C): C {
for (item in this) {
destination.add(item)
}
return destination
}
/**
* Returns a new [HashSet] of all elements.
*
* The operation is _terminal_.
*/
public fun Sequence.toHashSet(): HashSet {
return toCollection(HashSet())
}
/**
* Returns a [List] containing all elements.
*
* The operation is _terminal_.
*/
public fun Sequence.toList(): List {
val it = iterator()
if (!it.hasNext())
return emptyList()
val element = it.next()
if (!it.hasNext())
return listOf(element)
val dst = ArrayList()
dst.add(element)
while (it.hasNext()) dst.add(it.next())
return dst
}
/**
* Returns a new [MutableList] filled with all elements of this sequence.
*
* The operation is _terminal_.
*/
public fun Sequence.toMutableList(): MutableList {
return toCollection(ArrayList())
}
/**
* Returns a [Set] of all elements.
*
* The returned set preserves the element iteration order of the original sequence.
*
* The operation is _terminal_.
*/
public fun Sequence.toSet(): Set {
val it = iterator()
if (!it.hasNext())
return emptySet()
val element = it.next()
if (!it.hasNext())
return setOf(element)
val dst = LinkedHashSet()
dst.add(element)
while (it.hasNext()) dst.add(it.next())
return dst
}
/**
* Returns a single sequence of all elements from results of [transform] function being invoked on each element of original sequence.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Transformations.flatMap
*/
@SinceKotlin("1.4")
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@OverloadResolutionByLambdaReturnType
@kotlin.jvm.JvmName("flatMapIterable")
public fun Sequence.flatMap(transform: (T) -> Iterable): Sequence {
return FlatteningSequence(this, transform, Iterable::iterator)
}
/**
* Returns a single sequence of all elements from results of [transform] function being invoked on each element of original sequence.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Transformations.flatMap
*/
public fun Sequence.flatMap(transform: (T) -> Sequence): Sequence {
return FlatteningSequence(this, transform, Sequence::iterator)
}
/**
* Returns a single sequence of all elements yielded from results of [transform] function being invoked on each element
* and its index in the original sequence.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Transformations.flatMapIndexed
*/
@SinceKotlin("1.4")
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@OverloadResolutionByLambdaReturnType
@kotlin.jvm.JvmName("flatMapIndexedIterable")
public fun Sequence.flatMapIndexed(transform: (index: Int, T) -> Iterable): Sequence {
return flatMapIndexed(this, transform, Iterable::iterator)
}
/**
* Returns a single sequence of all elements yielded from results of [transform] function being invoked on each element
* and its index in the original sequence.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Transformations.flatMapIndexed
*/
@SinceKotlin("1.4")
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@OverloadResolutionByLambdaReturnType
@kotlin.jvm.JvmName("flatMapIndexedSequence")
public fun Sequence.flatMapIndexed(transform: (index: Int, T) -> Sequence): Sequence {
return flatMapIndexed(this, transform, Sequence::iterator)
}
/**
* Appends all elements yielded from results of [transform] function being invoked on each element
* and its index in the original sequence, to the given [destination].
*
* The operation is _terminal_.
*/
@SinceKotlin("1.4")
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@OverloadResolutionByLambdaReturnType
@kotlin.jvm.JvmName("flatMapIndexedIterableTo")
@kotlin.internal.InlineOnly
public inline fun > Sequence.flatMapIndexedTo(destination: C, transform: (index: Int, T) -> Iterable): C {
var index = 0
for (element in this) {
val list = transform(checkIndexOverflow(index++), element)
destination.addAll(list)
}
return destination
}
/**
* Appends all elements yielded from results of [transform] function being invoked on each element
* and its index in the original sequence, to the given [destination].
*
* The operation is _terminal_.
*/
@SinceKotlin("1.4")
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@OverloadResolutionByLambdaReturnType
@kotlin.jvm.JvmName("flatMapIndexedSequenceTo")
@kotlin.internal.InlineOnly
public inline fun > Sequence.flatMapIndexedTo(destination: C, transform: (index: Int, T) -> Sequence): C {
var index = 0
for (element in this) {
val list = transform(checkIndexOverflow(index++), element)
destination.addAll(list)
}
return destination
}
/**
* Appends all elements yielded from results of [transform] function being invoked on each element of original sequence, to the given [destination].
*
* The operation is _terminal_.
*/
@SinceKotlin("1.4")
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@OverloadResolutionByLambdaReturnType
@kotlin.jvm.JvmName("flatMapIterableTo")
public inline fun > Sequence.flatMapTo(destination: C, transform: (T) -> Iterable): C {
for (element in this) {
val list = transform(element)
destination.addAll(list)
}
return destination
}
/**
* Appends all elements yielded from results of [transform] function being invoked on each element of original sequence, to the given [destination].
*
* The operation is _terminal_.
*/
public inline fun > Sequence.flatMapTo(destination: C, transform: (T) -> Sequence): C {
for (element in this) {
val list = transform(element)
destination.addAll(list)
}
return destination
}
/**
* Groups elements of the original sequence by the key returned by the given [keySelector] function
* applied to each element and returns a map where each group key is associated with a list of corresponding elements.
*
* The returned map preserves the entry iteration order of the keys produced from the original sequence.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.groupBy
*/
public inline fun Sequence.groupBy(keySelector: (T) -> K): Map> {
return groupByTo(LinkedHashMap>(), keySelector)
}
/**
* Groups values returned by the [valueTransform] function applied to each element of the original sequence
* by the key returned by the given [keySelector] function applied to the element
* and returns a map where each group key is associated with a list of corresponding values.
*
* The returned map preserves the entry iteration order of the keys produced from the original sequence.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.groupByKeysAndValues
*/
public inline fun Sequence.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map> {
return groupByTo(LinkedHashMap>(), keySelector, valueTransform)
}
/**
* Groups elements of the original sequence by the key returned by the given [keySelector] function
* applied to each element and puts to the [destination] map each group key associated with a list of corresponding elements.
*
* @return The [destination] map.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.groupBy
*/
public inline fun >> Sequence.groupByTo(destination: M, keySelector: (T) -> K): M {
for (element in this) {
val key = keySelector(element)
val list = destination.getOrPut(key) { ArrayList() }
list.add(element)
}
return destination
}
/**
* Groups values returned by the [valueTransform] function applied to each element of the original sequence
* by the key returned by the given [keySelector] function applied to the element
* and puts to the [destination] map each group key associated with a list of corresponding values.
*
* @return The [destination] map.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Transformations.groupByKeysAndValues
*/
public inline fun >> Sequence.groupByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M {
for (element in this) {
val key = keySelector(element)
val list = destination.getOrPut(key) { ArrayList() }
list.add(valueTransform(element))
}
return destination
}
/**
* Creates a [Grouping] source from a sequence to be used later with one of group-and-fold operations
* using the specified [keySelector] function to extract a key from each element.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Grouping.groupingByEachCount
*/
@SinceKotlin("1.1")
public inline fun Sequence.groupingBy(crossinline keySelector: (T) -> K): Grouping {
return object : Grouping {
override fun sourceIterator(): Iterator = [email protected]()
override fun keyOf(element: T): K = keySelector(element)
}
}
/**
* Returns a sequence containing the results of applying the given [transform] function
* to each element in the original sequence.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Transformations.map
*/
public fun Sequence.map(transform: (T) -> R): Sequence {
return TransformingSequence(this, transform)
}
/**
* Returns a sequence containing the results of applying the given [transform] function
* to each element and its index in the original sequence.
* @param [transform] function that takes the index of an element and the element itself
* and returns the result of the transform applied to the element.
*
* The operation is _intermediate_ and _stateless_.
*/
public fun Sequence.mapIndexed(transform: (index: Int, T) -> R): Sequence {
return TransformingIndexedSequence(this, transform)
}
/**
* Returns a sequence containing only the non-null results of applying the given [transform] function
* to each element and its index in the original sequence.
* @param [transform] function that takes the index of an element and the element itself
* and returns the result of the transform applied to the element.
*
* The operation is _intermediate_ and _stateless_.
*/
public fun Sequence.mapIndexedNotNull(transform: (index: Int, T) -> R?): Sequence {
return TransformingIndexedSequence(this, transform).filterNotNull()
}
/**
* Applies the given [transform] function to each element and its index in the original sequence
* and appends only the non-null results to the given [destination].
* @param [transform] function that takes the index of an element and the element itself
* and returns the result of the transform applied to the element.
*
* The operation is _terminal_.
*/
public inline fun > Sequence.mapIndexedNotNullTo(destination: C, transform: (index: Int, T) -> R?): C {
forEachIndexed { index, element -> transform(index, element)?.let { destination.add(it) } }
return destination
}
/**
* Applies the given [transform] function to each element and its index in the original sequence
* and appends the results to the given [destination].
* @param [transform] function that takes the index of an element and the element itself
* and returns the result of the transform applied to the element.
*
* The operation is _terminal_.
*/
public inline fun > Sequence.mapIndexedTo(destination: C, transform: (index: Int, T) -> R): C {
var index = 0
for (item in this)
destination.add(transform(checkIndexOverflow(index++), item))
return destination
}
/**
* Returns a sequence containing only the non-null results of applying the given [transform] function
* to each element in the original sequence.
*
* The operation is _intermediate_ and _stateless_.
*
* @sample samples.collections.Collections.Transformations.mapNotNull
*/
public fun Sequence.mapNotNull(transform: (T) -> R?): Sequence {
return TransformingSequence(this, transform).filterNotNull()
}
/**
* Applies the given [transform] function to each element in the original sequence
* and appends only the non-null results to the given [destination].
*
* The operation is _terminal_.
*/
public inline fun > Sequence.mapNotNullTo(destination: C, transform: (T) -> R?): C {
forEach { element -> transform(element)?.let { destination.add(it) } }
return destination
}
/**
* Applies the given [transform] function to each element of the original sequence
* and appends the results to the given [destination].
*
* The operation is _terminal_.
*/
public inline fun > Sequence.mapTo(destination: C, transform: (T) -> R): C {
for (item in this)
destination.add(transform(item))
return destination
}
/**
* Returns a sequence that wraps each element of the original sequence
* into an [IndexedValue] containing the index of that element and the element itself.
*
* The operation is _intermediate_ and _stateless_.
*/
public fun Sequence.withIndex(): Sequence> {
return IndexingSequence(this)
}
/**
* Returns a sequence containing only distinct elements from the given sequence.
*
* Among equal elements of the given sequence, only the first one will be present in the resulting sequence.
* The elements in the resulting sequence are in the same order as they were in the source sequence.
*
* The operation is _intermediate_ and _stateful_.
*
* @sample samples.collections.Collections.Transformations.distinctAndDistinctBy
*/
public fun Sequence.distinct(): Sequence {
return this.distinctBy { it }
}
/**
* Returns a sequence containing only elements from the given sequence
* having distinct keys returned by the given [selector] function.
*
* Among elements of the given sequence with equal keys, only the first one will be present in the resulting sequence.
* The elements in the resulting sequence are in the same order as they were in the source sequence.
*
* The operation is _intermediate_ and _stateful_.
*
* @sample samples.collections.Collections.Transformations.distinctAndDistinctBy
*/
public fun Sequence.distinctBy(selector: (T) -> K): Sequence {
return DistinctSequence(this, selector)
}
/**
* Returns a new [MutableSet] containing all distinct elements from the given sequence.
*
* The returned set preserves the element iteration order of the original sequence.
*
* The operation is _terminal_.
*/
public fun Sequence.toMutableSet(): MutableSet {
val set = LinkedHashSet()
for (item in this) set.add(item)
return set
}
/**
* Returns `true` if all elements match the given [predicate].
*
* Note that if the sequence contains no elements, the function returns `true`
* because there are no elements in it that _do not_ match the predicate.
* See a more detailed explanation of this logic concept in ["Vacuous truth"](https://en.wikipedia.org/wiki/Vacuous_truth) article.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Aggregates.all
*/
public inline fun Sequence.all(predicate: (T) -> Boolean): Boolean {
for (element in this) if (!predicate(element)) return false
return true
}
/**
* Returns `true` if sequence has at least one element.
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Aggregates.any
*/
public fun Sequence.any(): Boolean {
return iterator().hasNext()
}
/**
* Returns `true` if at least one element matches the given [predicate].
*
* The operation is _terminal_.
*
* @sample samples.collections.Collections.Aggregates.anyWithPredicate
*/
public inline fun Sequence.any(predicate: (T) -> Boolean): Boolean {
for (element in this) if (predicate(element)) return true
return false
}
/**
* Returns the number of elements in this sequence.
*
* The operation is _terminal_.
*/
public fun Sequence.count(): Int {
var count = 0
for (element in this) checkCountOverflow(++count)
return count
}
/**
* Returns the number of elements matching the given [predicate].
*
* The operation is _terminal_.
*/
public inline fun Sequence.count(predicate: (T) -> Boolean): Int {
var count = 0
for (element in this) if (predicate(element)) checkCountOverflow(++count)
return count
}
/**
* Accumulates value starting with [initial] value and applying [operation] from left to right
* to current accumulator value and each element.
*
* Returns the specified [initial] value if the sequence is empty.
*
* @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value.
*
* The operation is _terminal_.
*/
public inline fun Sequence.fold(initial: R, operation: (acc: R, T) -> R): R {
var accumulator = initial
for (element in this) accumulator = operation(accumulator, element)
return accumulator
}
/**
* Accumulates value starting with [initial] value and applying [operation] from left to right
* to current accumulator value and each element with its index in the original sequence.
*
* Returns the specified [initial] value if the sequence is empty.
*
* @param [operation] function that takes the index of an element, current accumulator value
* and the element itself, and calculates the next accumulator value.
*
* The operation is _terminal_.
*/
public inline fun Sequence.foldIndexed(initial: R, operation: (index: Int, acc: R, T) -> R): R {
var index = 0
var accumulator = initial
for (element in this) accumulator = operation(checkIndexOverflow(index++), accumulator, element)
return accumulator
}
/**
* Performs the given [action] on each element.
*
* The operation is _terminal_.
*/
public inline fun Sequence.forEach(action: (T) -> Unit): Unit {
for (element in this) action(element)
}
/**
* Performs the given [action] on each element, providing sequential index with the element.
* @param [action] function that takes the index of an element and the element itself
* and performs the action on the element.
*
* The operation is _terminal_.
*/
public inline fun Sequence.forEachIndexed(action: (index: Int, T) -> Unit): Unit {
var index = 0
for (item in this) action(checkIndexOverflow(index++), item)
}
/**
* Returns the largest element.
*
* If any of elements is `NaN` returns `NaN`.
*
* The operation is _terminal_.
*
* @throws NoSuchElementException if the sequence is empty.
*/
@SinceKotlin("1.7")
@kotlin.jvm.JvmName("maxOrThrow")
@Suppress("CONFLICTING_OVERLOADS")
public fun Sequence.max(): Double {
val iterator = iterator()
if (!iterator.hasNext()) throw NoSuchElementException()
var max = iterator.next()
while (iterator.hasNext()) {
val e = iterator.next()
max = maxOf(max, e)
}
return max
}
/**
* Returns the largest element.
*
* If any of elements is `NaN` returns `NaN`.
*
* The operation is _terminal_.
*
* @throws NoSuchElementException if the sequence is empty.
*/
@SinceKotlin("1.7")
@kotlin.jvm.JvmName("maxOrThrow")
@Suppress("CONFLICTING_OVERLOADS")
public fun Sequence.max(): Float {
val iterator = iterator()
if (!iterator.hasNext()) throw NoSuchElementException()
var max = iterator.next()
while (iterator.hasNext()) {
val e = iterator.next()
max = maxOf(max, e)
}
return max
}
/**
* Returns the largest element.
*
* The operation is _terminal_.
*
* @throws NoSuchElementException if the sequence is empty.
*/
@SinceKotlin("1.7")
@kotlin.jvm.JvmName("maxOrThrow")
@Suppress("CONFLICTING_OVERLOADS")
public fun > Sequence