Merge #177

177: implement DoubleEndedStream r=yoshuawuyts a=yoshuawuyts

Ref #129. This is the most basic version of the `DoubleEndedStream` trait. Because there is no counterpart in `futures-rs` we allow this to be implementable (not sure if we should though?).

This is not a high-priority trait to implement, with probably the most useful addition being the blanket impl over [`std::iter::Fuse`](https://doc.rust-lang.org/std/iter/struct.Fuse.html) (where we should have a `Fuse` counterpart for `Stream` also).

So I'm taking this one step at the time, and this PR introduces just the bare minimum to get things working. Thanks!

r? @stjepang @taiki-e

## Refs
- https://doc.rust-lang.org/std/iter/trait.DoubleEndedIterator.html
- #129 


Co-authored-by: Yoshua Wuyts <[email protected]>

src/stream/double_ended_stream.rs

@@ -0,0 +1,23 @@
+use crate::stream::Stream;
+
+use std::pin::Pin;
+use std::task::{Context, Poll};
+
+/// A stream able to yield elements from both ends.
+///
+/// Something that implements `DoubleEndedStream` has one extra capability
+/// over something that implements [`Stream`]: the ability to also take
+/// `Item`s from the back, as well as the front.
+///
+/// [`Stream`]: trait.Stream.html
+#[cfg_attr(feature = "docs", doc(cfg(unstable)))]
+pub trait DoubleEndedStream: Stream {
+    /// Removes and returns an element from the end of the stream.
+    ///
+    /// Returns `None` when there are no more elements.
+    ///
+    /// The [trait-level] docs contain more details.
+    ///
+    /// [trait-level]: trait.DoubleEndedStream.html
+    fn poll_next_back(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
+}

src/stream/mod.rs

@@ -21,11 +21,13 @@
 //! # }) }
 //! ```
 
+pub use double_ended_stream::DoubleEndedStream;
 pub use empty::{empty, Empty};
 pub use once::{once, Once};
 pub use repeat::{repeat, Repeat};
 pub use stream::{Stream, Take};
 
+mod double_ended_stream;
 mod empty;
 mod once;
 mod repeat;