From 2dd69aaafc64fe9dce74088b5371a6cfb032e01e Mon Sep 17 00:00:00 2001 From: Janik Rabe Date: Thu, 1 Jul 2021 22:15:13 +0100 Subject: Document iteration order of `retain` functions For `HashSet` and `HashMap`, this simply copies the comment from `BinaryHeap::retain`. For `BTreeSet` and `BTreeMap`, this adds an additional guarantee that wasn't previously documented. I think that because these data structures are inherently ordered and other functions guarantee ordered iteration, it makes sense to provide this guarantee for `retain` as well. --- library/alloc/src/collections/btree/map.rs | 1 + library/alloc/src/collections/btree/set.rs | 1 + 2 files changed, 2 insertions(+) (limited to 'library/alloc/src') diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index d7519c6d093..70eae641928 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -936,6 +936,7 @@ impl BTreeMap { /// Retains only the elements specified by the predicate. /// /// In other words, remove all pairs `(k, v)` such that `f(&k, &mut v)` returns `false`. + /// The elements are visited in ascending key order. /// /// # Examples /// diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index 737932d931c..9f4296e26b8 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -847,6 +847,7 @@ impl BTreeSet { /// Retains only the elements specified by the predicate. /// /// In other words, remove all elements `e` such that `f(&e)` returns `false`. + /// The elements are visited in ascending order. /// /// # Examples /// -- cgit 1.4.1-3-g733a5