Trait Read

pub trait Read {
    // Required method
    fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>;

    // Provided methods
    fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error> { ... }
    fn by_ref(&mut self) -> &mut Self
       where Self: Sized { ... }
}

The Read trait allows for reading bytes from a source.

Implementors of the Read trait are called ‘readers’.

Readers are defined by one required method, read(). Each call to read() will attempt to pull bytes from this source into a provided buffer. A number of other methods are implemented in terms of read(), giving implementors a number of ways to read bytes while only needing to implement a single method.

Readers are intended to be composable with one another. Many implementors throughout ark_std::io take and provide types which implement the Read trait.

Please note that each call to read() may involve a system call, and therefore, using something that implements BufRead, such as BufReader, will be more efficient.

Read from &str because &[u8] implements Read:

use ark_std::io::prelude::*;

fn main() -> Result<()> {
    let mut b = "This string will be read".as_bytes();
    let mut buffer = [0; 10];

    // read up to 10 bytes
    b.read(&mut buffer)?;

    Ok(())
}

Required Methods

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

This function does not provide any guarantees about whether it blocks waiting for data, but if an object needs to block for a read but cannot it will typically signal this via an Err return value.

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 that the 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.

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.

An error of the ErrorKind::Interrupted kind is non-fatal and the read operation should be retried if there is nothing else to do.

Provided Methods

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read 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.

Errors

If this function encounters an error of the kind ErrorKind::Interrupted then the error is ignored and the operation will continue.

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.

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.

Implementations on Foreign Types

impl Read for &[u8]

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

impl<R> Read for &mut R

where R: Read + ?Sized,

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Implementors

impl<T> Read for Cursor<T>

where T: AsRef<[u8]>,