lending_stream/
lib.rs

1//! A lending version of Stream
2//!
3//! # Examples
4//!
5//! ```
6//! // tbi
7//! ```
8
9// #![forbid(unsafe_code)]
10#![deny(missing_debug_implementations, nonstandard_style)]
11#![warn(missing_docs, unreachable_pub)]
12
13mod lend;
14mod lend_mut;
15mod next;
16
17use std::task::{Context, Poll};
18
19pub use lend::Lend;
20pub use lend_mut::LendMut;
21pub use next::Next;
22
23use futures_core::Stream;
24
25/// The lending-stream prelude
26pub mod prelude {
27    pub use super::LendingStream;
28    pub use super::StreamExt as _;
29}
30
31/// An extension for the `Stream` trait
32pub trait StreamExt: Stream {
33    /// Creates a stream which yields a reference to `self` as well as
34    /// the next value.
35    fn lend(self) -> Lend<Self>
36    where
37        Self: Sized + Unpin,
38    {
39        Lend::new(self)
40    }
41    /// Creates a stream which yields a mutable reference to `self` as well
42    /// as the next value.
43    fn lend_mut(self) -> LendMut<Self>
44    where
45        Self: Sized + Unpin,
46    {
47        LendMut::new(self)
48    }
49}
50
51impl<S: Stream> StreamExt for S {}
52
53/// An interface for dealing with iterators which borrow from `Self`
54
55#[must_use = "iterators are lazy and do nothing unless consumed"]
56pub trait LendingStream {
57    /// The type of the elements being iterated over.
58    type Item<'a>
59    where
60        Self: 'a;
61
62    /// Attempt to pull out the next value of this stream, registering
63    /// the current task for wakeup if the value is not yet available, and
64    /// returning None if the async iterator is exhausted.
65    fn poll_next(&mut self, cx: &mut Context<'_>) -> Poll<Option<Self::Item<'_>>>;
66
67    /// Returns the bounds on the remaining length of the Stream.
68    fn size_hint(&self) -> (usize, Option<usize>) {
69        (0, None)
70    }
71
72    /// Retrieves the next item in the stream.
73    ///
74    /// Returns [`None`] when iteration is finished. Stream implementations may choose to or not to
75    /// resume iteration after that.
76    fn next(&mut self) -> Next<'_, Self>
77    where
78        Self: Unpin,
79    {
80        Next::new(self)
81    }
82}
lending_stream/lib.rs

lending_stream/
lib.rs
