Add free function for .sorted(). Edit docs & example.

src/free.rs

@@ -202,7 +202,7 @@ pub fn merge<I, J>(i: I, j: J) -> Merge<I::IntoIter, J::IntoIter>
 
 /// Combine all iterator elements into one String, seperated by `sep`.
 ///
-/// `IntoIterator` enabled version of `i.join(sep)`.
+/// `IntoIterator` enabled version of `iterable.join(sep)`.
 ///
 /// ```
 /// use itertools::free::join;
@@ -215,3 +215,20 @@ 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.
+///
+/// `IntoIterator` enabled version of `iterable.sorted()`.
+///
+/// ```
+/// use itertools::free::sorted;
+/// use itertools::assert_equal;
+///
+/// assert_equal(sorted("rust".chars()), "rstu".chars());
+/// ```
+pub fn sorted<I>(iterable: I) -> Vec<I::Item>
+    where I: IntoIterator,
+          I::Item: Ord,
+{
+    iterable.into_iter().sorted()
+}

src/lib.rs

@@ -1221,6 +1221,26 @@ pub trait Itertools : Iterator {
         }
     }
 
+    /// Collect all iterator elements into a sorted vector in ascending order.
+    ///
+    /// **Note:** This consumes the entire iterator, uses the
+    /// `slice::sort_by()` method and returns the sorted vector.
+    ///
+    /// ```
+    /// use itertools::Itertools;
+    ///
+    /// // sort the letters of the text in ascending order
+    /// let text = "bdacfe";
+    /// itertools::assert_equal(text.chars().sorted(),
+    ///                         "abcdef".chars());
+    /// ```
+    fn sorted(self) -> Vec<Self::Item>
+        where Self: Sized,
+              Self::Item: Ord
+    {
+        self.sorted_by(Ord::cmp)
+    }
+
     /// Collect all iterator elements into a sorted vector.
     ///
     /// **Note:** This consumes the entire iterator, uses the
@@ -1251,28 +1271,6 @@ pub trait Itertools : Iterator {
         v
     }
 
-    /// Collect all iterator elements into a sorted vector in ascending order.
-    ///
-    /// ```
-    /// use itertools::Itertools;
-    ///
-    /// // sort chars in ascending order
-    /// let chars = vec!['b', 'd', 'a', 'c', 'f', 'e'];
-    ///
-    /// let sorted_chars = chars
-    ///     .into_iter()
-    ///     .sorted();
-    ///
-    /// itertools::assert_equal(sorted_chars,
-    ///                         vec!['a', 'b', 'c', 'd', 'e', 'f']);
-    /// ```
-    fn sorted(self) -> Vec<Self::Item>
-        where Self: Sized,
-              Self::Item: Ord
-    {
-        self.sorted_by(Ord::cmp)
-    }
-
     /// **Deprecated:** renamed to `.sorted_by()`
     fn sort_by<F>(self, cmp: F) -> Vec<Self::Item>
         where Self: Sized,