Source code
Revision control
Copy as Markdown
Other Tools
use crate::io::util::chain::{chain, Chain};
use crate::io::util::read::{read, Read};
use crate::io::util::read_buf::{read_buf, ReadBuf};
use crate::io::util::read_exact::{read_exact, ReadExact};
use crate::io::util::read_int::{ReadF32, ReadF32Le, ReadF64, ReadF64Le};
use crate::io::util::read_int::{
ReadI128, ReadI128Le, ReadI16, ReadI16Le, ReadI32, ReadI32Le, ReadI64, ReadI64Le, ReadI8,
};
use crate::io::util::read_int::{
ReadU128, ReadU128Le, ReadU16, ReadU16Le, ReadU32, ReadU32Le, ReadU64, ReadU64Le, ReadU8,
};
use crate::io::util::read_to_end::{read_to_end, ReadToEnd};
use crate::io::util::read_to_string::{read_to_string, ReadToString};
use crate::io::util::take::{take, Take};
use crate::io::AsyncRead;
use bytes::BufMut;
cfg_io_util! {
/// Defines numeric reader
macro_rules! read_impl {
(
$(
$(#[$outer:meta])*
fn $name:ident(&mut self) -> $($fut:ident)*;
)*
) => {
$(
$(#[$outer])*
fn $name<'a>(&'a mut self) -> $($fut)*<&'a mut Self> where Self: Unpin {
$($fut)*::new(self)
}
)*
}
}
/// Reads bytes from a source.
///
/// Implemented as an extension trait, adding utility methods to all
/// [`AsyncRead`] types. Callers will tend to import this trait instead of
/// [`AsyncRead`].
///
/// ```no_run
/// use tokio::fs::File;
/// use tokio::io::{self, AsyncReadExt};
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut f = File::open("foo.txt").await?;
/// let mut buffer = [0; 10];
///
/// // The `read` method is defined by this trait.
/// let n = f.read(&mut buffer[..]).await?;
///
/// Ok(())
/// }
/// ```
///
/// See [module][crate::io] documentation for more details.
///
/// [`AsyncRead`]: AsyncRead
pub trait AsyncReadExt: AsyncRead {
/// Creates a new `AsyncRead` instance that chains this stream with
/// `next`.
///
/// The returned `AsyncRead` instance will first read all bytes from this object
/// until EOF is encountered. Afterwards the output is equivalent to the
/// output of `next`.
///
/// # Examples
///
/// [`File`][crate::fs::File]s implement `AsyncRead`:
///
/// ```no_run
/// use tokio::fs::File;
/// use tokio::io::{self, AsyncReadExt};
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let f1 = File::open("foo.txt").await?;
/// let f2 = File::open("bar.txt").await?;
///
/// let mut handle = f1.chain(f2);
/// let mut buffer = String::new();
///
/// // read the value into a String. We could use any AsyncRead
/// // method here, this is just one example.
/// handle.read_to_string(&mut buffer).await?;
/// Ok(())
/// }
/// ```
fn chain<R>(self, next: R) -> Chain<Self, R>
where
Self: Sized,
R: AsyncRead,
{
chain(self, next)
}
/// Pulls some bytes from this source into the specified buffer,
/// returning how many bytes were read.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>;
/// ```
///
/// This method does not provide any guarantees about whether it
/// completes immediately or asynchronously.
///
/// # Return
///
/// If the return value of this method is `Ok(n)`, then it must be
/// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates
/// that the buffer `buf` has been filled in with `n` bytes of data from
/// this source. If `n` is `0`, then it can indicate one of two
/// scenarios:
///
/// 1. This reader has reached its "end of file" and will likely no longer
/// be able to produce bytes. Note that this does not mean that the
/// reader will *always* no longer be able to produce bytes.
/// 2. The buffer specified was 0 bytes in length.
///
/// No guarantees are provided about the contents of `buf` when this
/// function is called, implementations cannot rely on any property of the
/// contents of `buf` being `true`. It is recommended that *implementations*
/// only write data to `buf` instead of reading its contents.
///
/// Correspondingly, however, *callers* of this method may not assume
/// any guarantees about how the implementation uses `buf`. It is
/// possible that the code that's supposed to write to the buffer might
/// also read from it. It is your responsibility to make sure that `buf`
/// is initialized before calling `read`.
///
/// # Errors
///
/// If this function encounters any form of I/O or other error, an error
/// variant will be returned. If an error is returned then it must be
/// guaranteed that no bytes were read.
///
/// # Cancel safety
///
/// This method is cancel safe. If you use it as the event in a
/// [`tokio::select!`](crate::select) statement and some other branch
/// completes first, then it is guaranteed that no data was read.
///
/// # Examples
///
/// [`File`][crate::fs::File]s implement `Read`:
///
/// ```no_run
/// use tokio::fs::File;
/// use tokio::io::{self, AsyncReadExt};
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut f = File::open("foo.txt").await?;
/// let mut buffer = [0; 10];
///
/// // read up to 10 bytes
/// let n = f.read(&mut buffer[..]).await?;
///
/// println!("The bytes: {:?}", &buffer[..n]);
/// Ok(())
/// }
/// ```
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>
where
Self: Unpin,
{
read(self, buf)
}
/// Pulls some bytes from this source into the specified buffer,
/// advancing the buffer's internal cursor.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_buf<B: BufMut>(&mut self, buf: &mut B) -> io::Result<usize>;
/// ```
///
/// Usually, only a single `read` syscall is issued, even if there is
/// more space in the supplied buffer.
///
/// This method does not provide any guarantees about whether it
/// completes immediately or asynchronously.
///
/// # Return
///
/// A nonzero `n` value indicates that the buffer `buf` has been filled
/// in with `n` bytes of data from this source. If `n` is `0`, then it
/// can indicate one of two scenarios:
///
/// 1. This reader has reached its "end of file" and will likely no longer
/// be able to produce bytes. Note that this does not mean that the
/// reader will *always* no longer be able to produce bytes.
/// 2. The buffer specified had a remaining capacity of zero.
///
/// # Errors
///
/// If this function encounters any form of I/O or other error, an error
/// variant will be returned. If an error is returned then it must be
/// guaranteed that no bytes were read.
///
/// # Cancel safety
///
/// This method is cancel safe. If you use it as the event in a
/// [`tokio::select!`](crate::select) statement and some other branch
/// completes first, then it is guaranteed that no data was read.
///
/// # Examples
///
/// [`File`] implements `Read` and [`BytesMut`] implements [`BufMut`]:
///
/// [`File`]: crate::fs::File
/// [`BytesMut`]: bytes::BytesMut
/// [`BufMut`]: bytes::BufMut
///
/// ```no_run
/// use tokio::fs::File;
/// use tokio::io::{self, AsyncReadExt};
///
/// use bytes::BytesMut;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut f = File::open("foo.txt").await?;
/// let mut buffer = BytesMut::with_capacity(10);
///
/// assert!(buffer.is_empty());
///
/// // read up to 10 bytes, note that the return value is not needed
/// // to access the data that was read as `buffer`'s internal
/// // cursor is updated.
/// f.read_buf(&mut buffer).await?;
///
/// println!("The bytes: {:?}", &buffer[..]);
/// Ok(())
/// }
/// ```
fn read_buf<'a, B>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B>
where
Self: Sized + Unpin,
B: BufMut,
{
read_buf(self, buf)
}
/// Reads the exact number of bytes required to fill `buf`.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<usize>;
/// ```
///
/// This function reads as many bytes as necessary to completely fill
/// the specified buffer `buf`.
///
/// # Errors
///
/// If the operation encounters an "end of file" before completely
/// filling the buffer, it returns an error of the kind
/// [`ErrorKind::UnexpectedEof`]. The contents of `buf` are unspecified
/// in this case.
///
/// If any other read error is encountered then the operation
/// immediately returns. The contents of `buf` are unspecified in this
/// case.
///
/// If this operation returns an error, it is unspecified how many bytes
/// it has read, but it will never read more than would be necessary to
/// completely fill the buffer.
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may already have been
/// read into `buf`.
///
/// # Examples
///
/// [`File`][crate::fs::File]s implement `Read`:
///
/// ```no_run
/// use tokio::fs::File;
/// use tokio::io::{self, AsyncReadExt};
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut f = File::open("foo.txt").await?;
/// let mut buffer = [0; 10];
///
/// // read exactly 10 bytes
/// f.read_exact(&mut buffer).await?;
/// Ok(())
/// }
/// ```
///
/// [`ErrorKind::UnexpectedEof`]: std::io::ErrorKind::UnexpectedEof
fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>
where
Self: Unpin,
{
read_exact(self, buf)
}
read_impl! {
/// Reads an unsigned 8 bit integer from the underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u8(&mut self) -> io::Result<u8>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 8 bit integers from an `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![2, 5]);
///
/// assert_eq!(2, reader.read_u8().await?);
/// assert_eq!(5, reader.read_u8().await?);
///
/// Ok(())
/// }
/// ```
fn read_u8(&mut self) -> ReadU8;
/// Reads a signed 8 bit integer from the underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i8(&mut self) -> io::Result<i8>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 8 bit integers from an `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0x02, 0xfb]);
///
/// assert_eq!(2, reader.read_i8().await?);
/// assert_eq!(-5, reader.read_i8().await?);
///
/// Ok(())
/// }
/// ```
fn read_i8(&mut self) -> ReadI8;
/// Reads an unsigned 16-bit integer in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u16(&mut self) -> io::Result<u16>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 16 bit big-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![2, 5, 3, 0]);
///
/// assert_eq!(517, reader.read_u16().await?);
/// assert_eq!(768, reader.read_u16().await?);
/// Ok(())
/// }
/// ```
fn read_u16(&mut self) -> ReadU16;
/// Reads a signed 16-bit integer in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i16(&mut self) -> io::Result<i16>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read signed 16 bit big-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0x00, 0xc1, 0xff, 0x7c]);
///
/// assert_eq!(193, reader.read_i16().await?);
/// assert_eq!(-132, reader.read_i16().await?);
/// Ok(())
/// }
/// ```
fn read_i16(&mut self) -> ReadI16;
/// Reads an unsigned 32-bit integer in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u32(&mut self) -> io::Result<u32>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 32-bit big-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0x00, 0x00, 0x01, 0x0b]);
///
/// assert_eq!(267, reader.read_u32().await?);
/// Ok(())
/// }
/// ```
fn read_u32(&mut self) -> ReadU32;
/// Reads a signed 32-bit integer in big-endian order from the
/// underlying reader.
///
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i32(&mut self) -> io::Result<i32>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read signed 32-bit big-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7a, 0x33]);
///
/// assert_eq!(-34253, reader.read_i32().await?);
/// Ok(())
/// }
/// ```
fn read_i32(&mut self) -> ReadI32;
/// Reads an unsigned 64-bit integer in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u64(&mut self) -> io::Result<u64>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 64-bit big-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![
/// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
/// ]);
///
/// assert_eq!(918733457491587, reader.read_u64().await?);
/// Ok(())
/// }
/// ```
fn read_u64(&mut self) -> ReadU64;
/// Reads an signed 64-bit integer in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i64(&mut self) -> io::Result<i64>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read signed 64-bit big-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0x80, 0, 0, 0, 0, 0, 0, 0]);
///
/// assert_eq!(i64::MIN, reader.read_i64().await?);
/// Ok(())
/// }
/// ```
fn read_i64(&mut self) -> ReadI64;
/// Reads an unsigned 128-bit integer in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u128(&mut self) -> io::Result<u128>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 128-bit big-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![
/// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83,
/// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
/// ]);
///
/// assert_eq!(16947640962301618749969007319746179, reader.read_u128().await?);
/// Ok(())
/// }
/// ```
fn read_u128(&mut self) -> ReadU128;
/// Reads an signed 128-bit integer in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i128(&mut self) -> io::Result<i128>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read signed 128-bit big-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![
/// 0x80, 0, 0, 0, 0, 0, 0, 0,
/// 0, 0, 0, 0, 0, 0, 0, 0
/// ]);
///
/// assert_eq!(i128::MIN, reader.read_i128().await?);
/// Ok(())
/// }
/// ```
fn read_i128(&mut self) -> ReadI128;
/// Reads an 32-bit floating point type in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_f32(&mut self) -> io::Result<f32>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read 32-bit floating point type from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0xff, 0x7f, 0xff, 0xff]);
///
/// assert_eq!(f32::MIN, reader.read_f32().await?);
/// Ok(())
/// }
/// ```
fn read_f32(&mut self) -> ReadF32;
/// Reads an 64-bit floating point type in big-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_f64(&mut self) -> io::Result<f64>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read 64-bit floating point type from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![
/// 0xff, 0xef, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
/// ]);
///
/// assert_eq!(f64::MIN, reader.read_f64().await?);
/// Ok(())
/// }
/// ```
fn read_f64(&mut self) -> ReadF64;
/// Reads an unsigned 16-bit integer in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u16_le(&mut self) -> io::Result<u16>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 16 bit little-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![2, 5, 3, 0]);
///
/// assert_eq!(1282, reader.read_u16_le().await?);
/// assert_eq!(3, reader.read_u16_le().await?);
/// Ok(())
/// }
/// ```
fn read_u16_le(&mut self) -> ReadU16Le;
/// Reads a signed 16-bit integer in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i16_le(&mut self) -> io::Result<i16>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read signed 16 bit little-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0x00, 0xc1, 0xff, 0x7c]);
///
/// assert_eq!(-16128, reader.read_i16_le().await?);
/// assert_eq!(31999, reader.read_i16_le().await?);
/// Ok(())
/// }
/// ```
fn read_i16_le(&mut self) -> ReadI16Le;
/// Reads an unsigned 32-bit integer in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u32_le(&mut self) -> io::Result<u32>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 32-bit little-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0x00, 0x00, 0x01, 0x0b]);
///
/// assert_eq!(184614912, reader.read_u32_le().await?);
/// Ok(())
/// }
/// ```
fn read_u32_le(&mut self) -> ReadU32Le;
/// Reads a signed 32-bit integer in little-endian order from the
/// underlying reader.
///
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i32_le(&mut self) -> io::Result<i32>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read signed 32-bit little-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7a, 0x33]);
///
/// assert_eq!(863698943, reader.read_i32_le().await?);
/// Ok(())
/// }
/// ```
fn read_i32_le(&mut self) -> ReadI32Le;
/// Reads an unsigned 64-bit integer in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u64_le(&mut self) -> io::Result<u64>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 64-bit little-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![
/// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
/// ]);
///
/// assert_eq!(9477368352180732672, reader.read_u64_le().await?);
/// Ok(())
/// }
/// ```
fn read_u64_le(&mut self) -> ReadU64Le;
/// Reads an signed 64-bit integer in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i64_le(&mut self) -> io::Result<i64>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read signed 64-bit little-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0x80, 0, 0, 0, 0, 0, 0, 0]);
///
/// assert_eq!(128, reader.read_i64_le().await?);
/// Ok(())
/// }
/// ```
fn read_i64_le(&mut self) -> ReadI64Le;
/// Reads an unsigned 128-bit integer in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_u128_le(&mut self) -> io::Result<u128>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read unsigned 128-bit little-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![
/// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83,
/// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
/// ]);
///
/// assert_eq!(174826588484952389081207917399662330624, reader.read_u128_le().await?);
/// Ok(())
/// }
/// ```
fn read_u128_le(&mut self) -> ReadU128Le;
/// Reads an signed 128-bit integer in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_i128_le(&mut self) -> io::Result<i128>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read signed 128-bit little-endian integers from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![
/// 0x80, 0, 0, 0, 0, 0, 0, 0,
/// 0, 0, 0, 0, 0, 0, 0, 0
/// ]);
///
/// assert_eq!(128, reader.read_i128_le().await?);
/// Ok(())
/// }
/// ```
fn read_i128_le(&mut self) -> ReadI128Le;
/// Reads an 32-bit floating point type in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_f32_le(&mut self) -> io::Result<f32>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read 32-bit floating point type from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7f, 0xff]);
///
/// assert_eq!(f32::MIN, reader.read_f32_le().await?);
/// Ok(())
/// }
/// ```
fn read_f32_le(&mut self) -> ReadF32Le;
/// Reads an 64-bit floating point type in little-endian order from the
/// underlying reader.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_f64_le(&mut self) -> io::Result<f64>;
/// ```
///
/// It is recommended to use a buffered reader to avoid excessive
/// syscalls.
///
/// # Errors
///
/// This method returns the same errors as [`AsyncReadExt::read_exact`].
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Examples
///
/// Read 64-bit floating point type from a `AsyncRead`:
///
/// ```rust
/// use tokio::io::{self, AsyncReadExt};
///
/// use std::io::Cursor;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut reader = Cursor::new(vec![
/// 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xef, 0xff
/// ]);
///
/// assert_eq!(f64::MIN, reader.read_f64_le().await?);
/// Ok(())
/// }
/// ```
fn read_f64_le(&mut self) -> ReadF64Le;
}
/// Reads all bytes until EOF in this source, placing them into `buf`.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize>;
/// ```
///
/// All bytes read from this source will be appended to the specified
/// buffer `buf`. This function will continuously call [`read()`] to
/// append more data to `buf` until [`read()`] returns `Ok(0)`.
///
/// If successful, the total number of bytes read is returned.
///
/// [`read()`]: AsyncReadExt::read
///
/// # Errors
///
/// If a read error is encountered then the `read_to_end` operation
/// immediately completes. Any bytes which have already been read will
/// be appended to `buf`.
///
/// # Examples
///
/// [`File`][crate::fs::File]s implement `Read`:
///
/// ```no_run
/// use tokio::io::{self, AsyncReadExt};
/// use tokio::fs::File;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut f = File::open("foo.txt").await?;
/// let mut buffer = Vec::new();
///
/// // read the whole file
/// f.read_to_end(&mut buffer).await?;
/// Ok(())
/// }
/// ```
///
/// (See also the [`tokio::fs::read`] convenience function for reading from a
/// file.)
///
/// [`tokio::fs::read`]: fn@crate::fs::read
fn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self>
where
Self: Unpin,
{
read_to_end(self, buf)
}
/// Reads all bytes until EOF in this source, appending them to `buf`.
///
/// Equivalent to:
///
/// ```ignore
/// async fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize>;
/// ```
///
/// If successful, the number of bytes which were read and appended to
/// `buf` is returned.
///
/// # Errors
///
/// If the data in this stream is *not* valid UTF-8 then an error is
/// returned and `buf` is unchanged.
///
/// See [`read_to_end`][AsyncReadExt::read_to_end] for other error semantics.
///
/// # Examples
///
/// [`File`][crate::fs::File]s implement `Read`:
///
/// ```no_run
/// use tokio::io::{self, AsyncReadExt};
/// use tokio::fs::File;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut f = File::open("foo.txt").await?;
/// let mut buffer = String::new();
///
/// f.read_to_string(&mut buffer).await?;
/// Ok(())
/// }
/// ```
///
/// (See also the [`crate::fs::read_to_string`] convenience function for
/// reading from a file.)
///
/// [`crate::fs::read_to_string`]: fn@crate::fs::read_to_string
fn read_to_string<'a>(&'a mut self, dst: &'a mut String) -> ReadToString<'a, Self>
where
Self: Unpin,
{
read_to_string(self, dst)
}
/// Creates an adaptor which reads at most `limit` bytes from it.
///
/// This function returns a new instance of `AsyncRead` which will read
/// at most `limit` bytes, after which it will always return EOF
/// (`Ok(0)`). Any read errors will not count towards the number of
/// bytes read and future calls to [`read()`] may succeed.
///
/// [`read()`]: fn@crate::io::AsyncReadExt::read
///
/// [read]: AsyncReadExt::read
///
/// # Examples
///
/// [`File`][crate::fs::File]s implement `Read`:
///
/// ```no_run
/// use tokio::io::{self, AsyncReadExt};
/// use tokio::fs::File;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let f = File::open("foo.txt").await?;
/// let mut buffer = [0; 5];
///
/// // read at most five bytes
/// let mut handle = f.take(5);
///
/// handle.read(&mut buffer).await?;
/// Ok(())
/// }
/// ```
fn take(self, limit: u64) -> Take<Self>
where
Self: Sized,
{
take(self, limit)
}
}
}
impl<R: AsyncRead + ?Sized> AsyncReadExt for R {}