document undefined collection behavior with interior mutability

closes #23327

diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs
index 2e575ddb00a3275bb23cf8c33fedea0857050192..4c57fdc46681b75666afa56278fc41cc2ad06ab9 100644 (file)
--- a/src/libcollections/binary_heap.rs
+++ b/src/libcollections/binary_heap.rs
@@ -163,6 +163,11 @@
 /// A priority queue implemented with a binary heap.
 ///
 /// This will be a max-heap.
+///
+/// It is a logic error for an item to be modified in such a way that the
+/// item's ordering relative to any other item, as determined by the `Ord`
+/// trait, changes while it is in the heap. This is normally only possible
+/// through `Cell`, `RefCell`, global state, I/O, or unsafe code.
 #[derive(Clone)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct BinaryHeap<T> {

diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs
index 5de6cbe61e9e6af7a367d4fd8c965da52c5ec2d4..f2d94709c9a3272fd81b2a91c53abc7c7d52db1e 100644 (file)
--- a/src/libcollections/btree/map.rs
+++ b/src/libcollections/btree/map.rs
@@ -64,6 +64,10 @@
 /// and possibly other factors. Using linear search, searching for a random element is expected
 /// to take O(B log<sub>B</sub>n) comparisons, which is generally worse than a BST. In practice,
 /// however, performance is excellent.
+///
+/// It is a logic error for a key to be modified in such a way that the key's ordering relative to
+/// any other key, as determined by the `Ord` trait, changes while it is in the map. This is
+/// normally only possible through `Cell`, `RefCell`, global state, I/O, or unsafe code.
 #[derive(Clone)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct BTreeMap<K, V> {

diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs
index bc2e68b999a55e29ce02c218e60d3e7003e28da3..a5ef36bcdab7adb059ba83bcdde6d0f7fda1fe03 100644 (file)
--- a/src/libcollections/btree/set.rs
+++ b/src/libcollections/btree/set.rs
@@ -30,6 +30,10 @@
 ///
 /// See BTreeMap's documentation for a detailed discussion of this collection's performance
 /// benefits and drawbacks.
+///
+/// It is a logic error for an item to be modified in such a way that the item's ordering relative
+/// to any other item, as determined by the `Ord` trait, changes while it is in the set. This is
+/// normally only possible through `Cell`, `RefCell`, global state, I/O, or unsafe code.
 #[derive(Clone, Hash, PartialEq, Eq, Ord, PartialOrd)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct BTreeSet<T>{

diff --git a/src/libcollections/enum_set.rs b/src/libcollections/enum_set.rs
index 68ff94cfbfb942f33ec251dceee5941156f5a90b..eec61cfcd56242964a5a1df22c3b3b378b92d3df 100644 (file)
--- a/src/libcollections/enum_set.rs
+++ b/src/libcollections/enum_set.rs
@@ -24,6 +24,11 @@
 
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 /// A specialized set implementation to use enum types.
+///
+/// It is a logic error for an item to be modified in such a way that the transformation of the
+/// item to or from a `usize`, as determined by the `CLike` trait, changes while the item is in the
+/// set. This is normally only possible through `Cell`, `RefCell`, global state, I/O, or unsafe
+/// code.
 pub struct EnumSet<E> {
     // We must maintain the invariant that no bits are set
     // for which no variant exists

diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs
index 18f86901b8f440517f4e4238af2b0210ede94450..0892365d9d5a5a77a546c06589e09c3735a5037e 100644 (file)
--- a/src/libstd/collections/hash/map.rs
+++ b/src/libstd/collections/hash/map.rs
@@ -217,6 +217,11 @@ fn test_resize_policy() {
 /// It is required that the keys implement the `Eq` and `Hash` traits, although
 /// this can frequently be achieved by using `#[derive(Eq, Hash)]`.
 ///
+/// It is a logic error for a key to be modified in such a way that the key's
+/// hash, as determined by the `Hash` trait, or its equality, as determined by
+/// the `Eq` trait, changes while it is in the map. This is normally only
+/// possible through `Cell`, `RefCell`, global state, I/O, or unsafe code.
+///
 /// Relevant papers/articles:
 ///
 /// 1. Pedro Celis. ["Robin Hood Hashing"](https://cs.uwaterloo.ca/research/tr/1986/CS-86-14.pdf)

diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs
index 35115ad77fefda0ae95838f368e7dae017581e04..de3f080de829651d6b8d7b87db99ecddf263f739 100644 (file)
--- a/src/libstd/collections/hash/set.rs
+++ b/src/libstd/collections/hash/set.rs
@@ -38,6 +38,12 @@
 /// HashMap where the value is (). As with the `HashMap` type, a `HashSet`
 /// requires that the elements implement the `Eq` and `Hash` traits.
 ///
+/// It is a logic error for an item to be modified in such a way that the
+/// item's hash, as determined by the `Hash` trait, or its equality, as
+/// determined by the `Eq` trait, changes while it is in the set. This is
+/// normally only possible through `Cell`, `RefCell`, global state, I/O, or
+/// unsafe code.
+///
 /// # Examples
 ///
 /// ```