add stream::FusedStream

Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com>

Author: yoshuawuyts

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<S: FusedStream + ?Sized + Unpin> FusedStream for &mut S {}

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;
     }