Skip to content

Commit 65a6a82

Browse files
yoshuawuytsyoshuawuyts
committed
from/into stream
Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> update examples Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> impl collect Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> compiles! Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> layout base for collect into vec Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> fmt Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> progress Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> compiles! Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> define failing test Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> cargo fmt Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> stuck again Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> fix trait bounds! Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> cargo fmt Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> hide dyn fut impl Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> dyn ret for vec Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> cargo fmt Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> collect docs Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> remove macro from vec::from_stream Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> shorten collect trait bound Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com> Remove some Unpin and Send bounds Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com>
1 parent 8fe7347 commit 65a6a82

File tree

7 files changed

+163
-1
lines changed

7 files changed

+163
-1
lines changed

‎src/lib.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,4 +42,6 @@ pub mod stream;
4242
pub mod sync;
4343
pub mod task;
4444

45+
mod vec;
46+
4547
pub(crate) mod utils;

‎src/stream/from_stream.rs

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
use super::IntoStream;
2+
3+
use std::pin::Pin;
4+
5+
/// Conversion from a `Stream`.
6+
///
7+
/// By implementing `FromStream` for a type, you define how it will be created from a stream.
8+
/// This is common for types which describe a collection of some kind.
9+
///
10+
/// See also: [`IntoStream`].
11+
///
12+
/// [`IntoStream`]: trait.IntoStream.html
13+
pub trait FromStream<T> {
14+
/// Creates a value from a stream.
15+
///
16+
/// # Examples
17+
///
18+
/// Basic usage:
19+
///
20+
/// ```
21+
/// // use async_std::stream::FromStream;
22+
///
23+
/// // let _five_fives = async_std::stream::repeat(5).take(5);
24+
/// ```
25+
fn from_stream<'a, S: IntoStream<Item = T> + 'a>(
26+
stream: S,
27+
) -> Pin<Box<dyn core::future::Future<Output = Self> + 'a>>;
28+
}

‎src/stream/into_stream.rs

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
use futures_core::stream::Stream;
2+
3+
/// Conversion into a `Stream`.
4+
///
5+
/// By implementing `IntoIterator` for a type, you define how it will be
6+
/// converted to an iterator. This is common for types which describe a
7+
/// collection of some kind.
8+
///
9+
/// [`from_stream`]: #tymethod.from_stream
10+
/// [`Stream`]: trait.Stream.html
11+
/// [`collect`]: trait.Stream.html#method.collect
12+
///
13+
/// See also: [`FromStream`].
14+
///
15+
/// [`FromStream`]: trait.FromStream.html
16+
pub trait IntoStream {
17+
/// The type of the elements being iterated over.
18+
type Item;
19+
20+
/// Which kind of stream are we turning this into?
21+
type IntoStream: Stream<Item = Self::Item>;
22+
23+
/// Creates a stream from a value.
24+
fn into_stream(self) -> Self::IntoStream;
25+
}
26+
27+
impl<I: Stream> IntoStream for I {
28+
type Item = I::Item;
29+
type IntoStream = I;
30+
31+
#[inline]
32+
fn into_stream(self) -> I {
33+
self
34+
}
35+
}

‎src/stream/mod.rs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,15 @@
2222
//! ```
2323
2424
pub use empty::{empty, Empty};
25+
pub use from_stream::FromStream;
26+
pub use into_stream::IntoStream;
2527
pub use once::{once, Once};
2628
pub use repeat::{repeat, Repeat};
2729
pub use stream::{Stream, Take};
2830

2931
mod empty;
32+
mod from_stream;
33+
mod into_stream;
3034
mod once;
3135
mod repeat;
3236
mod stream;

‎src/stream/stream/mod.rs

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ use min_by::MinByFuture;
4242
use next::NextFuture;
4343
use nth::NthFuture;
4444

45+
use super::from_stream::FromStream;
46+
use crate::future::Future;
47+
use crate::task::{Context, Poll};
4548
use std::cmp::Ordering;
4649
use std::marker::PhantomData;
4750
use std::pin::Pin;
@@ -72,6 +75,21 @@ cfg_if! {
7275
}
7376
}
7477

78+
cfg_if! {
79+
if #[cfg(feature = "docs")] {
80+
#[doc(hidden)]
81+
pub struct DynFuture<'a, T>(std::marker::PhantomData<&'a T>);
82+
83+
macro_rules! dyn_ret {
84+
($a:lifetime, $o:ty) => (DynFuture<$a, $o>);
85+
}
86+
} else {
87+
macro_rules! dyn_ret {
88+
($a:lifetime, $o:ty) => (Pin<Box<dyn core::future::Future<Output = $o> + 'a>>)
89+
}
90+
}
91+
}
92+
7593
/// An asynchronous stream of values.
7694
///
7795
/// This trait is an async version of [`std::iter::Iterator`].
@@ -462,7 +480,6 @@ pub trait Stream {
462480
///
463481
/// Basic usage:
464482
///
465-
/// ```
466483
/// # fn main() { async_std::task::block_on(async {
467484
/// #
468485
/// use async_std::prelude::*;
@@ -501,6 +518,48 @@ pub trait Stream {
501518
f,
502519
}
503520
}
521+
522+
/// Transforms a stream into a collection.
523+
///
524+
/// `collect()` can take anything streamable, and turn it into a relevant
525+
/// collection. This is one of the more powerful methods in the async
526+
/// standard library, used in a variety of contexts.
527+
///
528+
/// The most basic pattern in which `collect()` is used is to turn one
529+
/// collection into another. You take a collection, call [`stream`] on it,
530+
/// do a bunch of transformations, and then `collect()` at the end.
531+
///
532+
/// Because `collect()` is so general, it can cause problems with type
533+
/// inference. As such, `collect()` is one of the few times you'll see
534+
/// the syntax affectionately known as the 'turbofish': `::<>`. This
535+
/// helps the inference algorithm understand specifically which collection
536+
/// you're trying to collect into.
537+
///
538+
/// # Examples
539+
///
540+
/// ```
541+
/// # fn main() { async_std::task::block_on(async {
542+
/// #
543+
/// use async_std::prelude::*;
544+
/// use async_std::stream;
545+
///
546+
/// let s = stream::repeat(9u8).take(3);
547+
/// let buf: Vec<u8> = s.collect().await;
548+
///
549+
/// assert_eq!(buf, vec![9; 3]);
550+
/// #
551+
/// # }) }
552+
/// ```
553+
///
554+
/// [`stream`]: trait.Stream.html#tymethod.next
555+
#[must_use = "if you really need to exhaust the iterator, consider `.for_each(drop)` instead (TODO)"]
556+
fn collect<'a, B>(self) -> dyn_ret!('a, B)
557+
where
558+
Self: futures_core::stream::Stream + Sized + 'a,
559+
B: FromStream<<Self as futures_core::stream::Stream>::Item>,
560+
{
561+
FromStream::from_stream(self)
562+
}
504563
}
505564

506565
impl<T: futures_core::stream::Stream + Unpin + ?Sized> Stream for T {

‎src/vec/from_stream.rs

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
use crate::stream::{FromStream, IntoStream, Stream};
2+
3+
use std::pin::Pin;
4+
5+
impl<T> FromStream<T> for Vec<T> {
6+
#[inline]
7+
fn from_stream<'a, S: IntoStream<Item = T>>(
8+
stream: S,
9+
) -> Pin<Box<dyn core::future::Future<Output = Self> + 'a>>
10+
where
11+
<S as IntoStream>::IntoStream: 'a,
12+
{
13+
let stream = stream.into_stream();
14+
15+
Pin::from(Box::new(async move {
16+
pin_utils::pin_mut!(stream);
17+
18+
let mut out = vec![];
19+
while let Some(item) = stream.next().await {
20+
out.push(item);
21+
}
22+
out
23+
}))
24+
}
25+
}

‎src/vec/mod.rs

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
//! The Rust core allocation and collections library
2+
//!
3+
//! This library provides smart pointers and collections for managing
4+
//! heap-allocated values.
5+
6+
mod from_stream;
7+
8+
#[doc(inline)]
9+
pub use std::vec::Vec;

0 commit comments

Comments
 (0)