From e8e3c6f38616acb0b45433454d57f5b2ecf78a96 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 18 Aug 2015 18:38:07 -0400 Subject: [PATCH] Document replacement behavior in some collections {BTree,Hash}{Map,Set} will not update their key if it already exists, which can matter with more complex keys. This behavior is now documented. Fixes #26888 --- src/libcollections/btree/map.rs | 10 +++++-- src/libcollections/btree/set.rs | 10 +++++-- src/libstd/collections/hash/map.rs | 10 +++++-- src/libstd/collections/hash/set.rs | 10 +++++-- src/libstd/collections/mod.rs | 46 ++++++++++++++++++++++++++++++ 5 files changed, 78 insertions(+), 8 deletions(-) diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index 59ffc1bd36f..1ad836f9bdf 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -315,8 +315,14 @@ pub fn get_mut(&mut self, key: &Q) -> Option<&mut V> where K: Borrow< // 2) While ODS may potentially return the pair we *just* inserted after // the split, we will never do this. Again, this shouldn't effect the analysis. - /// Inserts a key-value pair into the map. If the key already had a value - /// present in the map, that value is returned. Otherwise, `None` is returned. + /// Inserts a key-value pair into the map. + /// + /// If the map did not have this key present, `None` is returned. + /// + /// If the map did have this key present, that value is returned, and the + /// entry is not updated. See the [module-level documentation] for more. + /// + /// [module-level documentation]: index.html#insert-and-complex-keys /// /// # Examples /// diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index eb2a6d5e088..3ca0aa377c1 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -430,8 +430,14 @@ pub fn is_superset(&self, other: &BTreeSet) -> bool { other.is_subset(self) } - /// Adds a value to the set. Returns `true` if the value was not already - /// present in the set. + /// Adds a value to the set. + /// + /// If the set did not have a value present, `true` is returned. + /// + /// If the set did have this key present, that value is returned, and the + /// entry is not updated. See the [module-level documentation] for more. + /// + /// [module-level documentation]: index.html#insert-and-complex-keys /// /// # Examples /// diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 0b7c5b0d840..7c6add80337 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -1101,8 +1101,14 @@ pub fn get_mut(&mut self, k: &Q) -> Option<&mut V> self.search_mut(k).map(|bucket| bucket.into_mut_refs().1) } - /// Inserts a key-value pair into the map. If the key already had a value - /// present in the map, that value is returned. Otherwise, `None` is returned. + /// Inserts a key-value pair into the map. + /// + /// If the map did not have this key present, `None` is returned. + /// + /// If the map did have this key present, that value is returned, and the + /// entry is not updated. See the [module-level documentation] for more. + /// + /// [module-level documentation]: index.html#insert-and-complex-keys /// /// # Examples /// diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs index 7264b5827c4..1f6b3493996 100644 --- a/src/libstd/collections/hash/set.rs +++ b/src/libstd/collections/hash/set.rs @@ -540,8 +540,14 @@ pub fn is_superset(&self, other: &HashSet) -> bool { other.is_subset(self) } - /// Adds a value to the set. Returns `true` if the value was not already - /// present in the set. + /// Adds a value to the set. + /// + /// If the set did not have a value present, `true` is returned. + /// + /// If the set did have this key present, that value is returned, and the + /// entry is not updated. See the [module-level documentation] for more. + /// + /// [module-level documentation]: index.html#insert-and-complex-keys /// /// # Examples /// diff --git a/src/libstd/collections/mod.rs b/src/libstd/collections/mod.rs index 83e28e39a72..77f571d580b 100644 --- a/src/libstd/collections/mod.rs +++ b/src/libstd/collections/mod.rs @@ -359,6 +359,52 @@ //! } //! } //! ``` +//! +//! # Insert and complex keys +//! +//! If we have a more complex key, calls to `insert()` will +//! not update the value of the key. For example: +//! +//! ``` +//! use std::cmp::Ordering; +//! use std::collections::BTreeMap; +//! use std::hash::{Hash, Hasher}; +//! +//! #[derive(Debug)] +//! struct Foo { +//! a: u32, +//! b: &'static str, +//! } +//! +//! // we will compare `Foo`s by their `a` value only. +//! impl PartialEq for Foo { +//! fn eq(&self, other: &Self) -> bool { self.a == other.a } +//! } +//! +//! impl Eq for Foo {} +//! +//! // we will hash `Foo`s by their `a` value only. +//! impl Hash for Foo { +//! fn hash(&self, h: &mut H) { self.a.hash(h); } +//! } +//! +//! impl PartialOrd for Foo { +//! fn partial_cmp(&self, other: &Self) -> Option { self.a.partial_cmp(&other.a) } +//! } +//! +//! impl Ord for Foo { +//! fn cmp(&self, other: &Self) -> Ordering { self.a.cmp(&other.a) } +//! } +//! +//! let mut map = BTreeMap::new(); +//! map.insert(Foo { a: 1, b: "baz" }, ()); +//! +//! // We already have a Foo with an a of 1, so this will be updating the value. +//! map.insert(Foo { a: 1, b: "xyz" }, ()); +//! +//! // ... but the key hasn't changed. b is still "baz", not "xyz" +//! assert_eq!(map.keys().next().unwrap().b, "baz"); +//! ``` #![stable(feature = "rust1", since = "1.0.0")]