Trait utf8_bufread::BufRead [−][src]
A trait implemented for all types implementing io::BufRead
, providing functions to
read utf-8 text streams without waiting for newline delimiters.
Examples
use std::io::Cursor; use utf8_bufread::BufRead; // Prints "I luv you too !" if Cursor::new("💖").read_str().map_or(false, |s| s == "💖") { println!("I luv you too !"); }
Provided methods
fn read_str(&mut self) -> Result<Cow<'_, str>, Error>
[src]
Reads some bytes from the inner reader and returns a Cow
<&
str
>
of it referring
to all valid codepoints read, wrapped in an io::Result
.
This function will read all bytes from the underlying stream until its buffer is full, an invalid or incomplete codepoint is found, or EOF is found. Once found, all codepoints up to, including the EOF (if found), but not including the invalid or incomplete codepoint (if found), will be returned. This function may read an arbitrary number of byte, between 1 and this reader’s buffer capacity (unless the buffer is not big enough to fit a unicode codepoint).
The returned reference points to this reader’s actual buffer, meaning it borrows the reader.
A Cow
is used to gracefully handle cases where a valid codepoint is cut by the end of
the buffer of this reader, and more bytes may need to be read from the inner reader to form
a hopefully valid codepoint. This function only allocates a new String
and clones data
in that scenario. In worst case it happens once every two calls, allocating and cloning
4 bytes every c
bytes read, where c
is this reader’s buffer capacity.
If this function returns Ok
("")
, the stream has reached EOF.
Errors
If the internal call to fill_buf
returns an io::Error
or this function returns
immediately an Error
wrapping the original error.
If the first codepoint read from the inner reader is invalid, an Error
wrapping the
original Utf8Error
or FromUtf8Error
is returned.
If the codepoint is complete but invalid, the returned error will have a kind
of
ErrorKind
::
InvalidData
. If EOF was encountered before the end of a codepoint,
the error will have a kind
of ErrorKind
::
UnexpectedEof
.
The returned Error
may contain a non-zero amount of “leftover” bytes (see
Error::leftovers
for more info). When it is the case, it is guaranteed that the
following read operation will not return any of those bytes, nor “skip” bytes from this
reader.
Note that if the buffer of this reader is less than 4 bytes long it may fail to read
complete codepoints and “spuriously” return the same error as when it unexpectedly
encounters EOF, since we’re unable to load enough bytes to form a valid codepoint. We
cannot check the capacity of the buffer using the io::BufRead
API only, it is then up
to the user to ensure this won’t happen. It should not happen unless you explicitly set
the capacity yourself.
Examples
This example simply reads from a stream and prints it to standard output.
use std::io::{Cursor, Error, ErrorKind}; use utf8_bufread::BufRead; use std::borrow::Cow; // We could use any type implementing io::BufRead, we'll just use a cursor here let mut reader = Cursor::new("Löwe 老虎 Léopard"); loop { match reader.read_str() { Ok(s) => { if s.is_empty() { break; // EOF } print!("{}", s) } Err(e) => { if ErrorKind::Interrupted != e.kind() { // Ignore interrupted errors eprintln!("{}", e); } } } }
fn read_char(&mut self) -> Result<char, Error>
[src]
Reads 1 to 4 bytes from the inner reader and returns the char
read, wrapped in an
io::Result
.
This function will read bytes from the underlying stream until one codepoint is read, an invalid or incomplete codepoint is found, or EOF is found.
If this function returns Ok
('\0')
, the stream has reached EOF.
Errors
If the internal call to fill_buf
returns an io::Error
or this function returns
immediately an Error
wrapping the original error.
If the first codepoint read from the inner reader is invalid or incomplete, an Error
wrapping the original Utf8Error
or FromUtf8Error
is returned.
If the codepoint is complete but invalid, the returned error will have a kind
of
ErrorKind
::
InvalidData
. If EOF was encountered before the end of a codepoint,
the error will have a kind
of ErrorKind
::
UnexpectedEof
.
The returned Error
may contain a non-zero amount of “leftover” bytes (see
Error::leftovers
for more info). When it is the case, it is guaranteed that the
following read operation will not return any of those bytes, nor “skip” bytes from this
reader.
Note that if the buffer of this reader is less than 4 bytes long it may fail to read
complete codepoints and “spuriously” return the same error as when it unexpectedly
encounters EOF, since we’re unable to load enough bytes to form a valid codepoint. We
cannot check the capacity of the buffer using the io::BufRead
API only, it is then up
to the user to ensure this won’t happen. It should not happen unless you explicitly set
the capacity yourself.
Examples
This example simply reads from a stream and counts the number of lowercase characters
use std::io::{Cursor, Error, ErrorKind}; use utf8_bufread::BufRead; use std::borrow::Cow; // We could use any type implementing io::BufRead, we'll just use a cursor here let mut reader = Cursor::new("Löwe 老虎 Léopard"); let mut count = 0; loop { match reader.read_char() { Ok('\0') => break, // EOF Ok(c) => { if c.is_lowercase() { count += 1; } } Err(e) => { if ErrorKind::Interrupted != e.kind() { // Ignore interrupted errors eprintln!("{}", e); } } } } assert_eq!(count, 9);
fn str_iter(&mut self) -> StrIter<'_, Self>ⓘ
[src]
Returns an iterator over string slices of this reader.
It is equivalent to calling read_str
in a loop, ignoring
ErrorKind
::
Interrupted
errors, until EOF or the first error encountered.
The iterator returned by this function will yield instances of
io::Result
<
Rc
<
String
>>
. We use the Rc
to check while iterating if the
iterator is the only one holding a reference to it, avoiding allocating a new buffer if
that’s the case.
The iterator returned will yield at most one io::Error
. Once an error is yielded, it
will only yield None
.
Examples
This example simply reads from a string and prints it to standard output:
use std::io::Cursor; use utf8_bufread::BufRead; // We could use any type implementing io::BufRead, we'll just use a cursor here let mut reader = Cursor::new("Löwe 老虎 Léopard"); // We ignore any error, we know once we encounter one we can't read any further anyway reader.str_iter().filter_map(Result::ok).for_each(|s| print!("{}", s));
fn char_iter(&mut self) -> CharIter<'_, Self>ⓘ
[src]
Returns an iterator over chars of this reader.
It is equivalent to calling read_char
in a loop, ignoring
ErrorKind
::
Interrupted
errors, until EOF or the first error encountered.
The iterator returned by this function will yield instances of
io::Result
<
char
>
.
The iterator returned will yield at most one io::Error
. Once an error is yielded, it
will only yield None
.
Examples
This example simply reads from a stream, filtering out any whitespace:
use std::io::Cursor; use utf8_bufread::BufRead; // We could use any type implementing io::BufRead, we'll just use a cursor here let mut reader = Cursor::new("Löwe 老虎 Léopard"); let result: String = reader.char_iter() .filter_map(Result::ok) .filter(|c| !c.is_whitespace()) .collect(); assert_eq!(result.as_str(), "Löwe老虎Léopard");
fn str_map<F, T>(&mut self, f: F) -> StrMap<'_, Self, F>ⓘ where
F: FnMut(Cow<'_, str>) -> T,
[src]
F: FnMut(Cow<'_, str>) -> T,
Returns an mapping iterator over string slices of this reader.
It is equivalent to calling read_str
in a loop, ignoring
ErrorKind
::
Interrupted
errors, until EOF or the first error encountered.
The iterator returned by this function will call f
with instances of Cow
<
str
>
as returned by read_str
, and yield instances of io::Result
<T>
. This may help
avoids the allocations and clonings str_iter
does.
The iterator returned will yield at most one io::Error
, and if one is yielded it will
always be the last item.
Examples
This example simply reads from a stream and counts the number of bytes read:
use std::io::Cursor; use utf8_bufread::BufRead; // We could use any type implementing io::BufRead, we'll just use a cursor here let mut reader = Cursor::new("Löwe 老虎 Léopard"); let count: usize = reader.str_map(|s| s.len()).filter_map(Result::ok).sum(); assert_eq!(count, 21);