Rollup merge of rust-lang#148995 - RalfJung:extract_if, r=the8472

add must_use to extract_if methods

Also, mention the `.for_each(drop)` pattern in the documentation. One can't always use `retain` with a negated predicate as that does not have a range argument.

r? `@the8472`

Author: matthiaskrgr

library/alloc/src/collections/btree/map.rs

@@ -1434,7 +1434,8 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
     ///
     /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating
     /// or the iteration short-circuits, then the remaining elements will be retained.
-    /// Use [`retain`] with a negated predicate if you do not need the returned iterator.
+    /// Use `extract_if().for_each(drop)` if you do not need the returned iterator,
+    /// or [`retain`] with a negated predicate if you also do not need to restrict the range.
     ///
     /// [`retain`]: BTreeMap::retain
     ///
@@ -1945,7 +1946,8 @@ impl<K, V> Default for Values<'_, K, V> {
 
 /// An iterator produced by calling `extract_if` on BTreeMap.
 #[stable(feature = "btree_extract_if", since = "1.91.0")]
-#[must_use = "iterators are lazy and do nothing unless consumed"]
+#[must_use = "iterators are lazy and do nothing unless consumed; \
+    use `retain` or `extract_if().for_each(drop)` to remove and discard elements"]
 pub struct ExtractIf<
     'a,
     K,

library/alloc/src/collections/btree/set.rs

@@ -1189,7 +1189,8 @@ impl<T, A: Allocator + Clone> BTreeSet<T, A> {
     ///
     /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating
     /// or the iteration short-circuits, then the remaining elements will be retained.
-    /// Use [`retain`] with a negated predicate if you do not need the returned iterator.
+    /// Use `extract_if().for_each(drop)` if you do not need the returned iterator,
+    /// or [`retain`] with a negated predicate if you also do not need to restrict the range.
     ///
     /// [`retain`]: BTreeSet::retain
     /// # Examples
@@ -1547,7 +1548,8 @@ impl<'a, T, A: Allocator + Clone> IntoIterator for &'a BTreeSet<T, A> {
 
 /// An iterator produced by calling `extract_if` on BTreeSet.
 #[stable(feature = "btree_extract_if", since = "1.91.0")]
-#[must_use = "iterators are lazy and do nothing unless consumed"]
+#[must_use = "iterators are lazy and do nothing unless consumed; \
+    use `retain` or `extract_if().for_each(drop)` to remove and discard elements"]
 pub struct ExtractIf<
     'a,
     T,

library/alloc/src/collections/linked_list.rs

@@ -1943,7 +1943,8 @@ impl<'a, T, A: Allocator> CursorMut<'a, T, A> {
 
 /// An iterator produced by calling `extract_if` on LinkedList.
 #[stable(feature = "extract_if", since = "1.87.0")]
-#[must_use = "iterators are lazy and do nothing unless consumed"]
+#[must_use = "iterators are lazy and do nothing unless consumed; \
+    use `extract_if().for_each(drop)` to remove and discard elements"]
 pub struct ExtractIf<
     'a,
     T: 'a,

library/alloc/src/collections/vec_deque/extract_if.rs

@@ -21,7 +21,8 @@ use crate::alloc::{Allocator, Global};
 /// let iter: ExtractIf<'_, _, _> = v.extract_if(.., |x| *x % 2 == 0);
 /// ```
 #[unstable(feature = "vec_deque_extract_if", issue = "147750")]
-#[must_use = "iterators are lazy and do nothing unless consumed"]
+#[must_use = "iterators are lazy and do nothing unless consumed; \
+    use `retain_mut` or `extract_if().for_each(drop)` to remove and discard elements"]
 pub struct ExtractIf<
     'a,
     T,

library/alloc/src/collections/vec_deque/mod.rs

@@ -676,7 +676,8 @@ impl<T, A: Allocator> VecDeque<T, A> {
     ///
     /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating
     /// or the iteration short-circuits, then the remaining elements will be retained.
-    /// Use [`retain_mut`] with a negated predicate if you do not need the returned iterator.
+    /// Use `extract_if().for_each(drop)` if you do not need the returned iterator,
+    /// or [`retain_mut`] with a negated predicate if you also do not need to restrict the range.
     ///
     /// [`retain_mut`]: VecDeque::retain_mut
     ///

library/alloc/src/vec/extract_if.rs

@@ -16,7 +16,8 @@ use crate::alloc::{Allocator, Global};
 /// let iter: std::vec::ExtractIf<'_, _, _> = v.extract_if(.., |x| *x % 2 == 0);
 /// ```
 #[stable(feature = "extract_if", since = "1.87.0")]
-#[must_use = "iterators are lazy and do nothing unless consumed"]
+#[must_use = "iterators are lazy and do nothing unless consumed; \
+    use `retain_mut` or `extract_if().for_each(drop)` to remove and discard elements"]
 pub struct ExtractIf<
     'a,
     T,

library/alloc/src/vec/mod.rs

@@ -3933,7 +3933,8 @@ impl<T, A: Allocator> Vec<T, A> {
     ///
     /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating
     /// or the iteration short-circuits, then the remaining elements will be retained.
-    /// Use [`retain_mut`] with a negated predicate if you do not need the returned iterator.
+    /// Use `extract_if().for_each(drop)` if you do not need the returned iterator,
+    /// or [`retain_mut`] with a negated predicate if you also do not need to restrict the range.
     ///
     /// [`retain_mut`]: Vec::retain_mut
     ///

library/std/src/collections/hash/map.rs

@@ -1685,7 +1685,8 @@ impl<'a, K, V> Drain<'a, K, V> {
 /// let iter = map.extract_if(|_k, v| *v % 2 == 0);
 /// ```
 #[stable(feature = "hash_extract_if", since = "1.88.0")]
-#[must_use = "iterators are lazy and do nothing unless consumed"]
+#[must_use = "iterators are lazy and do nothing unless consumed; \
+    use `retain` to remove and discard elements"]
 pub struct ExtractIf<'a, K, V, F> {
     base: base::ExtractIf<'a, K, V, F>,
 }

library/std/src/collections/hash/set.rs

@@ -1391,6 +1391,8 @@ pub struct Drain<'a, K: 'a> {
 /// let mut extract_ifed = a.extract_if(|v| v % 2 == 0);
 /// ```
 #[stable(feature = "hash_extract_if", since = "1.88.0")]
+#[must_use = "iterators are lazy and do nothing unless consumed; \
+    use `retain` to remove and discard elements"]
 pub struct ExtractIf<'a, K, F> {
     base: base::ExtractIf<'a, K, F>,
 }