Document TrustedLen’s contract

1 files changed, 13 insertions, 1 deletions

diff --git a/src/libcore/iter/traits.rs b/src/libcore/iter/traits.rs
index da150f1d57a..a56a864f618 100644
--- a/src/libcore/iter/traits.rs
+++ b/src/libcore/iter/traits.rs
@@ -666,7 +666,19 @@ pub trait FusedIterator: Iterator {}
 #[unstable(feature = "fused", issue = "35602")]
 impl<'a, I: FusedIterator + ?Sized> FusedIterator for &'a mut I {}
 
-/// An iterator that has correct length
+/// An iterator that reports an accurate length using size_hint.
+///
+/// The iterator reports a size hint where it is either exact
+/// (lower bound is equal to upper bound), or the upper bound is `None`.
+/// The upper bound must only be `None` if the actual iterator length is
+/// larger than `usize::MAX`.
+///
+/// The iterator must produce exactly the number of elements it reported.
+///
+/// # Safety
+///
+/// This trait must only be implemented when the contract is upheld.
+/// Consumers of this trait must inspect `.size_hint()`’s upper bound.
 #[unstable(feature = "trusted_len", issue = "0")]
 pub unsafe trait TrustedLen : Iterator {}