|
| 1 | +/// An iterator whose elements may be checked without advancing the iterator. |
| 2 | +/// |
| 3 | +/// In general, many [`Iterator`]s are able to "peek" their next element, |
| 4 | +/// showing what would be returned by a call to `next` without advancing their |
| 5 | +/// internal state. If these iterators do not offer such functionality, it can |
| 6 | +/// be manually added to an iterator using the [`peekable`] method. |
| 7 | +/// |
| 8 | +/// In most cases, calling [`peekable`] on a [`PeekableIterator`] shouldn't |
| 9 | +/// noticeably affect functionality, however, it's worth pointing out a few |
| 10 | +/// differences between [`peekable`] and [`PeekableIterator`]: |
| 11 | +/// |
| 12 | +/// * Stateful iterators like those using [`inspect`](Iterator::inspect) will |
| 13 | +/// eagerly evaluate when peeked by a [`peekable`] wrapper, but may do so |
| 14 | +/// lazily with a custom [`PeekableIterator`] implementation. |
| 15 | +/// * The [`peekable`] wrapper will incur a small performance penalty for |
| 16 | +/// [`next`] and [`next_back`], but [`PeekableIterator`] implementations |
| 17 | +/// incur no such penalty. |
| 18 | +/// * The [`peekable`] wrapper will return a reference to its item, whereas |
| 19 | +/// [`PeekableIterator`] will return the item directly. |
| 20 | +/// |
| 21 | +/// Note that this trait is a safe trait and as such does *not* and *cannot* |
| 22 | +/// guarantee that the peeked value will be returned in a subsequent call to |
| 23 | +/// [`next`], no matter how soon the two are called together. A common |
| 24 | +/// example of this is interior mutability; if the interior state of the |
| 25 | +/// iterator is mutated between a call to [`peek`] and [`next`], then the |
| 26 | +/// values may differ. |
| 27 | +/// |
| 28 | +/// [`peek`]: Self::peek |
| 29 | +/// [`peekable`]: Iterator::peekable |
| 30 | +/// [`Peekable`]: super::Peekable |
| 31 | +/// [`next`]: Iterator::next |
| 32 | +/// [`next_back`]: DoubleEndedIterator::next_back |
| 33 | +/// |
| 34 | +/// # Examples |
| 35 | +/// |
| 36 | +/// Basic usage: |
| 37 | +/// |
| 38 | +/// ``` |
| 39 | +/// #![feature(peekable_iterator)] |
| 40 | +/// use std::iter::PeekableIterator; |
| 41 | +/// |
| 42 | +/// // a range knows its current state exactly |
| 43 | +/// let five = 0..5; |
| 44 | +/// |
| 45 | +/// assert_eq!(Some(0), five.peek()); |
| 46 | +/// ``` |
| 47 | +#[unstable(feature = "peekable_iterator", issue = "none")] |
| 48 | +pub trait PeekableIterator: Iterator { |
| 49 | + /// Returns a reference to the [`next`] value without advancing the iterator. |
| 50 | + /// |
| 51 | + /// [`next`]: Iterator::next |
| 52 | + /// |
| 53 | + /// # Examples |
| 54 | + /// |
| 55 | + /// Basic usage: |
| 56 | + /// |
| 57 | + /// ``` |
| 58 | + /// #![feature(peekable_iterator)] |
| 59 | + /// use std::iter::PeekableIterator; |
| 60 | + /// |
| 61 | + /// // a finite range knows its current state exactly |
| 62 | + /// let five = 0..5; |
| 63 | + /// |
| 64 | + /// assert_eq!(Some(0), five.peek()); |
| 65 | + /// ``` |
| 66 | + #[unstable(feature = "peekable_iterator", issue = "none")] |
| 67 | + fn peek(&self) -> Option<Self::Item>; |
| 68 | + |
| 69 | + /// Returns `true` if the [`next`] value is `None`. |
| 70 | + /// |
| 71 | + /// [`next`]: Iterator::next |
| 72 | + /// |
| 73 | + /// # Examples |
| 74 | + /// |
| 75 | + /// Basic usage: |
| 76 | + /// |
| 77 | + /// ``` |
| 78 | + /// #![feature(peekable_iterator)] |
| 79 | + /// use std::iter::PeekableIterator; |
| 80 | + /// |
| 81 | + /// let mut one_element = std::iter::once(0); |
| 82 | + /// assert!(one_element.has_next()); |
| 83 | + /// |
| 84 | + /// assert_eq!(one_element.next(), Some(0)); |
| 85 | + /// assert!(!one_element.has_next()); |
| 86 | + /// |
| 87 | + /// assert_eq!(one_element.next(), None); |
| 88 | + /// ``` |
| 89 | + #[inline] |
| 90 | + #[unstable(feature = "peekable_iterator", issue = "none")] |
| 91 | + fn has_next(&self) -> bool { |
| 92 | + self.peek().is_some() |
| 93 | + } |
| 94 | +} |
| 95 | + |
| 96 | +#[unstable(feature = "peekable_iterator", issue = "none")] |
| 97 | +impl<I: PeekableIterator + ?Sized> PeekableIterator for &mut I { |
| 98 | + fn peek(&self) -> Option<I::Item> { |
| 99 | + (**self).peek() |
| 100 | + } |
| 101 | +} |
0 commit comments