Add persistent Collection builder functions

Author: Goooler

core/api/kotlinx-collections-immutable.api

@@ -1,4 +1,9 @@
 public final class kotlinx/collections/immutable/ExtensionsKt {
+	public static final fun buildPersistentHashMap (Lkotlin/jvm/functions/Function1;)Lkotlinx/collections/immutable/PersistentMap;
+	public static final fun buildPersistentHashSet (Lkotlin/jvm/functions/Function1;)Lkotlinx/collections/immutable/PersistentSet;
+	public static final fun buildPersistentList (Lkotlin/jvm/functions/Function1;)Lkotlinx/collections/immutable/PersistentList;
+	public static final fun buildPersistentMap (Lkotlin/jvm/functions/Function1;)Lkotlinx/collections/immutable/PersistentMap;
+	public static final fun buildPersistentSet (Lkotlin/jvm/functions/Function1;)Lkotlinx/collections/immutable/PersistentSet;
 	public static final fun immutableHashMapOf ([Lkotlin/Pair;)Lkotlinx/collections/immutable/PersistentMap;
 	public static final fun immutableHashSetOf ([Ljava/lang/Object;)Lkotlinx/collections/immutable/PersistentSet;
 	public static final fun immutableListOf ()Lkotlinx/collections/immutable/PersistentList;

core/commonMain/src/extensions.kt

@@ -16,6 +16,10 @@ import kotlinx.collections.immutable.implementations.persistentOrderedMap.Persis
 import kotlinx.collections.immutable.implementations.persistentOrderedMap.PersistentOrderedMapBuilder
 import kotlinx.collections.immutable.implementations.persistentOrderedSet.PersistentOrderedSet
 import kotlinx.collections.immutable.implementations.persistentOrderedSet.PersistentOrderedSetBuilder
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
+import kotlin.experimental.ExperimentalTypeInference
 
 //@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
 //inline fun <T> @kotlin.internal.Exact ImmutableCollection<T>.mutate(mutator: (MutableCollection<T>) -> Unit): ImmutableCollection<T> = builder().apply(mutator).build()
@@ -766,3 +770,76 @@ public fun <K, V> Map<K, V>.toPersistentHashMap(): PersistentMap<K, V>
         = this as? PersistentHashMap
         ?: (this as? PersistentHashMapBuilder<K, V>)?.build()
         ?: PersistentHashMap.emptyOf<K, V>().putAll(this)
+
+/**
+ * Builds a new [PersistentList] by populating a [PersistentList.Builder] using the given [builderAction]
+ * and returning an immutable list with the same elements.
+ *
+ * The list passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside the function produces an unspecified behavior.
+ */
+@OptIn(ExperimentalTypeInference::class, ExperimentalContracts::class)
+public inline fun <T> buildPersistentList(@BuilderInference builderAction: PersistentList.Builder<T>.() -> Unit): PersistentList<T> {
+        contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
+        return persistentListOf<T>().builder().apply(builderAction).build()
+}
+
+/**
+ * Builds a new [PersistentSet] by populating a [PersistentSet.Builder] using the given [builderAction]
+ * and returning an immutable set with the same elements.
+ *
+ * The set passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside the function produces an unspecified behavior.
+ *
+ * Elements of the set are iterated in the order they were added by the [builderAction].
+ */
+@OptIn(ExperimentalTypeInference::class, ExperimentalContracts::class)
+public inline fun <T> buildPersistentSet(@BuilderInference builderAction: PersistentSet.Builder<T>.() -> Unit): PersistentSet<T> {
+        contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
+        return persistentSetOf<T>().builder().apply(builderAction).build()
+}
+
+/**
+ * Builds a new [PersistentSet] by populating a [PersistentSet.Builder] using the given [builderAction]
+ * and returning an immutable set with the same elements.
+ *
+ * The set passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside the function produces an unspecified behavior.
+ *
+ * Order of the elements in the returned set is unspecified.
+ */
+@OptIn(ExperimentalTypeInference::class, ExperimentalContracts::class)
+public inline fun <T> buildPersistentHashSet(@BuilderInference builderAction: PersistentSet.Builder<T>.() -> Unit): PersistentSet<T> {
+        contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
+        return persistentHashSetOf<T>().builder().apply(builderAction).build()
+}
+
+/**
+ * Builds a new [PersistentMap] by populating a [PersistentMap.Builder] using the given [builderAction]
+ * and returning an immutable map with the same key-value pairs.
+ *
+ * The map passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside the function produces an unspecified behavior.
+ *
+ * Entries of the map are iterated in the order they were added by the [builderAction].
+ */
+@OptIn(ExperimentalTypeInference::class, ExperimentalContracts::class)
+public inline fun <K, V> buildPersistentMap(@BuilderInference builderAction: PersistentMap.Builder<K, V>.() -> Unit): PersistentMap<K, V> {
+        contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
+        return persistentMapOf<K, V>().builder().apply(builderAction).build()
+}
+
+/**
+ * Builds a new [PersistentMap] by populating a [PersistentMap.Builder] using the given [builderAction]
+ * and returning an immutable map with the same key-value pairs.
+ *
+ * The map passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside the function produces an unspecified behavior.
+ *
+ * Order of the entries in the returned map is unspecified.
+ */
+@OptIn(ExperimentalTypeInference::class, ExperimentalContracts::class)
+public inline fun <K, V> buildPersistentHashMap(@BuilderInference builderAction: PersistentMap.Builder<K, V>.() -> Unit): PersistentMap<K, V> {
+        contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
+        return persistentHashMapOf<K, V>().builder().apply(builderAction).build()
+}

core/commonTest/src/contract/list/ImmutableListTest.kt

@@ -152,6 +152,16 @@ class ImmutableListTest {
         }
     }
 
+    @Test fun buildPersistentList() {
+        val expected = persistentListOf(1, 2, 3, 4, 5, 6)
+        val actual = buildPersistentList {
+            for (i in 1..6) {
+                add(i)
+            }
+        }
+        assertEquals(expected, actual)
+    }
+
     @Test fun subListOfBuilder() {
         val list = "abcxaxyz12".toImmutableList().toPersistentList()
         val builder = list.builder()

core/commonTest/src/contract/map/ImmutableMapTest.kt

@@ -78,6 +78,21 @@ class ImmutableHashMapTest : ImmutableMapTest() {
         compareMaps(expected, builder1.build())
     }
 
+    @Test fun buildPersistentHashMap() {
+        val expected = mutableMapOf<String, Int>()
+        val actual = buildPersistentHashMap {
+            for (i in 300..400) {
+                put("$i", i)
+                expected["$i"] = i
+            }
+            for (i in 0..200) {
+                put("$i", i)
+                expected["$i"] = i
+            }
+        }
+        compareMapsUnordered(expected, actual)
+    }
+
     @Test fun regressionGithubIssue109() {
         // https://github.com/Kotlin/kotlinx.collections.immutable/issues/109
         val map0 = immutableMapOf<Int, Int>().put(0, 0).put(1, 1).put(32, 32)
@@ -139,6 +154,21 @@ class ImmutableOrderedMapTest : ImmutableMapTest() {
         changing.add("break iteration")
         assertFailsWith<ConcurrentModificationException> { builder.filter { it.key === changing } }
     }
+
+    @Test fun buildPersistentMap() {
+        val expected = mutableMapOf<String, Int>()
+        val actual = buildPersistentMap {
+            for (i in 300..400) {
+                put("$i", i)
+                expected["$i"] = i
+            }
+            for (i in 0..200) {
+                put("$i", i)
+                expected["$i"] = i
+            }
+        }
+        compareMaps(expected, actual)
+    }
 }
 
 abstract class ImmutableMapTest {

core/commonTest/src/contract/set/ImmutableSetTest.kt

@@ -195,6 +195,17 @@ class ImmutableHashSetTest : ImmutableSetTestBase() {
             compareSets(immutableSetOf<Int>(), left - right)
         }
     }
+
+    @Test fun buildPersistentHashSet() {
+        val expected = mutableSetOf<Int>()
+        val actual = buildPersistentHashSet {
+            for (i in 0..2000) {
+                add(i)
+                expected.add(i)
+            }
+        }
+        compareSetsUnordered(expected, actual)
+    }
 }
 
 class ImmutableOrderedSetTest : ImmutableSetTestBase() {
@@ -221,6 +232,17 @@ class ImmutableOrderedSetTest : ImmutableSetTestBase() {
         changing.add("break iteration")
         assertFailsWith<ConcurrentModificationException> { builder.filter { it === changing } }
     }
+
+    @Test fun buildPersistentSet() {
+        val expected = mutableSetOf<Int>()
+        val actual = buildPersistentSet {
+            for (i in 0..2000) {
+                add(i)
+                expected.add(i)
+            }
+        }
+        compareSets(expected, actual)
+    }
 }
 
 abstract class ImmutableSetTestBase {