std::io::BufReader - Rust
Description: API documentation for the Rust `BufReader` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, BufReader

# Struct std::io::BufReader 1.0.0 [−] [src]

    pub struct BufReader<R> { /* fields omitted */ }

The `BufReader` struct adds buffering to any reader.

It can be excessively inefficient to work directly with a `Read` instance. For example, every call to `read` on `TcpStream` results in a system call. A `BufReader` performs large, infrequent reads on the underlying `Read` and maintains an in-memory buffer of the results.

# Examples

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

    let mut f = File::open("log.txt")?;
    let mut reader = BufReader::new(f);

    let mut line = String::new();
    let len = reader.read_line(&mut line)?;
    println!("First line is {} bytes long", len);Run

## Methods

### `impl<R: Read> BufReader<R>`
[src]

#### `fn new(inner: R) -> BufReader<R>`

Creates a new `BufReader` with a default buffer capacity.

# Examples

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

    let mut f = File::open("log.txt")?;
    let mut reader = BufReader::new(f);Run

#### `fn with_capacity(cap: usize, inner: R) -> BufReader<R>`

Creates a new `BufReader` with the specified buffer capacity.

# Examples

Creating a buffer with ten bytes of capacity:

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

    let mut f = File::open("log.txt")?;
    let mut reader = BufReader::with_capacity(10, f);Run

#### `fn get_ref(&self) -> &R`

Gets a reference to the underlying reader.

It is inadvisable to directly read from the underlying reader.

# Examples

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

    let mut f1 = File::open("log.txt")?;
    let mut reader = BufReader::new(f1);

    let f2 = reader.get_ref();Run

#### `fn get_mut(&mut self) -> &mut R`

Gets a mutable reference to the underlying reader.

It is inadvisable to directly read from the underlying reader.

# Examples

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

    let mut f1 = File::open("log.txt")?;
    let mut reader = BufReader::new(f1);

    let f2 = reader.get_mut();Run

#### `fn into_inner(self) -> R`

Unwraps this `BufReader`, returning the underlying reader.

Note that any leftover data in the internal buffer is lost.

# Examples

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

    let mut f1 = File::open("log.txt")?;
    let mut reader = BufReader::new(f1);

    let f2 = reader.into_inner();Run

## Trait Implementations

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

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

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

#### `unsafe fn initializer(&self) -> Initializer`

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

Determines if this `Read`er can work with buffers of uninitialized memory. Read more

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

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

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

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

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

Read the exact number of bytes required to fill `buf`. Read more

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

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

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

Transforms this `Read` instance to an `Iterator` over its bytes. Read more

#### `fn chars(self) -> Chars<Self> 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 `char`s. Read more

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

Creates an adaptor which will chain this stream with another. Read more

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

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

### `impl<R: Read> BufRead for BufReader<R>`
[src]

#### `fn fill_buf(&mut self) -> Result<&[u8]>`

Fills the internal buffer of this object, returning the buffer contents. Read more

#### `fn consume(&mut self, amt: usize)`

Tells this buffer that `amt` bytes have been consumed from the buffer, so they should no longer be returned in calls to `read`. Read more

#### `fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize>`

Read all bytes into `buf` until the delimiter `byte` or EOF is reached. Read more

#### `fn read_line(&mut self, buf: &mut String) -> Result<usize>`

Read all bytes until a newline (the 0xA byte) is reached, and append them to the provided buffer. Read more

#### `fn split(self, byte: u8) -> Split<Self> where
Self: Sized,`

Returns an iterator over the contents of this reader split on the byte `byte`. Read more

#### `fn lines(self) -> Lines<Self> where
Self: Sized,`

Returns an iterator over the lines of this reader. Read more

### `impl<R> Debug for BufReader<R> where
R: Debug,`
[src]

#### `fn fmt(&self, fmt: &mut Formatter) -> Result`

Formats the value using the given formatter.

### `impl<R: Seek> Seek for BufReader<R>`
[src]

#### `fn seek(&mut self, pos: SeekFrom) -> Result<u64>`

Seek to an offset, in bytes, in the underlying reader.

The position used for seeking with `SeekFrom::Current(_)` is the position the underlying reader would be at if the `BufReader` had no internal buffer.

Seeking always discards the internal buffer, even if the seek position would otherwise fall within it. This guarantees that calling `.into_inner()` immediately after a seek yields the underlying reader at the same position.

See `std::io::Seek` for more details.

Note: In the edge case where you're seeking with `SeekFrom::Current(n)` where `n` minus the internal buffer length underflows an `i64`, two seeks will be performed instead of one. If the second seek returns `Err`, the underlying reader will be left at the same position it would have if you seeked to `SeekFrom::Current(0)`.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)