commonMain.kotlin.collections.Sets.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-2023 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("SetsKt")
@file:OptIn(kotlin.experimental.ExperimentalTypeInference::class)
package kotlin.collections
import kotlin.contracts.*
internal object EmptySet : Set, Serializable {
private const val serialVersionUID: Long = 3406603774387020532
override fun equals(other: Any?): Boolean = other is Set<*> && other.isEmpty()
override fun hashCode(): Int = 0
override fun toString(): String = "[]"
override val size: Int get() = 0
override fun isEmpty(): Boolean = true
override fun contains(element: Nothing): Boolean = false
override fun containsAll(elements: Collection): Boolean = elements.isEmpty()
override fun iterator(): Iterator = EmptyIterator
private fun readResolve(): Any = EmptySet
}
/**
* Returns an empty read-only set. The returned set is serializable (JVM).
* @sample samples.collections.Collections.Sets.emptyReadOnlySet
*/
public fun emptySet(): Set = EmptySet
/**
* Returns a new read-only set with the given elements.
* Elements of the set are iterated in the order they were specified.
* The returned set is serializable (JVM).
* @sample samples.collections.Collections.Sets.readOnlySet
*/
public fun setOf(vararg elements: T): Set = elements.toSet()
/**
* Returns a new read-only set containing only the specified object [element].
*
* The returned set is serializable (JVM).
*
* @sample samples.collections.Collections.Sets.singletonReadOnlySet
*/
@SinceKotlin("1.9")
public expect fun setOf(element: T): Set
/**
* Returns an empty read-only set. The returned set is serializable (JVM).
* @sample samples.collections.Collections.Sets.emptyReadOnlySet
*/
@kotlin.internal.InlineOnly
public inline fun setOf(): Set = emptySet()
/**
* Returns an empty new [MutableSet].
*
* The returned set preserves the element iteration order.
* @sample samples.collections.Collections.Sets.emptyMutableSet
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
public inline fun mutableSetOf(): MutableSet = LinkedHashSet()
/**
* Returns a new [MutableSet] with the given elements.
* Elements of the set are iterated in the order they were specified.
* @sample samples.collections.Collections.Sets.mutableSet
*/
public fun mutableSetOf(vararg elements: T): MutableSet = elements.toCollection(LinkedHashSet(mapCapacity(elements.size)))
/** Returns an empty new [HashSet]. */
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
public inline fun hashSetOf(): HashSet = HashSet()
/** Returns a new [HashSet] with the given elements. */
public fun hashSetOf(vararg elements: T): HashSet = elements.toCollection(HashSet(mapCapacity(elements.size)))
/**
* Returns an empty new [LinkedHashSet].
* @sample samples.collections.Collections.Sets.emptyLinkedHashSet
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
public inline fun linkedSetOf(): LinkedHashSet = LinkedHashSet()
/**
* Returns a new [LinkedHashSet] with the given elements.
* Elements of the set are iterated in the order they were specified.
* @sample samples.collections.Collections.Sets.linkedHashSet
*/
public fun linkedSetOf(vararg elements: T): LinkedHashSet = elements.toCollection(LinkedHashSet(mapCapacity(elements.size)))
/**
* Returns a new read-only set either with single given element, if it is not null, or empty set if the element is null.
* The returned set is serializable (JVM).
* @sample samples.collections.Collections.Sets.setOfNotNull
*/
@SinceKotlin("1.4")
public fun setOfNotNull(element: T?): Set = if (element != null) setOf(element) else emptySet()
/**
* Returns a new read-only set only with those given elements, that are not null.
* Elements of the set are iterated in the order they were specified.
* The returned set is serializable (JVM).
* @sample samples.collections.Collections.Sets.setOfNotNull
*/
@SinceKotlin("1.4")
public fun setOfNotNull(vararg elements: T?): Set {
return elements.filterNotNullTo(LinkedHashSet())
}
/**
* Builds a new read-only [Set] by populating a [MutableSet] using the given [builderAction]
* and returning a read-only set with the same elements.
*
* The set passed as a receiver to the [builderAction] is valid only inside that function.
* Using it outside of the function produces an unspecified behavior.
*
* Elements of the set are iterated in the order they were added by the [builderAction].
*
* The returned set is serializable (JVM).
*
* @sample samples.collections.Builders.Sets.buildSetSample
*/
@SinceKotlin("1.6")
@WasExperimental(ExperimentalStdlibApi::class)
@kotlin.internal.InlineOnly
@Suppress("LEAKED_IN_PLACE_LAMBDA", "WRONG_INVOCATION_KIND")
public inline fun buildSet(@BuilderInference builderAction: MutableSet.() -> Unit): Set {
contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
return buildSetInternal(builderAction)
}
@PublishedApi
@SinceKotlin("1.3")
@kotlin.internal.InlineOnly
internal expect inline fun buildSetInternal(builderAction: MutableSet.() -> Unit): Set
/**
* Builds a new read-only [Set] by populating a [MutableSet] using the given [builderAction]
* and returning a read-only set with the same elements.
*
* The set passed as a receiver to the [builderAction] is valid only inside that function.
* Using it outside of the function produces an unspecified behavior.
*
* [capacity] is used to hint the expected number of elements added in the [builderAction].
*
* Elements of the set are iterated in the order they were added by the [builderAction].
*
* The returned set is serializable (JVM).
*
* @throws IllegalArgumentException if the given [capacity] is negative.
*
* @sample samples.collections.Builders.Sets.buildSetSample
*/
@SinceKotlin("1.6")
@WasExperimental(ExperimentalStdlibApi::class)
@kotlin.internal.InlineOnly
@Suppress("LEAKED_IN_PLACE_LAMBDA", "WRONG_INVOCATION_KIND")
public inline fun buildSet(capacity: Int, @BuilderInference builderAction: MutableSet.() -> Unit): Set {
contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
return buildSetInternal(capacity, builderAction)
}
@PublishedApi
@SinceKotlin("1.3")
@kotlin.internal.InlineOnly
internal expect inline fun buildSetInternal(capacity: Int, builderAction: MutableSet.() -> Unit): Set
/** Returns this Set if it's not `null` and the empty set otherwise. */
@kotlin.internal.InlineOnly
public inline fun Set?.orEmpty(): Set = this ?: emptySet()
internal fun Set.optimizeReadOnlySet() = when (size) {
0 -> emptySet()
1 -> setOf(iterator().next())
else -> this
}