Explain that size_hint cannot be trusted

Same applies to `len()` function of `ExactSizeIterator` trait.

1 files changed, 23 insertions, 0 deletions

diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index e6dae771792..da7d673cd96 100644
--- a/src/libcore/iter.rs
+++ b/src/libcore/iter.rs
@@ -369,6 +369,25 @@ pub trait Iterator {
     /// `None` here means that either there is no known upper bound, or the
     /// upper bound is larger than `usize`.
     ///
+    /// # Implementation notes
+    ///
+    /// It is not enforced that an iterator implementation yields the
+    /// declared number of elements. A buggy iterator may yield less
+    /// than the lower bound or more than the upper bound of elements.
+    ///
+    /// `size_hint()` is primarily intended to be used for optimizations
+    /// such as reserving space for the elements of the iterator, but
+    /// must not be trusted to e.g. omit bounds checks in unsafe code.
+    /// An incorrect implementation of `size_hint()` should not lead to
+    /// memory safety violations.
+    ///
+    /// That said, the implementation should provide a correct
+    /// estimation, because otherwise it would be a violation of the
+    /// trait's protocol.
+    ///
+    /// The default implementation returns `(0, None)` which is correct
+    /// for any iterator.
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -2731,7 +2750,11 @@ pub trait ExactSizeIterator: Iterator {
     /// implementation, you can do so. See the [trait-level] docs for an
     /// example.
     ///
+    /// This function has the same safety guarantees as [`size_hint()`]
+    /// function.
+    ///
     /// [trait-level]: trait.ExactSizeIterator.html
+    /// [`size_hint()`]: trait.Iterator.html#method.size_hint
     ///
     /// # Examples
     ///