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
Kotlin Standard Library
There is a newer version: 2.1.0-RC
/*
 * 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("DEPRECATION")
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("DEPRECATION")
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
}