From 7bb504321ce1a9092246e983b17410052348cd79 Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Tue, 21 Jan 2020 05:19:28 +0300
Subject: [PATCH] KT-15363 Rename expectedSize to capacity and edit docs

---
 .../src/kotlin/collections/Collections.kt     | 23 +++++++++++----
 .../stdlib/src/kotlin/collections/Maps.kt     | 28 ++++++++++++++-----
 .../stdlib/src/kotlin/collections/Sets.kt     | 28 ++++++++++++++-----
 3 files changed, 59 insertions(+), 20 deletions(-)

diff --git a/libraries/stdlib/src/kotlin/collections/Collections.kt b/libraries/stdlib/src/kotlin/collections/Collections.kt
index a052d33e351..18c476af78f 100644
--- a/libraries/stdlib/src/kotlin/collections/Collections.kt
+++ b/libraries/stdlib/src/kotlin/collections/Collections.kt
@@ -155,7 +155,11 @@ public inline fun <T> MutableList(size: Int, init: (index: Int) -> T): MutableLi
 }
 
 /**
- * Build a new read-only [List] with the [elements][E] from the [builderAction].
+ * Builds a new read-only [List] by populating a [MutableList] using the given [builderAction]
+ * and returning a read-only list with the same elements.
+ *
+ * The list passed as a receiver to the [builderAction] is valid only inside that function.
+ * Using it outside of the function produces an unspecified behavior.
  *
  * @sample samples.collections.Builders.Lists.buildListSample
  */
@@ -168,18 +172,25 @@ public inline fun <E> buildList(@BuilderInference builderAction: MutableList<E>.
 }
 
 /**
- * Build a new read-only [List] with the given [expectedSize] and [elements][E] from the [builderAction].
+ * Builds a new read-only [List] by populating a [MutableList] using the given [builderAction]
+ * and returning a read-only list with the same elements.
+ *
+ * The list 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].
+ *
+ * @throws IllegalArgumentException if the given [capacity] is negative.
  *
  * @sample samples.collections.Builders.Lists.buildListSample
- * @throws IllegalArgumentException if the given [expectedSize] is negative.
  */
 @SinceKotlin("1.3")
 @ExperimentalStdlibApi
 @kotlin.internal.InlineOnly
-public inline fun <E> buildList(expectedSize: Int, @BuilderInference builderAction: MutableList<E>.() -> Unit): List<E> {
+public inline fun <E> buildList(capacity: Int, @BuilderInference builderAction: MutableList<E>.() -> Unit): List<E> {
     contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
-    checkBuilderCapacity(expectedSize)
-    return ArrayList<E>(expectedSize).apply(builderAction)
+    checkBuilderCapacity(capacity)
+    return ArrayList<E>(capacity).apply(builderAction)
 }
 
 
diff --git a/libraries/stdlib/src/kotlin/collections/Maps.kt b/libraries/stdlib/src/kotlin/collections/Maps.kt
index 0757c82b6b2..b7e2daff563 100644
--- a/libraries/stdlib/src/kotlin/collections/Maps.kt
+++ b/libraries/stdlib/src/kotlin/collections/Maps.kt
@@ -124,7 +124,13 @@ public inline fun <K, V> linkedMapOf(): LinkedHashMap<K, V> = LinkedHashMap<K, V
 public fun <K, V> linkedMapOf(vararg pairs: Pair<K, V>): LinkedHashMap<K, V> = pairs.toMap(LinkedHashMap(mapCapacity(pairs.size)))
 
 /**
- * Build a new read-only [Map] with the [key][K]-[value][V] pairs from the [builderAction] while preserving the insertion order.
+ * Builds a new read-only [Map] by populating a [MutableMap] using the given [builderAction]
+ * and returning a read-only 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 of the function produces an unspecified behavior.
+ *
+ * Entries of the map are iterated in the order they were added by the [builderAction].
  *
  * @sample samples.collections.Builders.Maps.buildMapSample
  */
@@ -137,19 +143,27 @@ public inline fun <K, V> buildMap(@BuilderInference builderAction: MutableMap<K,
 }
 
 /**
- * Build a new read-only [Map] with the given [expectedSize] and [key][K]-[value][V] pairs from the [builderAction] while preserving
- * the insertion order.
+ * Builds a new read-only [Map] by populating a [MutableMap] using the given [builderAction]
+ * and returning a read-only 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 of the function produces an unspecified behavior.
+ *
+ * [capacity] is used to hint the expected number of pairs added in the [builderAction].
+ *
+ * Entries of the map are iterated in the order they were added by the [builderAction].
+ *
+ * @throws IllegalArgumentException if the given [capacity] is negative.
  *
  * @sample samples.collections.Builders.Maps.buildMapSample
- * @throws IllegalArgumentException if the given [expectedSize] is negative.
  */
 @SinceKotlin("1.3")
 @ExperimentalStdlibApi
 @kotlin.internal.InlineOnly
-public inline fun <K, V> buildMap(expectedSize: Int, @BuilderInference builderAction: MutableMap<K, V>.() -> Unit): Map<K, V> {
+public inline fun <K, V> buildMap(capacity: Int, @BuilderInference builderAction: MutableMap<K, V>.() -> Unit): Map<K, V> {
     contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
-    checkBuilderCapacity(expectedSize)
-    return LinkedHashMap<K, V>(mapCapacity(expectedSize)).apply(builderAction)
+    checkBuilderCapacity(capacity)
+    return LinkedHashMap<K, V>(mapCapacity(capacity)).apply(builderAction)
 }
 
 /**
diff --git a/libraries/stdlib/src/kotlin/collections/Sets.kt b/libraries/stdlib/src/kotlin/collections/Sets.kt
index 1112d70d9fc..9628034285a 100644
--- a/libraries/stdlib/src/kotlin/collections/Sets.kt
+++ b/libraries/stdlib/src/kotlin/collections/Sets.kt
@@ -91,7 +91,13 @@ public inline fun <T> linkedSetOf(): LinkedHashSet<T> = LinkedHashSet()
 public fun <T> linkedSetOf(vararg elements: T): LinkedHashSet<T> = elements.toCollection(LinkedHashSet(mapCapacity(elements.size)))
 
 /**
- * Build a new read-only [Set] with the [elements][E] from the [builderAction] while preserving the insertion order.
+ * 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].
  *
  * @sample samples.collections.Builders.Sets.buildSetSample
  */
@@ -104,19 +110,27 @@ public inline fun <E> buildSet(@BuilderInference builderAction: MutableSet<E>.()
 }
 
 /**
- * Build a new read-only [Set] with the given [expectedSize] and [elements][E] from the [builderAction] while preserving the insertion
- * order.
+ * 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].
+ *
+ * @throws IllegalArgumentException if the given [capacity] is negative.
  *
  * @sample samples.collections.Builders.Sets.buildSetSample
- * @throws IllegalArgumentException if the given [expectedSize] is negative.
  */
 @SinceKotlin("1.3")
 @ExperimentalStdlibApi
 @kotlin.internal.InlineOnly
-public inline fun <E> buildSet(expectedSize: Int, @BuilderInference builderAction: MutableSet<E>.() -> Unit): Set<E> {
+public inline fun <E> buildSet(capacity: Int, @BuilderInference builderAction: MutableSet<E>.() -> Unit): Set<E> {
     contract { callsInPlace(builderAction, InvocationKind.EXACTLY_ONCE) }
-    checkBuilderCapacity(expectedSize)
-    return LinkedHashSet<E>(mapCapacity(expectedSize)).apply(builderAction)
+    checkBuilderCapacity(capacity)
+    return LinkedHashSet<E>(mapCapacity(capacity)).apply(builderAction)
 }