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

[Dmitry Nekrasov (DmitryNekrasov)]

^KT-88708 Fixed

[kotlin-safemerge]

Code Owners

Rule	Owners	Approval
/​libraries/​stdlib/​	DmitryNekrasov, fzhinkin, ilya-g, qwwdfsad 🌴	🔴 ilya-g

PR commands for maintainers

Command	Description	Parameters
/safe-merge	Rebase-merges with automatic fixup commit squashing	--fixup Autosquash fixup commits (on by default)
/safe-squash-merge	Squash-merges with optional commit title/body override	--title Title of the squashed commit --message Body of the squashed commit
/dry-run	Runs the test pipeline with changes rebased on latest master	--retry Retry the CI run on failure
/test-public	Triggers the public test suite without rebasing on latest master	—
/test-private	Triggers the private test suite without rebasing on latest master	—
/codeowners	Triggers code owners check and comment update	—
/fixup	Squashes fixup commits and force pushes the branch	—
/cancel-coordinator	Cancels the merge coordinator currently running for this branch	—

[Dmitry Nekrasov (DmitryNekrasov)]

/dry-run

[Copilot]

Pull request overview

Documents that mutable maps and sets retain existing key/element instances when equal instances are added.

Changes:

• Expands collection API documentation across platforms.
• Adds executable samples demonstrating identity retention.
• Adds cross-implementation regression tests.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
libraries/stdlib/test/collections/StoredKeyIdentityTest.kt	Tests identity retention for maps, sets, and builders.
libraries/stdlib/src/kotlin/collections/Maps.kt	Links indexed assignment to put.
libraries/stdlib/src/kotlin/Collections.kt	Documents common add, addAll, put, and putAll behavior.
libraries/stdlib/samples/test/samples/collections/maps.kt	Adds a stored-key sample.
libraries/stdlib/samples/test/samples/collections/collections.kt	Adds a stored-element sample.
libraries/stdlib/native-wasm/src/kotlin/collections/Set.kt	Updates Native/Wasm set contracts.
libraries/stdlib/native-wasm/src/kotlin/collections/Map.kt	Updates Native/Wasm map contracts.
libraries/stdlib/native-wasm/src/kotlin/collections/AbstractMutableSet.kt	Documents abstract set behavior.
libraries/stdlib/native-wasm/src/kotlin/collections/AbstractMutableMap.kt	Documents abstract map behavior.
libraries/stdlib/jvm/src/kotlin/collections/AbstractMutableSet.kt	Documents JVM abstract set behavior.
libraries/stdlib/jvm/src/kotlin/collections/AbstractMutableMap.kt	Documents JVM abstract map behavior.
libraries/stdlib/jvm/builtins/Collections.kt	Updates JVM built-in collection contracts.
libraries/stdlib/js/builtins/Collections.kt	Updates JS built-in collection contracts.
libraries/stdlib/common/src/kotlin/collections/AbstractMutableMap.kt	Updates the common abstract map contract.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Build Server (KotlinBuild)]

THIS IS A DRY RUN

Quality gate is triggered at https://buildserver.labs.intellij.net/build/1038193983 — use this link to get full insight.

Quality gate was triggered with the following revisions:

kotlin
Branch: refs/merge/GITHUB-7643/safe-merge
Commit: b80aee8

---

Quality gate finished successfully.

[ilya-g]

I don't think it deserves a separate sample or even a sample at all.

[ilya-g]

I would rather say what happens with the value, it would be more useful from the user perspective.

Suggested change

	* If the map already contains a mapping for [key], the key instance stored in the map is retained.
	* If the map already contains a mapping for [key], the value for that key is replaced with the specified [value].