1use crate::iter::TrustedLen;
2
3/// [`TrustedLen`] cannot have methods, so this allows augmenting it.
4///
5/// It currently requires `TrustedLen` because it's unclear whether it's
6/// reasonably possible to depend on the `size_hint` of anything else.
7pub(crate) trait UncheckedIterator: TrustedLen {
8 /// Gets the next item from a non-empty iterator.
9 ///
10 /// Because there's always a value to return, that means it can return
11 /// the `Item` type directly, without wrapping it in an `Option`.
12 ///
13 /// # Safety
14 ///
15 /// This can only be called if `size_hint().0 != 0`, guaranteeing that
16 /// there's at least one item available.
17 ///
18 /// Otherwise (aka when `size_hint().1 == Some(0)`), this is UB.
19 ///
20 /// # Note to Implementers
21 ///
22 /// This has a default implementation using [`Option::unwrap_unchecked`].
23 /// That's probably sufficient if your `next` *always* returns `Some`,
24 /// such as for infinite iterators. In more complicated situations, however,
25 /// sometimes there can still be `insertvalue`/`assume`/`extractvalue`
26 /// instructions remaining in the IR from the `Option` handling, at which
27 /// point you might want to implement this manually instead.
28 #[unstable(feature = "trusted_len_next_unchecked", issue = "37572")]
29 #[inline]
30 unsafe fn next_unchecked(&mut self) -> Self::Item {
31 let opt = self.next();
32 // SAFETY: The caller promised that we're not empty, and
33 // `Self: TrustedLen` so we can actually trust the `size_hint`.
34 unsafe { opt.unwrap_unchecked() }
35 }
36}
37