reinstate the previous public interface; document the interpretation of return values
@@ -66,32 +66,49 @@ impl<St: Stream> Peekable<St> {
self.stream.into_inner()
}
- /// Peek retrieves a reference to the next item in the stream.
- ///
- /// This method polls the underlying stream and return either a reference
- /// to the next item if the stream is ready or passes through any errors.
+ /// Produces a `Peek` future which retrieves a reference to the next item
+ /// in the stream, or `None` if the underlying stream terminates.
pub fn peek(self: Pin<&mut Self>) -> Peek<'_, St> {
Peek { inner: Some(self) }
}
- fn poll_peek(
+ /// Attempt to poll the underlying stream, and return the mutable borrow
+ /// in case that is desirable to try for another time.
+ /// In case a peeking poll is successful, the reference to the next item
+ /// will be in the `Either::Right` variant; otherwise, the mutable borrow
+ /// will be in the `Either::Left` variant.
+ fn do_poll_peek(
mut self: Pin<&mut Self>,
cx: &mut Context<'_>,
- ) -> Either<Pin<&mut Self>, Poll<Option<&St::Item>>> {
+ ) -> Either<Pin<&mut Self>, Option<&St::Item>> {
if self.peeked.is_some() {
let this: &Self = self.into_ref().get_ref();
- return Either::Right(Poll::Ready(this.peeked.as_ref()));
+ return Either::Right(this.peeked.as_ref());
}
match self.as_mut().stream().poll_next(cx) {
- Poll::Ready(None) => Either::Right(Poll::Ready(None)),
+ Poll::Ready(None) => Either::Right(None),
Poll::Ready(Some(item)) => {
*self.as_mut().peeked() = Some(item);
let this: &Self = self.into_ref().get_ref();
- Either::Right(Poll::Ready(this.peeked.as_ref()))
+ Either::Right(this.peeked.as_ref())
}
_ => Either::Left(self),
}
}
+
+ /// Peek retrieves a reference to the next item in the stream.
+ ///
+ /// This method polls the underlying stream and return either a reference
+ /// to the next item if the stream is ready or passes through any errors.
+ pub fn poll_peek(
+ self: Pin<&mut Self>,
+ cx: &mut Context<'_>,
+ ) -> Poll<Option<&St::Item>> {
+ match self.do_poll_peek(cx) {
+ Either::Left(_) => Poll::Pending,
+ Either::Right(poll) => Poll::Ready(poll),
+ }
+ }
}
impl<St: Stream> FusedStream for Peekable<St> {
@@ -141,9 +158,14 @@ pub struct Peek<'a, St: Stream> {
impl<St: Stream> Unpin for Peek<'_, St> {}
-impl<St: Stream> fmt::Debug for Peek<'_, St> {
+impl<St> fmt::Debug for Peek<'_, St>
+where
+ St: Stream + fmt::Debug,
+ St::Item: fmt::Debug,
+{
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Peek")
+ .field("inner", &self.inner)
.finish()
}
}
@@ -161,15 +183,15 @@ where
type Output = Option<&'a St::Item>;
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
if let Some(peekable) = self.inner.take() {
- match peekable.poll_peek(cx) {
+ match peekable.do_poll_peek(cx) {
Either::Left(peekable) => {
self.inner = Some(peekable);
Poll::Pending
}
- Either::Right(poll) => poll,
+ Either::Right(peek) => Poll::Ready(peek),
}
} else {
- Poll::Pending
+ panic!("Peek polled after completion")
}
}
}
