From b5e8a5d3939935eecfe8ed2dbc97ad748e090d90 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Wed, 13 Oct 2021 08:46:34 -0700 Subject: [PATCH 1/2] 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 d1ce4e215ed9c..56679eaa11894 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -2289,6 +2289,10 @@ impl FusedIterator for RangeMut<'_, K, V> {} #[stable(feature = "rust1", since = "1.0.0")] impl FromIterator<(K, V)> for BTreeMap { + /// Constructs a `BTreeMap` 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>(iter: T) -> BTreeMap { let mut inputs: Vec<_> = iter.into_iter().collect(); @@ -2403,7 +2407,10 @@ where #[stable(feature = "std_collections_from_array", since = "1.56.0")] impl From<[(K, V); N]> for BTreeMap { - /// Converts a `[(K, V); N]` into a `BTreeMap<(K, V)>`. + /// Converts a `[(K, V); N]` into a `BTreeMap`. + /// + /// 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 6f8c3b2d152b8..9f5a42b5f6d2d 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -1491,6 +1491,10 @@ impl BTreeSet { impl From<[T; N]> for BTreeSet { /// Converts a `[T; N]` into a `BTreeSet`. /// + /// 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 109bc3946346f..5b2cd53763b90 100644 --- a/library/std/src/collections/hash/map.rs +++ b/library/std/src/collections/hash/map.rs @@ -1446,6 +1446,11 @@ impl From<[(K, V); N]> for HashMap where K: Eq + Hash, { + /// Converts a `[(K, V); N]` into a `HashMap`. + /// + /// 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 @@ where K: Eq + Hash, S: BuildHasher + Default, { + /// Constructs a `HashMap` 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>(iter: T) -> HashMap { 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 4c81aaff45886..8e840aaa07f92 100644 --- a/library/std/src/collections/hash/set.rs +++ b/library/std/src/collections/hash/set.rs @@ -1091,6 +1091,10 @@ impl From<[T; N]> for HashSet where T: Eq + Hash, { + /// Converts a `[T; N]` into a `HashSet`. + /// + /// If the array contains any equal values, all but the last instance of each are discarded. + /// /// # Examples /// /// ``` From 6a43716ada10c18d6991dd9408ce2f31214cb8f3 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Sun, 22 Dec 2024 08:13:00 -0800 Subject: [PATCH 2/2] Specify only that duplicates are discarded, not the order. --- library/alloc/src/collections/btree/map.rs | 6 +++--- library/alloc/src/collections/btree/set.rs | 3 ++- library/std/src/collections/hash/map.rs | 6 +++--- library/std/src/collections/hash/set.rs | 3 ++- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index 56679eaa11894..6d305386dbfa0 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -2292,7 +2292,7 @@ impl FromIterator<(K, V)> for BTreeMap { /// Constructs a `BTreeMap` 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. + /// all but one of the corresponding values will be dropped. fn from_iter>(iter: T) -> BTreeMap { let mut inputs: Vec<_> = iter.into_iter().collect(); @@ -2409,8 +2409,8 @@ where impl From<[(K, V); N]> for BTreeMap { /// Converts a `[(K, V); N]` into a `BTreeMap`. /// - /// If any entries in the array have equal keys, all but the last entry for each such key - /// are discarded. + /// If any entries in the array have equal keys, + /// all but one of the corresponding values will be dropped. /// /// ``` /// use std::collections::BTreeMap; diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index 9f5a42b5f6d2d..9660023d6945e 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -1491,7 +1491,8 @@ impl BTreeSet { impl From<[T; N]> for BTreeSet { /// Converts a `[T; N]` into a `BTreeSet`. /// - /// If the array contains any equal values, all but the last instance of each are discarded. + /// If the array contains any equal values, + /// all but one will be dropped. /// /// # Examples /// diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs index 5b2cd53763b90..56d734ba2fbfb 100644 --- a/library/std/src/collections/hash/map.rs +++ b/library/std/src/collections/hash/map.rs @@ -1448,8 +1448,8 @@ where { /// Converts a `[(K, V); N]` into a `HashMap`. /// - /// If any entries in the array have equal keys, all but the last entry for each such key - /// are discarded. + /// If any entries in the array have equal keys, + /// all but one of the corresponding values will be dropped. /// /// # Examples /// @@ -3227,7 +3227,7 @@ where /// Constructs a `HashMap` 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. + /// all but one of the corresponding values will be dropped. fn from_iter>(iter: T) -> HashMap { 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 8e840aaa07f92..bcf6d6b4ccf3a 100644 --- a/library/std/src/collections/hash/set.rs +++ b/library/std/src/collections/hash/set.rs @@ -1093,7 +1093,8 @@ where { /// Converts a `[T; N]` into a `HashSet`. /// - /// If the array contains any equal values, all but the last instance of each are discarded. + /// If the array contains any equal values, + /// all but one will be dropped. /// /// # Examples ///