add must_use to extract_if methods

Author: RalfJung

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
     ///
@@ -1458,6 +1459,8 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
     /// assert_eq!(high.keys().copied().collect::<Vec<_>>(), [4, 5, 6, 7]);
     /// ```
     #[stable(feature = "btree_extract_if", since = "1.91.0")]
+    #[must_use = "this iterator is lazy and does nothing unless consumed; \
+        use `retain` or `extract_if().for_each(drop)` to remove and discard elements"]
     pub fn extract_if<F, R>(&mut self, range: R, pred: F) -> ExtractIf<'_, K, V, R, F, A>
     where
         K: Ord,

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
@@ -1212,6 +1213,8 @@ impl<T, A: Allocator + Clone> BTreeSet<T, A> {
     /// assert_eq!(high.into_iter().collect::<Vec<_>>(), [4, 5, 6, 7]);
     /// ```
     #[stable(feature = "btree_extract_if", since = "1.91.0")]
+    #[must_use = "this iterator is lazy and does nothing unless consumed; \
+        use `retain` or `extract_if().for_each(drop)` to remove and discard elements"]
     pub fn extract_if<F, R>(&mut self, range: R, pred: F) -> ExtractIf<'_, T, R, F, A>
     where
         T: Ord,

library/alloc/src/collections/linked_list.rs

@@ -1141,7 +1141,9 @@ impl<T, A: Allocator> LinkedList<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 `extract_if().for_each(drop)` if you do not need the returned iterator.
+    /// Use [`retain`] with a negated predicate if you do not need the returned iterator.
+    ///
+    /// [`retain`]: LinkedList::retain
     ///
     /// The iterator also lets you mutate the value of each element in the
     /// closure, regardless of whether you choose to keep or remove it.
@@ -1163,6 +1165,8 @@ impl<T, A: Allocator> LinkedList<T, A> {
     /// assert_eq!(odds.into_iter().collect::<Vec<_>>(), vec![1, 3, 5, 9, 11, 13, 15]);
     /// ```
     #[stable(feature = "extract_if", since = "1.87.0")]
+    #[must_use = "this iterator is lazy and does nothing unless consumed; \
+        use `retain` to remove and discard elements"]
     pub fn extract_if<F>(&mut self, filter: F) -> ExtractIf<'_, T, F, A>
     where
         F: FnMut(&mut T) -> bool,

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
     ///
@@ -747,6 +748,8 @@ impl<T, A: Allocator> VecDeque<T, A> {
     /// assert_eq!(ones.len(), 3);
     /// ```
     #[unstable(feature = "vec_deque_extract_if", issue = "147750")]
+    #[must_use = "this iterator is lazy and does nothing unless consumed; \
+        use `retain_mut` or `extract_if().for_each(drop)` to remove and discard elements"]
     pub fn extract_if<F, R>(&mut self, range: R, filter: F) -> ExtractIf<'_, T, F, A>
     where
         F: FnMut(&mut T) -> bool,

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
     ///
@@ -3996,6 +3997,8 @@ impl<T, A: Allocator> Vec<T, A> {
     /// assert_eq!(ones.len(), 3);
     /// ```
     #[stable(feature = "extract_if", since = "1.87.0")]
+    #[must_use = "this iterator is lazy and does nothing unless consumed; \
+        use `retain_mut` or `extract_if().for_each(drop)` to remove and discard elements"]
     pub fn extract_if<F, R>(&mut self, range: R, filter: F) -> ExtractIf<'_, T, F, A>
     where
         F: FnMut(&mut T) -> bool,

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

@@ -688,6 +688,8 @@ impl<K, V, S> HashMap<K, V, S> {
     #[inline]
     #[rustc_lint_query_instability]
     #[stable(feature = "hash_extract_if", since = "1.88.0")]
+    #[must_use = "this iterator is lazy and does nothing unless consumed; \
+        use `retain` to remove and discard elements"]
     pub fn extract_if<F>(&mut self, pred: F) -> ExtractIf<'_, K, V, F>
     where
         F: FnMut(&K, &mut V) -> bool,

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

@@ -309,6 +309,8 @@ impl<T, S> HashSet<T, S> {
     #[inline]
     #[rustc_lint_query_instability]
     #[stable(feature = "hash_extract_if", since = "1.88.0")]
+    #[must_use = "this iterator is lazy and does nothing unless consumed; \
+        use `retain` to remove and discard elements"]
     pub fn extract_if<F>(&mut self, pred: F) -> ExtractIf<'_, T, F>
     where
         F: FnMut(&T) -> bool,