commonMain.generated._Collections.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("CollectionsKt")
package kotlin.collections
//
// 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.*
import kotlin.ranges.contains
import kotlin.ranges.reversed
/**
* Returns 1st *element* from the list.
*
* Throws an [IndexOutOfBoundsException] if the size of this list is less than 1.
*/
@kotlin.internal.InlineOnly
public inline operator fun List.component1(): T {
return get(0)
}
/**
* Returns 2nd *element* from the list.
*
* Throws an [IndexOutOfBoundsException] if the size of this list is less than 2.
*/
@kotlin.internal.InlineOnly
public inline operator fun List.component2(): T {
return get(1)
}
/**
* Returns 3rd *element* from the list.
*
* Throws an [IndexOutOfBoundsException] if the size of this list is less than 3.
*/
@kotlin.internal.InlineOnly
public inline operator fun List.component3(): T {
return get(2)
}
/**
* Returns 4th *element* from the list.
*
* Throws an [IndexOutOfBoundsException] if the size of this list is less than 4.
*/
@kotlin.internal.InlineOnly
public inline operator fun List.component4(): T {
return get(3)
}
/**
* Returns 5th *element* from the list.
*
* Throws an [IndexOutOfBoundsException] if the size of this list is less than 5.
*/
@kotlin.internal.InlineOnly
public inline operator fun List.component5(): T {
return get(4)
}
/**
* Returns `true` if [element] is found in the collection.
*/
public operator fun <@kotlin.internal.OnlyInputTypes T> Iterable.contains(element: T): Boolean {
if (this is Collection)
return contains(element)
return indexOf(element) >= 0
}
/**
* Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this collection.
*
* @sample samples.collections.Collections.Elements.elementAt
*/
public fun Iterable.elementAt(index: Int): T {
if (this is List)
return get(index)
return elementAtOrElse(index) { throw IndexOutOfBoundsException("Collection doesn't contain element at index $index.") }
}
/**
* Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this list.
*
* @sample samples.collections.Collections.Elements.elementAt
*/
@kotlin.internal.InlineOnly
public inline fun List.elementAt(index: Int): T {
return get(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 collection.
*
* @sample samples.collections.Collections.Elements.elementAtOrElse
*/
public fun Iterable.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T {
contract {
callsInPlace(defaultValue, InvocationKind.AT_MOST_ONCE)
}
if (this is List)
return this.getOrElse(index, defaultValue)
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 the result of calling the [defaultValue] function if the [index] is out of bounds of this list.
*
* @sample samples.collections.Collections.Elements.elementAtOrElse
*/
@kotlin.internal.InlineOnly
public inline fun List.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T {
contract {
callsInPlace(defaultValue, InvocationKind.AT_MOST_ONCE)
}
return if (index in 0.. Iterable.elementAtOrNull(index: Int): T? {
if (this is List)
return this.getOrNull(index)
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 an element at the given [index] or `null` if the [index] is out of bounds of this list.
*
* @sample samples.collections.Collections.Elements.elementAtOrNull
*/
@kotlin.internal.InlineOnly
public inline fun List.elementAtOrNull(index: Int): T? {
return this.getOrNull(index)
}
/**
* Returns the first element matching the given [predicate], or `null` if no such element was found.
*
* @sample samples.collections.Collections.Elements.find
*/
@kotlin.internal.InlineOnly
public inline fun Iterable.find(predicate: (T) -> Boolean): T? {
return firstOrNull(predicate)
}
/**
* Returns the last element matching the given [predicate], or `null` if no such element was found.
*
* @sample samples.collections.Collections.Elements.find
*/
@kotlin.internal.InlineOnly
public inline fun Iterable.findLast(predicate: (T) -> Boolean): T? {
return lastOrNull(predicate)
}
/**
* Returns the last element matching the given [predicate], or `null` if no such element was found.
*
* @sample samples.collections.Collections.Elements.find
*/
@kotlin.internal.InlineOnly
public inline fun List.findLast(predicate: (T) -> Boolean): T? {
return lastOrNull(predicate)
}
/**
* Returns the first element.
*
* @throws NoSuchElementException if the collection is empty.
*/
public fun Iterable.first(): T {
when (this) {
is List -> return this.first()
else -> {
val iterator = iterator()
if (!iterator.hasNext())
throw NoSuchElementException("Collection is empty.")
return iterator.next()
}
}
}
/**
* Returns the first element.
*
* @throws NoSuchElementException if the list is empty.
*/
public fun List.first(): T {
if (isEmpty())
throw NoSuchElementException("List is empty.")
return this[0]
}
/**
* Returns the first element matching the given [predicate].
* @throws [NoSuchElementException] if no such element is found.
*/
public inline fun Iterable.first(predicate: (T) -> Boolean): T {
for (element in this) if (predicate(element)) return element
throw NoSuchElementException("Collection contains no element matching the predicate.")
}
/**
* Returns the first non-null value produced by [transform] function being applied to elements of this collection in iteration order,
* or throws [NoSuchElementException] if no non-null value was produced.
*
* @sample samples.collections.Collections.Transformations.firstNotNullOf
*/
@SinceKotlin("1.5")
@kotlin.internal.InlineOnly
public inline fun Iterable.firstNotNullOf(transform: (T) -> R?): R {
return firstNotNullOfOrNull(transform) ?: throw NoSuchElementException("No element of the collection was transformed to a non-null value.")
}
/**
* Returns the first non-null value produced by [transform] function being applied to elements of this collection in iteration order,
* or `null` if no non-null value was produced.
*
* @sample samples.collections.Collections.Transformations.firstNotNullOf
*/
@SinceKotlin("1.5")
@kotlin.internal.InlineOnly
public inline fun Iterable.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 collection is empty.
*/
public fun Iterable.firstOrNull(): T? {
when (this) {
is List -> {
if (isEmpty())
return null
else
return this[0]
}
else -> {
val iterator = iterator()
if (!iterator.hasNext())
return null
return iterator.next()
}
}
}
/**
* Returns the first element, or `null` if the list is empty.
*/
public fun List.firstOrNull(): T? {
return if (isEmpty()) null else this[0]
}
/**
* Returns the first element matching the given [predicate], or `null` if element was not found.
*/
public inline fun Iterable.firstOrNull(predicate: (T) -> Boolean): T? {
for (element in this) if (predicate(element)) return element
return null
}
/**
* Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this list.
*/
@kotlin.internal.InlineOnly
public inline fun List.getOrElse(index: Int, defaultValue: (Int) -> T): T {
contract {
callsInPlace(defaultValue, InvocationKind.AT_MOST_ONCE)
}
return if (index in 0.. List.getOrNull(index: Int): T? {
return if (index in 0.. Iterable.indexOf(element: T): Int {
if (this is List) return this.indexOf(element)
var index = 0
for (item in this) {
checkIndexOverflow(index)
if (element == item)
return index
index++
}
return -1
}
/**
* Returns first index of [element], or -1 if the list does not contain element.
*/
@Suppress("EXTENSION_SHADOWED_BY_MEMBER") // false warning, extension takes precedence in some cases
public fun <@kotlin.internal.OnlyInputTypes T> List.indexOf(element: T): Int {
return indexOf(element)
}
/**
* Returns index of the first element matching the given [predicate], or -1 if the collection does not contain such element.
*/
public inline fun Iterable.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 first element matching the given [predicate], or -1 if the list does not contain such element.
*/
public inline fun List.indexOfFirst(predicate: (T) -> Boolean): Int {
var index = 0
for (item in this) {
if (predicate(item))
return index
index++
}
return -1
}
/**
* Returns index of the last element matching the given [predicate], or -1 if the collection does not contain such element.
*/
public inline fun Iterable.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 index of the last element matching the given [predicate], or -1 if the list does not contain such element.
*/
public inline fun List.indexOfLast(predicate: (T) -> Boolean): Int {
val iterator = this.listIterator(size)
while (iterator.hasPrevious()) {
if (predicate(iterator.previous())) {
return iterator.nextIndex()
}
}
return -1
}
/**
* Returns the last element.
*
* @throws NoSuchElementException if the collection is empty.
*
* @sample samples.collections.Collections.Elements.last
*/
public fun Iterable.last(): T {
when (this) {
is List -> return this.last()
else -> {
val iterator = iterator()
if (!iterator.hasNext())
throw NoSuchElementException("Collection is empty.")
var last = iterator.next()
while (iterator.hasNext())
last = iterator.next()
return last
}
}
}
/**
* Returns the last element.
*
* @throws NoSuchElementException if the list is empty.
*
* @sample samples.collections.Collections.Elements.last
*/
public fun List.last(): T {
if (isEmpty())
throw NoSuchElementException("List is empty.")
return this[lastIndex]
}
/**
* Returns the last element matching the given [predicate].
*
* @throws NoSuchElementException if no such element is found.
*
* @sample samples.collections.Collections.Elements.last
*/
public inline fun Iterable.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("Collection contains no element matching the predicate.")
@Suppress("UNCHECKED_CAST")
return last as T
}
/**
* Returns the last element matching the given [predicate].
*
* @throws NoSuchElementException if no such element is found.
*
* @sample samples.collections.Collections.Elements.last
*/
public inline fun List.last(predicate: (T) -> Boolean): T {
val iterator = this.listIterator(size)
while (iterator.hasPrevious()) {
val element = iterator.previous()
if (predicate(element)) return element
}
throw NoSuchElementException("List contains no element matching the predicate.")
}
/**
* Returns last index of [element], or -1 if the collection does not contain element.
*/
public fun <@kotlin.internal.OnlyInputTypes T> Iterable.lastIndexOf(element: T): Int {
if (this is List) return this.lastIndexOf(element)
var lastIndex = -1
var index = 0
for (item in this) {
checkIndexOverflow(index)
if (element == item)
lastIndex = index
index++
}
return lastIndex
}
/**
* Returns last index of [element], or -1 if the list does not contain element.
*/
@Suppress("EXTENSION_SHADOWED_BY_MEMBER") // false warning, extension takes precedence in some cases
public fun <@kotlin.internal.OnlyInputTypes T> List.lastIndexOf(element: T): Int {
return lastIndexOf(element)
}
/**
* Returns the last element, or `null` if the collection is empty.
*
* @sample samples.collections.Collections.Elements.last
*/
public fun Iterable.lastOrNull(): T? {
when (this) {
is List -> return if (isEmpty()) null else this[size - 1]
else -> {
val iterator = iterator()
if (!iterator.hasNext())
return null
var last = iterator.next()
while (iterator.hasNext())
last = iterator.next()
return last
}
}
}
/**
* Returns the last element, or `null` if the list is empty.
*
* @sample samples.collections.Collections.Elements.last
*/
public fun List.lastOrNull(): T? {
return if (isEmpty()) null else this[size - 1]
}
/**
* Returns the last element matching the given [predicate], or `null` if no such element was found.
*
* @sample samples.collections.Collections.Elements.last
*/
public inline fun Iterable.lastOrNull(predicate: (T) -> Boolean): T? {
var last: T? = null
for (element in this) {
if (predicate(element)) {
last = element
}
}
return last
}
/**
* Returns the last element matching the given [predicate], or `null` if no such element was found.
*
* @sample samples.collections.Collections.Elements.last
*/
public inline fun List.lastOrNull(predicate: (T) -> Boolean): T? {
val iterator = this.listIterator(size)
while (iterator.hasPrevious()) {
val element = iterator.previous()
if (predicate(element)) return element
}
return null
}
/**
* Returns a random element from this collection.
*
* @throws NoSuchElementException if this collection is empty.
*/
@SinceKotlin("1.3")
@kotlin.internal.InlineOnly
public inline fun Collection.random(): T {
return random(Random)
}
/**
* Returns a random element from this collection using the specified source of randomness.
*
* @throws NoSuchElementException if this collection is empty.
*/
@SinceKotlin("1.3")
public fun Collection.random(random: Random): T {
if (isEmpty())
throw NoSuchElementException("Collection is empty.")
return elementAt(random.nextInt(size))
}
/**
* Returns a random element from this collection, or `null` if this collection is empty.
*/
@SinceKotlin("1.4")
@kotlin.internal.InlineOnly
public inline fun Collection.randomOrNull(): T? {
return randomOrNull(Random)
}
/**
* Returns a random element from this collection using the specified source of randomness, or `null` if this collection is empty.
*/
@SinceKotlin("1.4")
public fun Collection.randomOrNull(random: Random): T? {
if (isEmpty())
return null
return elementAt(random.nextInt(size))
}
/**
* Returns the single element, or throws an exception if the collection is empty or has more than one element.
*/
public fun Iterable.single(): T {
when (this) {
is List -> return this.single()
else -> {
val iterator = iterator()
if (!iterator.hasNext())
throw NoSuchElementException("Collection is empty.")
val single = iterator.next()
if (iterator.hasNext())
throw IllegalArgumentException("Collection has more than one element.")
return single
}
}
}
/**
* Returns the single element, or throws an exception if the list is empty or has more than one element.
*/
public fun List.single(): T {
return when (size) {
0 -> throw NoSuchElementException("List is empty.")
1 -> this[0]
else -> throw IllegalArgumentException("List has more than one element.")
}
}
/**
* Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element.
*/
public inline fun Iterable.single(predicate: (T) -> Boolean): T {
var single: T? = null
var found = false
for (element in this) {
if (predicate(element)) {
if (found) throw IllegalArgumentException("Collection contains more than one matching element.")
single = element
found = true
}
}
if (!found) throw NoSuchElementException("Collection contains no element matching the predicate.")
@Suppress("UNCHECKED_CAST")
return single as T
}
/**
* Returns single element, or `null` if the collection is empty or has more than one element.
*/
public fun Iterable.singleOrNull(): T? {
when (this) {
is List -> return if (size == 1) this[0] else null
else -> {
val iterator = iterator()
if (!iterator.hasNext())
return null
val single = iterator.next()
if (iterator.hasNext())
return null
return single
}
}
}
/**
* Returns single element, or `null` if the list is empty or has more than one element.
*/
public fun List.singleOrNull(): T? {
return if (size == 1) this[0] else null
}
/**
* Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found.
*/
public inline fun Iterable.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 list containing all elements except first [n] elements.
*
* @throws IllegalArgumentException if [n] is negative.
*
* @sample samples.collections.Collections.Transformations.drop
*/
public fun Iterable.drop(n: Int): List {
require(n >= 0) { "Requested element count $n is less than zero." }
if (n == 0) return toList()
val list: ArrayList
if (this is Collection<*>) {
val resultSize = size - n
if (resultSize <= 0)
return emptyList()
if (resultSize == 1)
return listOf(last())
list = ArrayList(resultSize)
if (this is List) {
if (this is RandomAccess) {
for (index in n until size)
list.add(this[index])
} else {
for (item in listIterator(n))
list.add(item)
}
return list
}
}
else {
list = ArrayList()
}
var count = 0
for (item in this) {
if (count >= n) list.add(item) else ++count
}
return list.optimizeReadOnlyList()
}
/**
* Returns a list containing all elements except last [n] elements.
*
* @throws IllegalArgumentException if [n] is negative.
*
* @sample samples.collections.Collections.Transformations.drop
*/
public fun List.dropLast(n: Int): List {
require(n >= 0) { "Requested element count $n is less than zero." }
return take((size - n).coerceAtLeast(0))
}
/**
* Returns a list containing all elements except last elements that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.drop
*/
public inline fun List.dropLastWhile(predicate: (T) -> Boolean): List {
if (!isEmpty()) {
val iterator = listIterator(size)
while (iterator.hasPrevious()) {
if (!predicate(iterator.previous())) {
return take(iterator.nextIndex() + 1)
}
}
}
return emptyList()
}
/**
* Returns a list containing all elements except first elements that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.drop
*/
public inline fun Iterable.dropWhile(predicate: (T) -> Boolean): List {
var yielding = false
val list = ArrayList()
for (item in this)
if (yielding)
list.add(item)
else if (!predicate(item)) {
list.add(item)
yielding = true
}
return list
}
/**
* Returns a list containing only elements matching the given [predicate].
*
* @sample samples.collections.Collections.Filtering.filter
*/
public inline fun Iterable.filter(predicate: (T) -> Boolean): List {
return filterTo(ArrayList(), predicate)
}
/**
* Returns a list 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.
*
* @sample samples.collections.Collections.Filtering.filterIndexed
*/
public inline fun Iterable.filterIndexed(predicate: (index: Int, T) -> Boolean): List {
return filterIndexedTo(ArrayList(), predicate)
}
/**
* 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.
*
* @sample samples.collections.Collections.Filtering.filterIndexedTo
*/
public inline fun > Iterable.filterIndexedTo(destination: C, predicate: (index: Int, T) -> Boolean): C {
forEachIndexed { index, element ->
if (predicate(index, element)) destination.add(element)
}
return destination
}
/**
* Returns a list containing all elements that are instances of specified type parameter R.
*
* @sample samples.collections.Collections.Filtering.filterIsInstance
*/
public inline fun Iterable<*>.filterIsInstance(): List<@kotlin.internal.NoInfer R> {
return filterIsInstanceTo(ArrayList())
}
/**
* Appends all elements that are instances of specified type parameter R to the given [destination].
*
* @sample samples.collections.Collections.Filtering.filterIsInstanceTo
*/
public inline fun > Iterable<*>.filterIsInstanceTo(destination: C): C {
for (element in this) if (element is R) destination.add(element)
return destination
}
/**
* Returns a list containing all elements not matching the given [predicate].
*
* @sample samples.collections.Collections.Filtering.filter
*/
public inline fun Iterable.filterNot(predicate: (T) -> Boolean): List {
return filterNotTo(ArrayList(), predicate)
}
/**
* Returns a list containing all elements that are not `null`.
*
* @sample samples.collections.Collections.Filtering.filterNotNull
*/
public fun Iterable.filterNotNull(): List {
return filterNotNullTo(ArrayList())
}
/**
* Appends all elements that are not `null` to the given [destination].
*
* @sample samples.collections.Collections.Filtering.filterNotNullTo
*/
public fun , T : Any> Iterable.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].
*
* @sample samples.collections.Collections.Filtering.filterTo
*/
public inline fun > Iterable.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].
*
* @sample samples.collections.Collections.Filtering.filterTo
*/
public inline fun > Iterable.filterTo(destination: C, predicate: (T) -> Boolean): C {
for (element in this) if (predicate(element)) destination.add(element)
return destination
}
/**
* Returns a list containing elements at indices in the specified [indices] range.
*/
public fun List.slice(indices: IntRange): List {
if (indices.isEmpty()) return listOf()
return this.subList(indices.start, indices.endInclusive + 1).toList()
}
/**
* Returns a list containing elements at specified [indices].
*/
public fun List.slice(indices: Iterable): List {
val size = indices.collectionSizeOrDefault(10)
if (size == 0) return emptyList()
val list = ArrayList(size)
for (index in indices) {
list.add(get(index))
}
return list
}
/**
* Returns a list containing first [n] elements.
*
* @throws IllegalArgumentException if [n] is negative.
*
* @sample samples.collections.Collections.Transformations.take
*/
public fun Iterable.take(n: Int): List {
require(n >= 0) { "Requested element count $n is less than zero." }
if (n == 0) return emptyList()
if (this is Collection) {
if (n >= size) return toList()
if (n == 1) return listOf(first())
}
var count = 0
val list = ArrayList(n)
for (item in this) {
list.add(item)
if (++count == n)
break
}
return list.optimizeReadOnlyList()
}
/**
* Returns a list containing last [n] elements.
*
* @throws IllegalArgumentException if [n] is negative.
*
* @sample samples.collections.Collections.Transformations.take
*/
public fun List.takeLast(n: Int): List {
require(n >= 0) { "Requested element count $n is less than zero." }
if (n == 0) return emptyList()
val size = size
if (n >= size) return toList()
if (n == 1) return listOf(last())
val list = ArrayList(n)
if (this is RandomAccess) {
for (index in size - n until size)
list.add(this[index])
} else {
for (item in listIterator(size - n))
list.add(item)
}
return list
}
/**
* Returns a list containing last elements satisfying the given [predicate].
*
* @sample samples.collections.Collections.Transformations.take
*/
public inline fun List.takeLastWhile(predicate: (T) -> Boolean): List {
if (isEmpty())
return emptyList()
val iterator = listIterator(size)
while (iterator.hasPrevious()) {
if (!predicate(iterator.previous())) {
iterator.next()
val expectedSize = size - iterator.nextIndex()
if (expectedSize == 0) return emptyList()
return ArrayList(expectedSize).apply {
while (iterator.hasNext())
add(iterator.next())
}
}
}
return toList()
}
/**
* Returns a list containing first elements satisfying the given [predicate].
*
* @sample samples.collections.Collections.Transformations.take
*/
public inline fun Iterable.takeWhile(predicate: (T) -> Boolean): List {
val list = ArrayList()
for (item in this) {
if (!predicate(item))
break
list.add(item)
}
return list
}
/**
* Reverses elements in the list in-place.
*/
public expect fun MutableList.reverse(): Unit
/**
* Returns a list with elements in reversed order.
*/
public fun Iterable.reversed(): List {
if (this is Collection && size <= 1) return toList()
val list = toMutableList()
list.reverse()
return list
}
/**
* Randomly shuffles elements in this list in-place using the specified [random] instance as the source of randomness.
*
* See: https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm
*/
@SinceKotlin("1.3")
public fun MutableList.shuffle(random: Random): Unit {
for (i in lastIndex downTo 1) {
val j = random.nextInt(i + 1)
this[j] = this.set(i, this[j])
}
}
/**
* Sorts elements in the list in-place 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.
*/
public inline fun > MutableList.sortBy(crossinline selector: (T) -> R?): Unit {
if (size > 1) sortWith(compareBy(selector))
}
/**
* Sorts elements in the list in-place 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.
*/
public inline fun > MutableList.sortByDescending(crossinline selector: (T) -> R?): Unit {
if (size > 1) sortWith(compareByDescending(selector))
}
/**
* Sorts elements in the list in-place 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.
*/
public fun > MutableList.sortDescending(): Unit {
sortWith(reverseOrder())
}
/**
* Returns a list of all elements 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.
*/
public fun > Iterable.sorted(): List {
if (this is Collection) {
if (size <= 1) return this.toList()
@Suppress("UNCHECKED_CAST")
return (toTypedArray>() as Array).apply { sort() }.asList()
}
return toMutableList().apply { sort() }
}
/**
* Returns a list of all elements 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.
*
* @sample samples.collections.Collections.Sorting.sortedBy
*/
public inline fun > Iterable.sortedBy(crossinline selector: (T) -> R?): List {
return sortedWith(compareBy(selector))
}
/**
* Returns a list of all elements 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.
*/
public inline fun > Iterable.sortedByDescending(crossinline selector: (T) -> R?): List {
return sortedWith(compareByDescending(selector))
}
/**
* Returns a list of all elements 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.
*/
public fun > Iterable.sortedDescending(): List {
return sortedWith(reverseOrder())
}
/**
* Returns a list of all elements sorted according to the specified [comparator].
*
* The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
*/
public fun Iterable.sortedWith(comparator: Comparator): List {
if (this is Collection) {
if (size <= 1) return this.toList()
@Suppress("UNCHECKED_CAST")
return (toTypedArray() as Array).apply { sortWith(comparator) }.asList()
}
return toMutableList().apply { sortWith(comparator) }
}
/**
* Returns an array of Boolean containing all of the elements of this collection.
*/
public fun Collection.toBooleanArray(): BooleanArray {
val result = BooleanArray(size)
var index = 0
for (element in this)
result[index++] = element
return result
}
/**
* Returns an array of Byte containing all of the elements of this collection.
*/
public fun Collection.toByteArray(): ByteArray {
val result = ByteArray(size)
var index = 0
for (element in this)
result[index++] = element
return result
}
/**
* Returns an array of Char containing all of the elements of this collection.
*/
public fun Collection.toCharArray(): CharArray {
val result = CharArray(size)
var index = 0
for (element in this)
result[index++] = element
return result
}
/**
* Returns an array of Double containing all of the elements of this collection.
*/
public fun Collection.toDoubleArray(): DoubleArray {
val result = DoubleArray(size)
var index = 0
for (element in this)
result[index++] = element
return result
}
/**
* Returns an array of Float containing all of the elements of this collection.
*/
public fun Collection.toFloatArray(): FloatArray {
val result = FloatArray(size)
var index = 0
for (element in this)
result[index++] = element
return result
}
/**
* Returns an array of Int containing all of the elements of this collection.
*/
public fun Collection.toIntArray(): IntArray {
val result = IntArray(size)
var index = 0
for (element in this)
result[index++] = element
return result
}
/**
* Returns an array of Long containing all of the elements of this collection.
*/
public fun Collection.toLongArray(): LongArray {
val result = LongArray(size)
var index = 0
for (element in this)
result[index++] = element
return result
}
/**
* Returns an array of Short containing all of the elements of this collection.
*/
public fun Collection.toShortArray(): ShortArray {
val result = ShortArray(size)
var index = 0
for (element in this)
result[index++] = element
return result
}
/**
* Returns a [Map] containing key-value pairs provided by [transform] function
* applied to elements of the given collection.
*
* 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 collection.
*
* @sample samples.collections.Collections.Transformations.associate
*/
public inline fun Iterable.associate(transform: (T) -> Pair): Map {
val capacity = mapCapacity(collectionSizeOrDefault(10)).coerceAtLeast(16)
return associateTo(LinkedHashMap(capacity), transform)
}
/**
* Returns a [Map] containing the elements from the given collection 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 collection.
*
* @sample samples.collections.Collections.Transformations.associateBy
*/
public inline fun Iterable.associateBy(keySelector: (T) -> K): Map {
val capacity = mapCapacity(collectionSizeOrDefault(10)).coerceAtLeast(16)
return associateByTo(LinkedHashMap(capacity), keySelector)
}
/**
* Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given collection.
*
* 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 collection.
*
* @sample samples.collections.Collections.Transformations.associateByWithValueTransform
*/
public inline fun Iterable.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map {
val capacity = mapCapacity(collectionSizeOrDefault(10)).coerceAtLeast(16)
return associateByTo(LinkedHashMap(capacity), 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 collection
* 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.
*
* @sample samples.collections.Collections.Transformations.associateByTo
*/
public inline fun > Iterable.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 collection.
*
* If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
*
* @sample samples.collections.Collections.Transformations.associateByToWithValueTransform
*/
public inline fun > Iterable.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 collection.
*
* If any of two pairs would have the same key the last one gets added to the map.
*
* @sample samples.collections.Collections.Transformations.associateTo
*/
public inline fun > Iterable.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 collection 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 collection.
*
* @sample samples.collections.Collections.Transformations.associateWith
*/
@SinceKotlin("1.3")
public inline fun Iterable.associateWith(valueSelector: (K) -> V): Map {
val result = LinkedHashMap(mapCapacity(collectionSizeOrDefault(10)).coerceAtLeast(16))
return associateWithTo(result, valueSelector)
}
/**
* Populates and returns the [destination] mutable map with key-value pairs for each element of the given collection,
* 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.
*
* @sample samples.collections.Collections.Transformations.associateWithTo
*/
@SinceKotlin("1.3")
public inline fun > Iterable.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.
*/
public fun > Iterable.toCollection(destination: C): C {
for (item in this) {
destination.add(item)
}
return destination
}
/**
* Returns a new [HashSet] of all elements.
*/
public fun Iterable.toHashSet(): HashSet {
return toCollection(HashSet(mapCapacity(collectionSizeOrDefault(12))))
}
/**
* Returns a [List] containing all elements.
*/
public fun Iterable.toList(): List {
if (this is Collection) {
return when (size) {
0 -> emptyList()
1 -> listOf(if (this is List) get(0) else iterator().next())
else -> this.toMutableList()
}
}
return this.toMutableList().optimizeReadOnlyList()
}
/**
* Returns a new [MutableList] filled with all elements of this collection.
*/
public fun Iterable.toMutableList(): MutableList {
if (this is Collection)
return this.toMutableList()
return toCollection(ArrayList())
}
/**
* Returns a new [MutableList] filled with all elements of this collection.
*/
public fun Collection.toMutableList(): MutableList