async_std/stream/
from_stream.rs

1use std::future::Future;
2use std::pin::Pin;
3
4use crate::stream::IntoStream;
5
6/// Conversion from a `Stream`.
7///
8/// By implementing `FromStream` for a type, you define how it will be created from a stream.
9/// This is common for types which describe a collection of some kind.
10///
11/// See also: [`IntoStream`].
12///
13/// # Examples
14///
15/// Basic usage:
16///
17/// ```
18/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
19/// #
20/// use async_std::prelude::*;
21/// use async_std::stream::{self, FromStream};
22///
23/// let five_fives = stream::repeat(5).take(5);
24///
25/// let v = Vec::from_stream(five_fives).await;
26///
27/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
28/// #
29/// # Ok(()) }) }
30/// ```
31///
32/// Using `collect` to  implicitly use `FromStream`
33///
34/// ```
35/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
36/// #
37/// use async_std::prelude::*;
38/// use async_std::stream;
39/// let five_fives = stream::repeat(5).take(5);
40///
41/// let v: Vec<i32> = five_fives.collect().await;
42///
43/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
44/// #
45/// # Ok(()) }) }
46/// ```
47///
48/// Implementing `FromStream` for your type:
49///
50/// ```
51/// use async_std::prelude::*;
52/// use async_std::stream::{self, FromStream, IntoStream};
53/// use std::pin::Pin;
54///
55/// // A sample collection, that's just a wrapper over Vec<T>
56/// #[derive(Debug)]
57/// struct MyCollection(Vec<i32>);
58///
59/// // Let's give it some methods so we can create one and add things
60/// // to it.
61/// impl MyCollection {
62///     fn new() -> MyCollection {
63///         MyCollection(Vec::new())
64///     }
65///
66///     fn add(&mut self, elem: i32) {
67///         self.0.push(elem);
68///     }
69/// }
70///
71/// // and we'll implement FromIterator
72/// impl FromStream<i32> for MyCollection {
73///     fn from_stream<'a, S: IntoStream<Item = i32> + 'a>(
74///         stream: S,
75///     ) -> Pin<Box<dyn Future<Output = Self> + 'a>> {
76///         let stream = stream.into_stream();
77///
78///         Box::pin(async move {
79///             let mut c = MyCollection::new();
80///
81///             let mut v = vec![];
82///             stream::extend(&mut v, stream).await;
83///
84///             for i in v {
85///                 c.add(i);
86///             }
87///             c
88///         })
89///     }
90/// }
91///
92/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
93/// #
94/// // Now we can make a new stream...
95/// let stream = stream::repeat(5).take(5);
96///
97/// // ...and make a MyCollection out of it
98/// let c = MyCollection::from_stream(stream).await;
99///
100/// assert_eq!(c.0, vec![5, 5, 5, 5, 5]);
101///
102/// // collect works too!
103///
104/// let stream = stream::repeat(5).take(5);
105/// let c: MyCollection = stream.collect().await;
106///
107/// assert_eq!(c.0, vec![5, 5, 5, 5, 5]);
108/// #
109/// # Ok(()) }) }
110///```
111///
112/// [`IntoStream`]: trait.IntoStream.html
113#[cfg(feature = "unstable")]
114#[cfg_attr(feature = "docs", doc(cfg(unstable)))]
115pub trait FromStream<T> {
116    /// Creates a value from a stream.
117    ///
118    /// # Examples
119    ///
120    /// Basic usage:
121    ///
122    /// ```
123    /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
124    /// #
125    /// use async_std::prelude::*;
126    /// use async_std::stream::{self, FromStream};
127    ///
128    /// let five_fives = stream::repeat(5).take(5);
129    ///
130    /// let v = Vec::from_stream(five_fives).await;
131    ///
132    /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
133    /// #
134    /// # Ok(()) }) }
135    /// ```
136    fn from_stream<'a, S: IntoStream<Item = T> + 'a>(
137        stream: S,
138    ) -> Pin<Box<dyn Future<Output = Self> + 'a>>;
139}
async_std/stream/from_stream.rs

async_std/stream/
from_stream.rs
