std::io::Read - Rust (original) (raw)

Trait std::io::Read1.0.0 [−] [src]

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

unsafe fn [initializer](#method.initializer)(&self) -> [Initializer](../../std/io/struct.Initializer.html "struct std::io::Initializer") { ... }
fn [read_to_end](#method.read%5Fto%5Fend)(&mut self, buf: &mut [Vec](../../std/vec/struct.Vec.html "struct std::vec::Vec")<[u8](../primitive.u8.html)>) -> [Result](../../std/io/type.Result.html "type std::io::Result")<[usize](../primitive.usize.html)> { ... }
fn [read_to_string](#method.read%5Fto%5Fstring)(&mut self, buf: &mut [String](../../std/string/struct.String.html "struct std:🧵:String")) -> [Result](../../std/io/type.Result.html "type std::io::Result")<[usize](../primitive.usize.html)> { ... }
fn [read_exact](#method.read%5Fexact)(&mut self, buf: [&mut [](../primitive.slice.html)[u8](../primitive.u8.html)[]](../primitive.slice.html)) -> [Result](../../std/io/type.Result.html "type std::io::Result")<[()](../primitive.unit.html)> { ... }
fn [by_ref](#method.by%5Fref)(&mut self) -> [&mut ](../primitive.reference.html)Self

    where
        Self: Sized, { ... } fn bytes(self) -> Bytes
    where
        Self: Sized, { ... } fn chars(self) -> Chars
    where
        Self: Sized, { ... } fn chain<R: Read>(self, next: R) -> Chain<Self, R>
    where
        Self: Sized, { ... } fn take(self, limit: u64) -> Take
    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 std::io take and provide types which implement the Readtrait.

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

Files implement Read:

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

let mut f = File::open("foo.txt")?; let mut buffer = [0; 10];

f.read(&mut buffer)?;

let mut buffer = vec![0; 10];

f.read_to_end(&mut buffer)?;

let mut buffer = String::new(); f.read_to_string(&mut buffer)?;

Run

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

use std::io::prelude::*;

let mut b = "This string will be read".as_bytes(); let mut buffer = [0; 10];

b.read(&mut buffer)?;

Run

fn [read](#tymethod.read)(&mut self, buf: [&mut [](../primitive.slice.html)[u8](../primitive.u8.html)[]](../primitive.slice.html)) -> [Result](../../std/io/type.Result.html "type std::io::Result")<[usize](../primitive.usize.html)>

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

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

Files implement Read:

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

let mut f = File::open("foo.txt")?; let mut buffer = [0; 10];

f.read(&mut buffer[..])?;Run

unsafe fn [initializer](#method.initializer)(&self) -> [Initializer](../../std/io/struct.Initializer.html "struct std::io::Initializer")

🔬 This is a nightly-only experimental API. (read_initializer #42788)

Determines if this Reader can work with buffers of uninitialized memory.

The default implementation returns an initializer which will zero buffers.

If a Reader guarantees that it can work properly with uninitialized memory, it should call Initializer::nop(). See the documentation forInitializer for details.

The behavior of this method must be independent of the state of theReader - the method only takes &self so that it can be used through trait objects.

This method is unsafe because a Reader could otherwise return a non-zeroing Initializer from another Read type without an unsafeblock.

fn [read_to_end](#method.read%5Fto%5Fend)(&mut self, buf: &mut [Vec](../../std/vec/struct.Vec.html "struct std::vec::Vec")<[u8](../primitive.u8.html)>) -> [Result](../../std/io/type.Result.html "type std::io::Result")<[usize](../primitive.usize.html)>

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

All bytes read from this source will be appended to the specified bufferbuf. This function will continuously call read() to append more data tobuf 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.

If this function encounters an error of the kindErrorKind::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 tobuf.

Files implement Read:

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

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

f.read_to_end(&mut buffer)?;Run

fn [read_to_string](#method.read%5Fto%5Fstring)(&mut self, buf: &mut [String](../../std/string/struct.String.html "struct std:🧵:String")) -> [Result](../../std/io/type.Result.html "type std::io::Result")<[usize](../primitive.usize.html)>

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

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.

Files implement Read:

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

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

f.read_to_string(&mut buffer)?;Run

fn [read_exact](#method.read%5Fexact)(&mut self, buf: [&mut [](../primitive.slice.html)[u8](../primitive.u8.html)[]](../primitive.slice.html)) -> [Result](../../std/io/type.Result.html "type std::io::Result")<[()](../primitive.unit.html)>

1.6.0

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.

If this function encounters an error of the kindErrorKind::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.

Files implement Read:

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

let mut f = File::open("foo.txt")?; let mut buffer = [0; 10];

f.read_exact(&mut buffer)?;Run

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

Files implement Read:

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

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

{ let reference = f.by_ref();

reference.take(5).read_to_end(&mut buffer)?;

}

f.read_to_end(&mut other_buffer)?;Run

ⓘImportant traits for Bytes

`fn bytes(self) -> Bytes where

Self: Sized, `

Transforms this Read instance to an Iterator over its bytes.

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

Files implement Read:

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

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

for byte in f.bytes() { println!("{}", byte.unwrap()); }Run

ⓘImportant traits for Chars

`fn chars(self) -> Chars where

Self: Sized, `

🔬 This is a nightly-only experimental API. (io #27802)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an Iterator over chars.

This adaptor will attempt to interpret this reader as a UTF-8 encoded sequence of characters. The returned iterator will return None once EOF is reached for this reader. Otherwise each element yielded will be aResult<char, E> where E may contain information about what I/O error occurred or where decoding failed.

Currently this adaptor will discard intermediate data read, and should be avoided if this is not desired.

Files implement Read:

#![feature(io)] use std::io; use std::io::prelude::*; use std::fs::File;

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

for c in f.chars() { println!("{}", c.unwrap()); }Run

ⓘImportant traits for Chain<T, U>

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

Files implement Read:

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

let mut f1 = File::open("foo.txt")?; let mut f2 = File::open("bar.txt")?;

let mut handle = f1.chain(f2); let mut buffer = String::new();

handle.read_to_string(&mut buffer)?;Run

ⓘImportant traits for Take

`fn take(self, limit: u64) -> Take 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 mostlimit 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.

Files implement Read:

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

let mut f = File::open("foo.txt")?; let mut buffer = [0; 5];

let mut handle = f.take(5);

handle.read(&mut buffer)?;Run