Trait utf8_bufread::BufRead

pub trait BufRead: BufRead {
    fn read_utf8(&mut self) -> Result<String> { ... }
}

Provided methods

fn read_utf8(&mut self) -> Result<String>

Read a number of bytes les than or equal to the capacity of the its buffer, and return their utf-8 representation as a io::Result<&str>.

This function will read 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.

If this function returns Ok(""), the stream has reached EOF.

This function avoids the usual issues of using BufRead::read_line(&self, &mut String) or BufRead::lines(&self) on big text file without newline delimiters: It will not load the whole file in memory.

Errors

This function will immediately return any errors returned by fill_buf.

If an Utf8Error is returned by the internal call to from_utf8, all valid codepoints are returned, and no error is returned, unless no valid codepoints were read. This allows not to lose any valid data, and the error will be returned on the next call.

If the first codepoint encountered by from_utf8 is invalid or incomplete, an ErrorKind::[InvalidData] caused by an Utf8Error is returned. This error cannot be recovered from, and you will have to read bytes manually to determine if the error was caused by an invalid codepoint in middle of the file or by an incomplete codepoint because of an early EOF.

Examples

[std::io::Cursor][Cursor] is a type that implements BufRead. In this example, we use [Cursor] to read

use utf8_bufread::BufRead;
use std::io::{BufReader, ErrorKind};

// "foo\nbar" + some invalid bytes
// We give the buffer more than enough capacity to be able to read all the bytes in one
// call
let mut reader = BufReader::with_capacity(
    16,
    [0x66u8, 0x6f, 0x6f, 0xa, 0x62, 0x61, 0x72, 0x9f, 0x92, 0x96].as_ref(),
);

// On the first read_utf8() call, we will read up to the first byte of the invalid
// codepoint (ie "foo\nbar")
let read_str = reader
    .read_utf8()
    .expect("We will get all the valid bytes without error");
assert_eq!("foo\nbar", read_str);

// Then on the second call we will get the InvalidData error caused by the Utf8Error error,
// as there is no bytes forming valid codepoints left
let read_err = reader.read_utf8().expect_err("We will get an error");
assert_eq!(ErrorKind::InvalidData, read_err.kind())

Loading content...

Implementors

impl<R: BufRead> BufRead for R

Loading content...