FEAT: Return an iterator from sorted/sorted_by/sorted_by_key

Author: bluss

src/free.rs

@@ -6,6 +6,9 @@
 #[cfg(feature = "use_std")]
 use std::fmt::Display;
 use std::iter::{self, Zip};
+#[cfg(feature = "use_std")]
+type VecIntoIter<T> = ::std::vec::IntoIter<T>;
+
 #[cfg(feature = "use_std")]
 use Itertools;
 
@@ -211,9 +214,11 @@ pub fn join<I>(iterable: I, sep: &str) -> String
     iterable.into_iter().join(sep)
 }
 
-/// Collect all the iterable's elements into a sorted vector in ascending order.
+/// Sort all iterator elements into a new iterator in ascending order.
+///
+/// `IntoIterator` enabled version of [`iterable.sorted()`][1].
 ///
-/// `IntoIterator` enabled version of `iterable.sorted()`.
+/// [1]: trait.Itertools.html#method.sorted
 ///
 /// ```
 /// use itertools::sorted;
@@ -222,7 +227,7 @@ pub fn join<I>(iterable: I, sep: &str) -> String
 /// assert_equal(sorted("rust".chars()), "rstu".chars());
 /// ```
 #[cfg(feature = "use_std")]
-pub fn sorted<I>(iterable: I) -> Vec<I::Item>
+pub fn sorted<I>(iterable: I) -> VecIntoIter<I::Item>
     where I: IntoIterator,
           I::Item: Ord
 {

src/lib.rs

@@ -38,6 +38,10 @@ use std::fmt;
 use std::hash::Hash;
 #[cfg(feature = "use_std")]
 use std::fmt::Write;
+#[cfg(feature = "use_std")]
+type VecIntoIter<T> = ::std::vec::IntoIter<T>;
+#[cfg(feature = "use_std")]
+use std::iter::FromIterator;
 
 #[macro_use]
 mod impl_macros;
@@ -1609,10 +1613,14 @@ pub trait Itertools : Iterator {
         FoldWhile::Continue(acc)
     }
 
-    /// Collect all iterator elements into a sorted vector in ascending order.
+    /// Sort all iterator elements into a new iterator in ascending order.
     ///
     /// **Note:** This consumes the entire iterator, uses the
-    /// `slice::sort_by()` method and returns the sorted vector.
+    /// `slice::sort()` method and returns the result as a new
+    /// iterator that owns its elements.
+    ///
+    /// The sorted iterator, if directly collected to a `Vec`, is converted
+    /// without any extra copying or allocation cost.
     ///
     /// ```
     /// use itertools::Itertools;
@@ -1623,17 +1631,25 @@ pub trait Itertools : Iterator {
     ///                         "abcdef".chars());
     /// ```
     #[cfg(feature = "use_std")]
-    fn sorted(self) -> Vec<Self::Item>
+    fn sorted(self) -> VecIntoIter<Self::Item>
         where Self: Sized,
               Self::Item: Ord
     {
-        self.sorted_by(Ord::cmp)
+        // Use .sort() directly since it is not quite identical with
+        // .sort_by(Ord::cmp)
+        let mut v = Vec::from_iter(self);
+        v.sort();
+        v.into_iter()
     }
 
-    /// Collect all iterator elements into a sorted vector.
+    /// Sort all iterator elements into a new iterator in ascending order.
     ///
     /// **Note:** This consumes the entire iterator, uses the
-    /// `slice::sort_by()` method and returns the sorted vector.
+    /// `slice::sort_by()` method and returns the result as a new
+    /// iterator that owns its elements.
+    ///
+    /// The sorted iterator, if directly collected to a `Vec`, is converted
+    /// without any extra copying or allocation cost.
     ///
     /// ```
     /// use itertools::Itertools;
@@ -1644,27 +1660,29 @@ pub trait Itertools : Iterator {
     /// let oldest_people_first = people
     ///     .into_iter()
     ///     .sorted_by(|a, b| Ord::cmp(&b.1, &a.1))
-    ///     .into_iter()
     ///     .map(|(person, _age)| person);
     ///
     /// itertools::assert_equal(oldest_people_first,
     ///                         vec!["Jill", "Jack", "Jane", "John"]);
     /// ```
     #[cfg(feature = "use_std")]
-    fn sorted_by<F>(self, cmp: F) -> Vec<Self::Item>
+    fn sorted_by<F>(self, cmp: F) -> VecIntoIter<Self::Item>
         where Self: Sized,
               F: FnMut(&Self::Item, &Self::Item) -> Ordering,
     {
-        let mut v: Vec<Self::Item> = self.collect();
-
+        let mut v = Vec::from_iter(self);
         v.sort_by(cmp);
-        v
+        v.into_iter()
     }
 
-    /// Collect all iterator elements into a sorted vector.
+    /// Sort all iterator elements into a new iterator in ascending order.
     ///
     /// **Note:** This consumes the entire iterator, uses the
-    /// `slice::sort_by_key()` method and returns the sorted vector.
+    /// `slice::sort_by_key()` method and returns the result as a new
+    /// iterator that owns its elements.
+    ///
+    /// The sorted iterator, if directly collected to a `Vec`, is converted
+    /// without any extra copying or allocation cost.
     ///
     /// ```
     /// use itertools::Itertools;
@@ -1675,22 +1693,20 @@ pub trait Itertools : Iterator {
     /// let oldest_people_first = people
     ///     .into_iter()
     ///     .sorted_by_key(|x| -x.1)
-    ///     .into_iter()
     ///     .map(|(person, _age)| person);
     ///
     /// itertools::assert_equal(oldest_people_first,
     ///                         vec!["Jill", "Jack", "Jane", "John"]);
     /// ```
     #[cfg(feature = "use_std")]
-    fn sorted_by_key<K, F>(self, f: F) -> Vec<Self::Item>
+    fn sorted_by_key<K, F>(self, f: F) -> VecIntoIter<Self::Item>
         where Self: Sized,
               K: Ord,
               F: FnMut(&Self::Item) -> K,
     {
-        let mut v: Vec<Self::Item> = self.collect();
-
+        let mut v = Vec::from_iter(self);
         v.sort_by_key(f);
-        v
+        v.into_iter()
     }
 
     /// Collect all iterator elements into one of two

tests/test_std.rs

@@ -269,19 +269,19 @@ fn sorted_by() {
     let sc = [3, 4, 1, 2].iter().cloned().sorted_by(|&a, &b| {
         a.cmp(&b)
     });
-    assert_eq!(sc, vec![1, 2, 3, 4]);
+    it::assert_equal(sc, vec![1, 2, 3, 4]);
 
     let v = (0..5).sorted_by(|&a, &b| a.cmp(&b).reverse());
-    assert_eq!(v, vec![4, 3, 2, 1, 0]);
+    it::assert_equal(v, vec![4, 3, 2, 1, 0]);
 }
 
 #[test]
 fn sorted_by_key() {
     let sc = [3, 4, 1, 2].iter().cloned().sorted_by_key(|&x| x);
-    assert_eq!(sc, vec![1, 2, 3, 4]);
+    it::assert_equal(sc, vec![1, 2, 3, 4]);
 
     let v = (0..5).sorted_by_key(|&x| -x);
-    assert_eq!(v, vec![4, 3, 2, 1, 0]);
+    it::assert_equal(v, vec![4, 3, 2, 1, 0]);
 }
 
 #[test]