add .into_iter_sorted(). (sekineh#20)

* add .into_iter_sorted().

* Add README.md and CHANGELOG.md entry.

Author: sekineh

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 * Quickstart section in the doc
+* `.into_iter_sorted()` which returns the values in *heap* order. (#13)
+  * Note: `.into_iter()` returns the values in *arbitrary* order. There is a good reason (ex. make `.extend()` efficient) for `std` to do that, it was surprising to some people.
 
 ### Changed
 

README.md

@@ -10,6 +10,9 @@ It supports the following features and still maintains backward compatibility.
 - Heap ordered by closure
 - Heap ordered by key generated by closure
 
+Notable added method is:
+- `.into_iter_sorted()` backported from `std`.
+
 ## MSRV (Minimum Supported Rust Version)
 
 This crate requires Rust 1.31.1 or later.

src/binary_heap.rs

@@ -616,6 +616,26 @@ impl<T, C: Compare<T>> BinaryHeap<T, C> {
         }
     }
 
+    /// Returns an iterator which retrieves elements in heap order.
+    /// This method consumes the original heap.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use binary_heap_plus::*;
+    /// let heap = BinaryHeap::from(vec![1, 2, 3, 4, 5]);
+    ///
+    /// assert_eq!(heap.into_iter_sorted().take(2).collect::<Vec<_>>(), vec![5, 4]);
+    /// ```
+    // #[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")]
+    pub fn into_iter_sorted(self) -> IntoIterSorted<T, C> {
+        IntoIterSorted {
+            inner: self,
+        }
+    }
+
     /// Returns the greatest item in the binary heap, or `None` if it is empty.
     ///
     /// # Examples
@@ -1285,6 +1305,28 @@ impl<T> DoubleEndedIterator for IntoIter<T> {
 // #[stable(feature = "fused", since = "1.26.0")]
 // impl<T> FusedIterator for IntoIter<T> {}
 
+// #[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")]
+#[derive(Clone, Debug)]
+pub struct IntoIterSorted<T, C: Compare<T>> {
+    inner: BinaryHeap<T, C>,
+}
+
+// #[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")]
+impl<T, C: Compare<T>> Iterator for IntoIterSorted<T, C> {
+    type Item = T;
+
+    #[inline]
+    fn next(&mut self) -> Option<T> {
+        self.inner.pop()
+    }
+
+    #[inline]
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let exact = self.inner.len();
+        (exact, Some(exact))
+    }
+}
+
 /// A draining iterator over the elements of a `BinaryHeap`.
 ///
 /// This `struct` is created by the [`drain`] method on [`BinaryHeap`]. See its

src/lib.rs

@@ -171,6 +171,14 @@ mod from_liballoc {
         assert_eq!(v, iterout);
     }
 
+    #[test]
+    fn test_into_iter_sorted_collect() {
+        let heap = BinaryHeap::from(vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]);
+        let it = heap.into_iter_sorted();
+        let sorted = it.collect::<Vec<_>>();
+        assert_eq!(sorted, vec![10, 9, 8, 7, 6, 5, 4, 3, 2, 2, 1, 1, 0]);
+    }
+
     #[test]
     fn test_peek_and_pop() {
         let data = vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1];