1.0.0[][src]Struct core::iter::Peekable

#[must_use = "iterators are lazy and do nothing unless consumed"]pub struct Peekable<I: Iterator> { /* fields omitted */ }

An iterator with a peek() that returns an optional reference to the next element.

This struct is created by the peekable method on Iterator. See its documentation for more.


impl<I: Iterator> Peekable<I>[src]

pub fn peek(&mut self) -> Option<&I::Item>[src]

Returns a reference to the next() value without advancing the iterator.

Like next, if there is a value, it is wrapped in a Some(T). But if the iteration is over, None is returned.

Because peek() returns a reference, and many iterators iterate over references, there can be a possibly confusing situation where the return value is a double reference. You can see this effect in the examples below.


Basic usage:

let xs = [1, 2, 3];

let mut iter = xs.iter().peekable();

// peek() lets us see into the future
assert_eq!(iter.peek(), Some(&&1));
assert_eq!(iter.next(), Some(&1));

assert_eq!(iter.next(), Some(&2));

// The iterator does not advance even if we `peek` multiple times
assert_eq!(iter.peek(), Some(&&3));
assert_eq!(iter.peek(), Some(&&3));

assert_eq!(iter.next(), Some(&3));

// After the iterator is finished, so is `peek()`
assert_eq!(iter.peek(), None);
assert_eq!(iter.next(), None);

Trait Implementations

impl<I: Clone + Iterator> Clone for Peekable<I> where
    I::Item: Clone

impl<I: Debug + Iterator> Debug for Peekable<I> where
    I::Item: Debug

impl<I> DoubleEndedIterator for Peekable<I> where
    I: DoubleEndedIterator

impl<I: ExactSizeIterator> ExactSizeIterator for Peekable<I>[src]

impl<I: FusedIterator> FusedIterator for Peekable<I>1.26.0[src]

impl<I: Iterator> Iterator for Peekable<I>[src]

type Item = I::Item

The type of the elements being iterated over.

Auto Trait Implementations

impl<I> Send for Peekable<I> where
    I: Send,
    <I as Iterator>::Item: Send

impl<I> Sync for Peekable<I> where
    I: Sync,
    <I as Iterator>::Item: Sync

impl<I> Unpin for Peekable<I> where
    I: Unpin,
    <I as Iterator>::Item: Unpin

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized

impl<T> Borrow<T> for T where
    T: ?Sized

impl<T> BorrowMut<T> for T where
    T: ?Sized

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.