Trait netio::BufRead
[−]
[src]
pub trait BufRead { fn fill_buf(&mut self) -> Result<&[u8]>; fn consume(&mut self, amt: usize); fn read_to_end<R: Write + ?Sized>(&mut self, buf: &mut R) -> Result<()> { ... } 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: Write + ?Sized>(&mut self, delim: u8, buf: &mut W) -> Result<()> { ... } 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<R: Write + ?Sized>(&mut self, buf: &mut R) -> 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 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 ofRead
. - 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 ofRead
. - 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
Advantages
- No accidentialy unbuffered reading of single bytes
fn read_until<W: Write + ?Sized>(&mut self, delim: u8, buf: &mut W) -> Result<()>
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.