Struct futures_util::stream::Peekable

source · [−]
pub struct Peekable<St: Stream> { /* private fields */ }
Expand description

A Stream that implements a peek method.

The peek method can be used to retrieve a reference to the next Stream::Item if available. A subsequent call to poll will return the owned item.

Implementations

Acquires a reference to the underlying sink or stream that this combinator is pulling from.

Acquires a mutable reference to the underlying sink or stream that this combinator is pulling from.

Note that care must be taken to avoid tampering with the state of the sink or stream which may otherwise confuse this combinator.

Acquires a pinned mutable reference to the underlying sink or stream that this combinator is pulling from.

Note that care must be taken to avoid tampering with the state of the sink or stream which may otherwise confuse this combinator.

Consumes this combinator, returning the underlying sink or stream.

Note that this may discard intermediate state of this combinator, so care should be taken to avoid losing resources when this is called.

Produces a future which retrieves a reference to the next item in the stream, or None if the underlying stream terminates.

Peek retrieves a reference to the next item in the stream.

This method polls the underlying stream and return either a reference to the next item if the stream is ready or passes through any errors.

Produces a future which retrieves a mutable reference to the next item in the stream, or None if the underlying stream terminates.

Examples
use futures::stream::{self, StreamExt};
use futures::pin_mut;

let stream = stream::iter(vec![1, 2, 3]).peekable();
pin_mut!(stream);

assert_eq!(stream.as_mut().peek_mut().await, Some(&mut 1));
assert_eq!(stream.as_mut().next().await, Some(1));

// Peek into the stream and modify the value which will be returned next
if let Some(p) = stream.as_mut().peek_mut().await {
    if *p == 2 {
        *p = 5;
    }
}

assert_eq!(stream.collect::<Vec<_>>().await, vec![5, 3]);

Peek retrieves a mutable reference to the next item in the stream.

Creates a future which will consume and return the next value of this stream if a condition is true.

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

Examples

Consume a number if it’s equal to 0.

use futures::stream::{self, StreamExt};
use futures::pin_mut;

let stream = stream::iter(0..5).peekable();
pin_mut!(stream);
// The first item of the stream is 0; consume it.
assert_eq!(stream.as_mut().next_if(|&x| x == 0).await, Some(0));
// The next item returned is now 1, so `consume` will return `false`.
assert_eq!(stream.as_mut().next_if(|&x| x == 0).await, None);
// `next_if` saves the value of the next item if it was not equal to `expected`.
assert_eq!(stream.next().await, Some(1));

Consume any number less than 10.

use futures::stream::{self, StreamExt};
use futures::pin_mut;

let stream = stream::iter(1..20).peekable();
pin_mut!(stream);
// Consume all numbers less than 10
while stream.as_mut().next_if(|&x| x < 10).await.is_some() {}
// The next value returned will be 10
assert_eq!(stream.next().await, Some(10));

Creates a future which will consume and return the next item if it is equal to expected.

Example

Consume a number if it’s equal to 0.

use futures::stream::{self, StreamExt};
use futures::pin_mut;

let stream = stream::iter(0..5).peekable();
pin_mut!(stream);
// The first item of the stream is 0; consume it.
assert_eq!(stream.as_mut().next_if_eq(&0).await, Some(0));
// The next item returned is now 1, so `consume` will return `false`.
assert_eq!(stream.as_mut().next_if_eq(&0).await, None);
// `next_if_eq` saves the value of the next item if it was not equal to `expected`.
assert_eq!(stream.next().await, Some(1));

Trait Implementations

Formats the value using the given formatter. Read more
Returns true if the stream should no longer be polled.
Values yielded by the stream.
Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted. Read more
Returns the bounds on the remaining length of the stream. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
The type of successful values yielded by this future
The type of failures yielded by this future
Poll this TryStream as if it were a Stream. Read more