commonMain.extensions.kt Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of kotlinx-collections-immutable-jvm Show documentation
Show all versions of kotlinx-collections-immutable-jvm Show documentation
Kotlin Immutable Collections multiplatform library
/*
* Copyright 2016-2019 JetBrains s.r.o.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/
@file:Suppress("NOTHING_TO_INLINE")
package kotlinx.collections.immutable
import kotlinx.collections.immutable.implementations.immutableList.persistentVectorOf
import kotlinx.collections.immutable.implementations.immutableMap.PersistentHashMap
import kotlinx.collections.immutable.implementations.immutableMap.PersistentHashMapBuilder
import kotlinx.collections.immutable.implementations.immutableSet.PersistentHashSet
import kotlinx.collections.immutable.implementations.immutableSet.PersistentHashSetBuilder
import kotlinx.collections.immutable.implementations.persistentOrderedMap.PersistentOrderedMap
import kotlinx.collections.immutable.implementations.persistentOrderedMap.PersistentOrderedMapBuilder
import kotlinx.collections.immutable.implementations.persistentOrderedSet.PersistentOrderedSet
import kotlinx.collections.immutable.implementations.persistentOrderedSet.PersistentOrderedSetBuilder
//@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
//inline fun @kotlin.internal.Exact ImmutableCollection.mutate(mutator: (MutableCollection) -> Unit): ImmutableCollection = builder().apply(mutator).build()
// it or this?
/**
* Returns the result of applying the provided modifications on this set.
*
* The mutable set passed to the [mutator] closure has the same contents as this persistent set.
*
* @return a new persistent set with the provided modifications applied;
* or this instance if no modifications were made in the result of this operation.
*/
inline fun PersistentSet.mutate(mutator: (MutableSet) -> Unit): PersistentSet = builder().apply(mutator).build()
/**
* Returns the result of applying the provided modifications on this list.
*
* The mutable list passed to the [mutator] closure has the same contents as this persistent list.
*
* @return a new persistent list with the provided modifications applied;
* or this instance if no modifications were made in the result of this operation.
*/
inline fun PersistentList.mutate(mutator: (MutableList) -> Unit): PersistentList = builder().apply(mutator).build()
/**
* Returns the result of applying the provided modifications on this map.
*
* The mutable map passed to the [mutator] closure has the same contents as this persistent map.
*
* @return a new persistent map with the provided modifications applied;
* or this instance if no modifications were made in the result of this operation.
*/
inline fun PersistentMap.mutate(mutator: (MutableMap) -> Unit): PersistentMap =
(this as PersistentMap).builder().apply(mutator).build()
/**
* Returns the result of adding the specified [element] to this collection.
*
* @returns a new persistent collection with the specified [element] added;
* or this instance if this collection does not support duplicates and it already contains the element.
*/
inline operator fun PersistentCollection.plus(element: E): PersistentCollection = add(element)
/**
* Returns the result of removing a single appearance of the specified [element] from this collection.
*
* @return a new persistent collection with a single appearance of the specified [element] removed;
* or this instance if there is no such element in this collection.
*/
inline operator fun PersistentCollection.minus(element: E): PersistentCollection = remove(element)
/**
* Returns the result of adding all elements of the specified [elements] collection to this collection.
*
* @return a new persistent collection with elements of the specified [elements] collection added;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentCollection.plus(elements: Iterable): PersistentCollection
= if (elements is Collection) addAll(elements) else builder().also { it.addAll(elements) }.build()
/**
* Returns the result of adding all elements of the specified [elements] array to this collection.
*
* @return a new persistent collection with elements of the specified [elements] array added;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentCollection.plus(elements: Array): PersistentCollection
= builder().also { it.addAll(elements) }.build()
/**
* Returns the result of adding all elements of the specified [elements] sequence to this collection.
*
* @return a new persistent collection with elements of the specified [elements] sequence added;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentCollection.plus(elements: Sequence): PersistentCollection
= builder().also { it.addAll(elements) }.build()
/**
* Returns the result of removing all elements in this collection that are also
* contained in the specified [elements] collection.
*
* @return a new persistent collection with elements in this collection that are also
* contained in the specified [elements] collection removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentCollection.minus(elements: Iterable): PersistentCollection
= if (elements is Collection) removeAll(elements) else builder().also { it.removeAll(elements) }.build()
/**
* Returns the result of removing all elements in this collection that are also
* contained in the specified [elements] array.
*
* @return a new persistent collection with elements in this collection that are also
* contained in the specified [elements] array removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentCollection.minus(elements: Array): PersistentCollection
= builder().also { it.removeAll(elements) }.build()
/**
* Returns the result of removing all elements in this collection that are also
* contained in the specified [elements] sequence.
*
* @return a new persistent collection with elements in this collection that are also
* contained in the specified [elements] sequence removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentCollection.minus(elements: Sequence): PersistentCollection
= builder().also { it.removeAll(elements) }.build()
/**
* Returns a new persistent list with the specified [element] appended.
*/
inline operator fun PersistentList.plus(element: E): PersistentList = add(element)
/**
* Returns the result of removing the first appearance of the specified [element] from this list.
*
* @return a new persistent list with the first appearance of the specified [element] removed;
* or this instance if there is no such element in this list.
*/
inline operator fun PersistentList.minus(element: E): PersistentList = remove(element)
/**
* Returns the result of appending all elements of the specified [elements] collection to this list.
*
* The elements are appended in the order they appear in the specified collection.
*
* @return a new persistent list with elements of the specified [elements] collection appended;
* or this instance if the specified collection is empty.
*/
operator fun PersistentList.plus(elements: Iterable): PersistentList
= if (elements is Collection) addAll(elements) else mutate { it.addAll(elements) }
/**
* Returns the result of appending all elements of the specified [elements] array to this list.
*
* The elements are appended in the order they appear in the specified array.
*
* @return a new persistent list with elements of the specified [elements] array appended;
* or this instance if the specified array is empty.
*/
operator fun PersistentList.plus(elements: Array): PersistentList
= mutate { it.addAll(elements) }
/**
* Returns the result of appending all elements of the specified [elements] sequence to this list.
*
* The elements are appended in the order they appear in the specified sequence.
*
* @return a new persistent list with elements of the specified [elements] sequence appended;
* or this instance if the specified sequence is empty.
*/
operator fun PersistentList.plus(elements: Sequence): PersistentList
= mutate { it.addAll(elements) }
/**
* Returns the result of removing all elements in this list that are also
* contained in the specified [elements] collection.
*
* @return a new persistent list with elements in this list that are also
* contained in the specified [elements] collection removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentList.minus(elements: Iterable): PersistentList
= if (elements is Collection) removeAll(elements) else mutate { it.removeAll(elements) }
/**
* Returns the result of removing all elements in this list that are also
* contained in the specified [elements] array.
*
* @return a new persistent list with elements in this list that are also
* contained in the specified [elements] array removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentList.minus(elements: Array): PersistentList
= mutate { it.removeAll(elements) }
/**
* Returns the result of removing all elements in this list that are also
* contained in the specified [elements] sequence.
*
* @return a new persistent list with elements in this list that are also
* contained in the specified [elements] sequence removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentList.minus(elements: Sequence): PersistentList
= mutate { it.removeAll(elements) }
/**
* Returns the result of adding the specified [element] to this set.
*
* @return a new persistent set with the specified [element] added;
* or this instance if it already contains the element.
*/
inline operator fun PersistentSet.plus(element: E): PersistentSet = add(element)
/**
* Returns the result of removing the specified [element] from this set.
*
* @return a new persistent set with the specified [element] removed;
* or this instance if there is no such element in this set.
*/
inline operator fun PersistentSet.minus(element: E): PersistentSet = remove(element)
/**
* Returns the result of adding all elements of the specified [elements] collection to this set.
*
* @return a new persistent set with elements of the specified [elements] collection added;
* or this instance if it already contains every element of the specified collection.
*/
operator fun PersistentSet.plus(elements: Iterable): PersistentSet
= if (elements is Collection) addAll(elements) else mutate { it.addAll(elements) }
/**
* Returns the result of adding all elements of the specified [elements] array to this set.
*
* @return a new persistent set with elements of the specified [elements] array added;
* or this instance if it already contains every element of the specified array.
*/
operator fun PersistentSet.plus(elements: Array): PersistentSet
= mutate { it.addAll(elements) }
/**
* Returns the result of adding all elements of the specified [elements] sequence to this set.
*
* @return a new persistent set with elements of the specified [elements] sequence added;
* or this instance if it already contains every element of the specified sequence.
*/
operator fun PersistentSet.plus(elements: Sequence): PersistentSet
= mutate { it.addAll(elements) }
/**
* Returns the result of removing all elements in this set that are also
* contained in the specified [elements] collection.
*
* @return a new persistent set with elements in this set that are also
* contained in the specified [elements] collection removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentSet.minus(elements: Iterable): PersistentSet
= if (elements is Collection) removeAll(elements) else mutate { it.removeAll(elements) }
/**
* Returns the result of removing all elements in this set that are also
* contained in the specified [elements] array.
*
* @return a new persistent set with elements in this set that are also
* contained in the specified [elements] array removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentSet.minus(elements: Array): PersistentSet
= mutate { it.removeAll(elements) }
/**
* Returns the result of removing all elements in this set that are also
* contained in the specified [elements] sequence.
*
* @return a new persistent set with elements in this set that are also
* contained in the specified [elements] sequence removed;
* or this instance if no modifications were made in the result of this operation.
*/
operator fun PersistentSet.minus(elements: Sequence): PersistentSet
= mutate { it.removeAll(elements) }
/**
* Returns all elements in this set that are also
* contained in the specified [elements] collection.
*
* @return a new persistent set with elements in this set that are also
* contained in the specified [elements] collection;
* or this instance if no modifications were made in the result of this operation.
*/
infix fun PersistentSet.intersect(elements: Iterable): PersistentSet
= if (elements is Collection) retainAll(elements) else mutate { it.retainAll(elements) }
/**
* Returns all elements in this collection that are also
* contained in the specified [elements] collection.
*
* @return a new persistent set with elements in this collection that are also
* contained in the specified [elements] collection
*/
infix fun PersistentCollection.intersect(elements: Iterable): PersistentSet
= this.toPersistentSet().intersect(elements)
/**
* Returns the result of adding an entry to this map from the specified key-value [pair].
*
* If this map already contains a mapping for the key,
* the old value is replaced by the value from the specified [pair].
*
* @return a new persistent map with an entry from the specified key-value [pair] added;
* or this instance if no modifications were made in the result of this operation.
*/
inline operator fun PersistentMap.plus(pair: Pair): PersistentMap
= (this as PersistentMap).put(pair.first, pair.second)
/**
* Returns the result of replacing or adding entries to this map from the specified key-value pairs.
*
* @return a new persistent map with entries from the specified key-value pairs added;
* or this instance if no modifications were made in the result of this operation.
*/
inline operator fun PersistentMap.plus(pairs: Iterable>): PersistentMap = putAll(pairs)
/**
* Returns the result of replacing or adding entries to this map from the specified key-value pairs.
*
* @return a new persistent map with entries from the specified key-value pairs added;
* or this instance if no modifications were made in the result of this operation.
*/
inline operator fun PersistentMap.plus(pairs: Array>): PersistentMap = putAll(pairs)
/**
* Returns the result of replacing or adding entries to this map from the specified key-value pairs.
*
* @return a new persistent map with entries from the specified key-value pairs added;
* or this instance if no modifications were made in the result of this operation.
*/
inline operator fun PersistentMap.plus(pairs: Sequence>): PersistentMap = putAll(pairs)
/**
* Returns the result of merging the specified [map] with this map.
*
* The effect of this call is equivalent to that of calling `put(k, v)` once for each
* mapping from key `k` to value `v` in the specified map.
*
* @return a new persistent map with keys and values from the specified [map] associated;
* or this instance if no modifications were made in the result of this operation.
*/
inline operator fun PersistentMap.plus(map: Map): PersistentMap = putAll(map)
/**
* Returns the result of merging the specified [map] with this map.
*
* The effect of this call is equivalent to that of calling `put(k, v)` once for each
* mapping from key `k` to value `v` in the specified map.
*
* @return a new persistent map with keys and values from the specified [map] associated;
* or this instance if no modifications were made in the result of this operation.
*/
public fun PersistentMap.putAll(map: Map): PersistentMap =
(this as PersistentMap).putAll(map)
/**
* Returns the result of replacing or adding entries to this map from the specified key-value pairs.
*
* @return a new persistent map with entries from the specified key-value pairs added;
* or this instance if no modifications were made in the result of this operation.
*/
public fun PersistentMap.putAll(pairs: Iterable>): PersistentMap
= mutate { it.putAll(pairs) }
/**
* Returns the result of replacing or adding entries to this map from the specified key-value pairs.
*
* @return a new persistent map with entries from the specified key-value pairs added;
* or this instance if no modifications were made in the result of this operation.
*/
public fun PersistentMap.putAll(pairs: Array>): PersistentMap
= mutate { it.putAll(pairs) }
/**
* Returns the result of replacing or adding entries to this map from the specified key-value pairs.
*
* @return a new persistent map with entries from the specified key-value pairs added;
* or this instance if no modifications were made in the result of this operation.
*/
public fun PersistentMap.putAll(pairs: Sequence>): PersistentMap
= mutate { it.putAll(pairs) }
/**
* Returns the result of removing the specified [key] and its corresponding value from this map.
*
* @return a new persistent map with the specified [key] and its corresponding value removed;
* or this instance if it contains no mapping for the key.
*/
public operator fun PersistentMap.minus(key: K): PersistentMap
= (this as PersistentMap).remove(key)
/**
* Returns the result of removing the specified [keys] and their corresponding values from this map.
*
* @return a new persistent map with the specified [keys] and their corresponding values removed;
* or this instance if no modifications were made in the result of this operation.
*/
public operator fun PersistentMap.minus(keys: Iterable): PersistentMap
= mutate { it.minusAssign(keys) }
/**
* Returns the result of removing the specified [keys] and their corresponding values from this map.
*
* @return a new persistent map with the specified [keys] and their corresponding values removed;
* or this instance if no modifications were made in the result of this operation.
*/
public operator fun PersistentMap.minus(keys: Array): PersistentMap
= mutate { it.minusAssign(keys) }
/**
* Returns the result of removing the specified [keys] and their corresponding values from this map.
*
* @return a new persistent map with the specified [keys] and their corresponding values removed;
* or this instance if no modifications were made in the result of this operation.
*/
public operator fun PersistentMap.minus(keys: Sequence): PersistentMap
= mutate { it.minusAssign(keys) }
/**
* Returns a new persistent list of the specified elements.
*/
fun persistentListOf(vararg elements: E): PersistentList = persistentVectorOf().addAll(elements.asList())
/**
* Returns an empty persistent list.
*/
fun persistentListOf(): PersistentList = persistentVectorOf()
/**
* Returns a new persistent set with the given elements.
*
* Elements of the returned set are iterated in the order they were specified.
*/
fun persistentSetOf(vararg elements: E): PersistentSet = PersistentOrderedSet.emptyOf().addAll(elements.asList())
/**
* Returns an empty persistent set.
*/
fun persistentSetOf(): PersistentSet = PersistentOrderedSet.emptyOf()
/**
* Returns a new persistent set with the given elements.
*
* Order of the elements in the returned set is unspecified.
*/
fun persistentHashSetOf(vararg elements: E): PersistentSet = PersistentHashSet.emptyOf().addAll(elements.asList())
/**
* Returns an empty persistent set.
*/
fun persistentHashSetOf(): PersistentSet = PersistentHashSet.emptyOf()
/**
* Returns a new persistent map with the specified contents, given as a list of pairs
* where the first component is the key and the second is the value.
*
* If multiple pairs have the same key, the resulting map will contain the value from the last of those pairs.
*
* Entries of the map are iterated in the order they were specified.
*/
fun persistentMapOf(vararg pairs: Pair): PersistentMap = PersistentOrderedMap.emptyOf().mutate { it += pairs }
/**
* Returns an empty persistent map.
*/
fun persistentMapOf(): PersistentMap = PersistentOrderedMap.emptyOf()
/**
* Returns a new persistent map with the specified contents, given as a list of pairs
* where the first component is the key and the second is the value.
*
* If multiple pairs have the same key, the resulting map will contain the value from the last of those pairs.
*
* Order of the entries in the returned map is unspecified.
*/
fun persistentHashMapOf(vararg pairs: Pair): PersistentMap = PersistentHashMap.emptyOf().mutate { it += pairs }
/**
* Returns an empty persistent map.
*/
fun persistentHashMapOf(): PersistentMap = PersistentHashMap.emptyOf()
/**
* Returns a new persistent list of the specified elements.
*/
@Deprecated("Use persistentListOf instead.", ReplaceWith("persistentListOf(*elements)"))
fun immutableListOf(vararg elements: E): PersistentList = persistentListOf(*elements)
/**
* Returns an empty persistent list.
*/
@Deprecated("Use persistentListOf instead.", ReplaceWith("persistentListOf()"))
fun immutableListOf(): PersistentList = persistentListOf()
/**
* Returns a new persistent set with the given elements.
*
* Elements of the returned set are iterated in the order they were specified.
*/
@Deprecated("Use persistentSetOf instead.", ReplaceWith("persistentSetOf(*elements)"))
fun immutableSetOf(vararg elements: E): PersistentSet = persistentSetOf(*elements)
/**
* Returns an empty persistent set.
*/
@Deprecated("Use persistentSetOf instead.", ReplaceWith("persistentSetOf()"))
fun immutableSetOf(): PersistentSet = persistentSetOf()
/**
* Returns a new persistent set with the given elements.
*
* Order of the elements in the returned set is unspecified.
*/
@Deprecated("Use persistentHashSetOf instead.", ReplaceWith("persistentHashSetOf(*elements)"))
fun immutableHashSetOf(vararg elements: E): PersistentSet = persistentHashSetOf(*elements)
/**
* Returns a new persistent map with the specified contents, given as a list of pairs
* where the first component is the key and the second is the value.
*
* If multiple pairs have the same key, the resulting map will contain the value from the last of those pairs.
*
* Entries of the map are iterated in the order they were specified.
*/
@Deprecated("Use persistentMapOf instead.", ReplaceWith("persistentMapOf(*pairs)"))
fun immutableMapOf(vararg pairs: Pair): PersistentMap = persistentMapOf(*pairs)
/**
* Returns a new persistent map with the specified contents, given as a list of pairs
* where the first component is the key and the second is the value.
*
* If multiple pairs have the same key, the resulting map will contain the value from the last of those pairs.
*
* Order of the entries in the returned map is unspecified.
*/
@Deprecated("Use persistentHashMapOf instead.", ReplaceWith("persistentHashMapOf(*pairs)"))
fun immutableHashMapOf(vararg pairs: Pair): PersistentMap = persistentHashMapOf(*pairs)
/**
* Returns an immutable list containing all elements of this collection.
*
* If the receiver is already an immutable list, returns it as is.
*/
fun Iterable.toImmutableList(): ImmutableList =
this as? ImmutableList
?: this.toPersistentList()
/**
* Returns an immutable list containing all elements of this sequence.
*/
fun Sequence.toImmutableList(): ImmutableList = toPersistentList()
/**
* Returns an immutable list containing all characters.
*/
fun CharSequence.toImmutableList(): ImmutableList = toPersistentList()
// fun Array.toImmutableList(): ImmutableList = immutableListOf() + this.asList()
/**
* Returns a persistent list containing all elements of this collection.
*
* If the receiver is already a persistent list, returns it as is.
* If the receiver is a persistent list builder, calls `build` on it and returns the result.
*/
fun Iterable.toPersistentList(): PersistentList =
this as? PersistentList
?: (this as? PersistentList.Builder)?.build()
?: persistentListOf() + this
/**
* Returns a persistent list containing all elements of this sequence.
*/
fun Sequence.toPersistentList(): PersistentList = persistentListOf() + this
/**
* Returns a persistent list containing all characters.
*/
fun CharSequence.toPersistentList(): PersistentList =
persistentListOf().mutate { this.toCollection(it) }
/**
* Returns an immutable set of all elements of this collection.
*
* If the receiver is already an immutable set, returns it as is.
*
* Elements of the returned set are iterated in the same order as in this collection.
*/
fun Iterable.toImmutableSet(): ImmutableSet =
this as? ImmutableSet
?: (this as? PersistentSet.Builder)?.build()
?: persistentSetOf() + this
/**
* Returns an immutable set of all elements of this sequence.
*
* Elements of the returned set are iterated in the same order as in this sequence.
*/
fun Sequence.toImmutableSet(): ImmutableSet = toPersistentSet()
/**
* Returns an immutable set of all characters.
*
* Elements of the returned set are iterated in the same order as in this char sequence.
*/
fun CharSequence.toImmutableSet(): PersistentSet = toPersistentSet()
/**
* Returns a persistent set of all elements of this collection.
*
* If the receiver is already a persistent set, returns it as is.
* If the receiver is a persistent set builder, calls `build` on it and returns the result.
*
* Elements of the returned set are iterated in the same order as in this collection.
*/
fun Iterable.toPersistentSet(): PersistentSet =
this as? PersistentOrderedSet
?: (this as? PersistentOrderedSetBuilder)?.build()
?: PersistentOrderedSet.emptyOf() + this
/**
* Returns a persistent set of all elements of this sequence.
*
* Elements of the returned set are iterated in the same order as in this sequence.
*/
fun Sequence