Skip to content

Commit

Permalink
Clarify explicitly that BTree{Map,Set} are ordered.
Browse files Browse the repository at this point in the history
  • Loading branch information
umanwizard committed Jan 9, 2022
1 parent 092e1c9 commit 9057a6d
Show file tree
Hide file tree
Showing 3 changed files with 10 additions and 4 deletions.
5 changes: 4 additions & 1 deletion library/alloc/src/collections/btree/map.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion library/alloc/src/collections/btree/set.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions library/alloc/src/collections/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,15 @@ 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::*;
}

#[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::*;
}
Expand Down

0 comments on commit 9057a6d

Please sign in to comment.