Skip to content
master
Switch branches/tags
Code

Latest commit

… produce incorrect results #114

When putting all entries of a cell (1) into another cell (2), if (1) is an entry and (2) is a node, for optimization reasons the entry is put into the node. This leads to saving the old value of the entry if the node already contains the key.
06a2423

Git stats

Files

Permalink
Failed to load latest commit information.

Immutable Collections Library for Kotlin

JetBrains incubator project GitHub license Build status Maven Central IR

Immutable collection interfaces and implementation prototypes for Kotlin.

This is a multiplatform library providing implementations for jvm, js, mingwX64, linuxX64, macosX64, iosX64, iosArm64, iosArm32 Kotlin targets.

For further details see the proposal.

What's in this library

Interfaces and implementations

This library provides interfaces for immutable and persistent collections.

Immutable collection interfaces

Interface Bases
ImmutableCollection Collection
ImmutableList ImmutableCollection, List
ImmutableSet ImmutableCollection, Set
ImmutableMap Map

Persistent collection interfaces

Interface Bases
PersistentCollection ImmutableCollection
PersistentList PersistentCollection, ImmutableList
PersistentSet PersistentCollection, ImmutableSet
PersistentMap ImmutableMap

Persistent collection builder interfaces

Interface Bases
PersistentCollection.Builder MutableCollection
PersistentList.Builder PersistentCollection.Builder, MutableList
PersistentSet.Builder PersistentCollection.Builder, MutableSet
PersistentMap.Builder MutableMap

To instantiate an empty persistent collection or a collection with the specified elements use the functions persistentListOf, persistentSetOf, and persistentMapOf.

The default implementations of PersistentSet and PersistentMap, which are returned by persistentSetOf and persistentMapOf, preserve the element insertion order during iteration. This comes at expense of maintaining more complex data structures. If the order of elements doesn't matter, the more efficient implementations returned by the functions persistentHashSetOf and persistentHashMapOf can be used.

Operations

toImmutableList/Set/Map

Converts a read-only or mutable collection to an immutable one. If the receiver is already immutable and has the required type, returns it as is.

fun Iterable<T>.toImmutableList(): ImmutableList<T>
fun Iterable<T>.toImmutableSet(): ImmutableSet<T>

toPersistentList/Set/Map

Converts a read-only or mutable collection to a persistent one. If the receiver is already persistent and has the required type, returns it as is. If the receiver is a builder of the required persistent collection type, calls build on it and returns the result.

fun Iterable<T>.toPersistentList(): PersistentList<T>
fun Iterable<T>.toPersistentSet(): PersistentSet<T>

+ and - operators

plus and minus operators on persistent collections exploit their immutability and delegate the implementation to the collections themselves. The operation is performed with persistence in mind: the returned immutable collection may share storage with the original collection.

val newList = persistentListOf("a", "b") + "c"
// newList is also a PersistentList

Note: you need to import these operators from kotlinx.collections.immutable package in order for them to take the precedence over the ones from the standard library.

import kotlinx.collections.immutable.*

Mutate

mutate extension function simplifies quite common pattern of persistent collection modification: get a builder, apply some mutating operations on it, transform it back to a persistent collection:

collection.builder().apply { some_actions_on(this) }.build()

With mutate it transforms to:

collection.mutate { some_actions_on(it) }

Using in your projects

Note that the library is experimental and the API is subject to change.

The library is published to Maven Central repository.

The library depends on the Kotlin Standard Library of the version at least 1.4.30.

Gradle

Add the Maven Central repository:

repositories {
    mavenCentral()
}

Add the library to dependencies of the platform source set, e.g.:

kotlin {
    sourceSets {
        commonMain {
             dependencies {
                 implementation("org.jetbrains.kotlinx:kotlinx-collections-immutable:0.3.4")
             }
        }
    }
}

Maven

The Maven Central repository is available for dependency lookup by default. Add dependencies (you can also add other modules that you need):

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-collections-immutable-jvm</artifactId>
    <version>0.3.4</version>
</dependency>

Building from source

ℹ️ To build this project you will need to have a path to JDK 6 specified with the JDK_6 environment variable or gradle property. For the local development purposes any JDK newer than that can be used instead.

You can build and install artifacts to maven local with:

gradlew build install

About

Immutable persistent collections for Kotlin

Topics

Resources

License

Code of conduct

Packages

No packages published

Languages