Provided Methods

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

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 equivalently to a single call to read with concatenated buffers.

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

fn is_read_vectored(self: &Self) -> bool

Determines if this Reader has an efficient read_vectored implementation.

If a Reader does not override the default read_vectored implementation, code using it may want to avoid the method all together and coalesce writes into a single buffer for higher performance.

The default implementation returns false.

fn read_to_end(self: &mut Self, buf: &mut Vec<u8>) -> Result<usize>

Reads all bytes until EOF in this source, placing them into buf.

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 either Ok(0) or an error of non-ErrorKind::Interrupted kind.

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

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. Any bytes which have already been read will be appended to buf.

Examples

Files implement Read:

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

fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt")?;
    let mut buffer = Vec::new();

    // read the whole file
    f.read_to_end(&mut buffer)?;
    Ok(())
}

(See also the std::fs::read convenience function for reading from a file.)

Implementing read_to_end

When implementing the io::Read trait, it is recommended to allocate memory using Vec::try_reserve. However, this behavior is not guaranteed by all implementations, and read_to_end may not handle out-of-memory situations gracefully.

# use std::io::{self, BufRead};
# struct Example { example_datasource: io::Empty } impl Example {
# fn get_some_data_for_the_example(&self) -> &'static [u8] { &[] }
fn read_to_end(&mut self, dest_vec: &mut Vec<u8>) -> io::Result<usize> {
    let initial_vec_len = dest_vec.len();
    loop {
        let src_buf = self.example_datasource.fill_buf()?;
        if src_buf.is_empty() {
            break;
        }
        dest_vec.try_reserve(src_buf.len())?;
        dest_vec.extend_from_slice(src_buf);

        // Any irreversible side effects should happen after `try_reserve` succeeds,
        // to avoid losing data on allocation error.
        let read = src_buf.len();
        self.example_datasource.consume(read);
    }
    Ok(dest_vec.len() - initial_vec_len)
}
# }

Usage Notes

read_to_end attempts to read a source until EOF, but many sources are continuous streams that do not send EOF. In these cases, read_to_end will block indefinitely. Standard input is one such stream which may be finite if piped, but is typically continuous. For example, cat file | my-rust-program will correctly terminate with an EOF upon closure of cat. Reading user input or running programs that remain open indefinitely will never terminate the stream with EOF (e.g. yes | my-rust-program).

Using .lines() with a BufReader or using read can provide a better solution

fn read_to_string(self: &mut Self, buf: &mut String) -> Result<usize>

Reads all bytes until EOF in this source, appending them to buf.

If successful, this function returns the number of bytes which were read and appended to buf.

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 for other error semantics.

Examples

Files implement Read:

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

fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt")?;
    let mut buffer = String::new();

    f.read_to_string(&mut buffer)?;
    Ok(())
}

(See also the std::fs::read_to_string convenience function for reading from a file.)

Usage Notes

read_to_string attempts to read a source until EOF, but many sources are continuous streams that do not send EOF. In these cases, read_to_string will block indefinitely. Standard input is one such stream which may be finite if piped, but is typically continuous. For example, cat file | my-rust-program will correctly terminate with an EOF upon closure of cat. Reading user input or running programs that remain open indefinitely will never terminate the stream with EOF (e.g. yes | my-rust-program).

Using .lines() with a BufReader or using read can provide a better solution

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

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.

Implementations of this method can make no assumptions about the contents of buf when this function is called. It is recommended that implementations only write data to buf instead of reading its contents. The documentation on read has a more detailed explanation of this subject.

Errors

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

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

Files implement Read:

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

fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt")?;
    let mut buffer = [0; 10];

    // read exactly 10 bytes
    f.read_exact(&mut buffer)?;
    Ok(())
}

fn read_buf(self: &mut Self, buf: BorrowedCursor<'_>) -> Result<()>

Pull some bytes from this source into the specified buffer.

This is equivalent to the read method, except that it is passed a BorrowedCursor rather than [u8] to allow use with uninitialized buffers. The new data will be appended to any existing contents of buf.

The default implementation delegates to read.

This method makes it possible to return both data and an error but it is advised against.

fn read_buf_exact(self: &mut Self, cursor: BorrowedCursor<'_>) -> Result<()>

Reads the exact number of bytes required to fill cursor.

This is similar to the read_exact method, except that it is passed a BorrowedCursor rather than [u8] to allow use with uninitialized buffers.

Errors

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

If this function encounters an "end of file" before completely filling the buffer, it returns an error of the kind ErrorKind::UnexpectedEof.

If any other read error is encountered then this function immediately returns.

If this function returns an error, all bytes read will be appended to cursor.

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

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

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

Examples

Files implement Read:

use std::io;
use std::io::Read;
use std::fs::File;

fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt")?;
    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)?;

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

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

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

Transforms this Read instance to an Iterator over its bytes.

The returned type implements Iterator 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.

The default implementation calls read for each byte, which can be very inefficient for data that's not in memory, such as File. Consider using a BufReader in such cases.

Examples

Files implement Read:

use std::io;
use std::io::prelude::*;
use std::io::BufReader;
use std::fs::File;

fn main() -> io::Result<()> {
    let f = BufReader::new(File::open("foo.txt")?);

    for byte in f.bytes() {
        println!("{}", byte?);
    }
    Ok(())
}

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

Creates an adapter 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 std::io;
use std::io::prelude::*;
use std::fs::File;

fn main() -> io::Result<()> {
    let f1 = File::open("foo.txt")?;
    let f2 = File::open("bar.txt")?;

    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)?;
    Ok(())
}

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

Creates an adapter 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 std::io;
use std::io::prelude::*;
use std::fs::File;

fn main() -> io::Result<()> {
    let f = File::open("foo.txt")?;
    let mut buffer = [0; 5];

    // read at most five bytes
    let mut handle = f.take(5);

    handle.read(&mut buffer)?;
    Ok(())
}

fn read_array<N: usize>(self: &mut Self) -> Result<[u8; N]>
where
    Self: Sized

Read and return a fixed array of bytes from this source.

This function uses an array sized based on a const generic size known at compile time. You can specify the size with turbofish (reader.read_array::<8>()), or let type inference determine the number of bytes needed based on how the return value gets used. For instance, this function works well with functions like u64::from_le_bytes to turn an array of bytes into an integer of the same size.

Like read_exact, if this function encounters an "end of file" before reading the desired number of bytes, it returns an error of the kind ErrorKind::UnexpectedEof.

#![feature(read_array)]
use std::io::Cursor;
use std::io::prelude::*;

fn main() -> std::io::Result<()> {
    let mut buf = Cursor::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 8, 7, 6, 5, 4, 3, 2]);
    let x = u64::from_le_bytes(buf.read_array()?);
    let y = u32::from_be_bytes(buf.read_array()?);
    let z = u16::from_be_bytes(buf.read_array()?);
    assert_eq!(x, 0x807060504030201);
    assert_eq!(y, 0x9080706);
    assert_eq!(z, 0x504);
    Ok(())
}