Coverage Report

Created: 2024-05-20 06:38

/rust/registry/src/index.crates.io-6f17d22bba15001f/futures-util-0.3.28/src/stream/unfold.rs
Line
Count
Source (jump to first uncovered line)
1
use super::assert_stream;
2
use crate::unfold_state::UnfoldState;
3
use core::fmt;
4
use core::pin::Pin;
5
use futures_core::future::Future;
6
use futures_core::ready;
7
use futures_core::stream::{FusedStream, Stream};
8
use futures_core::task::{Context, Poll};
9
use pin_project_lite::pin_project;
10
11
/// Creates a `Stream` from a seed and a closure returning a `Future`.
12
///
13
/// This function is the dual for the `Stream::fold()` adapter: while
14
/// `Stream::fold()` reduces a `Stream` to one single value, `unfold()` creates a
15
/// `Stream` from a seed value.
16
///
17
/// `unfold()` will call the provided closure with the provided seed, then wait
18
/// for the returned `Future` to complete with `(a, b)`. It will then yield the
19
/// value `a`, and use `b` as the next internal state.
20
///
21
/// If the closure returns `None` instead of `Some(Future)`, then the `unfold()`
22
/// will stop producing items and return `Poll::Ready(None)` in future
23
/// calls to `poll()`.
24
///
25
/// This function can typically be used when wanting to go from the "world of
26
/// futures" to the "world of streams": the provided closure can build a
27
/// `Future` using other library functions working on futures, and `unfold()`
28
/// will turn it into a `Stream` by repeating the operation.
29
///
30
/// # Example
31
///
32
/// ```
33
/// # futures::executor::block_on(async {
34
/// use futures::stream::{self, StreamExt};
35
///
36
/// let stream = stream::unfold(0, |state| async move {
37
///     if state <= 2 {
38
///         let next_state = state + 1;
39
///         let yielded = state  * 2;
40
///         Some((yielded, next_state))
41
///     } else {
42
///         None
43
///     }
44
/// });
45
///
46
/// let result = stream.collect::<Vec<i32>>().await;
47
/// assert_eq!(result, vec![0, 2, 4]);
48
/// # });
49
/// ```
50
0
pub fn unfold<T, F, Fut, Item>(init: T, f: F) -> Unfold<T, F, Fut>
51
0
where
52
0
    F: FnMut(T) -> Fut,
53
0
    Fut: Future<Output = Option<(Item, T)>>,
54
0
{
55
0
    assert_stream::<Item, _>(Unfold { f, state: UnfoldState::Value { value: init } })
56
0
}
57
58
pin_project! {
59
    /// Stream for the [`unfold`] function.
60
    #[must_use = "streams do nothing unless polled"]
61
    pub struct Unfold<T, F, Fut> {
62
        f: F,
63
        #[pin]
64
        state: UnfoldState<T, Fut>,
65
    }
66
}
67
68
impl<T, F, Fut> fmt::Debug for Unfold<T, F, Fut>
69
where
70
    T: fmt::Debug,
71
    Fut: fmt::Debug,
72
{
73
0
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
74
0
        f.debug_struct("Unfold").field("state", &self.state).finish()
75
0
    }
76
}
77
78
impl<T, F, Fut, Item> FusedStream for Unfold<T, F, Fut>
79
where
80
    F: FnMut(T) -> Fut,
81
    Fut: Future<Output = Option<(Item, T)>>,
82
{
83
0
    fn is_terminated(&self) -> bool {
84
0
        if let UnfoldState::Empty = self.state {
85
0
            true
86
        } else {
87
0
            false
88
        }
89
0
    }
90
}
91
92
impl<T, F, Fut, Item> Stream for Unfold<T, F, Fut>
93
where
94
    F: FnMut(T) -> Fut,
95
    Fut: Future<Output = Option<(Item, T)>>,
96
{
97
    type Item = Item;
98
99
0
    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
100
0
        let mut this = self.project();
101
102
0
        if let Some(state) = this.state.as_mut().take_value() {
103
0
            this.state.set(UnfoldState::Future { future: (this.f)(state) });
104
0
        }
105
106
0
        let step = match this.state.as_mut().project_future() {
107
0
            Some(fut) => ready!(fut.poll(cx)),
108
0
            None => panic!("Unfold must not be polled after it returned `Poll::Ready(None)`"),
109
        };
110
111
0
        if let Some((item, next_state)) = step {
112
0
            this.state.set(UnfoldState::Value { value: next_state });
113
0
            Poll::Ready(Some(item))
114
        } else {
115
0
            this.state.set(UnfoldState::Empty);
116
0
            Poll::Ready(None)
117
        }
118
0
    }
119
}