diff --git a/src/stream/fused_stream.rs b/src/stream/fused_stream.rs new file mode 100644 index 0000000..42e7e6f --- /dev/null +++ b/src/stream/fused_stream.rs @@ -0,0 +1,21 @@ +use crate::stream::Stream; + +/// A stream that always continues to yield `None` when exhausted. +/// +/// Calling next on a fused stream that has returned `None` once is guaranteed +/// to return [`None`] again. This trait should be implemented by all streams +/// that behave this way because it allows optimizing [`Stream::fuse`]. +/// +/// Note: In general, you should not use `FusedStream` in generic bounds if +/// you need a fused stream. Instead, you should just call [`Stream::fuse`] +/// on the stream. If the stream is already fused, the additional [`Fuse`] +/// wrapper will be a no-op with no performance penalty. +/// +/// [`None`]: https://doc.rust-lang.org/std/option/enum.Option.html#variant.None +/// [`Stream::fuse`]: trait.Stream.html#method.fuse +/// [`Fuse`]: struct.Fuse.html +#[cfg(any(feature = "unstable", feature = "docs"))] +#[cfg_attr(feature = "docs", doc(cfg(unstable)))] +pub trait FusedStream: Stream {} + +impl FusedStream for &mut S {} diff --git a/src/stream/mod.rs b/src/stream/mod.rs index 359cb7a..9f5097d 100644 --- a/src/stream/mod.rs +++ b/src/stream/mod.rs @@ -37,6 +37,7 @@ mod repeat; cfg_if! { if #[cfg(any(feature = "unstable", feature = "docs"))] { mod double_ended_stream; + mod fused_stream; mod extend; mod from_stream; mod into_stream; @@ -45,6 +46,7 @@ cfg_if! { pub use extend::Extend; pub use from_stream::FromStream; pub use into_stream::IntoStream; + pub use fused_stream::FusedStream; pub use stream::Merge; }