Merge #222

222: adds stream::skip combinator r=stjepang a=montekki

Ref: #129 
Stdlib: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.skip

Co-authored-by: Fedor Sakharov <fedor.sakharov@gmail.com>

Author: bors[bot]

src/stream/stream/mod.rs

@@ -33,11 +33,13 @@ mod min_by;
 mod next;
 mod nth;
 mod scan;
+mod skip;
 mod take;
 mod zip;
 
 pub use fuse::Fuse;
 pub use scan::Scan;
+pub use skip::Skip;
 pub use take::Take;
 pub use zip::Zip;
 
@@ -661,6 +663,31 @@ pub trait Stream {
         Scan::new(self, initial_state, f)
     }
 
+    /// Creates a combinator that skips the first `n` elements.
+    ///
+    /// ## 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 mut skipped = s.skip(2);
+    ///
+    /// assert_eq!(skipped.next().await, Some(3));
+    /// assert_eq!(skipped.next().await, None);
+    /// #
+    /// # }) }
+    /// ```
+    fn skip(self, n: usize) -> Skip<Self>
+    where
+        Self: Sized,
+    {
+        Skip::new(self, n)
+    }
+
     /// 'Zips up' two streams into a single stream of pairs.
     ///
     /// `zip()` returns a new stream that will iterate over two other streams, returning a tuple

src/stream/stream/skip.rs

@@ -0,0 +1,41 @@
+use std::pin::Pin;
+use std::task::{Context, Poll};
+
+use crate::stream::Stream;
+
+/// A stream to skip first n elements of another stream.
+#[derive(Debug)]
+pub struct Skip<S> {
+    stream: S,
+    n: usize,
+}
+
+impl<S> Skip<S> {
+    pin_utils::unsafe_pinned!(stream: S);
+    pin_utils::unsafe_unpinned!(n: usize);
+
+    pub(crate) fn new(stream: S, n: usize) -> Self {
+        Skip { stream, n }
+    }
+}
+
+impl<S> Stream for Skip<S>
+where
+    S: Stream,
+{
+    type Item = S::Item;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        loop {
+            let next = futures_core::ready!(self.as_mut().stream().poll_next(cx));
+
+            match next {
+                Some(v) => match self.n {
+                    0 => return Poll::Ready(Some(v)),
+                    _ => *self.as_mut().n() -= 1,
+                },
+                None => return Poll::Ready(None),
+            }
+        }
+    }
+}