From 90f06ae33fdf34e60c29cbd38dd3ec7be6b3badb Mon Sep 17 00:00:00 2001 From: Andrew Paseltiner Date: Fri, 13 Mar 2015 13:47:55 -0400 Subject: [PATCH] document undefined collection behavior with interior mutability closes #23327 --- src/libcollections/binary_heap.rs | 5 +++++ src/libcollections/btree/map.rs | 4 ++++ src/libcollections/btree/set.rs | 4 ++++ src/libcollections/enum_set.rs | 5 +++++ src/libstd/collections/hash/map.rs | 5 +++++ src/libstd/collections/hash/set.rs | 6 ++++++ 6 files changed, 29 insertions(+) diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs index 2e575ddb00a..4c57fdc4668 100644 --- a/src/libcollections/binary_heap.rs +++ b/src/libcollections/binary_heap.rs @@ -163,6 +163,11 @@ use vec::{self, Vec}; /// 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 { diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index 5de6cbe61e9..f2d94709c9a 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -64,6 +64,10 @@ use super::node::{self, Node, Found, GoDown}; /// and possibly other factors. Using linear search, searching for a random element is expected /// to take O(B logBn) 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 { diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index bc2e68b999a..a5ef36bcdab 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -30,6 +30,10 @@ use Bound; /// /// 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{ diff --git a/src/libcollections/enum_set.rs b/src/libcollections/enum_set.rs index 68ff94cfbfb..eec61cfcd56 100644 --- a/src/libcollections/enum_set.rs +++ b/src/libcollections/enum_set.rs @@ -24,6 +24,11 @@ use core::ops::{Sub, BitOr, BitAnd, BitXor}; #[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 { // 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 18f86901b8f..0892365d9d5 100644 --- 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 35115ad77fe..de3f080de82 100644 --- a/src/libstd/collections/hash/set.rs +++ b/src/libstd/collections/hash/set.rs @@ -38,6 +38,12 @@ use super::state::HashState; /// 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 /// /// ```