Trait BufRead

pub trait BufRead: Read {
    // Required methods
    fn fill_buf(&mut self) -> Result<&[u8]>;
    fn consume(&mut self, amt: usize);

    // Provided methods
    fn read_to_end<B>(&mut self, buf: &mut B) -> Result<()>
       where Self: Sized,
             B: Write + ?Sized { ... }
    fn skip_to_end(&mut self) -> Result<()> { ... }
    fn read_exact(&mut self, buf: &mut Cursor<&mut [u8]>) -> Result<()> { ... }
    fn bytes(self) -> Bytes<Self> 
       where Self: Sized { ... }
    fn read_until<W>(&mut self, delim: u8, buf: &mut W) -> Result<()>
       where Self: Sized,
             W: Write + ?Sized { ... }
    fn skip_until(&mut self, delim: u8) -> Result<()> { ... }
    fn split(self, byte: u8) -> Split<Self> 
       where Self: Sized { ... }
}

Alternative to std::io::BufRead

This trait is automatically implemented for all types that implement std::io::BufRead.

Differences to std::io::BufRead

Methods that are just wrappers around the equivalent methods of std::io::BufRead:

• fill_buf
• consume

Methods that provide a slightly different functionality than their counterparts in std::io::BufRead:

• read_until
• split

Methods originally implemented in a different place:

• read_to_end ← std::io::Read::read_to_end
• read_exact ← std::io::Read::read_exact
• bytes ← std::io::Read::bytes

New methods that have no counterpart in std::io:

• skip_to_end
• skip_until

Functions that were removed or moved to a different trait, because they cannot be implemented with providing all desired guarantees:

• read_line → Utf8Reader::read_line

Required Methods

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

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

This method is equivalent to std::io::BufRead::fill_buf.

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.

This method is equivalent to std::io::BufRead::consume.

Provided Methods

fn read_to_end<B>(&mut self, buf: &mut B) -> Result<()>

where Self: Sized, B: Write + ?Sized,

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

Similar to std::io::Read::read_to_end, all bytes read from this source will be appended to the specified buffer buf.

This function will continuously call fill_buf and consume to append more data to buf until fill_buf returns either Ok(&[]) or any kind of error.

Errors

This function will return an error immediately if any call to fill_buf returns any kind of error. Instances of ErrorKind::Interrupted are not handled by this function.

All bytes consumed from the reader will be written to the buffer and vice versa. It is guaranteed that no data is lost in case of error.

Differences to std::io::Read::read_to_end

• Does not retry on ErrorKind::Interrupted.
• Uses BufRead instead of Read.
• Does not return the number of bytes that are copied.
• Works with all kind of writers, not just Vec<u8>

Advantages

• Function is interruptable, e.g. to allow graceful shutdown for server applications.
• Avoids double buffering if the source already implements BufRead.
• Allows different buffer sizes by using BufReader::with_capacity.

Disadvantages

The fact that it does not return the number of bytes copied stems from the fact that it cannot return this information in case of error. This would go against the goal of allowing reliable retry.

fn skip_to_end(&mut self) -> Result<()>

Skip all bytes until EOF in this source.

Acts like read_to_end, but all bytes read from this source are discarded.

This function will continuously call fill_buf and consume until fill_buf returns either Ok(&[]) or any kind of error.

Errors

This function will return an error immediately if any call to fill_buf returns any kind of error. Instances of ErrorKind::Interrupted are not handled by this function.

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

Read the exact number of bytes required to fill buf.

Similarliy to std::io::Read::read_exact, 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

This function will return an error immediately if any call to fill_buf returns any kind of error. Instances of ErrorKind::Interrupted are not handled by this function.

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

If this function returns an error, the buffer will contain all bytes read up to that point. The position of the cursor will point one byte past the last read byte.

All bytes consumed from the reader will be written to the buffer and vice versa. It is guaranteed that no data is lost in case of error.

Differences to std::io::Read::read_exact

• Does not retry on ErrorKind::Interrupted.
• Uses BufRead instead of Read.
• In case of error the buffer contains all bytes read up to that point.
• Takes a Cursor instead of plain buffer to track the current position.

Advantages

• Function is interruptable, e.g. to allow graceful shutdown for server applications.
• No data ist lost on error.

Disadvantages

The function is slightly less ergonomic to use.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this buffered reader into an iterator over its bytes.

This method is approximately equivalent to std::io::Read::bytes.

The returned type implements std::iter::Iterator where the Item is Result<u8, R::Err>. The yielded item is Ok if a byte was successfully read and Err otherwise for I/O errors. EOF is mapped to returning None from this iterator.

Errors

If fill_buf returns any kind of error, the iterator yields Some(Err). In case of error it is safe to iterate further to retry the reading operation. Instances of ErrorKind::Interrupted are not handled by the iterator.

Differences to std::io::Read::bytes

• Uses BufRead instead of Read.

Advantages

• No accidentialy unbuffered reading of single bytes

fn read_until<W>(&mut self, delim: u8, buf: &mut W) -> Result<()>

where Self: Sized, W: Write + ?Sized,

Read all bytes into a buffer until a delimiter is reached.

Similar to std::io::BufRead::read_until ,this function will read bytes from the underlying stream and push them to the specified buffer buf, until the delimiter delim is found. If the delimiter is found, it is also part of the result.

Errors

This function will return an error immediately if any call to fill_buf returns any kind of error. Instances of ErrorKind::Interrupted are not handled by this function.

If this reader has reached EOF then this function will return ErrorKind::UnexpectedEof.

All bytes consumed from the buffered reader will be written to the specified buffer and vice versa. It is guaranteed that no data is lost in case of error.

Differences to std::io::BufRead::read_until

• Does not retry on ErrorKind::Interrupted.
• Does not return the number of bytes that are read.
• Returns an error on EOF instead of success.
• Works with all kind of writers, not just Vec<u8>

Advantages

• Function is interruptable, e.g. to allow graceful shutdown for server applications.

Disadvantages

The fact that it does not return the number of bytes copied stems from the fact that it cannot return this information in case of error. This would go against the goal of allowing reliable retry.

fn skip_until(&mut self, delim: u8) -> Result<()>

Skips all bytes until a delimiter is reached.

This function will discard bytes from the underlying stream until the delimiter delim is found.

Acts like read_until, but all bytes read from this source are discarded.

Errors

This function will return an error immediately if any call to fill_buf returns any kind of error. Instances of ErrorKind::Interrupted are not handled by this function.

If this reader has reached EOF then this function will return ErrorKind::UnexpectedEof.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on a delimiter.

The iterator returned from this function will return instances of io::Result<Vec<u8>>. Each vector returned will not have the delimiter byte at the end.

Errors

The iterator will yield an error whenever read_until would have also returned an error.

Implementations on Foreign Types

impl BufRead for Empty

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

fn consume(&mut self, amt: usize)

impl<'a> BufRead for &'a [u8]

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

fn consume(&mut self, amt: usize)

impl<'a> BufRead for StdinLock<'a>

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

fn consume(&mut self, amt: usize)

impl<'a, B: BufRead + ?Sized> BufRead for &'a mut B

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

fn consume(&mut self, amt: usize)

fn skip_to_end(&mut self) -> Result<()>

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

fn skip_until(&mut self, delim: u8) -> Result<()>

impl<B: BufRead + ?Sized> BufRead for Box<B>

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

fn consume(&mut self, amt: usize)

fn skip_to_end(&mut self) -> Result<()>

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

fn skip_until(&mut self, delim: u8) -> Result<()>

impl<R, Rs, Ms> BufRead for BufReader<R, Rs, Ms>

where R: Read, Rs: ReadStrategy, Ms: MoveStrategy,

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

fn consume(&mut self, amt: usize)

impl<R: Read> BufRead for BufReader<R>

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

fn consume(&mut self, amt: usize)

impl<T> BufRead for Cursor<T>

where T: AsRef<[u8]>,

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

fn consume(&mut self, amt: usize)

impl<T: BufRead> BufRead for Take<T>

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

fn consume(&mut self, amt: usize)

impl<T: BufRead, U: BufRead> BufRead for Chain<T, U>

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

fn consume(&mut self, amt: usize)

Implementors

impl<I: BufRead + Seek> BufRead for Repeat<I>

impl<R: BufRead> BufRead for Compat<R>

impl<R: BufRead> BufRead for Collect<R>

impl<R: BufRead> BufRead for Retry<R>

impl<T: BufRead> BufRead for netio::Take<T>

impl<T: BufRead, U: BufRead> BufRead for netio::Chain<T, U>