From a3cab90fda3b1ccfa4eb952dda49677c8d06c1ef Mon Sep 17 00:00:00 2001 From: Ulrik Sverdrup Date: Thu, 20 Oct 2016 14:44:31 +0200 Subject: [PATCH] =?UTF-8?q?Document=20TrustedLen=E2=80=99s=20contract?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/libcore/iter/traits.rs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) 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 {}