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 ofRead
. - 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
- Does not retry on
ErrorKind::Interrupted
. - Does not return the number of bytes that are read.
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
impl<R: BufRead> BufReadExt for R