third_party/rust_crates/vendor/async-std/src/stream/mod.rs - fuchsia - Git at Google

 //! Composable asynchronous iteration.
 //!
 //! This module is an async version of [`std::iter`].
 //!
 //! If you've found yourself with an asynchronous collection of some kind,
 //! and needed to perform an operation on the elements of said collection,
 //! you'll quickly run into 'streams'. Streams are heavily used in idiomatic
 //! asynchronous Rust code, so it's worth becoming familiar with them.
 //!
 //! Before explaining more, let's talk about how this module is structured:
 //!
 //! # Organization
 //!
 //! This module is largely organized by type:
 //!
 //! * [Traits] are the core portion: these traits define what kind of streams
 //!   exist and what you can do with them. The methods of these traits are worth
 //!   putting some extra study time into.
 //! * [Functions] provide some helpful ways to create some basic streams.
 //! * [Structs] are often the return types of the various methods on this
 //!   module's traits. You'll usually want to look at the method that creates
 //!   the `struct`, rather than the `struct` itself. For more detail about why,
 //!   see '[Implementing Stream](#implementing-stream)'.
 //!
 //! [Traits]: #traits
 //! [Functions]: #functions
 //! [Structs]: #structs
 //!
 //! That's it! Let's dig into streams.
 //!
 //! # Stream
 //!
 //! The heart and soul of this module is the [`Stream`] trait. The core of
 //! [`Stream`] looks like this:
 //!
 //! ```
 //! # use async_std::task::{Context, Poll};
 //! # use std::pin::Pin;
 //! trait Stream {
 //!     type Item;
 //!     fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
 //! }
 //! ```
 //!
 //! A stream has a method, [`next`], which when called, returns an
 //! [`Poll`]<[`Option`]`<Item>>`. [`next`] will return `Ready(Some(Item))`
 //! as long as there are elements, and once they've all been exhausted, will
 //! return `None` to indicate that iteration is finished. If we're waiting on
 //! something asynchronous to resolve `Pending` is returned.
 //!
 //! Individual streams may choose to resume iteration, and so calling
 //! [`next`] again may or may not eventually start returning `Ready(Some(Item))`
 //! again at some point.
 //!
 //! [`Stream`]'s full definition includes a number of other methods as well,
 //! but they are default methods, built on top of [`next`], and so you get
 //! them for free.
 //!
 //! Streams are also composable, and it's common to chain them together to do
 //! more complex forms of processing. See the [Adapters](#adapters) section
 //! below for more details.
 //!
 //! [`Poll`]: ../task/enum.Poll.html
 //! [`Stream`]: trait.Stream.html
 //! [`next`]: trait.Stream.html#tymethod.next
 //! [`Option`]: ../../std/option/enum.Option.html
 //!
 //! # The three forms of streaming
 //!
 //! There are three common methods which can create streams from a collection:
 //!
 //! * `stream()`, which iterates over `&T`.
 //! * `stream_mut()`, which iterates over `&mut T`.
 //! * `into_stream()`, which iterates over `T`.
 //!
 //! Various things in async-std may implement one or more of the
 //! three, where appropriate.
 //!
 //! # Implementing Stream
 //!
 //! Creating a stream of your own involves two steps: creating a `struct` to
 //! hold the stream's state, and then `impl`ementing [`Stream`] for that
 //! `struct`. This is why there are so many `struct`s in this module: there is
 //! one for each stream and iterator adapter.
 //!
 //! Let's make a stream named `Counter` which counts from `1` to `5`:
 //!
 //! ```
 //! # use async_std::prelude::*;
 //! # use async_std::task::{Context, Poll};
 //! # use std::pin::Pin;
 //! // First, the struct:
 //!
 //! /// A stream which counts from one to five
 //! struct Counter {
 //!     count: usize,
 //! }
 //!
 //! // we want our count to start at one, so let's add a new() method to help.
 //! // This isn't strictly necessary, but is convenient. Note that we start
 //! // `count` at zero, we'll see why in `next()`'s implementation below.
 //! impl Counter {
 //!     fn new() -> Counter {
 //!         Counter { count: 0 }
 //!     }
 //! }
 //!
 //! // Then, we implement `Stream` for our `Counter`:
 //!
 //! impl Stream for Counter {
 //!     // we will be counting with usize
 //!     type Item = usize;
 //!
 //!     // poll_next() is the only required method
 //!     fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
 //!         // Increment our count. This is why we started at zero.
 //!         self.count += 1;
 //!
 //!         // Check to see if we've finished counting or not.
 //!         if self.count < 6 {
 //!             Poll::Ready(Some(self.count))
 //!         } else {
 //!             Poll::Ready(None)
 //!         }
 //!     }
 //! }
 //!
 //! // And now we can use it!
 //! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
 //! #
 //! let mut counter = Counter::new();
 //!
 //! let x = counter.next().await.unwrap();
 //! println!("{}", x);
 //!
 //! let x = counter.next().await.unwrap();
 //! println!("{}", x);
 //!
 //! let x = counter.next().await.unwrap();
 //! println!("{}", x);
 //!
 //! let x = counter.next().await.unwrap();
 //! println!("{}", x);
 //!
 //! let x = counter.next().await.unwrap();
 //! println!("{}", x);
 //! #
 //! # Ok(()) }) }
 //! ```
 //!
 //! This will print `1` through `5`, each on their own line.
 //!
 //! Calling `next().await` this way gets repetitive. Rust has a construct which
 //! can call `next()` on your stream, until it reaches `None`. Let's go over
 //! that next.
 //!
 //! # while let Loops and IntoStream
 //!
 //! Rust's `while let` loop syntax is an idiomatic way to iterate over streams. Here's a basic
 //! example of `while let`:
 //!
 //! ```
 //! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
 //! #
 //! # use async_std::prelude::*;
 //! # use async_std::stream;
 //! let mut values = stream::repeat(1u8).take(5);
 //!
 //! while let Some(x) = values.next().await {
 //!     println!("{}", x);
 //! }
 //! #
 //! # Ok(()) }) }
 //! ```
 //!
 //! This will print the numbers one through five, each on their own line. But
 //! you'll notice something here: we never called anything on our vector to
 //! produce a stream. What gives?
 //!
 //! There's a trait in the standard library for converting something into an
 //! stream: [`IntoStream`]. This trait has one method, [`into_stream`],
 //! which converts the thing implementing [`IntoStream`] into a stream.
 //!
 //! Unlike `std::iter::IntoIterator`, `IntoStream` does not have compiler
 //! support yet. This means that automatic conversions like with `for` loops
 //! doesn't occur yet, and `into_stream` will always have to be called manually.
 //!
 //! [`IntoStream`]: trait.IntoStream.html
 //! [`into_stream`]: trait.IntoStream.html#tymethod.into_stream
 //!
 //! # Adapters
 //!
 //! Functions which take an [`Stream`] and return another [`Stream`] are
 //! often called 'stream adapters', as they are a form of the 'adapter
 //! pattern'.
 //!
 //! Common stream adapters include [`map`], [`take`], and [`filter`].
 //! For more, see their documentation.
 //!
 //! [`map`]: trait.Stream.html#method.map
 //! [`take`]: trait.Stream.html#method.take
 //! [`filter`]: trait.Stream.html#method.filter
 //!
 //! # Laziness
 //!
 //! Streams (and stream [adapters](#adapters)) are *lazy*. This means that
 //! just creating a stream doesn't _do_ a whole lot. Nothing really happens
 //! until you call [`next`]. This is sometimes a source of confusion when
 //! creating a stream solely for its side effects. For example, the [`map`]
 //! method calls a closure on each element it iterates over:
 //!
 //! ```
 //! # #![allow(unused_must_use)]
 //! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
 //! #
 //! # use async_std::prelude::*;
 //! # use async_std::stream;
 //! let v = stream::repeat(1u8).take(5);
 //! v.map(|x| println!("{}", x));
 //! #
 //! # Ok(()) }) }
 //! ```
 //!
 //! This will not print any values, as we only created a stream, rather than
 //! using it. The compiler will warn us about this kind of behavior:
 //!
 //! ```text
 //! warning: unused result that must be used: streams are lazy and
 //! do nothing unless consumed
 //! ```
 //!
 //! The idiomatic way to write a [`map`] for its side effects is to use a
 //! `while let` loop instead:
 //!
 //! ```
 //! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
 //! #
 //! # use async_std::prelude::*;
 //! # use async_std::stream;
 //! let mut v = stream::repeat(1u8).take(5);
 //!
 //! while let Some(x) = &v.next().await {
 //!     println!("{}", x);
 //! }
 //! #
 //! # Ok(()) }) }
 //! ```
 //!
 //! [`map`]: trait.Stream.html#method.map
 //!
 //! The two most common ways to evaluate a stream are to use a `while let` loop
 //! like this, or using the [`collect`] method to produce a new collection.
 //!
 //! [`collect`]: trait.Stream.html#method.collect
 //!
 //! # Infinity
 //!
 //! Streams do not have to be finite. As an example, an repeat stream is
 //! an infinite stream:
 //!
 //! ```
 //! # use async_std::stream;
 //! let numbers = stream::repeat(1u8);
 //! ```
 //!
 //! It is common to use the [`take`] stream adapter to turn an infinite
 //! stream into a finite one:
 //!
 //! ```
 //! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
 //! #
 //! # use async_std::prelude::*;
 //! # use async_std::stream;
 //! let numbers = stream::repeat(1u8);
 //! let mut five_numbers = numbers.take(5);
 //!
 //! while let Some(number) = five_numbers.next().await {
 //!     println!("{}", number);
 //! }
 //! #
 //! # Ok(()) }) }
 //! ```
 //!
 //! This will print the numbers `0` through `4`, each on their own line.
 //!
 //! Bear in mind that methods on infinite streams, even those for which a
 //! result can be determined mathematically in finite time, may not terminate.
 //! Specifically, methods such as [`min`], which in the general case require
 //! traversing every element in the stream, are likely not to return
 //! successfully for any infinite streams.
 //!
 //! ```ignore
 //! let ones = async_std::stream::repeat(1);
 //! let least = ones.min().await.unwrap(); // Oh no! An infinite loop!
 //! // `ones.min()` causes an infinite loop, so we won't reach this point!
 //! println!("The smallest number one is {}.", least);
 //! ```
 //!
 //! [`std::iter`]: https://doc.rust-lang.org/std/iter/index.html
 //! [`take`]: trait.Stream.html#method.take
 //! [`min`]: trait.Stream.html#method.min

 pub use empty::{empty, Empty};
 pub use from_fn::{from_fn, FromFn};
 pub use from_iter::{from_iter, FromIter};
 pub use once::{once, Once};
 pub use repeat::{repeat, Repeat};
 pub use repeat_with::{repeat_with, RepeatWith};
 pub use stream::*;

 pub(crate) mod stream;

 mod empty;
 mod from_fn;
 mod from_iter;
 mod once;
 mod repeat;
 mod repeat_with;

 cfg_unstable! {
     mod double_ended_stream;
     mod exact_size_stream;
     mod extend;
     mod from_stream;
     mod fused_stream;
     mod interval;
     mod into_stream;
     mod pending;
     mod product;
     mod successors;
     mod sum;

     pub use double_ended_stream::DoubleEndedStream;
     pub use exact_size_stream::ExactSizeStream;
     pub use extend::{extend, Extend};
     pub use from_stream::FromStream;
     pub use fused_stream::FusedStream;
     pub use interval::{interval, Interval};
     pub use into_stream::IntoStream;
     pub use pending::{pending, Pending};
     pub use product::Product;
     pub use stream::Merge;
     pub use successors::{successors, Successors};
     pub use sum::Sum;
 }
	//! Composable asynchronous iteration.
	//!
	//! This module is an async version of [`std::iter`].
	//!
	//! If you've found yourself with an asynchronous collection of some kind,
	//! and needed to perform an operation on the elements of said collection,
	//! you'll quickly run into 'streams'. Streams are heavily used in idiomatic
	//! asynchronous Rust code, so it's worth becoming familiar with them.
	//!
	//! Before explaining more, let's talk about how this module is structured:
	//!
	//! # Organization
	//!
	//! This module is largely organized by type:
	//!
	//! * [Traits] are the core portion: these traits define what kind of streams
	//! exist and what you can do with them. The methods of these traits are worth
	//! putting some extra study time into.
	//! * [Functions] provide some helpful ways to create some basic streams.
	//! * [Structs] are often the return types of the various methods on this
	//! module's traits. You'll usually want to look at the method that creates
	//! the `struct`, rather than the `struct` itself. For more detail about why,
	//! see '[Implementing Stream](#implementing-stream)'.
	//!
	//! [Traits]: #traits
	//! [Functions]: #functions
	//! [Structs]: #structs
	//!
	//! That's it! Let's dig into streams.
	//!
	//! # Stream
	//!
	//! The heart and soul of this module is the [`Stream`] trait. The core of
	//! [`Stream`] looks like this:
	//!
	//! ```
	//! # use async_std::task::{Context, Poll};
	//! # use std::pin::Pin;
	//! trait Stream {
	//! type Item;
	//! fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
	//! }
	//! ```
	//!
	//! A stream has a method, [`next`], which when called, returns an
	//! [`Poll`]<[`Option`]`<Item>>`. [`next`] will return `Ready(Some(Item))`
	//! as long as there are elements, and once they've all been exhausted, will
	//! return `None` to indicate that iteration is finished. If we're waiting on
	//! something asynchronous to resolve `Pending` is returned.
	//!
	//! Individual streams may choose to resume iteration, and so calling
	//! [`next`] again may or may not eventually start returning `Ready(Some(Item))`
	//! again at some point.
	//!
	//! [`Stream`]'s full definition includes a number of other methods as well,
	//! but they are default methods, built on top of [`next`], and so you get
	//! them for free.
	//!
	//! Streams are also composable, and it's common to chain them together to do
	//! more complex forms of processing. See the [Adapters](#adapters) section
	//! below for more details.
	//!
	//! [`Poll`]: ../task/enum.Poll.html
	//! [`Stream`]: trait.Stream.html
	//! [`next`]: trait.Stream.html#tymethod.next
	//! [`Option`]: ../../std/option/enum.Option.html
	//!
	//! # The three forms of streaming
	//!
	//! There are three common methods which can create streams from a collection:
	//!
	//! * `stream()`, which iterates over `&T`.
	//! * `stream_mut()`, which iterates over `&mut T`.
	//! * `into_stream()`, which iterates over `T`.
	//!
	//! Various things in async-std may implement one or more of the
	//! three, where appropriate.
	//!
	//! # Implementing Stream
	//!
	//! Creating a stream of your own involves two steps: creating a `struct` to
	//! hold the stream's state, and then `impl`ementing [`Stream`] for that
	//! `struct`. This is why there are so many `struct`s in this module: there is
	//! one for each stream and iterator adapter.
	//!
	//! Let's make a stream named `Counter` which counts from `1` to `5`:
	//!
	//! ```
	//! # use async_std::prelude::*;
	//! # use async_std::task::{Context, Poll};
	//! # use std::pin::Pin;
	//! // First, the struct:
	//!
	//! /// A stream which counts from one to five
	//! struct Counter {
	//! count: usize,
	//! }
	//!
	//! // we want our count to start at one, so let's add a new() method to help.
	//! // This isn't strictly necessary, but is convenient. Note that we start
	//! // `count` at zero, we'll see why in `next()`'s implementation below.
	//! impl Counter {
	//! fn new() -> Counter {
	//! Counter { count: 0 }
	//! }
	//! }
	//!
	//! // Then, we implement `Stream` for our `Counter`:
	//!
	//! impl Stream for Counter {
	//! // we will be counting with usize
	//! type Item = usize;
	//!
	//! // poll_next() is the only required method
	//! fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
	//! // Increment our count. This is why we started at zero.
	//! self.count += 1;
	//!
	//! // Check to see if we've finished counting or not.
	//! if self.count < 6 {
	//! Poll::Ready(Some(self.count))
	//! } else {
	//! Poll::Ready(None)
	//! }
	//! }
	//! }
	//!
	//! // And now we can use it!
	//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
	//! #
	//! let mut counter = Counter::new();
	//!
	//! let x = counter.next().await.unwrap();
	//! println!("{}", x);
	//!
	//! let x = counter.next().await.unwrap();
	//! println!("{}", x);
	//!
	//! let x = counter.next().await.unwrap();
	//! println!("{}", x);
	//!
	//! let x = counter.next().await.unwrap();
	//! println!("{}", x);
	//!
	//! let x = counter.next().await.unwrap();
	//! println!("{}", x);
	//! #
	//! # Ok(()) }) }
	//! ```
	//!
	//! This will print `1` through `5`, each on their own line.
	//!
	//! Calling `next().await` this way gets repetitive. Rust has a construct which
	//! can call `next()` on your stream, until it reaches `None`. Let's go over
	//! that next.
	//!
	//! # while let Loops and IntoStream
	//!
	//! Rust's `while let` loop syntax is an idiomatic way to iterate over streams. Here's a basic
	//! example of `while let`:
	//!
	//! ```
	//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
	//! #
	//! # use async_std::prelude::*;
	//! # use async_std::stream;
	//! let mut values = stream::repeat(1u8).take(5);
	//!
	//! while let Some(x) = values.next().await {
	//! println!("{}", x);
	//! }
	//! #
	//! # Ok(()) }) }
	//! ```
	//!
	//! This will print the numbers one through five, each on their own line. But
	//! you'll notice something here: we never called anything on our vector to
	//! produce a stream. What gives?
	//!
	//! There's a trait in the standard library for converting something into an
	//! stream: [`IntoStream`]. This trait has one method, [`into_stream`],
	//! which converts the thing implementing [`IntoStream`] into a stream.
	//!
	//! Unlike `std::iter::IntoIterator`, `IntoStream` does not have compiler
	//! support yet. This means that automatic conversions like with `for` loops
	//! doesn't occur yet, and `into_stream` will always have to be called manually.
	//!
	//! [`IntoStream`]: trait.IntoStream.html
	//! [`into_stream`]: trait.IntoStream.html#tymethod.into_stream
	//!
	//! # Adapters
	//!
	//! Functions which take an [`Stream`] and return another [`Stream`] are
	//! often called 'stream adapters', as they are a form of the 'adapter
	//! pattern'.
	//!
	//! Common stream adapters include [`map`], [`take`], and [`filter`].
	//! For more, see their documentation.
	//!
	//! [`map`]: trait.Stream.html#method.map
	//! [`take`]: trait.Stream.html#method.take
	//! [`filter`]: trait.Stream.html#method.filter
	//!
	//! # Laziness
	//!
	//! Streams (and stream [adapters](#adapters)) are lazy. This means that
	//! just creating a stream doesn't _do_ a whole lot. Nothing really happens
	//! until you call [`next`]. This is sometimes a source of confusion when
	//! creating a stream solely for its side effects. For example, the [`map`]
	//! method calls a closure on each element it iterates over:
	//!
	//! ```
	//! # #![allow(unused_must_use)]
	//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
	//! #
	//! # use async_std::prelude::*;
	//! # use async_std::stream;
	//! let v = stream::repeat(1u8).take(5);
	//! v.map(\|x\| println!("{}", x));
	//! #
	//! # Ok(()) }) }
	//! ```
	//!
	//! This will not print any values, as we only created a stream, rather than
	//! using it. The compiler will warn us about this kind of behavior:
	//!
	//! ```text
	//! warning: unused result that must be used: streams are lazy and
	//! do nothing unless consumed
	//! ```
	//!
	//! The idiomatic way to write a [`map`] for its side effects is to use a
	//! `while let` loop instead:
	//!
	//! ```
	//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
	//! #
	//! # use async_std::prelude::*;
	//! # use async_std::stream;
	//! let mut v = stream::repeat(1u8).take(5);
	//!
	//! while let Some(x) = &v.next().await {
	//! println!("{}", x);
	//! }
	//! #
	//! # Ok(()) }) }
	//! ```
	//!
	//! [`map`]: trait.Stream.html#method.map
	//!
	//! The two most common ways to evaluate a stream are to use a `while let` loop
	//! like this, or using the [`collect`] method to produce a new collection.
	//!
	//! [`collect`]: trait.Stream.html#method.collect
	//!
	//! # Infinity
	//!
	//! Streams do not have to be finite. As an example, an repeat stream is
	//! an infinite stream:
	//!
	//! ```
	//! # use async_std::stream;
	//! let numbers = stream::repeat(1u8);
	//! ```
	//!
	//! It is common to use the [`take`] stream adapter to turn an infinite
	//! stream into a finite one:
	//!
	//! ```
	//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
	//! #
	//! # use async_std::prelude::*;
	//! # use async_std::stream;
	//! let numbers = stream::repeat(1u8);
	//! let mut five_numbers = numbers.take(5);
	//!
	//! while let Some(number) = five_numbers.next().await {
	//! println!("{}", number);
	//! }
	//! #
	//! # Ok(()) }) }
	//! ```
	//!
	//! This will print the numbers `0` through `4`, each on their own line.
	//!
	//! Bear in mind that methods on infinite streams, even those for which a
	//! result can be determined mathematically in finite time, may not terminate.
	//! Specifically, methods such as [`min`], which in the general case require
	//! traversing every element in the stream, are likely not to return
	//! successfully for any infinite streams.
	//!
	//! ```ignore
	//! let ones = async_std::stream::repeat(1);
	//! let least = ones.min().await.unwrap(); // Oh no! An infinite loop!
	//! // `ones.min()` causes an infinite loop, so we won't reach this point!
	//! println!("The smallest number one is {}.", least);
	//! ```
	//!
	//! [`std::iter`]: https://doc.rust-lang.org/std/iter/index.html
	//! [`take`]: trait.Stream.html#method.take
	//! [`min`]: trait.Stream.html#method.min

	pub use empty::{empty, Empty};
	pub use from_fn::{from_fn, FromFn};
	pub use from_iter::{from_iter, FromIter};
	pub use once::{once, Once};
	pub use repeat::{repeat, Repeat};
	pub use repeat_with::{repeat_with, RepeatWith};
	pub use stream::*;

	pub(crate) mod stream;

	mod empty;
	mod from_fn;
	mod from_iter;
	mod once;
	mod repeat;
	mod repeat_with;

	cfg_unstable! {
	mod double_ended_stream;
	mod exact_size_stream;
	mod extend;
	mod from_stream;
	mod fused_stream;
	mod interval;
	mod into_stream;
	mod pending;
	mod product;
	mod successors;
	mod sum;

	pub use double_ended_stream::DoubleEndedStream;
	pub use exact_size_stream::ExactSizeStream;
	pub use extend::{extend, Extend};
	pub use from_stream::FromStream;
	pub use fused_stream::FusedStream;
	pub use interval::{interval, Interval};
	pub use into_stream::IntoStream;
	pub use pending::{pending, Pending};
	pub use product::Product;
	pub use stream::Merge;
	pub use successors::{successors, Successors};
	pub use sum::Sum;
	}