Change:
Collections that perform lookups based on a given property (e.g. a hash or an ordering) can be put into an inconsistent state when the property changes while its corresponding item is in the collection. This is normally not a problem, because such collections (at least those in ) do not provide mutable access to the type from which the property is derived (keys in the case of maps, items in the case of sets), but types with interior mutability can induce this behavior in safe code: Output: This is obvious from the definition of interior mutability, but it's definitely a footgun. If the use of such keys cannot be prevented with the type system, the collections should at least document that the property must remain constant for the duration of the item's presence in the collection. For example, Java's contains the following note:
This is a dupe of , which was for reasons in the thread itself. I believe the gist of the conversion was that yes, this can happen. Our implementations should ensure that this does not cause memory unsafety, but otherwise these sorts of "odd assertions" are ok to happen as this should be quite a rare occurrence anyway.
I still think the collection documentation needs to identify this problem. On Friday, March 13, 2015, Alex Crichton wrote:
Hm good point! I've an appropriate tag.
I'm working on a patch to document this.

Discussion:
/// A priority queue implemented with a binary heap. /// /// This will be a max-heap. <ins> /// /// 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. </ins> #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] pub struct BinaryHeap<T> {

/// 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. <ins> /// /// 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. </ins> #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] pub struct BTreeMap<K, V> {

/// /// See BTreeMap's documentation for a detailed discussion of this collection's performance /// benefits and drawbacks. <ins> /// /// 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. </ins> #[derive(Clone, Hash, PartialEq, Eq, Ord, PartialOrd)] #[stable(feature = "rust1", since = "1.0.0")] pub struct BTreeSet<T>{

#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] /// A specialized set implementation to use enum types. <ins> /// /// 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. </ins> pub struct EnumSet<E> { // We must maintain the invariant that no bits are set // for which no variant exists

/// It is required that the keys implement the `Eq` and `Hash` traits, although /// this can frequently be achieved by using `#[derive(Eq, Hash)]`. /// <ins> /// 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. /// </ins> /// Relevant papers/articles: /// /// 1. Pedro Celis. ["Robin Hood Hashing"](https://cs.uwaterloo.ca/research/tr/1986/CS-86-14.pdf)

/// HashMap where the value is (). As with the `HashMap` type, a `HashSet` /// requires that the elements implement the `Eq` and `Hash` traits. /// <ins> /// 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. /// </ins> /// # Examples /// /// ```