Should provide function returning future for Peekable::peek

[Nemo157]

The current Peekable::peek signature doesn't seem right to me when related to other methods:

pub fn peek(
    self: Pin<&mut Peekable<St>>, 
    cx: &mut Context
) -> Poll<Option<&<St as Stream>::Item>>

I think this should be renamed to poll_peek, and another function added that returns a Future resolving to the peeked item:

pub fn peek(self: Pin<&mut Self>) -> impl Future<Output = Option<&<St as Stream>::Item>>;

Preferably this should also take something like &mut self where Self: Unpin to really avoid the issue from the below linked thread, unfortunately making a really useful signature like that would probably require defining an extra extension trait so that a Pin<impl DerefMut<Target = Peekable<_>>> would also be a Peekable.

(Related to this u.rl.o thread)

[brennie]

The docs on Peekable are also incorrect and imply that peek() exists.