diff --git a/library/alloc/src/collections/binary_heap.rs b/library/alloc/src/collections/binary_heap.rs index 56a4700181199..e90e87d4685ad 100644 --- a/library/alloc/src/collections/binary_heap.rs +++ b/library/alloc/src/collections/binary_heap.rs @@ -748,12 +748,18 @@ impl BinaryHeap { /// Returns an iterator which retrieves elements in heap order. /// The retrieved elements are removed from the original heap. - /// The remaining elements will be removed on drop in heap order. + /// On drop, the remaining elements are removed and dropped in heap order. /// /// Note: /// * `.drain_sorted()` is *O*(*n* \* log(*n*)); much slower than `.drain()`. /// You should use the latter for most cases. /// + /// # Leaking + /// + /// In case the iterator disappears without getting dropped (using + /// [`mem::forget`], for example), it is unspecified whether the + /// remaining elements are still in the heap or leaked. + /// /// # Examples /// /// Basic usage: @@ -1162,6 +1168,14 @@ impl BinaryHeap { /// /// The elements are removed in arbitrary order. /// + /// # Leaking + /// + /// When the iterator **is** dropped, it drops any elements that it has not + /// yet yielded (none if the iterator was fully consumed). + /// If the iterator **is not** dropped (with [`mem::forget`], for example), + /// it is unspecified whether the elements not yet yielded are still in the + /// heap or leaked. + /// /// # Examples /// /// Basic usage: diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs index 4a07d5d4bed10..998a82b2b9b15 100644 --- a/library/alloc/src/collections/linked_list.rs +++ b/library/alloc/src/collections/linked_list.rs @@ -970,6 +970,14 @@ impl LinkedList { /// Note that `drain_filter` lets you mutate every element in the filter closure, regardless of /// whether you choose to keep or remove it. /// + /// # Leaking + /// + /// When the iterator **is** dropped, it drops any elements that it has not + /// yet yielded and for which the closure returns true. + /// If the iterator **is not** dropped (with [`mem::forget`], for example), + /// it is unspecified whether the elements not yet yielded are still in the + /// list or leaked. + /// /// # Examples /// /// Splitting a list into evens and odds, reusing the original list: diff --git a/library/alloc/src/collections/vec_deque/mod.rs b/library/alloc/src/collections/vec_deque/mod.rs index a8a18d655855e..8b43576f968b2 100644 --- a/library/alloc/src/collections/vec_deque/mod.rs +++ b/library/alloc/src/collections/vec_deque/mod.rs @@ -1215,15 +1215,16 @@ impl VecDeque { unsafe { IterMut::new(ring, tail, head, PhantomData) } } - /// Creates a draining iterator that removes the specified range in the - /// `VecDeque` and yields the removed items. + /// Removes the specified range from the `VecDeque`, returning all removed + /// elements as an iterator. /// - /// Note 1: The element range is removed even if the iterator is not - /// consumed until the end. + /// # Leaking /// - /// Note 2: It is unspecified how many elements are removed from the deque, - /// if the `Drain` value is not dropped, but the borrow it holds expires - /// (e.g., due to `mem::forget`). + /// When the iterator **is** dropped, it drops any elements that it has not + /// yet yielded (none if the iterator was fully consumed). + /// If the iterator **is not** dropped (with [`mem::forget`], for example), + /// it is unspecified which elements remain in the vector; even elements + /// outside the range may have been removed and leaked. /// /// # Panics /// @@ -1240,7 +1241,7 @@ impl VecDeque { /// assert_eq!(drained, [3]); /// assert_eq!(v, [1, 2]); /// - /// // A full range clears all contents + /// // A full range clears all contents, like `clear()` does /// v.drain(..); /// assert!(v.is_empty()); /// ``` diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs index 7c0faf0659a2c..b3ed79aaa402c 100644 --- a/library/alloc/src/string.rs +++ b/library/alloc/src/string.rs @@ -1628,11 +1628,13 @@ impl String { self.vec.clear() } - /// Creates a draining iterator that removes the specified range in the `String` - /// and yields the removed `chars`. + /// Removes the specified range from the string, returning all removed + /// characters as an iterator. /// - /// Note: The element range is removed even if the iterator is not - /// consumed until the end. + /// # Leaking + /// + /// In case the iterator disappears without getting dropped (using + /// [`core::mem::forget`], for example), the range remains in the string. /// /// # Panics /// @@ -1652,7 +1654,7 @@ impl String { /// assert_eq!(t, "α is alpha, "); /// assert_eq!(s, "β is beta"); /// - /// // A full range clears the string + /// // A full range clears the string, like `clear()` does /// s.drain(..); /// assert_eq!(s, ""); /// ``` diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index bd3262b51d480..6876166560a3f 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -1799,13 +1799,16 @@ impl Vec { self.len += count; } - /// Creates a draining iterator that removes the specified range in the vector - /// and yields the removed items. + /// Removes the specified range from the vector, returning all removed + /// elements as an iterator. /// - /// When the iterator **is** dropped, all elements in the range are removed - /// from the vector, even if the iterator was not fully consumed. If the - /// iterator **is not** dropped (with [`mem::forget`] for example), it is - /// unspecified how many elements are removed. + /// # Leaking + /// + /// When the iterator **is** dropped, it drops any elements that it has not + /// yet yielded (none if the iterator was fully consumed). + /// If the iterator **is not** dropped (with [`mem::forget`], for example), + /// it is unspecified which elements remain in the vector; even elements + /// outside the range may have been removed and leaked. /// /// # Panics /// @@ -1820,7 +1823,7 @@ impl Vec { /// assert_eq!(v, &[1]); /// assert_eq!(u, &[2, 3]); /// - /// // A full range clears the vector + /// // A full range clears the vector, like `clear()` does /// v.drain(..); /// assert_eq!(v, &[]); /// ``` @@ -2731,6 +2734,14 @@ impl Vec { /// Note that `drain_filter` also lets you mutate every element in the filter closure, /// regardless of whether you choose to keep or remove it. /// + /// # Leaking + /// + /// When the iterator **is** dropped, it drops any elements that it has not + /// yet yielded and for which the closure returns true. + /// If the iterator **is not** dropped (with [`mem::forget`], for example), + /// it is unspecified which elements remain in the vector; even elements + /// outside the range may have been removed and leaked. + /// /// # Examples /// /// Splitting an array into evens and odds, reusing the original allocation: diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs index d1450987e7374..a7af8c5a2e4b6 100644 --- a/library/std/src/collections/hash/set.rs +++ b/library/std/src/collections/hash/set.rs @@ -227,7 +227,7 @@ impl HashSet { self.base.is_empty() } - /// Clears the set, returning all elements in an iterator. + /// Clears the set, returning all elements as an iterator. /// /// # Examples ///