add stream::min_by method (#146)

* add stream::min_by method

* Update src/stream/stream.rs

Co-Authored-By: Yoshua Wuyts <yoshuawuyts+github@gmail.com>

src/stream/min_by.rs

@@ -0,0 +1,54 @@
+use std::cmp::Ordering;
+use std::pin::Pin;
+
+use super::stream::Stream;
+use crate::future::Future;
+use crate::task::{Context, Poll};
+
+/// A future that yields the minimum item in a stream by a given comparison function.
+#[derive(Clone, Debug)]
+pub struct MinBy<S: Stream, F> {
+    stream: S,
+    compare: F,
+    min: Option<S::Item>,
+}
+
+impl<S: Stream + Unpin, F> Unpin for MinBy<S, F> {}
+
+impl<S: Stream + Unpin, F> MinBy<S, F> {
+    pub(super) fn new(stream: S, compare: F) -> Self {
+        MinBy {
+            stream,
+            compare,
+            min: None,
+        }
+    }
+}
+
+impl<S, F> Future for MinBy<S, F>
+where
+    S: futures_core::stream::Stream + Unpin,
+    S::Item: Copy,
+    F: FnMut(&S::Item, &S::Item) -> Ordering,
+{
+    type Output = Option<S::Item>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        let next = futures_core::ready!(Pin::new(&mut self.stream).poll_next(cx));
+
+        match next {
+            Some(new) => {
+                cx.waker().wake_by_ref();
+                match self.as_mut().min.take() {
+                    None => self.as_mut().min = Some(new),
+                    Some(old) => match (&mut self.as_mut().compare)(&new, &old) {
+                        Ordering::Less => self.as_mut().min = Some(new),
+                        _ => self.as_mut().min = Some(old),
+                    },
+                }
+                Poll::Pending
+            }
+            None => Poll::Ready(self.min),
+        }
+    }
+}

src/stream/mod.rs

@@ -27,6 +27,7 @@ pub use repeat::{repeat, Repeat};
 pub use stream::{Stream, Take};
 
 mod empty;
+mod min_by;
 mod once;
 mod repeat;
 mod stream;

src/stream/stream.rs

@@ -21,10 +21,12 @@
 //! # }) }
 //! ```
 
+use std::cmp::Ordering;
 use std::pin::Pin;
 
 use cfg_if::cfg_if;
 
+use super::min_by::MinBy;
 use crate::future::Future;
 use crate::task::{Context, Poll};
 use std::marker::PhantomData;
@@ -118,6 +120,39 @@ pub trait Stream {
         }
     }
 
+    /// Returns the element that gives the minimum value with respect to the
+    /// specified comparison function. If several elements are equally minimum,
+    /// the first element is returned. If the stream is empty, `None` is returned.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # fn main() { async_std::task::block_on(async {
+    /// #
+    /// use std::collections::VecDeque;
+    /// use async_std::stream::Stream;
+    ///
+    /// let s: VecDeque<usize> = vec![1, 2, 3].into_iter().collect();
+    ///
+    /// let min = Stream::min_by(s.clone(), |x, y| x.cmp(y)).await;
+    /// assert_eq!(min, Some(1));
+    ///
+    /// let min = Stream::min_by(s, |x, y| y.cmp(x)).await;
+    /// assert_eq!(min, Some(3));
+    ///
+    /// let min = Stream::min_by(VecDeque::<usize>::new(), |x, y| x.cmp(y)).await;
+    /// assert_eq!(min, None);
+    /// #
+    /// # }) }
+    /// ```
+    fn min_by<F>(self, compare: F) -> MinBy<Self, F>
+    where
+        Self: Sized + Unpin,
+        F: FnMut(&Self::Item, &Self::Item) -> Ordering,
+    {
+        MinBy::new(self, compare)
+    }
+
     /// Tests if every element of the stream matches a predicate.
     ///
     /// `all()` takes a closure that returns `true` or `false`. It applies