Trait netio::BufReadExt [−] [src]

pub trait BufReadExt: BufRead {
    fn read_to_end_net(&mut self, buf: &mut Vec<u8>) -> Result<()> { ... }
    fn skip_to_end_net(&mut self) -> Result<()> { ... }
    fn bytes_net(self) -> Bytes<Self> where Self: Sized { ... }
    fn read_until_net(&mut self, delim: u8, buf: &mut Vec<u8>) -> Result<bool> { ... }
    fn skip_until_net(&mut self, delim: u8) -> Result<bool> { ... }
    fn split_net(self, byte: u8) -> Split<Self> where Self: Sized { ... }
}

Extension methods for std::io::BufRead

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

Provided Methods

fn read_to_end_net(&mut self, buf: &mut Vec<u8>) -> Result<()>

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 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::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.
  • Different reallocation behavior of the buffer.

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_net(&mut self) -> Result<()>

Skip all bytes until EOF in this source.

Acts like read_to_end_net, 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 bytes_net(self) -> Bytes<Self> where Self: Sized

Transforms this BufRead instance to an Iterator over its bytes.

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

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

Advantages

  • No accidentialy unbuffered reading of single bytes

fn read_until_net(&mut self, delim: u8, buf: &mut Vec<u8>) -> Result<bool>

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 or EOF is found. If the delimiter is found, it is also part of the result.

If this reader has reached EOF then this function will return Ok(true).

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

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_net(&mut self, delim: u8) -> Result<bool>

Skips all bytes until a delimiter is reached.

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

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

If this reader has reached EOF then this function will return Ok(true).

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 split_net(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_net would have also returned an error.

Implementors