1 use crate::iter::Step; 2 3 /// An iterator that always continues to yield `None` when exhausted. 4 /// 5 /// Calling next on a fused iterator that has returned `None` once is guaranteed 6 /// to return [`None`] again. This trait should be implemented by all iterators 7 /// that behave this way because it allows optimizing [`Iterator::fuse()`]. 8 /// 9 /// Note: In general, you should not use `FusedIterator` in generic bounds if 10 /// you need a fused iterator. Instead, you should just call [`Iterator::fuse()`] 11 /// on the iterator. If the iterator is already fused, the additional [`Fuse`] 12 /// wrapper will be a no-op with no performance penalty. 13 /// 14 /// [`Fuse`]: crate::iter::Fuse 15 #[stable(feature = "fused", since = "1.26.0")] 16 #[rustc_unsafe_specialization_marker] 17 pub trait FusedIterator: Iterator {} 18 19 #[stable(feature = "fused", since = "1.26.0")] 20 impl<I: FusedIterator + ?Sized> FusedIterator for &mut I {} 21 22 /// An iterator that reports an accurate length using size_hint. 23 /// 24 /// The iterator reports a size hint where it is either exact 25 /// (lower bound is equal to upper bound), or the upper bound is [`None`]. 26 /// The upper bound must only be [`None`] if the actual iterator length is 27 /// larger than [`usize::MAX`]. In that case, the lower bound must be 28 /// [`usize::MAX`], resulting in an [`Iterator::size_hint()`] of 29 /// `(usize::MAX, None)`. 30 /// 31 /// The iterator must produce exactly the number of elements it reported 32 /// or diverge before reaching the end. 33 /// 34 /// # When *shouldn't* an adapter be `TrustedLen`? 35 /// 36 /// If an adapter makes an iterator *shorter* by a given amount, then it's 37 /// usually incorrect for that adapter to implement `TrustedLen`. The inner 38 /// iterator might return more than `usize::MAX` items, but there's no way to 39 /// know what `k` elements less than that will be, since the `size_hint` from 40 /// the inner iterator has already saturated and lost that information. 41 /// 42 /// This is why [`Skip<I>`](crate::iter::Skip) isn't `TrustedLen`, even when 43 /// `I` implements `TrustedLen`. 44 /// 45 /// # Safety 46 /// 47 /// This trait must only be implemented when the contract is upheld. Consumers 48 /// of this trait must inspect [`Iterator::size_hint()`]’s upper bound. 49 #[unstable(feature = "trusted_len", issue = "37572")] 50 #[rustc_unsafe_specialization_marker] 51 pub unsafe trait TrustedLen: Iterator {} 52 53 #[unstable(feature = "trusted_len", issue = "37572")] 54 unsafe impl<I: TrustedLen + ?Sized> TrustedLen for &mut I {} 55 56 /// An iterator that when yielding an item will have taken at least one element 57 /// from its underlying [`SourceIter`]. 58 /// 59 /// Calling any method that advances the iterator, e.g. [`next()`] or [`try_fold()`], 60 /// guarantees that for each step at least one value of the iterator's underlying source 61 /// has been moved out and the result of the iterator chain could be inserted 62 /// in its place, assuming structural constraints of the source allow such an insertion. 63 /// In other words this trait indicates that an iterator pipeline can be collected in place. 64 /// 65 /// The primary use of this trait is in-place iteration. Refer to the [`vec::in_place_collect`] 66 /// module documentation for more information. 67 /// 68 /// [`vec::in_place_collect`]: ../../../../alloc/vec/in_place_collect/index.html 69 /// [`SourceIter`]: crate::iter::SourceIter 70 /// [`next()`]: Iterator::next 71 /// [`try_fold()`]: Iterator::try_fold 72 #[unstable(issue = "none", feature = "inplace_iteration")] 73 #[doc(hidden)] 74 pub unsafe trait InPlaceIterable: Iterator {} 75 76 /// A type that upholds all invariants of [`Step`]. 77 /// 78 /// The invariants of [`Step::steps_between()`] are a superset of the invariants 79 /// of [`TrustedLen`]. As such, [`TrustedLen`] is implemented for all range 80 /// types with the same generic type argument. 81 /// 82 /// # Safety 83 /// 84 /// The implementation of [`Step`] for the given type must guarantee all 85 /// invariants of all methods are upheld. See the [`Step`] trait's documentation 86 /// for details. Consumers are free to rely on the invariants in unsafe code. 87 #[unstable(feature = "trusted_step", issue = "85731")] 88 #[rustc_specialization_trait] 89 pub unsafe trait TrustedStep: Step + Copy {} 90