Trait futures::io::AsyncReadExt

pub trait AsyncReadExt: AsyncRead {
    fn chain<R>(self, next: R) -> Chain<Self, R>
    where
        R: AsyncRead,
    { ... }
    fn copy_into<W>(self, writer: &mut W) -> CopyInto<Self, W>
    where
        W: AsyncWrite + Unpin + ?Sized,
    { ... }
    fn read(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>
    where
        Self: Unpin,
    { ... }
    fn read_vectored(
        &'a mut self, 
        bufs: &'a mut [IoSliceMut<'a>]
    ) -> ReadVectored<'a, Self>
    where
        Self: Unpin,
    { ... }
    fn read_exact(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>
    where
        Self: Unpin,
    { ... }
    fn read_to_end(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self>
    where
        Self: Unpin,
    { ... }
    fn read_to_string(
        &'a mut self, 
        buf: &'a mut String
    ) -> ReadToString<'a, Self>
    where
        Self: Unpin,
    { ... }
    fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>)
    where
        Self: AsyncWrite,
    { ... }
    fn take(self, limit: u64) -> Take<Self> { ... }
    fn compat(self) -> Compat<Self>
    where
        Self: Unpin,
    { ... }
}

An extension trait which adds utility methods to AsyncRead types.

Provided methods

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: AsyncRead, 

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;
use std::io::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]);

Important traits for CopyInto<'_, R, W>

impl<'_, R, W> Future for CopyInto<'_, R, W> where
    R: AsyncRead,
    W: Unpin + AsyncWrite + ?Sized,  type Output = Result<u64, Error>;

fn copy_into<W>(self, writer: &mut W) -> CopyInto<Self, W> where
    W: AsyncWrite + Unpin + ?Sized, 

Creates a future which copies all the bytes from one object to another.

The returned future will copy all the bytes read from this AsyncRead into the writer specified. This future will only complete once the reader has hit EOF and all bytes have been written to and flushed from the writer provided.

On success the number of bytes is returned.

Examples

use futures::io::{AsyncReadExt, AsyncWriteExt};
use std::io::Cursor;

let reader = Cursor::new([1, 2, 3, 4]);
let mut writer = Cursor::new([0u8; 5]);

let bytes = reader.copy_into(&mut writer).await?;
writer.close().await?;

assert_eq!(bytes, 4);
assert_eq!(writer.into_inner(), [1, 2, 3, 4, 0]);

Important traits for Read<'_, R>

impl<'_, R> Future for Read<'_, R> where
    R: Unpin + AsyncRead + ?Sized,  type Output = Result<usize, Error>;

fn read(&'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;
use std::io::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]);

Important traits for ReadVectored<'_, R>

impl<'_, R> Future for ReadVectored<'_, R> where
    R: Unpin + AsyncRead + ?Sized,  type Output = Result<usize, Error>;

fn read_vectored(
    &'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.

Important traits for ReadExact<'_, R>

impl<'_, R> Future for ReadExact<'_, R> where
    R: Unpin + AsyncRead + ?Sized,  type Output = Result<(), Error>;

fn read_exact(&'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;
use std::io::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::AsyncReadExt;
use std::io::{self, 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);

Important traits for ReadToEnd<'_, A>

impl<'_, A> Future for ReadToEnd<'_, A> where
    A: AsyncRead + Unpin + ?Sized,  type Output = Result<usize, Error>;

fn read_to_end(&'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;
use std::io::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]);

Important traits for ReadToString<'_, A>

impl<'_, A> Future for ReadToString<'_, A> where
    A: AsyncRead + Unpin + ?Sized,  type Output = Result<usize, Error>;

fn read_to_string(&'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;
use std::io::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"));

fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>) where
    Self: AsyncWrite, 

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::AsyncReadExt;
use std::io::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([0, 0, 0, 0, 5, 6, 7, 8]);
let mut writer = Cursor::new([0u8; 5]);

{
    let (buffer_reader, mut buffer_writer) = (&mut buffer).split();
    reader.copy_into(&mut buffer_writer).await?;
    buffer_reader.copy_into(&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]);

fn take(self, limit: u64) -> Take<Self>

Creates an AsyncRead adapter which will read at most limit bytes from the underlying reader.

Examples

use futures::io::AsyncReadExt;
use std::io::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");

Important traits for Compat<W>

impl<W> Write for Compat<W> where
    W: Unpin + AsyncWrite, impl<R> Read for Compat<R> where
    R: Unpin + AsyncRead, 

fn compat(self) -> Compat<Self> where
    Self: Unpin, 

Wraps an AsyncRead in a compatibility wrapper that allows it to be used as a futures 0.1 / tokio-io 0.1 AsyncRead. If the wrapped type implements AsyncWrite as well, the result will also implement the futures 0.1 / tokio 0.1 AsyncWrite trait.

Requires the io-compat feature to enable.

Loading content...

Implementors

impl<R> AsyncReadExt for R where
    R: AsyncRead + ?Sized, 

Loading content...