[−][src]Trait async_std::io::Read

pub trait Read {
    fn poll_read(
        self: Pin<&mut Self>, 
        cx: &mut Context, 
        buf: &mut [u8]
    ) -> Poll<Result<usize>>;

    fn poll_read_vectored(
        self: Pin<&mut Self>, 
        cx: &mut Context, 
        bufs: &mut [IoSliceMut]
    ) -> Poll<Result<usize>> { ... }

    fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> ImplFuture<Result<usize>>
    where
        Self: Unpin,
    { ... }

    fn read_vectored<'a>(
        &'a mut self, 
        bufs: &'a mut [IoSliceMut<'a>]
    ) -> ImplFuture<Result<usize>>
    where
        Self: Unpin,
    { ... }

    fn read_to_end<'a>(
        &'a mut self, 
        buf: &'a mut Vec<u8>
    ) -> ImplFuture<Result<usize>>
    where
        Self: Unpin,
    { ... }

    fn read_to_string<'a>(
        &'a mut self, 
        buf: &'a mut String
    ) -> ImplFuture<Result<usize>>
    where
        Self: Unpin,
    { ... }

    fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ImplFuture<Result<()>>
    where
        Self: Unpin,
    { ... }

    fn take(self, limit: u64) -> Take<Self>
    where
        Self: Sized,
    { ... }

    fn by_ref(&mut self) -> &mut Self
    where
        Self: Sized,
    { ... }

    fn bytes(self) -> Bytes<Self>
    where
        Self: Sized,
    { ... }

    fn chain<R: Read>(self, next: R) -> Chain<Self, R>
    where
        Self: Sized,
    { ... }
}

Allows reading from a byte stream.

This trait is a re-export of futures::io::AsyncRead and is an async version of std::io::Read.

Methods other than poll_read and poll_read_vectored do not really exist in the trait itself, but they become available when ReadExt from the prelude is imported:

use async_std::prelude::*;

Required methods

fn poll_read(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &mut [u8]
) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

Loading content...

Provided methods

fn poll_read_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &mut [IoSliceMut]
) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> ImplFuture<Result<usize>> where
    Self: Unpin, 

Reads some bytes from the byte stream.

Returns the number of bytes read from the start of the buffer.

If the return value is Ok(n), then it must be guaranteed that 0 <= n <= buf.len(). A nonzero n value indicates that the buffer has been filled in with n bytes of data. 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.

Examples

use async_std::fs::File;
use async_std::prelude::*;

let mut file = File::open("a.txt").await?;

let mut buf = vec![0; 1024];
let n = file.read(&mut buf).await?;

fn read_vectored<'a>(
    &'a mut self,
    bufs: &'a mut [IoSliceMut<'a>]
) -> ImplFuture<Result<usize>> where
    Self: Unpin, 

Like read, except that it reads into a slice of buffers.

Data is copied to fill each buffer in order, with the final buffer written to possibly being only partially filled. This method must behave as a single call to read with the buffers concatenated would.

The default implementation calls read with either the first nonempty buffer provided, or an empty one if none exists.

fn read_to_end<'a>(
    &'a mut self,
    buf: &'a mut Vec<u8>
) -> ImplFuture<Result<usize>> where
    Self: Unpin, 

Reads all bytes from the byte stream.

All bytes read from this stream will be appended to the specified buffer buf. This function will continuously call read to append more data to buf until read returns either Ok(0) or an error.

If successful, this function will return the total number of bytes read.

Examples

use async_std::fs::File;
use async_std::prelude::*;

let mut file = File::open("a.txt").await?;

let mut buf = Vec::new();
file.read_to_end(&mut buf).await?;

fn read_to_string<'a>(
    &'a mut self,
    buf: &'a mut String
) -> ImplFuture<Result<usize>> where
    Self: Unpin, 

Reads all bytes from the byte stream and appends them into a string.

If successful, this function will return the number of bytes read.

If the data in this stream is not valid UTF-8 then an error will be returned and buf will be left unmodified.

Examples

use async_std::fs::File;
use async_std::prelude::*;

let mut file = File::open("a.txt").await?;

let mut buf = String::new();
file.read_to_string(&mut buf).await?;

fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ImplFuture<Result<()>> where
    Self: Unpin, 

Reads the exact number of bytes required to fill buf.

This function reads as many bytes as necessary to completely fill the specified buffer buf.

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.

If this function 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 this function immediately returns. The contents of buf are unspecified in this case.

If this function 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.

Examples

use async_std::fs::File;
use async_std::prelude::*;

let mut file = File::open("a.txt").await?;

let mut buf = vec![0; 10];
file.read_exact(&mut buf).await?;

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

Creates an adaptor which will read at most limit bytes from it.

This function returns a new instance of Read 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.

Examples

Files implement Read:

use async_std::io::prelude::*;
use async_std::fs::File;

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?;

fn by_ref(&mut self) -> &mut Self where
    Self: Sized, 

Creates a "by reference" adaptor for this instance of Read.

The returned adaptor also implements Read and will simply borrow this current reader.

Examples

Files implement Read:

use async_std::prelude::*;
use async_std::fs::File;

let mut f = File::open("foo.txt").await?;
let mut buffer = Vec::new();
let mut other_buffer = Vec::new();

{
    let reference = f.by_ref();

    // read at most 5 bytes
    reference.take(5).read_to_end(&mut buffer).await?;

} // drop our &mut reference so we can use f again

// original file still usable, read the rest
f.read_to_end(&mut other_buffer).await?;

fn bytes(self) -> Bytes<Self> where
    Self: Sized, 

Transforms this Read instance to a Stream over its bytes.

The returned type implements Stream where the Item is Result<u8, io::Error>. The yielded item is Ok if a byte was successfully read and Err otherwise. EOF is mapped to returning None from this iterator.

Examples

Files implement Read:

use async_std::prelude::*;
use async_std::fs::File;

let f = File::open("foo.txt").await?;
let mut s = f.bytes();

while let Some(byte) = s.next().await {
    println!("{}", byte.unwrap());
}

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

Creates an adaptor which will chain this stream with another.

The returned Read instance will first read all bytes from this object until EOF is encountered. Afterwards the output is equivalent to the output of next.

Examples

Files implement Read:

use async_std::prelude::*;
use async_std::fs::File;

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 Read method here,
// this is just one example.
handle.read_to_string(&mut buffer).await?;
Loading content...

Implementations on Foreign Types

impl<T: Read + Unpin + ?Sized> Read for Box<T>[src]

impl<'_, T: Read + Unpin + ?Sized> Read for &'_ mut T[src]

impl<'_> Read for &'_ [u8][src]

Loading content...

Implementors

impl Read for File[src]

impl Read for Empty[src]

impl Read for Repeat[src]

impl Read for Stdin[src]

impl Read for TcpStream[src]

impl Read for UnixStream[src]

impl<'_> Read for &'_ File[src]

impl<'_> Read for &'_ TcpStream[src]

impl<'_> Read for &'_ UnixStream[src]

impl<'_> Read for StdinLock<'_>[src]

impl<P> Read for Pin<P> where
    P: DerefMut + Unpin,
    <P as Deref>::Target: Read, [src]

impl<R: Read> Read for BufReader<R>[src]

impl<T> Read for Cursor<T> where
    T: AsRef<[u8]> + Unpin, [src]

Loading content...