[stdlib] Document that put and add keep the stored key or element

libraries/stdlib/common/src/kotlin/collections/AbstractMutableMap.kt

@@ -20,6 +20,8 @@ public expect abstract class AbstractMutableMap<K, V> : MutableMap<K, V> {
     /**
      * Associates the specified [value] with the specified [key] in the map.
      *
+     * If the map already contains a mapping for [key], the key instance stored in the map is retained.
+     *
      * This method is redeclared as abstract, because it's not implemented in the base class,
      * so it must be always overridden in the concrete mutable collection implementation.
      *

libraries/stdlib/js/builtins/Collections.kt

@@ -611,9 +611,12 @@ public actual interface MutableSet<E> : Set<E>, MutableCollection<E> {
     /**
      * Adds the specified element to the set.
      *
+     * If the set already contains [element], the element instance stored in the set is retained.
+     *
      * @return `true` if the element has been added, `false` if the element is already contained in the set.
      *
      * @sample samples.collections.Collections.Sets.add
+     * @sample samples.collections.Collections.Sets.addKeepsStoredElement
      */
     @JsExport.Ignore
     @IgnorableReturnValue
@@ -625,6 +628,17 @@ public actual interface MutableSet<E> : Set<E>, MutableCollection<E> {
 
     // Bulk Modification Operations
 
+    /**
+     * Adds all of the elements of the specified collection to the set.
+     *
+     * The effect of this call is equivalent to calling [add] for each element of [elements], so the element
+     * instances stored in the set are retained.
+     *
+     * @return `true` if any of the specified elements was added to the set, `false` if the set was not modified.
+     *
+     * @sample samples.collections.Collections.Sets.addAll
+     * @sample samples.collections.Collections.Sets.addKeepsStoredElement
+     */
     @JsExport.Ignore
     @IgnorableReturnValue
     actual override fun addAll(elements: Collection<E>): Boolean
@@ -853,9 +867,12 @@ public actual interface MutableMap<K, V> : Map<K, V> {
     /**
      * Associates the specified [value] with the specified [key] in the map.
      *
+     * If the map already contains a mapping for [key], the key instance stored in the map is retained.
+     *
      * @return the previous value associated with the key, or `null` if the key was not present in the map.
      *
      * @sample samples.collections.Maps.CoreApi.put
+     * @sample samples.collections.Maps.CoreApi.putKeepsStoredKey
      */
     @JsExport.Ignore
     @IgnorableReturnValue
@@ -876,7 +893,11 @@ public actual interface MutableMap<K, V> : Map<K, V> {
     /**
      * Updates this map with key/value pairs from the specified map [from].
      *
+     * The effect of this call is equivalent to calling [put] for each entry of [from], so the key instances
+     * stored in this map are retained.
+     *
      * @sample samples.collections.Maps.CoreApi.putAll
+     * @sample samples.collections.Maps.CoreApi.putKeepsStoredKey
      */
     @JsExport.Ignore
     public actual fun putAll(from: Map<out K, V>): Unit

libraries/stdlib/jvm/builtins/Collections.kt

@@ -502,9 +502,12 @@ public actual interface MutableSet<E> : Set<E>, MutableCollection<E> {
     /**
      * Adds the specified element to the set.
      *
+     * If the set already contains [element], the element instance stored in the set is retained.
+     *
      * @return `true` if the element has been added, `false` if the element is already contained in the set.
      *
      * @sample samples.collections.Collections.Sets.add
+     * @sample samples.collections.Collections.Sets.addKeepsStoredElement
      */
     @IgnorableReturnValue
     actual override fun add(element: E): Boolean
@@ -514,6 +517,17 @@ public actual interface MutableSet<E> : Set<E>, MutableCollection<E> {
 
     // Bulk Modification Operations
 
+    /**
+     * Adds all of the elements of the specified collection to the set.
+     *
+     * The effect of this call is equivalent to calling [add] for each element of [elements], so the element
+     * instances stored in the set are retained.
+     *
+     * @return `true` if any of the specified elements was added to the set, `false` if the set was not modified.
+     *
+     * @sample samples.collections.Collections.Sets.addAll
+     * @sample samples.collections.Collections.Sets.addKeepsStoredElement
+     */
     @IgnorableReturnValue
     actual override fun addAll(elements: Collection<E>): Boolean
     @IgnorableReturnValue
@@ -696,9 +710,12 @@ public actual interface MutableMap<K, V> : Map<K, V> {
     /**
      * Associates the specified [value] with the specified [key] in the map.
      *
+     * If the map already contains a mapping for [key], the key instance stored in the map is retained.
+     *
      * @return the previous value associated with the key, or `null` if the key was not present in the map.
      *
      * @sample samples.collections.Maps.CoreApi.put
+     * @sample samples.collections.Maps.CoreApi.putKeepsStoredKey
      */
     @IgnorableReturnValue
     public actual fun put(key: K, value: V): V?
@@ -730,7 +747,11 @@ public actual interface MutableMap<K, V> : Map<K, V> {
     /**
      * Updates this map with key/value pairs from the specified map [from].
      *
+     * The effect of this call is equivalent to calling [put] for each entry of [from], so the key instances
+     * stored in this map are retained.
+     *
      * @sample samples.collections.Maps.CoreApi.putAll
+     * @sample samples.collections.Maps.CoreApi.putKeepsStoredKey
      */
     public actual fun putAll(from: Map<out K, V>): Unit
 

libraries/stdlib/jvm/src/kotlin/collections/AbstractMutableMap.kt

@@ -20,6 +20,8 @@ public actual abstract class AbstractMutableMap<K, V> protected actual construct
     /**
      * Associates the specified [value] with the specified [key] in the map.
      *
+     * If the map already contains a mapping for [key], the key instance stored in the map is retained.
+     *
      * This method is redeclared as abstract, because it's not implemented in the base class,
      * so it must be always overridden in the concrete mutable collection implementation.
      *

libraries/stdlib/jvm/src/kotlin/collections/AbstractMutableSet.kt

@@ -17,6 +17,8 @@ public actual abstract class AbstractMutableSet<E> protected actual constructor(
     /**
      * Adds the specified element to the set.
      *
+     * If the set already contains [element], the element instance stored in the set is retained.
+     *
      * This method is redeclared as abstract, because it's not implemented in the base class,
      * so it must be always overridden in the concrete mutable collection implementation.
      *

libraries/stdlib/native-wasm/src/kotlin/collections/AbstractMutableMap.kt

@@ -13,6 +13,8 @@ public actual abstract class AbstractMutableMap<K, V> protected actual construct
     /**
      * Associates the specified [value] with the specified [key] in the map.
      *
+     * If the map already contains a mapping for [key], the key instance stored in the map is retained.
+     *
      * @return the previous value associated with the key, or `null` if the key was not present in the map.
      */
     @IgnorableReturnValue

libraries/stdlib/native-wasm/src/kotlin/collections/AbstractMutableSet.kt

@@ -10,6 +10,8 @@ public actual abstract class AbstractMutableSet<E> protected actual constructor(
     /**
      * Adds the specified element to the set.
      *
+     * If the set already contains [element], the element instance stored in the set is retained.
+     *
      * @return `true` if the element has been added, `false` if the element is already contained in the set.
      */
     @IgnorableReturnValue

libraries/stdlib/native-wasm/src/kotlin/collections/Map.kt

@@ -162,9 +162,12 @@ public actual interface MutableMap<K, V> : Map<K, V> {
     /**
      * Associates the specified [value] with the specified [key] in the map.
      *
+     * If the map already contains a mapping for [key], the key instance stored in the map is retained.
+     *
      * @return the previous value associated with the key, or `null` if the key was not present in the map.
      *
      * @sample samples.collections.Maps.CoreApi.put
+     * @sample samples.collections.Maps.CoreApi.putKeepsStoredKey
      */
     @IgnorableReturnValue
     public actual fun put(key: K, value: V): V?
@@ -183,7 +186,11 @@ public actual interface MutableMap<K, V> : Map<K, V> {
     /**
      * Updates this map with key/value pairs from the specified map [from].
      *
+     * The effect of this call is equivalent to calling [put] for each entry of [from], so the key instances
+     * stored in this map are retained.
+     *
      * @sample samples.collections.Maps.CoreApi.putAll
+     * @sample samples.collections.Maps.CoreApi.putKeepsStoredKey
      */
     public actual fun putAll(from: Map<out K, V>): Unit
 

libraries/stdlib/native-wasm/src/kotlin/collections/Set.kt

@@ -74,9 +74,12 @@ public actual interface MutableSet<E> : Set<E>, MutableCollection<E> {
     /**
      * Adds the specified element to the set.
      *
+     * If the set already contains [element], the element instance stored in the set is retained.
+     *
      * @return `true` if the element has been added, `false` if the element is already contained in the set.
      *
      * @sample samples.collections.Collections.Sets.add
+     * @sample samples.collections.Collections.Sets.addKeepsStoredElement
      */
     @IgnorableReturnValue
     actual override fun add(element: E): Boolean
@@ -85,6 +88,17 @@ public actual interface MutableSet<E> : Set<E>, MutableCollection<E> {
     actual override fun remove(element: E): Boolean
 
     // Bulk Modification Operations
+    /**
+     * Adds all of the elements of the specified collection to the set.
+     *
+     * The effect of this call is equivalent to calling [add] for each element of [elements], so the element
+     * instances stored in the set are retained.
+     *
+     * @return `true` if any of the specified elements was added to the set, `false` if the set was not modified.
+     *
+     * @sample samples.collections.Collections.Sets.addAll
+     * @sample samples.collections.Collections.Sets.addKeepsStoredElement
+     */
     @IgnorableReturnValue
     actual override fun addAll(elements: Collection<E>): Boolean
 

libraries/stdlib/samples/test/samples/collections/collections.kt

@@ -671,6 +671,27 @@ class Collections {
             assertPrints(set, "[a, b, c]")
         }
 
+        @Sample
+        fun addKeepsStoredElement() {
+            class User(val id: Int, val name: String) {
+                override fun equals(other: Any?): Boolean = other is User && id == other.id
+                override fun hashCode(): Int = id
+                override fun toString(): String = name
+            }
+
+            val set = mutableSetOf(User(1, "Alice"))
+
+            assertPrints(set.add(User(1, "Alicia")), "false")
+            assertPrints(set, "[Alice]")
+
+            assertPrints(set.addAll(listOf(User(1, "Alicia"))), "false")
+            assertPrints(set, "[Alice]")
+
+            set.remove(User(1, "Alice"))
+            set.add(User(1, "Alicia"))
+            assertPrints(set, "[Alicia]")
+        }
+
         @Sample
         fun addAll() {
             val set = mutableSetOf('a', 'b', 'c')

libraries/stdlib/samples/test/samples/collections/maps.kt

@@ -517,6 +517,27 @@ class Maps {
             assertPrints(map, "{1=_ONE_, 2=two, 3=three, 4=four}")
         }
 
+        @Sample
+        fun putKeepsStoredKey() {
+            class User(val id: Int, val name: String) {
+                override fun equals(other: Any?): Boolean = other is User && id == other.id
+                override fun hashCode(): Int = id
+                override fun toString(): String = name
+            }
+
+            val map = mutableMapOf(User(1, "Alice") to "admin")
+
+            map[User(1, "Alicia")] = "guest"
+            assertPrints(map, "{Alice=guest}")
+
+            map.putAll(mapOf(User(1, "Alicia") to "owner"))
+            assertPrints(map, "{Alice=owner}")
+
+            map.remove(User(1, "Alice"))
+            map[User(1, "Alicia")] = "guest"
+            assertPrints(map, "{Alicia=guest}")
+        }
+
         @Sample
         fun clear() {
             val map = mutableMapOf(1 to "one", 2 to "two")

libraries/stdlib/src/kotlin/Collections.kt

@@ -493,9 +493,12 @@ public expect interface MutableSet<E> : Set<E>, MutableCollection<E> {
     /**
      * Adds the specified element to the set.
      *
+     * If the set already contains [element], the element instance stored in the set is retained.
+     *
      * @return `true` if the element has been added, `false` if the element is already contained in the set.
      *
      * @sample samples.collections.Collections.Sets.add
+     * @sample samples.collections.Collections.Sets.addKeepsStoredElement
      */
     @IgnorableReturnValue
     override fun add(element: E): Boolean
@@ -504,6 +507,17 @@ public expect interface MutableSet<E> : Set<E>, MutableCollection<E> {
     override fun remove(element: E): Boolean
 
     // Bulk Modification Operations
+    /**
+     * Adds all of the elements of the specified collection to the set.
+     *
+     * The effect of this call is equivalent to calling [add] for each element of [elements], so the element
+     * instances stored in the set are retained.
+     *
+     * @return `true` if any of the specified elements was added to the set, `false` if the set was not modified.
+     *
+     * @sample samples.collections.Collections.Sets.addAll
+     * @sample samples.collections.Collections.Sets.addKeepsStoredElement
+     */
     @IgnorableReturnValue
     override fun addAll(elements: Collection<E>): Boolean
     @IgnorableReturnValue
@@ -674,9 +688,12 @@ public expect interface MutableMap<K, V> : Map<K, V> {
     /**
      * Associates the specified [value] with the specified [key] in the map.
      *
+     * If the map already contains a mapping for [key], the key instance stored in the map is retained.
+     *
      * @return the previous value associated with the key, or `null` if the key was not present in the map.
      *
      * @sample samples.collections.Maps.CoreApi.put
+     * @sample samples.collections.Maps.CoreApi.putKeepsStoredKey
      */
     @IgnorableReturnValue
     public fun put(key: K, value: V): V?
@@ -695,7 +712,11 @@ public expect interface MutableMap<K, V> : Map<K, V> {
     /**
      * Updates this map with key/value pairs from the specified map [from].
      *
+     * The effect of this call is equivalent to calling [put] for each entry of [from], so the key instances
+     * stored in this map are retained.
+     *
      * @sample samples.collections.Maps.CoreApi.putAll
+     * @sample samples.collections.Maps.CoreApi.putKeepsStoredKey
      */
     public fun putAll(from: Map<out K, V>): Unit
 

libraries/stdlib/src/kotlin/collections/Maps.kt

@@ -259,6 +259,8 @@ public inline operator fun <@kotlin.internal.OnlyInputTypes K, V> Map<out K, V>.
 
 /**
  * Allows to use the index operator for storing values in a mutable map.
+ *
+ * Equivalent to calling [MutableMap.put] with the given [key] and [value].
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <K, V> MutableMap<K, V>.set(key: K, value: V): Unit {