From b5e8a5d3939935eecfe8ed2dbc97ad748e090d90 Mon Sep 17 00:00:00 2001
From: Kevin Reid <kpreid@google.com>
Date: Wed, 13 Oct 2021 08:46:34 -0700
Subject: [PATCH] Document collection `From` and `FromIterator` impls that drop
 duplicate keys.

This behavior is worth documenting because there are other plausible
alternatives, such as panicking when a duplicate is encountered, and
it reminds the programmer to consider whether they should, for example,
coalesce duplicate keys first.
---
 library/alloc/src/collections/btree/map.rs | 9 ++++++++-
 library/alloc/src/collections/btree/set.rs | 4 ++++
 library/std/src/collections/hash/map.rs    | 9 +++++++++
 library/std/src/collections/hash/set.rs    | 4 ++++
 4 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs
index d1ce4e215ed9..56679eaa1189 100644
--- a/library/alloc/src/collections/btree/map.rs
+++ b/library/alloc/src/collections/btree/map.rs
@@ -2289,6 +2289,10 @@ impl<K, V> FusedIterator for RangeMut<'_, K, V> {}
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<K: Ord, V> FromIterator<(K, V)> for BTreeMap<K, V> {
+    /// Constructs a `BTreeMap<K, V>` from an iterator of key-value pairs.
+    ///
+    /// If the iterator produces any pairs with equal keys,
+    /// all but the last value for each such key are discarded.
     fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> BTreeMap<K, V> {
         let mut inputs: Vec<_> = iter.into_iter().collect();
 
@@ -2403,7 +2407,10 @@ fn index(&self, key: &Q) -> &V {
 
 #[stable(feature = "std_collections_from_array", since = "1.56.0")]
 impl<K: Ord, V, const N: usize> From<[(K, V); N]> for BTreeMap<K, V> {
-    /// Converts a `[(K, V); N]` into a `BTreeMap<(K, V)>`.
+    /// Converts a `[(K, V); N]` into a `BTreeMap<K, V>`.
+    ///
+    /// If any entries in the array have equal keys, all but the last entry for each such key
+    /// are discarded.
     ///
     /// ```
     /// use std::collections::BTreeMap;
diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs
index 6f8c3b2d152b..9f5a42b5f6d2 100644
--- a/library/alloc/src/collections/btree/set.rs
+++ b/library/alloc/src/collections/btree/set.rs
@@ -1491,6 +1491,10 @@ fn from_sorted_iter<I: Iterator<Item = T>>(iter: I, alloc: A) -> BTreeSet<T, A>
 impl<T: Ord, const N: usize> From<[T; N]> for BTreeSet<T> {
     /// Converts a `[T; N]` into a `BTreeSet<T>`.
     ///
+    /// If the array contains any equal values, all but the last instance of each are discarded.
+    ///
+    /// # Examples
+    ///
     /// ```
     /// use std::collections::BTreeSet;
     ///
diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs
index 109bc3946346..5b2cd53763b9 100644
--- a/library/std/src/collections/hash/map.rs
+++ b/library/std/src/collections/hash/map.rs
@@ -1446,6 +1446,11 @@ fn index(&self, key: &Q) -> &V {
 where
     K: Eq + Hash,
 {
+    /// Converts a `[(K, V); N]` into a `HashMap<K, V>`.
+    ///
+    /// If any entries in the array have equal keys, all but the last entry for each such key
+    /// are discarded.
+    ///
     /// # Examples
     ///
     /// ```
@@ -3219,6 +3224,10 @@ impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S>
     K: Eq + Hash,
     S: BuildHasher + Default,
 {
+    /// Constructs a `HashMap<K, V>` from an iterator of key-value pairs.
+    ///
+    /// If the iterator produces any pairs with equal keys,
+    /// all but the last value for each such key are discarded.
     fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> HashMap<K, V, S> {
         let mut map = HashMap::with_hasher(Default::default());
         map.extend(iter);
diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs
index 4c81aaff4588..8e840aaa07f9 100644
--- a/library/std/src/collections/hash/set.rs
+++ b/library/std/src/collections/hash/set.rs
@@ -1091,6 +1091,10 @@ fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> HashSet<T, S> {
 where
     T: Eq + Hash,
 {
+    /// Converts a `[T; N]` into a `HashSet<T>`.
+    ///
+    /// If the array contains any equal values, all but the last instance of each are discarded.
+    ///
     /// # Examples
     ///
     /// ```