From 2dd69aaafc64fe9dce74088b5371a6cfb032e01e Mon Sep 17 00:00:00 2001
From: Janik Rabe <info@janikrabe.com>
Date: Thu, 1 Jul 2021 22:15:13 +0100
Subject: [PATCH] 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 +
 library/std/src/collections/hash/map.rs    | 1 +
 library/std/src/collections/hash/set.rs    | 1 +
 4 files changed, 4 insertions(+)

diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs
index d7519c6d0936c..70eae6419281b 100644
--- a/library/alloc/src/collections/btree/map.rs
+++ b/library/alloc/src/collections/btree/map.rs
@@ -936,6 +936,7 @@ impl<K, V> BTreeMap<K, V> {
     /// 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 737932d931c02..9f4296e26b81d 100644
--- a/library/alloc/src/collections/btree/set.rs
+++ b/library/alloc/src/collections/btree/set.rs
@@ -847,6 +847,7 @@ impl<T> BTreeSet<T> {
     /// 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
     ///
diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs
index a1f52a9c2e880..241f33746d625 100644
--- a/library/std/src/collections/hash/map.rs
+++ b/library/std/src/collections/hash/map.rs
@@ -936,6 +936,7 @@ where
     /// 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 unsorted (and unspecified) order.
     ///
     /// # Examples
     ///
diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs
index 5220c8ad70977..372feff7fa026 100644
--- a/library/std/src/collections/hash/set.rs
+++ b/library/std/src/collections/hash/set.rs
@@ -914,6 +914,7 @@ where
     /// 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 unsorted (and unspecified) order.
     ///
     /// # Examples
     ///