Trait BufRead 

pub trait BufRead: BufRead {
    // Provided methods
    fn read_str(&mut self) -> Result<Cow<'_, str>, Error> { ... }
    fn read_char(&mut self) -> Result<char, Error> { ... }
    fn str_iter(&mut self) -> StrIter<'_, Self>  { ... }
    fn char_iter(&mut self) -> CharIter<'_, Self>  { ... }
    fn str_map<F, T>(&mut self, f: F) -> StrMap<'_, Self, F> 
       where F: FnMut(Cow<'_, str>) -> T { ... }
}

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>

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>

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>

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>

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,

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

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<R: BufRead> BufRead for R