Adds partial_cmp.rs file and partial_cmp signature to mod.rs

Author: assemblaj

src/stream/stream/mod.rs

@@ -35,6 +35,7 @@ mod inspect;
 mod min_by;
 mod next;
 mod nth;
+mod partial_cmp;
 mod scan;
 mod skip;
 mod skip_while;
@@ -52,6 +53,7 @@ use fold::FoldFuture;
 use min_by::MinByFuture;
 use next::NextFuture;
 use nth::NthFuture;
+use partial_cmp::PartialCmpFuture;
 
 pub use chain::Chain;
 pub use filter::Filter;
@@ -1030,6 +1032,50 @@ extension_trait! {
         {
             FromStream::from_stream(self)
         }
+
+        #[doc = r#"
+            Lexicographically compares the elements of this `Stream` with those
+            of another.
+            
+            # Examples
+            ```
+            # fn main() { async_std::task::block_on(async {
+            #
+            use async_std::prelude::*;
+            use std::collections::VecDeque;
+            
+            use std::cmp::Ordering;
+
+            let result_equal = vec![1.].into_iter().collect::<VecDeque<f64>>()
+                .partial_cmp(vec![1.].into_iter().collect::<VecDeque<f64>>()).await;
+            let result_less = vec![1.].into_iter().collect::<VecDeque<f64>>()
+                .partial_cmp(vec![1., 2.].into_iter().collect::<VecDeque<f64>>()).await;
+            let result_greater = vec![1., 2.].into_iter().collect::<VecDeque<f64>>()
+                .partial_cmp(vec![1.].into_iter().collect::<VecDeque<f64>>()).await;
+            let result_none = vec![std::f64::NAN].into_iter().collect::<VecDeque<f64>>()
+                .partial_cmp(vec![1.].into_iter().collect::<VecDeque<f64>>()).await;
+
+            assert_eq!(result_equal, Some(Ordering::Equal));
+            assert_eq!(result_less, Some(Ordering::Less));
+            assert_eq!(result_greater, Some(Ordering::Greater));            
+            assert_eq!(result_none, None);
+
+            #
+            # }) }
+            ```
+        "#]
+        fn partial_cmp<S>(
+           self,
+           other: S
+        ) -> impl Future<Output = Option<Ordering>> + '_ [PartialCmpFuture<Self, S>] 
+        where
+            Self: Sized + Stream,
+            S: Stream,             
+            Self::Item: PartialOrd<S::Item>,
+        {
+            PartialCmpFuture::new(self, other)
+        }
+        
     }
 
     impl<S: Stream + Unpin + ?Sized> Stream for Box<S> {

src/stream/stream/partial_cmp.rs

@@ -0,0 +1,56 @@
+use std::cmp::Ordering;
+use std::pin::Pin;
+
+use crate::future::Future;
+use crate::stream::Stream;
+use crate::task::{Context, Poll};
+
+// Lexicographically compares the elements of this `Stream` with those
+// of another.
+#[derive(Debug)]
+pub struct PartialCmpFuture<L: Stream, R> {
+    l: L,
+    r: R,
+}
+
+impl<L: Stream + Unpin, R: Unpin> Unpin for PartialCmpFuture<L, R> {}
+
+impl<L: Stream, R> PartialCmpFuture<L, R> {
+    pub(crate) fn new(l: L, r: R) -> Self {
+        PartialCmpFuture {
+            l,
+            r,
+        }
+    }
+
+    pin_utils::unsafe_pinned!(l: L);
+    pin_utils::unsafe_pinned!(r: R);
+}
+
+impl<L: Stream, R: Stream> Future for PartialCmpFuture<L, R> 
+where 
+    L: Stream + Unpin + Sized,
+    R: Stream + Unpin + Sized,
+    L::Item: PartialOrd<R::Item>
+{
+    type Output = Option<Ordering>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        let l_next  = futures_core::ready!(self.as_mut().l().poll_next(cx));
+        let r_next  = futures_core::ready!(self.as_mut().r().poll_next(cx));
+        
+        match (l_next, r_next) {
+            (None, None) => Poll::Ready(Some(Ordering::Equal)),
+            (None, _   ) => Poll::Ready(Some(Ordering::Less)),
+            (_,    None) => Poll::Ready(Some(Ordering::Greater)),
+            (Some(x), Some(y)) =>  match x.partial_cmp(&y) {
+                    Some(Ordering::Equal) => { 
+                        // wakes task to pull the next item from stream
+                        cx.waker().wake_by_ref();
+                        Poll::Pending
+                    },
+                    non_eq      => Poll::Ready(non_eq),
+            }
+        }
+    }
+}