kotlinx-collections-immutable/kotlinx.collections.immutable

Package-level declarations

The main API: immutable and persistent collection interfaces (ImmutableList, PersistentMap, etc.), entry-point factory functions (persistentListOf, persistentSetOf, persistentMapOf and their hash-based counterparts), and extension functions for conversion (toImmutableList, toPersistentSet, …), operators (+, -), and batch updates (mutate).

Types

ImmutableCollection

interface ImmutableCollection<out E> : Collection<E>

A generic immutable collection of elements. Methods in this interface support only read-only access to the collection.

ImmutableList

interface ImmutableList<out E> : List<E> , ImmutableCollection<E>

A generic immutable ordered collection of elements. Methods in this interface support only read-only access to the immutable list.

ImmutableMap

interface ImmutableMap<K, out V> : Map<K, V>

A generic immutable collection that holds pairs of objects (keys and values) and supports efficiently retrieving the value corresponding to each key. Map keys are unique; the map holds only one value for each key. Methods in this interface support only read-only access to the immutable map.

ImmutableSet

interface ImmutableSet<out E> : Set<E> , ImmutableCollection<E>

A generic immutable unordered collection of elements that does not support duplicate elements. Methods in this interface support only read-only access to the immutable set.

PersistentCollection

interface PersistentCollection<out E> : ImmutableCollection<E>

A generic persistent collection of elements that supports adding and removing elements.

PersistentList

interface PersistentList<out E> : ImmutableList<E> , PersistentCollection<E>

A generic persistent ordered collection of elements that supports adding and removing elements.

PersistentMap

interface PersistentMap<K, out V> : ImmutableMap<K, V>

A generic persistent collection that holds pairs of objects (keys and values) and supports efficiently retrieving the value corresponding to each key. Map keys are unique; the map holds only one value for each key.

PersistentSet

interface PersistentSet<out E> : ImmutableSet<E> , PersistentCollection<E>

A generic persistent unordered collection of elements that does not support duplicate elements, and supports adding and removing elements.

Functions

intersect

infix fun <E> PersistentCollection<E>.intersect(elements: Iterable<E>): PersistentSet<E>

Returns a new persistent set with elements in this collection that are also contained in the specified elements collection.

infix fun <E> PersistentSet<E>.intersect(elements: Iterable<E>): PersistentSet<E>

Returns 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.

minus

inline operator fun <E> PersistentCollection<E>.minus(element: E): PersistentCollection<E>

Returns 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.

operator fun <E> PersistentCollection<E>.minus(elements: Array<out E>): PersistentCollection<E>

Returns a new persistent collection containing all elements of this collection except the elements contained in the specified elements array, or this instance if there are no elements to remove.

operator fun <E> PersistentCollection<E>.minus(elements: Iterable<E>): PersistentCollection<E>

Returns a new persistent collection containing all elements of this collection except the elements contained in the specified elements collection, or this instance if there are no elements to remove.

operator fun <E> PersistentCollection<E>.minus(elements: Sequence<E>): PersistentCollection<E>

Returns a new persistent collection containing all elements of this collection except the elements contained in the specified elements sequence, or this instance if there are no elements to remove.

inline operator fun <E> PersistentList<E>.minus(element: E): PersistentList<E>

Returns 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.

operator fun <E> PersistentList<E>.minus(elements: Array<out E>): PersistentList<E>

Returns a new persistent list containing all elements of this list except the elements contained in the specified elements array, or this instance if there are no elements to remove.

operator fun <E> PersistentList<E>.minus(elements: Iterable<E>): PersistentList<E>

Returns a new persistent list containing all elements of this list except the elements contained in the specified elements collection, or this instance if there are no elements to remove.

operator fun <E> PersistentList<E>.minus(elements: Sequence<E>): PersistentList<E>

Returns a new persistent list containing all elements of this list except the elements contained in the specified elements sequence, or this instance if there are no elements to remove.

operator fun <K, V> PersistentMap<out K, V>.minus(key: K): PersistentMap<K, V>

Returns a new persistent map with the specified key and its corresponding value removed, or this instance if it contains no mapping for the key.

operator fun <K, V> PersistentMap<out K, V>.minus(keys: Array<out K>): PersistentMap<K, V>

Returns a new persistent map containing all entries of this map except those whose keys are contained in the specified keys array, or this instance if there are no entries to remove.

operator fun <K, V> PersistentMap<out K, V>.minus(keys: Iterable<K>): PersistentMap<K, V>

Returns a new persistent map containing all entries of this map except those whose keys are contained in the specified keys collection, or this instance if there are no entries to remove.

operator fun <K, V> PersistentMap<out K, V>.minus(keys: Sequence<K>): PersistentMap<K, V>

Returns a new persistent map containing all entries of this map except those whose keys are contained in the specified keys sequence, or this instance if there are no entries to remove.

inline operator fun <E> PersistentSet<E>.minus(element: E): PersistentSet<E>

Returns a new persistent set with the specified element removed, or this instance if there is no such element in this set.

operator fun <E> PersistentSet<E>.minus(elements: Array<out E>): PersistentSet<E>

Returns a new persistent set containing all elements of this set except the elements contained in the specified elements array, or this instance if there are no elements to remove.

operator fun <E> PersistentSet<E>.minus(elements: Iterable<E>): PersistentSet<E>

Returns a new persistent set containing all elements of this set except the elements contained in the specified elements collection, or this instance if there are no elements to remove.

operator fun <E> PersistentSet<E>.minus(elements: Sequence<E>): PersistentSet<E>

Returns a new persistent set containing all elements of this set except the elements contained in the specified elements sequence, or this instance if there are no elements to remove.

mutate

inline fun <T> PersistentList<T>.mutate(mutator: (MutableList<T>) -> Unit): PersistentList<T>

Returns 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 <K, V> PersistentMap<out K, V>.mutate(mutator: (MutableMap<K, V>) -> Unit): PersistentMap<K, V>

Returns 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 <T> PersistentSet<T>.mutate(mutator: (MutableSet<T>) -> Unit): PersistentSet<T>

Returns a new persistent set with the provided modifications applied, or this instance if no modifications were made in the result of this operation.

persistentHashMapOf

fun <K, V> persistentHashMapOf(): PersistentMap<K, V>

Returns an empty persistent map.

fun <K, V> persistentHashMapOf(vararg pairs: Pair<K, V>): PersistentMap<K, V>

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.

persistentHashSetOf

fun <E> persistentHashSetOf(): PersistentSet<E>

Returns an empty persistent set.

fun <E> persistentHashSetOf(vararg elements: E): PersistentSet<E>

Returns a new persistent set with the given elements.

persistentListOf

fun <E> persistentListOf(): PersistentList<E>

Returns an empty persistent list.

fun <E> persistentListOf(vararg elements: E): PersistentList<E>

Returns a new persistent list of the specified elements.

persistentMapOf

fun <K, V> persistentMapOf(): PersistentMap<K, V>

Returns an empty persistent map.

fun <K, V> persistentMapOf(vararg pairs: Pair<K, V>): PersistentMap<K, V>

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.

persistentSetOf

fun <E> persistentSetOf(): PersistentSet<E>

Returns an empty persistent set.

fun <E> persistentSetOf(vararg elements: E): PersistentSet<E>

Returns a new persistent set with the given elements.

plus

inline operator fun <E> PersistentCollection<E>.plus(element: E): PersistentCollection<E>

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.

operator fun <E> PersistentCollection<E>.plus(elements: Array<out E>): PersistentCollection<E>

Returns 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 <E> PersistentCollection<E>.plus(elements: Iterable<E>): PersistentCollection<E>

Returns 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 <E> PersistentCollection<E>.plus(elements: Sequence<E>): PersistentCollection<E>

Returns 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.

inline operator fun <E> PersistentList<E>.plus(element: E): PersistentList<E>

Returns a new persistent list with the specified element appended.

operator fun <E> PersistentList<E>.plus(elements: Array<out E>): PersistentList<E>

Returns a new persistent list with elements of the specified elements array appended, or this instance if the specified array is empty.

operator fun <E> PersistentList<E>.plus(elements: Iterable<E>): PersistentList<E>

Returns a new persistent list with elements of the specified elements collection appended, or this instance if the specified collection is empty.

operator fun <E> PersistentList<E>.plus(elements: Sequence<E>): PersistentList<E>

Returns a new persistent list with elements of the specified elements sequence appended, or this instance if the specified sequence is empty.

inline operator fun <K, V> PersistentMap<out K, V>.plus(pairs: Array<out Pair<K, V>>): PersistentMap<K, V>

inline operator fun <K, V> PersistentMap<out K, V>.plus(pairs: Iterable<Pair<K, V>>): PersistentMap<K, V>

inline operator fun <K, V> PersistentMap<out K, V>.plus(pairs: Sequence<Pair<K, V>>): PersistentMap<K, V>

Returns 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 <K, V> PersistentMap<out K, V>.plus(pair: Pair<K, V>): PersistentMap<K, V>

Returns 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 <K, V> PersistentMap<out K, V>.plus(map: Map<out K, V>): PersistentMap<K, V>

Returns 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 <E> PersistentSet<E>.plus(element: E): PersistentSet<E>

Returns a new persistent set with the specified element added, or this instance if it already contains the element.

operator fun <E> PersistentSet<E>.plus(elements: Array<out E>): PersistentSet<E>

Returns 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 <E> PersistentSet<E>.plus(elements: Iterable<E>): PersistentSet<E>

Returns 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 <E> PersistentSet<E>.plus(elements: Sequence<E>): PersistentSet<E>

Returns 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.

puttingAll

fun <K, V> PersistentMap<out K, V>.puttingAll(pairs: Array<out Pair<K, V>>): PersistentMap<K, V>

fun <K, V> PersistentMap<out K, V>.puttingAll(pairs: Iterable<Pair<K, V>>): PersistentMap<K, V>

fun <K, V> PersistentMap<out K, V>.puttingAll(pairs: Sequence<Pair<K, V>>): PersistentMap<K, V>

Returns 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.

fun <K, V> PersistentMap<out K, V>.puttingAll(map: Map<out K, V>): PersistentMap<K, V>

Returns 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.

toImmutableList