Function futures::stream::unfold

pub fn unfold<T, F, Fut, It>(init: T, f: F) -> Unfold<T, F, Fut> where
    F: FnMut(T) -> Option<Fut>,
    Fut: IntoFuture<Item = (It, T)>, 

Creates a Stream from a seed and a closure returning a Future.

This function is the dual for the Stream::fold() adapter: while Stream::fold() reduces a Stream to one single value, unfold() creates a Stream from a seed value.

unfold() will call the provided closure with the provided seed, then wait for the returned Future to complete with (a, b). It will then yield the value a, and use b as the next internal state.

If the closure returns None instead of Some(Future), then the unfold() will stop producing items and return Ok(Async::Ready(None)) in future calls to poll().

In case of error generated by the returned Future, the error will be returned by the Stream. The Stream will then yield Ok(Async::Ready(None)) in future calls to poll().

This function can typically be used when wanting to go from the “world of futures” to the “world of streams”: the provided closure can build a Future using other library functions working on futures, and unfold() will turn it into a Stream by repeating the operation.

Example

use futures::stream::{self, Stream};
use futures::future::{self, Future};

let mut stream = stream::unfold(0, |state| {
    if state <= 2 {
        let next_state = state + 1;
        let yielded = state  * 2;
        let fut = future::ok::<_, u32>((yielded, next_state));
        Some(fut)
    } else {
        None
    }
});

let result = stream.collect().wait();
assert_eq!(result, Ok(vec![0, 2, 4]));