io: Add the Peek trait

Add the trait for each struct which has a peek function.

library/std/src/io/mod.rs

@@ -445,6 +445,18 @@ pub(crate) fn default_read_exact<R: Read + ?Sized>(this: &mut R, mut buf: &mut [
     }
 }
 
+/// The `Peek` trait allows for reading bytes from a source, without removing that data from
+/// the queue.
+///
+/// This trait behaves like [`Read`], except the bytes are not removed from the source.
+#[unstable(feature = "peek_trait", issue = "none")]
+pub trait Peek {
+    /// This function behaves like [`Read::read`], except the bytes are not removed from the
+    /// source.
+    #[unstable(feature = "peek_trait", issue = "none")]
+    fn peek(&mut self, buf: &mut [u8]) -> Result<usize>;
+}
+
 /// The `Read` trait allows for reading bytes from a source.
 ///
 /// Implementors of the `Read` trait are called 'readers'.

library/std/src/io/prelude.rs

@@ -11,4 +11,4 @@
 #![stable(feature = "rust1", since = "1.0.0")]
 
 #[stable(feature = "rust1", since = "1.0.0")]
-pub use super::{BufRead, Read, Seek, Write};
+pub use super::{BufRead, Peek, Read, Seek, Write};

library/std/src/net/tcp.rs

@@ -605,6 +605,13 @@ impl TcpStream {
     }
 }
 
+#[unstable(feature = "peek_trait", issue = "none")]
+impl Peek for TcpStream {
+    fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        self.0.peek(buf)
+    }
+}
+
 // In addition to the `impl`s here, `TcpStream` also has `impl`s for
 // `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` and
 // `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and

library/std/src/net/udp.rs

@@ -2,7 +2,7 @@
 mod tests;
 
 use crate::fmt;
-use crate::io::{self, Error, ErrorKind};
+use crate::io::{self, Error, ErrorKind, Peek};
 use crate::net::{Ipv4Addr, Ipv6Addr, SocketAddr, ToSocketAddrs};
 use crate::sys_common::net as net_imp;
 use crate::sys_common::{AsInner, FromInner, IntoInner};
@@ -779,6 +779,13 @@ impl UdpSocket {
     }
 }
 
+#[unstable(feature = "peek_trait", issue = "none")]
+impl Peek for UdpSocket {
+    fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        self.0.peek(buf)
+    }
+}
+
 // In addition to the `impl`s here, `UdpSocket` also has `impl`s for
 // `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` and
 // `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and

library/std/src/os/unix/net/datagram.rs

@@ -19,7 +19,7 @@ use super::{sockaddr_un, SocketAddr};
     target_os = "netbsd",
     target_os = "openbsd",
 ))]
-use crate::io::{IoSlice, IoSliceMut};
+use crate::io::{IoSlice, IoSliceMut, Peek};
 use crate::net::Shutdown;
 use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};
 use crate::path::Path;
@@ -877,6 +877,13 @@ impl UnixDatagram {
     }
 }
 
+#[unstable(feature = "peek_trait", issue = "none")]
+impl Peek for UnixDatagram {
+    fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        self.0.peek(buf)
+    }
+}
+
 #[stable(feature = "unix_socket", since = "1.10.0")]
 impl AsRawFd for UnixDatagram {
     #[inline]

library/std/src/os/unix/net/stream.rs

@@ -573,6 +573,13 @@ impl UnixStream {
     }
 }
 
+#[unstable(feature = "peek_trait", issue = "none")]
+impl io::Peek for UnixStream {
+    fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        self.0.peek(buf)
+    }
+}
+
 #[stable(feature = "unix_socket", since = "1.10.0")]
 impl io::Read for UnixStream {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {