pub trait AsyncReadExt: AsyncRead {
// Provided methods
fn chain<R>(self, next: R) -> Chain<Self, R>
where Self: Sized,
R: AsyncRead { ... }
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self> ⓘ
where Self: Unpin { ... }
fn read_vectored<'a>(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>],
) -> ReadVectored<'a, Self> ⓘ
where Self: Unpin { ... }
fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self> ⓘ
where Self: Unpin { ... }
fn read_to_end<'a>(
&'a mut self,
buf: &'a mut Vec<u8>,
) -> ReadToEnd<'a, Self> ⓘ
where Self: Unpin { ... }
fn read_to_string<'a>(
&'a mut self,
buf: &'a mut String,
) -> ReadToString<'a, Self> ⓘ
where Self: Unpin { ... }
fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>)
where Self: AsyncWrite + Sized { ... }
fn take(self, limit: u64) -> Take<Self>
where Self: Sized { ... }
}
Expand description
An extension trait which adds utility methods to AsyncRead
types.
Provided Methods§
Sourcefn chain<R>(self, next: R) -> Chain<Self, R>
fn chain<R>(self, next: R) -> Chain<Self, R>
Creates an adaptor which will chain this stream with another.
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
use futures::io::{AsyncReadExt, Cursor};
let reader1 = Cursor::new([1, 2, 3, 4]);
let reader2 = Cursor::new([5, 6, 7, 8]);
let mut reader = reader1.chain(reader2);
let mut buffer = Vec::new();
// read the value into a Vec.
reader.read_to_end(&mut buffer).await?;
assert_eq!(buffer, [1, 2, 3, 4, 5, 6, 7, 8]);
Sourcefn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self> ⓘwhere
Self: Unpin,
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self> ⓘwhere
Self: Unpin,
Tries to read some bytes directly into the given buf
in asynchronous
manner, returning a future type.
The returned future will resolve to the number of bytes read once the read operation is completed.
§Examples
use futures::io::{AsyncReadExt, Cursor};
let mut reader = Cursor::new([1, 2, 3, 4]);
let mut output = [0u8; 5];
let bytes = reader.read(&mut output[..]).await?;
// This is only guaranteed to be 4 because `&[u8]` is a synchronous
// reader. In a real system you could get anywhere from 1 to
// `output.len()` bytes in a single read.
assert_eq!(bytes, 4);
assert_eq!(output, [1, 2, 3, 4, 0]);
Sourcefn read_vectored<'a>(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>],
) -> ReadVectored<'a, Self> ⓘwhere
Self: Unpin,
fn read_vectored<'a>(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>],
) -> ReadVectored<'a, Self> ⓘwhere
Self: Unpin,
Creates a future which will read from the AsyncRead
into bufs
using vectored
IO operations.
The returned future will resolve to the number of bytes read once the read operation is completed.
Sourcefn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self> ⓘwhere
Self: Unpin,
fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self> ⓘwhere
Self: Unpin,
Creates a future which will read exactly enough bytes to fill buf
,
returning an error if end of file (EOF) is hit sooner.
The returned future will resolve once the read operation is completed.
In the case of an error the buffer and the object will be discarded, with the error yielded.
§Examples
use futures::io::{AsyncReadExt, Cursor};
let mut reader = Cursor::new([1, 2, 3, 4]);
let mut output = [0u8; 4];
reader.read_exact(&mut output).await?;
assert_eq!(output, [1, 2, 3, 4]);
§EOF is hit before buf
is filled
use futures::io::{self, AsyncReadExt, Cursor};
let mut reader = Cursor::new([1, 2, 3, 4]);
let mut output = [0u8; 5];
let result = reader.read_exact(&mut output).await;
assert_eq!(result.unwrap_err().kind(), io::ErrorKind::UnexpectedEof);
Sourcefn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self> ⓘwhere
Self: Unpin,
fn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self> ⓘwhere
Self: Unpin,
Creates a future which will read all the bytes from this AsyncRead
.
On success the total number of bytes read is returned.
§Examples
use futures::io::{AsyncReadExt, Cursor};
let mut reader = Cursor::new([1, 2, 3, 4]);
let mut output = Vec::with_capacity(4);
let bytes = reader.read_to_end(&mut output).await?;
assert_eq!(bytes, 4);
assert_eq!(output, vec![1, 2, 3, 4]);
Sourcefn read_to_string<'a>(
&'a mut self,
buf: &'a mut String,
) -> ReadToString<'a, Self> ⓘwhere
Self: Unpin,
fn read_to_string<'a>(
&'a mut self,
buf: &'a mut String,
) -> ReadToString<'a, Self> ⓘwhere
Self: Unpin,
Creates a future which will read all the bytes from this AsyncRead
.
On success the total number of bytes read is returned.
§Examples
use futures::io::{AsyncReadExt, Cursor};
let mut reader = Cursor::new(&b"1234"[..]);
let mut buffer = String::with_capacity(4);
let bytes = reader.read_to_string(&mut buffer).await?;
assert_eq!(bytes, 4);
assert_eq!(buffer, String::from("1234"));
Sourcefn split(self) -> (ReadHalf<Self>, WriteHalf<Self>)where
Self: AsyncWrite + Sized,
fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>)where
Self: AsyncWrite + Sized,
Helper method for splitting this read/write object into two halves.
The two halves returned implement the AsyncRead
and AsyncWrite
traits, respectively.
§Examples
use futures::io::{self, AsyncReadExt, Cursor};
// Note that for `Cursor` the read and write halves share a single
// seek position. This may or may not be true for other types that
// implement both `AsyncRead` and `AsyncWrite`.
let reader = Cursor::new([1, 2, 3, 4]);
let mut buffer = Cursor::new(vec![0, 0, 0, 0, 5, 6, 7, 8]);
let mut writer = Cursor::new(vec![0u8; 5]);
{
let (buffer_reader, mut buffer_writer) = (&mut buffer).split();
io::copy(reader, &mut buffer_writer).await?;
io::copy(buffer_reader, &mut writer).await?;
}
assert_eq!(buffer.into_inner(), [1, 2, 3, 4, 5, 6, 7, 8]);
assert_eq!(writer.into_inner(), [5, 6, 7, 8, 0]);
Sourcefn take(self, limit: u64) -> Take<Self>where
Self: Sized,
fn take(self, limit: u64) -> Take<Self>where
Self: Sized,
Creates an AsyncRead adapter which will read at most limit
bytes
from the underlying reader.
§Examples
use futures::io::{AsyncReadExt, Cursor};
let reader = Cursor::new(&b"12345678"[..]);
let mut buffer = [0; 5];
let mut take = reader.take(4);
let n = take.read(&mut buffer).await?;
assert_eq!(n, 4);
assert_eq!(&buffer, b"1234\0");
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.