W3cubDocs

/Rust

Struct std::iter::Peekable

#[must_use = "iterators are lazy and do nothing unless consumed"]pub struct Peekable<I> where    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.

Implementations

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

pub fn peek(&mut self) -> Option<&<I as Iterator>::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.

Examples

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);

pub fn next_if(
    &mut self,
    func: impl FnOnce(&<I as Iterator>::Item) -> bool
) -> Option<<I as Iterator>::Item>
[src]

🔬 This is a nightly-only experimental API. (peekable_next_if #72480)

Consume the next value of this iterator if a condition is true.

If func returns true for the next value of this iterator, consume and return it. Otherwise, return None.

Examples

Consume a number if it's equal to 0.

#![feature(peekable_next_if)]
let mut iter = (0..5).peekable();
// The first item of the iterator is 0; consume it.
assert_eq!(iter.next_if(|&x| x == 0), Some(0));
// The next item returned is now 1, so `consume` will return `false`.
assert_eq!(iter.next_if(|&x| x == 0), None);
// `next_if` saves the value of the next item if it was not equal to `expected`.
assert_eq!(iter.next(), Some(1));

Consume any number less than 10.

#![feature(peekable_next_if)]
let mut iter = (1..20).peekable();
// Consume all numbers less than 10
while iter.next_if(|&x| x < 10).is_some() {}
// The next value returned will be 10
assert_eq!(iter.next(), Some(10));

pub fn next_if_eq<R>(&mut self, expected: &R) -> Option<<I as Iterator>::Item> where
    R: ?Sized,
    <I as Iterator>::Item: PartialEq<R>, 
[src]

🔬 This is a nightly-only experimental API. (peekable_next_if #72480)

Consume the next item if it is equal to expected.

Example

Consume a number if it's equal to 0.

#![feature(peekable_next_if)]
let mut iter = (0..5).peekable();
// The first item of the iterator is 0; consume it.
assert_eq!(iter.next_if_eq(&0), Some(0));
// The next item returned is now 1, so `consume` will return `false`.
assert_eq!(iter.next_if_eq(&0), None);
// `next_if_eq` saves the value of the next item if it was not equal to `expected`.
assert_eq!(iter.next(), Some(1));

Trait Implementations

impl<I> Clone for Peekable<I> where
    I: Clone + Iterator,
    <I as Iterator>::Item: Clone
[src]

impl<I> Debug for Peekable<I> where
    I: Iterator + Debug,
    <I as Iterator>::Item: Debug
[src]

impl<I> DoubleEndedIterator for Peekable<I> where
    I: DoubleEndedIterator
[src]1.38.0

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

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

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

type Item = <I as Iterator>::Item

The type of the elements being iterated over.

Auto Trait Implementations

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

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

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

Blanket Implementations

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

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

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

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<I> IntoIterator for I where
    I: Iterator
[src]

type Item = <I as Iterator>::Item

The type of the elements being iterated over.

type IntoIter = I

Which kind of iterator are we turning this into?

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

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

The type returned in the event of a conversion error.

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/iter/struct.Peekable.html