diff --git a/library/alloc/src/collections/binary_heap.rs b/library/alloc/src/collections/binary_heap.rs index 477a598ff5b00..27e23ae79c275 100644 --- a/library/alloc/src/collections/binary_heap.rs +++ b/library/alloc/src/collections/binary_heap.rs @@ -720,18 +720,27 @@ impl BinaryHeap { /// Returns an iterator which retrieves elements in heap order. /// This method consumes the original heap. /// + /// One good use for this is if you need the largest (or smallest) `k` + /// items from an iterator, but you're not sure exactly how many you'll + /// need -- just that `k` is much less than all of them -- so want to + /// compute those items on-demand. + /// + /// You could collect into a `Vec` and sort everything, but that's `O(n log n)`. + /// + /// By instead collecting into a `BinaryHeap` and using this method, + /// the complexity improves to `O(n + k log n)`. + /// /// # Examples /// /// Basic usage: /// /// ``` - /// #![feature(binary_heap_into_iter_sorted)] /// use std::collections::BinaryHeap; /// let heap = BinaryHeap::from(vec![1, 2, 3, 4, 5]); /// /// assert_eq!(heap.into_iter_sorted().take(2).collect::>(), vec![5, 4]); /// ``` - #[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] + #[stable(feature = "binary_heap_into_iter_sorted", since = "1.48.0")] pub fn into_iter_sorted(self) -> IntoIterSorted { IntoIterSorted { inner: self } } @@ -1173,13 +1182,20 @@ impl ExactSizeIterator for IntoIter { #[stable(feature = "fused", since = "1.26.0")] impl FusedIterator for IntoIter {} -#[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] +/// An owning iterator over the elements of a `BinaryHeap`. +/// +/// This `struct` is created by the [`into_iter_sorted`] method on [`BinaryHeap`]. +/// See its documentation for more. +/// +/// [`into_iter_sorted`]: struct.BinaryHeap.html#method.into_iter_sorted +/// [`BinaryHeap`]: struct.BinaryHeap.html +#[stable(feature = "binary_heap_into_iter_sorted", since = "1.48.0")] #[derive(Clone, Debug)] pub struct IntoIterSorted { inner: BinaryHeap, } -#[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] +#[stable(feature = "binary_heap_into_iter_sorted", since = "1.48.0")] impl Iterator for IntoIterSorted { type Item = T; @@ -1195,10 +1211,10 @@ impl Iterator for IntoIterSorted { } } -#[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] +#[stable(feature = "binary_heap_into_iter_sorted", since = "1.48.0")] impl ExactSizeIterator for IntoIterSorted {} -#[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] +#[stable(feature = "binary_heap_into_iter_sorted", since = "1.48.0")] impl FusedIterator for IntoIterSorted {} #[unstable(feature = "trusted_len", issue = "37572")] diff --git a/library/alloc/tests/lib.rs b/library/alloc/tests/lib.rs index f2ba1ab64810b..84b3f8e3437b1 100644 --- a/library/alloc/tests/lib.rs +++ b/library/alloc/tests/lib.rs @@ -9,7 +9,6 @@ #![feature(try_reserve)] #![feature(unboxed_closures)] #![feature(associated_type_bounds)] -#![feature(binary_heap_into_iter_sorted)] #![feature(binary_heap_drain_sorted)] #![feature(slice_ptr_get)] #![feature(split_inclusive)]