tokio-rs/tokio
1
0
Fork 0
mirror of https://github.com/tokio-rs/tokio.git synced 2026-08-19 00:00:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

doc: improve AsyncBufReadExt API documentation (#1868)

Browse Source 
Remove "old" docs that were left over during a rewrite, add examples and
additional details.
This commit is contained in:
Carl Lerche
2019-11-30 13:12:39 -08:00
committed by GitHub
parent b559a0cd9a
commit 8ce408492a
1 changed files with 96 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tokio/src/io/util/async_buf_read_ext.rs
+96 -31
View File
@@ -7,19 +7,75 @@ use crate::io::AsyncBufRead;
cfg_io_util! {
/// An extension trait which adds utility methods to `AsyncBufRead` types.
pub trait AsyncBufReadExt: AsyncBufRead {
/// Creates a future which will read all the bytes associated with this I/O
/// object into `buf` until the delimiter `byte` or EOF is reached.
/// This method is the async equivalent to [`BufRead::read_until`](std::io::BufRead::read_until).
/// Read all bytes into `buf` until the delimiter `byte` or EOF is reached.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_until(&mut self, buf: &mut Vec<u8>) -> io::Result<usize>;
/// ```
///
/// This function will read bytes from the underlying stream until the
/// delimiter or EOF is found. Once found, all bytes up to, and including,
/// the delimiter (if found) will be appended to `buf`.
///
/// The returned future will resolve to the number of bytes read once the read
/// operation is completed.
/// If successful, this function will return the total number of bytes read.
///
/// In the case of an error the buffer and the object will be discarded, with
/// the error yielded.
/// # Errors
///
/// This function will ignore all instances of [`ErrorKind::Interrupted`] and
/// will otherwise return any errors returned by [`fill_buf`].
///
/// If an I/O error is encountered then all bytes read so far will be
/// present in `buf` and its length will have been adjusted appropriately.
///
/// [`fill_buf`]: AsyncBufRead::poll_fill_buf
/// [`ErrorKind::Interrupted`]: std::io::ErrorKind::Interrupted
///
/// # Examples
///
/// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
/// this example, we use [`Cursor`] to read all the bytes in a byte slice
/// in hyphen delimited segments:
///
/// [`Cursor`]: std::io::Cursor
///
/// ```
/// use tokio::io::AsyncBufReadExt;
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() {
/// let mut cursor = Cursor::new(b"lorem-ipsum");
/// let mut buf = vec![];
///
/// // cursor is at 'l'
/// let num_bytes = cursor.read_until(b'-', &mut buf)
/// .await
/// .expect("reading from cursor won't fail");
///
/// assert_eq!(num_bytes, 6);
/// assert_eq!(buf, b"lorem-");
/// buf.clear();
///
/// // cursor is at 'i'
/// let num_bytes = cursor.read_until(b'-', &mut buf)
/// .await
/// .expect("reading from cursor won't fail");
///
/// assert_eq!(num_bytes, 5);
/// assert_eq!(buf, b"ipsum");
/// buf.clear();
///
/// // cursor is at EOF
/// let num_bytes = cursor.read_until(b'-', &mut buf)
/// .await
/// .expect("reading from cursor won't fail");
/// assert_eq!(num_bytes, 0);
/// assert_eq!(buf, b"");
/// }
/// ```
fn read_until<'a>(&'a mut self, byte: u8, buf: &'a mut Vec<u8>) -> ReadUntil<'a, Self>
where
Self: Unpin,
@@ -27,33 +83,15 @@ cfg_io_util! {
read_until(self, byte, buf)
}
/// Creates a future which will read all the bytes associated with this I/O
/// object into `buf` until a newline (the 0xA byte) or EOF is reached,
/// This method is the async equivalent to [`BufRead::read_line`](std::io::BufRead::read_line).
///
/// This function will read bytes from the underlying stream until the
/// newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes
/// up to, and including, the delimiter (if found) will be appended to
/// `buf`.
///
/// The returned future will resolve to the number of bytes read once the read
/// operation is completed.
///
/// In the case of an error the buffer and the object will be discarded, with
/// the error yielded.
///
/// # Errors
///
/// This function has the same error semantics as [`read_until`] and will
/// also return an error if the read bytes are not valid UTF-8. If an I/O
/// error is encountered then `buf` may contain some bytes already read in
/// the event that all data read so far was valid UTF-8.
///
/// [`read_until`]: AsyncBufReadExt::read_until
/// ------------
/// Read all bytes until a newline (the 0xA byte) is reached, and append
/// them to the provided buffer.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_line(&mut self, buf: &mut String) -> io::Result<usize>;
/// ```
///
/// This function will read bytes from the underlying stream until the
/// newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes
/// up to, and including, the delimiter (if found) will be appended to
@@ -178,6 +216,33 @@ cfg_io_util! {
///
/// Each line of the stream has the same error semantics as [`AsyncBufReadExt::read_line`].
///
/// # Examples
///
/// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
/// this example, we use [`Cursor`] to iterate over all the lines in a byte
/// slice.
///
/// [`Cursor`]: std::io::Cursor
///
/// ```
/// use tokio::io::AsyncBufReadExt;
///
/// use futures::{StreamExt};
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() {
/// let cursor = Cursor::new(b"lorem\nipsum\r\ndolor");
///
/// let mut lines = cursor.lines().map(|res| res.unwrap());
///
/// assert_eq!(lines.next().await, Some(String::from("lorem")));
/// assert_eq!(lines.next().await, Some(String::from("ipsum")));
/// assert_eq!(lines.next().await, Some(String::from("dolor")));
/// assert_eq!(lines.next().await, None);
/// }
/// ```
///
/// [`AsyncBufReadExt::read_line`]: AsyncBufReadExt::read_line
fn lines(self) -> Lines<Self>
where