documentation

src/lib.rs

@@ -1,12 +1,7 @@
-//!This crate offers a `futures::Stream` extension trait which allows for
+//!This crate offers two `futures::Stream` extension traits which allows for
 //! splitting a `Stream` into two streams using a predicate function thats
 //! checked on each `Stream::Item`.
 //!
-//!The current version of this crate buffers only one value and only in the
-//! scenario where the item yielded from the parent stream is not what the child
-//! stream requested per the predicate. In that scenario, the item is stored and
-//! the other stream is awakened
-//!
 //!```rust
 //! use futures::StreamExt;
 //! use split_stream_by::SplitStreamByExt;
@@ -28,7 +23,7 @@
 //! while splitting
 //!
 //!```rust
-//! use split_stream_by::{Either,SplitStreamByExt};
+//! use split_stream_by::{Either,SplitStreamByMapExt};
 //! use futures::StreamExt;
 //!
 //! #[derive(Debug, PartialEq)]
@@ -78,8 +73,9 @@ pub use split_by_map_buffered::{LeftSplitByMapBuffered, RightSplitByMapBuffered}
 pub use futures::future::Either;
 use futures::Stream;
 
-/// This is the extension crate would provides the functionality for splitting a
-/// stream
+/// This extension trait provides the functionality for splitting a
+/// stream by a predicate of type `Fn(&Self::Item) -> bool`. The two resulting
+/// streams will both yield `Self::Item`
 pub trait SplitStreamByExt<P>: Stream {
     /// This takes ownership of a stream and returns two streams based on a
     /// predicate. When the predicate returns `true`, the item will appear in
@@ -109,14 +105,51 @@ pub trait SplitStreamByExt<P>: Stream {
         (true_stream, false_stream)
     }
 
+    /// This takes ownership of a stream and returns two streams based on a
+    /// predicate. When the predicate returns `true`, the item will appear in
+    /// the first of the pair of streams returned. Items that return false will
+    /// go into the second of the pair of streams. This will buffer up to N
+    /// items of the inactive stream before returning Pending and notifying that
+    /// stream
+    ///
+    ///```rust
+    /// use split_stream_by::SplitStreamByExt;
+    ///
+    /// let incoming_stream = futures::stream::iter([0,1,2,3,4,5]);
+    /// let (even_stream, odd_stream) = incoming_stream.split_by_buffered::<3>(|&n| n % 2 == 0);
+    /// ```
+    fn split_by_buffered<const N: usize>(
+        self,
+        predicate: P,
+    ) -> (
+        TrueSplitByBuffered<Self::Item, Self, P, N>,
+        FalseSplitByBuffered<Self::Item, Self, P, N>,
+    )
+    where
+        P: Fn(&Self::Item) -> bool,
+        Self: Sized,
+    {
+        let stream = SplitByBuffered::new(self, predicate);
+        let true_stream = TrueSplitByBuffered::new(stream.clone());
+        let false_stream = FalseSplitByBuffered::new(stream);
+        (true_stream, false_stream)
+    }
+}
+
+impl<T, P> SplitStreamByExt<P> for T where T: Stream + ?Sized {}
+
+/// This extension trait provides the functionality for splitting a
+/// stream by a predicate of type `Fn(Self::Item) -> Either<L,R>`. The resulting
+/// streams will yield types `L` and `R` respectively
+pub trait SplitStreamByMapExt<P, L, R>: Stream {
     /// This takes ownership of a stream and returns two streams based on a
     /// predicate. The predicate takes an item by value and returns
     /// `Either::Left(..)` or `Either::Right(..)` where the inner
     /// values of `Left` and `Right` become the items of the two respective
     /// streams
     ///
     /// ```
-    /// use split_stream_by::{Either,SplitStreamByExt};
+    /// use split_stream_by::{Either,SplitStreamByMapExt};
     /// struct Request {
     /// 	//...
     /// }
@@ -138,7 +171,7 @@ pub trait SplitStreamByExt<P>: Stream {
     /// });
     /// ```
 
-    fn split_by_map<L, R>(
+    fn split_by_map(
         self,
         predicate: P,
     ) -> (
@@ -155,36 +188,6 @@ pub trait SplitStreamByExt<P>: Stream {
         (true_stream, false_stream)
     }
 
-    /// This takes ownership of a stream and returns two streams based on a
-    /// predicate. When the predicate returns `true`, the item will appear in
-    /// the first of the pair of streams returned. Items that return false will
-    /// go into the second of the pair of streams. This will buffer up to N
-    /// items of the inactive stream before returning Pending and notifying that
-    /// stream
-    ///
-    ///```rust
-    /// use split_stream_by::SplitStreamByExt;
-    ///
-    /// let incoming_stream = futures::stream::iter([0,1,2,3,4,5]);
-    /// let (even_stream, odd_stream) = incoming_stream.split_by_buffered::<3>(|&n| n % 2 == 0);
-    /// ```
-    fn split_by_buffered<const N: usize>(
-        self,
-        predicate: P,
-    ) -> (
-        TrueSplitByBuffered<Self::Item, Self, P, N>,
-        FalseSplitByBuffered<Self::Item, Self, P, N>,
-    )
-    where
-        P: Fn(&Self::Item) -> bool,
-        Self: Sized,
-    {
-        let stream = SplitByBuffered::new(self, predicate);
-        let true_stream = TrueSplitByBuffered::new(stream.clone());
-        let false_stream = FalseSplitByBuffered::new(stream);
-        (true_stream, false_stream)
-    }
-
     /// This takes ownership of a stream and returns two streams based on a
     /// predicate. The predicate takes an item by value and returns
     /// `Either::Left(..)` or `Either::Right(..)` where the inner
@@ -193,7 +196,7 @@ pub trait SplitStreamByExt<P>: Stream {
     /// returning Pending and notifying that stream
     ///
     /// ```
-    /// use split_stream_by::{Either,SplitStreamByExt};
+    /// use split_stream_by::{Either,SplitStreamByMapExt};
     /// struct Request {
     /// 	//...
     /// }
@@ -209,13 +212,13 @@ pub trait SplitStreamByExt<P>: Stream {
     /// 	Message::Response(Response {}),
     /// 	Message::Response(Response {}),
     /// ]);
-    /// let (mut request_stream, mut response_stream) = incoming_stream.split_by_map_buffered::<_,_,3>(|item| match item {
+    /// let (mut request_stream, mut response_stream) = incoming_stream.split_by_map_buffered::<3>(|item| match item {
     /// 	Message::Request(req) => Either::Left(req),
     /// 	Message::Response(res) => Either::Right(res),
     /// });
     /// ```
 
-    fn split_by_map_buffered<L, R, const N: usize>(
+    fn split_by_map_buffered<const N: usize>(
         self,
         predicate: P,
     ) -> (
@@ -233,4 +236,4 @@ pub trait SplitStreamByExt<P>: Stream {
     }
 }
 
-impl<T, P> SplitStreamByExt<P> for T where T: Stream + ?Sized {}
+impl<T, P, L, R> SplitStreamByMapExt<P, L, R> for T where T: Stream + ?Sized {}