Struct netio::Utf8Reader
[−]
[src]
pub struct Utf8Reader<I> { /* fields omitted */ }
Methods
impl<I> Utf8Reader<I>
[src]
fn new(inner: I) -> Utf8Reader<I>
fn get_ref(&self) -> &I
Gets a reference to the underlying reader.
It is inadvisable to directly read from the underlying reader.
fn get_mut(&mut self) -> &mut I
Gets a mutable reference to the underlying reader.
It is inadvisable to directly read from the underlying reader.
fn into_inner(self) -> I
Unwraps this BufReader
, returning the underlying reader.
impl<I: BufReadGrow> Utf8Reader<I>
[src]
fn fill_buf_str(&mut self) -> Result<&str>
Fills the internal buffer of this object, returning the buffer content as a string
This function will return at least one valid char
except when reaching EOF.
If invalid or incomplete UTF-8 is encountered,
the function returns all valid UTF-8 up to that point.
If the function returns an empty string slice, the unterlying reader has reached EOF and all data in the stream was valid UTF-8.
Errors
- If a call to
fill_buf
orgrow_buf
on the underlying buffered reader returns an error, this error is returned immediately. - If invalid UTF-8 is encountered at the beginning of the buffer, an error of kind
ErrorKind
::InvalidData
is returned. - If an incomplete UTF-8 character followed by EOF is encountered at the beginning of the
buffer, an error of kind
ErrorKind
::UnexpectedEof
is returned.
Panics
- If the underlying buffered reader behaves in an unexpected way,
i.e.
fill_buf
not returning the same buffer content without any call toconsume
. - If the user of this reader has previously called
consume_str
with an invalid amount of bytes that doesn't correspond to a valid UTF-8 substring.
Issues
Currently there's no way to decide if the remaining data is an incomplete UTF-8 char or
just plain invalid UTF-8 if the remaining buffer is smaller or equal than 4 bytes.
(Issue rust-lang/rust#32584
)
This case is currently just interpreted as ErrorKind
::UnexpectedEof
.
fn grow_buf_str(&mut self) -> Result<&str>
Grows the internal buffer of this the underlying buffered reader by at least one char, returning the buffer content as a string slice
This function will return at least one additional valid char
compared to a call to
fill_buf_str
.
If invalid or incomplete UTF-8 is encountered,
the function returns all valid UTF-8 up to that point.
If the function returns an empty string slice, the unterlying reader has reached EOF and all data in the stream was valid UTF-8.
Errors
- If a call to
fill_buf
orgrow_buf
on the underlying buffered reader returns an error, this error is returned immediately. - If invalid UTF-8 is encountered at the beginning of the buffer s.t. no additional char
can be returned, an error of kind
ErrorKind
::InvalidData
is returned. - If EOF is encountered, such that no additional char can be returned, an error of kind
ErrorKind
::UnexpectedEof
is returned.
Panics
- If the underlying buffered reader behaves in an unexpected way,
i.e.
fill_buf
not returning the same buffer content without any call toconsume
. - If the user of this reader has previously called
consume_str
with an invalid amount of bytes that doesn't correspond to a valid UTF-8 substring.
Issues
Currently there's no way to decide if the remaining data is an incomplete UTF-8 char or
just plain invalid UTF-8 if the remaining buffer is smaller or equal than 4 bytes.
(Issue rust-lang/rust#32584
)
This case is currently just interpreted as ErrorKind
::UnexpectedEof
.
fn consume_str(&mut self, amt: usize)
Tells this reader that amt
bytes have been consumed from the buffer,
so they should no longer be returned.
The amount bytes consumed must correspond to a a valid substring, otherwise the next string reading operation will panic.
fn read_to_string(&mut self, buf: &mut String) -> Result<()>
Read all bytes until EOF in this source, placing them into a string.
This function will continuously call fill_buf_str
and
consume_str
to append more data to buf
until fill_buf_str
returns
either an empty string slice or any kind of error occurs.
Errors
This function will return an error immediately if any call to fill_buf_str
returns any kind of error.
Instances of ErrorKind
::Interrupted
are not handled by this function.
If invalid UTF-8 is encountered, an error of kind ErrorKind
::InvalidData
is
returned and the string will contain all valid UTF-8 up to that point.
All bytes consumed from the underlying buffered reader will be written to the buffer and vice versa. It is guaranteed that no data is lost in case of error.
Panics
- If the underlying buffered reader behaves in an unexpected way,
i.e.
fill_buf
not returning the same buffer content without any call toconsume
. - If the user of this reader has previously called
consume_str
with an invalid amount of bytes that doesn't correspond to a valid UTF-8 substring.
Differences to std::io::Read::read_to_string
- Does not retry on
ErrorKind
::Interrupted
. - Uses
BufReadGrow
instead ofBufRead
. - Does not return the number of bytes that are copied.
- On error, string will contain all valid UTF-8 up to that point.
Advantages
- Function is interruptable, e.g. to allow graceful shutdown for server applications.
- No data ist lost on error (e.g. invalid UTF-8).
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 read_line(&mut self, buf: &mut String) -> Result<()>
Read all bytes until a CRLF is reached, and append them to the provided buffer.
This function will UTF-8 characters from the underlying stream and append them to the 'buf' until the CRLF delimiter (the 0xA 0xD bytes) is found.
Errors
This function will return an error immediately if any call to fill_buf_str
or
grow_buf_str
returns any kind of error.
Instances of ErrorKind
::Interrupted
are not handled by this function.
This function will return an error of kind ErrorKind
::InvalidData
if the
read bytes are not valid UTF-8.
If EOF is reached, an error of kind ErrorKind
::UnexpectedEof
is returned.
If any kind of error occurs, the buffer will contain all valid UTF-8 up to that point.
In any case, 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.
This method will will never leave a CR (\r
) as last character
in the underlying buffered reader, even in case of error.
Doing so could lead to skipping a CRLF sequence in case of retry.
In case of ErrorKind
::UnexpectedEof
,
this behavior is a bit unexpected and might change in a future version.
Panics
- If the underlying buffered reader behaves in an unexpected way,
i.e.
fill_buf
not returning the same buffer content without any call toconsume
. - If the user of this reader has previously called
consume_str
with an invalid amount of bytes that doesn't correspond to a valid UTF-8 substring.
Differences to std::io::BufRead::read_line
- Does not retry on
ErrorKind
::Interrupted
. - Uses
BufReadGrow
instead ofBufRead
. - Does not return the number of bytes that are read.
- Returns an error on EOF instead of success.
- Uses CRLF as line ending convention instead of just LF.
Advantages
- Function is interruptable, e.g. to allow graceful shutdown for server applications.
- Suitable for network protocols, because those usually use CRLF as line endings.
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 chars(self) -> Chars<I> where
Self: Sized,
Self: Sized,
Transforms this reader to an Iterator
over char
s.
Similar to std::io::Read::chars
, this adaptor will attempt to interpret this reader
as a UTF-8 encoded sequence of characters.
The returned iterator will return None
once
EOF is reached for this reader. Otherwise each element yielded will be a
io::Result<char>
.
Errors
The iterator will yield an error immediately if any call to fill_buf_str
or
grow_buf_str
returns any kind of error.
Instances of ErrorKind
::Interrupted
are not handled by the iterator.
The iterator will yield an error of kind ErrorKind
::InvalidData
if the
read bytes are not valid UTF-8.
If the stream is reaching EOF in the middle of an otherwise valid UTF-8 characters,
an error of kind ErrorKind
::UnexpectedEof
is yielded.
In case of an error, the iterator will not skip any data. Iterating further will simply retry the failed operation.
Note: Ignoring errors will most likely result in an endless loop
Panics
- If the underlying buffered reader behaves in an unexpected way,
i.e.
fill_buf
not returning the same buffer content without any call toconsume
. - If the user of this reader has previously called
consume_str
with an invalid amount of bytes that doesn't correspond to a valid UTF-8 substring.
Differences to std::io::Read::Chars
- Errors of kind
ErrorKind
::Interrupted
are not swallowed. - Uses the usual
io::Error
instead of a custom error type. - Invalid UTF-8 is not skipped.
Issues
Currently there's no way to decide if the remaining data is an incomplete but otherwise
valid UTF-8 char or just plain invalid UTF-8.
(Issue rust-lang/rust#32584
)