From f6f89dc2023315b777f0ffef3b4c4573d364beb8 Mon Sep 17 00:00:00 2001 From: ultrabear Date: Thu, 21 Mar 2024 00:54:50 -0700 Subject: [PATCH 1/3] BTree(Set|Map): Guarantee that `IntoIter` will iterate in sorted by key order --- library/alloc/src/collections/btree/map.rs | 3 ++- library/alloc/src/collections/btree/set.rs | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index e99c6220e2064..66b45f866017b 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -415,7 +415,7 @@ impl<'a, K: 'a, V: 'a> Default for IterMut<'a, K, V> { } } -/// An owning iterator over the entries of a `BTreeMap`. +/// An owning iterator over the entries of a `BTreeMap`, sorted by key. /// /// This `struct` is created by the [`into_iter`] method on [`BTreeMap`] /// (provided by the [`IntoIterator`] trait). See its documentation for more. @@ -1632,6 +1632,7 @@ impl<'a, K, V> IterMut<'a, K, V> { } } +/// Gets an owning iterator over the entries of the map, sorted by key. #[stable(feature = "rust1", since = "1.0.0")] impl IntoIterator for BTreeMap { type Item = (K, V); diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index ed91ae1a66e3d..9c0b89188d8c5 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -140,7 +140,7 @@ impl fmt::Debug for Iter<'_, T> { } } -/// An owning iterator over the items of a `BTreeSet`. +/// An owning iterator over the items of a `BTreeSet` in ascending order. /// /// This `struct` is created by the [`into_iter`] method on [`BTreeSet`] /// (provided by the [`IntoIterator`] trait). See its documentation for more. @@ -1232,6 +1232,7 @@ impl From<[T; N]> for BTreeSet { } } +/// Gets an owning iterator over the elements of the `BTreeSet` in ascending order. #[stable(feature = "rust1", since = "1.0.0")] impl IntoIterator for BTreeSet { type Item = T; From f8a093c8ea456cb64966da2983eb988e74700fde Mon Sep 17 00:00:00 2001 From: ultrabear Date: Thu, 21 Mar 2024 02:05:11 -0700 Subject: [PATCH 2/3] document iteration ordering on into_iter method instead of IntoIterator implementation --- library/alloc/src/collections/btree/map.rs | 2 +- library/alloc/src/collections/btree/set.rs | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index 66b45f866017b..53b25a9ef25f8 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -1632,12 +1632,12 @@ impl<'a, K, V> IterMut<'a, K, V> { } } -/// Gets an owning iterator over the entries of the map, sorted by key. #[stable(feature = "rust1", since = "1.0.0")] impl IntoIterator for BTreeMap { type Item = (K, V); type IntoIter = IntoIter; + /// Gets an owning iterator over the entries of the map, sorted by key. fn into_iter(self) -> IntoIter { let mut me = ManuallyDrop::new(self); if let Some(root) = me.root.take() { diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index 9c0b89188d8c5..a110ee9c7f36c 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -1232,13 +1232,12 @@ impl From<[T; N]> for BTreeSet { } } -/// Gets an owning iterator over the elements of the `BTreeSet` in ascending order. #[stable(feature = "rust1", since = "1.0.0")] impl IntoIterator for BTreeSet { type Item = T; type IntoIter = IntoIter; - /// Gets an iterator for moving out the `BTreeSet`'s contents. + /// Gets an iterator for moving out the `BTreeSet`'s contents in ascending order. /// /// # Examples /// From beb0c22c096c68fd853cf65bb44408cf0d5ac99a Mon Sep 17 00:00:00 2001 From: ultrabear Date: Thu, 21 Mar 2024 02:07:46 -0700 Subject: [PATCH 3/3] document into_iter in top level docs iterator ordering guarantees --- library/alloc/src/collections/btree/map.rs | 2 +- library/alloc/src/collections/btree/set.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index 53b25a9ef25f8..3875f61efafdf 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -72,7 +72,7 @@ pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT; /// `BTreeMap` that observed the logic error and not result in undefined behavior. This could /// include panics, incorrect results, aborts, memory leaks, and non-termination. /// -/// Iterators obtained from functions such as [`BTreeMap::iter`], [`BTreeMap::values`], or +/// Iterators obtained from functions such as [`BTreeMap::iter`], [`BTreeMap::into_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. /// diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index a110ee9c7f36c..7508ae468ae5b 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -27,7 +27,7 @@ use crate::alloc::{Allocator, Global}; /// `BTreeSet` that observed the logic error and not result in undefined behavior. This could /// include panics, incorrect results, aborts, memory leaks, and non-termination. /// -/// Iterators returned by [`BTreeSet::iter`] produce their items in order, and take worst-case +/// Iterators returned by [`BTreeSet::iter`] and [`BTreeSet::into_iter`] produce their items in order, and take worst-case /// logarithmic and amortized constant time per item returned. /// /// [`Cell`]: core::cell::Cell