Docs: Better explanation of return values for min, max functions

Explain that a None is returned if the iterator is empty.

diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index 3785bbe9bb0e42ad3c5853daf46ae55a8ffad902..0f47378aebb7ca03d3e41465b05bb525478e588b 100644 (file)
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -1616,7 +1616,9 @@ fn rposition<P>(&mut self, mut predicate: P) -> Option<usize> where
     /// Returns the maximum element of an iterator.
     ///
     /// If several elements are equally maximum, the last element is
-    /// returned.
+    /// returned. If the iterator is empty, [`None`] is returned.
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1624,8 +1626,10 @@ fn rposition<P>(&mut self, mut predicate: P) -> Option<usize> where
     ///
     /// ```
     /// let a = [1, 2, 3];
+    /// let b: Vec<u32> = Vec::new();
     ///
     /// assert_eq!(a.iter().max(), Some(&3));
+    /// assert_eq!(b.iter().max(), None);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -1642,7 +1646,9 @@ fn max(self) -> Option<Self::Item> where Self: Sized, Self::Item: Ord
     /// Returns the minimum element of an iterator.
     ///
     /// If several elements are equally minimum, the first element is
-    /// returned.
+    /// returned. If the iterator is empty, [`None`] is returned.
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1650,8 +1656,10 @@ fn max(self) -> Option<Self::Item> where Self: Sized, Self::Item: Ord
     ///
     /// ```
     /// let a = [1, 2, 3];
+    /// let b: Vec<u32> = Vec::new();
     ///
     /// assert_eq!(a.iter().min(), Some(&1));
+    /// assert_eq!(b.iter().min(), None);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -1669,7 +1677,9 @@ fn min(self) -> Option<Self::Item> where Self: Sized, Self::Item: Ord
     /// specified function.
     ///
     /// If several elements are equally maximum, the last element is
-    /// returned.
+    /// returned. If the iterator is empty, [`None`] is returned.
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1694,7 +1704,9 @@ fn max_by_key<B: Ord, F>(self, f: F) -> Option<Self::Item>
     /// specified comparison function.
     ///
     /// If several elements are equally maximum, the last element is
-    /// returned.
+    /// returned. If the iterator is empty, [`None`] is returned.
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1719,7 +1731,9 @@ fn max_by<F>(self, mut compare: F) -> Option<Self::Item>
     /// specified function.
     ///
     /// If several elements are equally minimum, the first element is
-    /// returned.
+    /// returned. If the iterator is empty, [`None`] is returned.
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1743,7 +1757,9 @@ fn min_by_key<B: Ord, F>(self, f: F) -> Option<Self::Item>
     /// specified comparison function.
     ///
     /// If several elements are equally minimum, the first element is
-    /// returned.
+    /// returned. If the iterator is empty, [`None`] is returned.
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///