From 9057a6d66a9e3a1929a43460e7b0230dc6b6fbda Mon Sep 17 00:00:00 2001 From: Brennan Vincent Date: Sun, 9 Jan 2022 17:58:52 -0500 Subject: [PATCH] Clarify explicitly that BTree{Map,Set} are ordered. --- library/alloc/src/collections/btree/map.rs | 5 ++++- library/alloc/src/collections/btree/set.rs | 5 ++++- library/alloc/src/collections/mod.rs | 4 ++-- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index 199c05dc5df3e..9e4c22c3f4565 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -31,7 +31,7 @@ pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT; // An empty map is represented either by the absence of a root node or by a // root node that is an empty leaf. -/// A map based on a [B-Tree]. +/// An ordered map based on a [B-Tree]. /// /// B-Trees represent a fundamental compromise between cache-efficiency and actually minimizing /// the amount of work performed in a search. In theory, a binary search tree (BST) is the optimal @@ -65,6 +65,9 @@ pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT; /// incorrect results, aborts, memory leaks, or non-termination) but will not be undefined /// behavior. /// +/// Entries in a `BTreeMap` are stored in ascending order according to the [`Ord`] implementation on the key. +/// Thus, iteration methods are guaranteed to produce iterators that yield items in that order. +/// /// [B-Tree]: https://en.wikipedia.org/wiki/B-tree /// [`Cell`]: core::cell::Cell /// [`RefCell`]: core::cell::RefCell diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index 394c21bf51cd2..c2bf63b4a413f 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -15,7 +15,7 @@ use super::Recover; // FIXME(conventions): implement bounded iterators -/// A set based on a B-Tree. +/// An ordered set based on a B-Tree. /// /// See [`BTreeMap`]'s documentation for a detailed discussion of this collection's performance /// benefits and drawbacks. @@ -27,6 +27,9 @@ use super::Recover; /// incorrect results, aborts, memory leaks, or non-termination) but will not be undefined /// behavior. /// +/// Entries in a `BTreeSet` are stored in ascending order according to the [`Ord`] implementation on the key. +/// Thus, iteration methods are guaranteed to produce iterators that yield items in that order. +/// /// [`Ord`]: core::cmp::Ord /// [`Cell`]: core::cell::Cell /// [`RefCell`]: core::cell::RefCell diff --git a/library/alloc/src/collections/mod.rs b/library/alloc/src/collections/mod.rs index 1ea135a2aed82..628a5b155673c 100644 --- a/library/alloc/src/collections/mod.rs +++ b/library/alloc/src/collections/mod.rs @@ -14,7 +14,7 @@ pub mod vec_deque; #[cfg(not(no_global_oom_handling))] #[stable(feature = "rust1", since = "1.0.0")] pub mod btree_map { - //! A map based on a B-Tree. + //! An ordered map based on a B-Tree. #[stable(feature = "rust1", since = "1.0.0")] pub use super::btree::map::*; } @@ -22,7 +22,7 @@ pub mod btree_map { #[cfg(not(no_global_oom_handling))] #[stable(feature = "rust1", since = "1.0.0")] pub mod btree_set { - //! A set based on a B-Tree. + //! An ordered set based on a B-Tree. #[stable(feature = "rust1", since = "1.0.0")] pub use super::btree::set::*; }