From 9057a6d66a9e3a1929a43460e7b0230dc6b6fbda Mon Sep 17 00:00:00 2001 From: Brennan Vincent Date: Sun, 9 Jan 2022 17:58:52 -0500 Subject: [PATCH 1/3] 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::*; } From 65d47347ada25ddb45358ec7af07f378f60aa00d Mon Sep 17 00:00:00 2001 From: Brennan Vincent Date: Tue, 11 Jan 2022 12:08:46 -0700 Subject: [PATCH 2/3] Address review comments --- library/alloc/src/collections/btree/map.rs | 4 ++-- library/alloc/src/collections/btree/set.rs | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index 9e4c22c3f4565..b38c5848b4907 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -65,8 +65,8 @@ 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. +/// Iterators yielded by functions such as [`BTreeMap::iter`], [`BTreeMap::values`], or [`BTreeMap::keys`] +/// yield their items in order by key, and take worst-case logarithmic and amortized constant time per item yielded. /// /// [B-Tree]: https://en.wikipedia.org/wiki/B-tree /// [`Cell`]: core::cell::Cell diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index c2bf63b4a413f..b32f539958861 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -27,8 +27,8 @@ 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. +/// Iterators returned by [`BTreeSet::iter`] yield their items in order, +/// and take worst-case logarithmic and amortized constant time per item yielded. /// /// [`Ord`]: core::cmp::Ord /// [`Cell`]: core::cell::Cell From ad6408dd7a786db603c2ed323894feb7110e8dea Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sat, 15 Jan 2022 19:28:19 -0800 Subject: [PATCH 3/3] Tweak btree iterator wording to not use 'yield' Yield means something else in the context of generators, which are sufficiently close to iterators that it's better to avoid the terminology collision here. --- library/alloc/src/collections/btree/map.rs | 5 +++-- library/alloc/src/collections/btree/set.rs | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index b38c5848b4907..885632c69a8cc 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -65,8 +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. /// -/// Iterators yielded by functions such as [`BTreeMap::iter`], [`BTreeMap::values`], or [`BTreeMap::keys`] -/// yield their items in order by key, and take worst-case logarithmic and amortized constant time per item yielded. +/// Iterators obtained from functions such as [`BTreeMap::iter`], [`BTreeMap::values`], or +/// [`BTreeMap::keys`] produce their items in order by key, and take worst-case logarithmic and +/// amortized constant time per item returned. /// /// [B-Tree]: https://en.wikipedia.org/wiki/B-tree /// [`Cell`]: core::cell::Cell diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index b32f539958861..31df4e98ed746 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -27,8 +27,8 @@ use super::Recover; /// incorrect results, aborts, memory leaks, or non-termination) but will not be undefined /// behavior. /// -/// Iterators returned by [`BTreeSet::iter`] yield their items in order, -/// and take worst-case logarithmic and amortized constant time per item yielded. +/// Iterators returned by [`BTreeSet::iter`] produce their items in order, and take worst-case +/// logarithmic and amortized constant time per item returned. /// /// [`Ord`]: core::cmp::Ord /// [`Cell`]: core::cell::Cell