Trait bstr::io::BufReadExt

pub trait BufReadExt: BufRead {
    fn byte_lines(self) -> ByteLines<Self>
    where
        Self: Sized,
    { ... }
    fn for_byte_line<F>(self, for_each_line: F) -> Result<()>
    where
        Self: Sized,
        F: FnMut(&[u8]) -> Result<bool>,
    { ... }
    fn for_byte_line_with_terminator<F>(self, for_each_line: F) -> Result<()>
    where
        Self: Sized,
        F: FnMut(&[u8]) -> Result<bool>,
    { ... }
}

An extention trait for std::io::BufRead which provides convenience APIs for dealing with byte strings.

Provided methods

fn byte_lines(self) -> ByteLines<Self> where
    Self: Sized, 

Returns an iterator over the lines of this reader, where each line is represented as a byte string.

Each item yielded by this iterator is a io::Result<Vec<u8>>, where an error is yielded if there was a problem reading from the underlying reader.

On success, the next line in the iterator is returned. The line does not contain a trailing \n or \r\n.

Examples

Basic usage:

use std::io;

use bstr::io::BufReadExt;

let cursor = io::Cursor::new(b"lorem\nipsum\r\ndolor");

let mut lines = vec![];
for result in cursor.byte_lines() {
    let line = result?;
    lines.push(line);
}
assert_eq!(lines.len(), 3);
assert_eq!(lines[0], "lorem".as_bytes());
assert_eq!(lines[1], "ipsum".as_bytes());
assert_eq!(lines[2], "dolor".as_bytes());

fn for_byte_line<F>(self, for_each_line: F) -> Result<()> where
    Self: Sized,
    F: FnMut(&[u8]) -> Result<bool>, 

Executes the given closure on each line in the underlying reader.

If the closure returns an error (or if the underlying reader returns an error), then iteration is stopped and the error is returned. If false is returned, then iteration is stopped and no error is returned.

The closure given is called on exactly the same values as yielded by the byte_lines iterator. Namely, lines do not contain trailing \n or \r\n bytes.

This routine is useful for iterating over lines as quickly as possible. Namely, a single allocation is reused for each line.

Examples

Basic usage:

use std::io;

use bstr::io::BufReadExt;

let cursor = io::Cursor::new(b"lorem\nipsum\r\ndolor");

let mut lines = vec![];
cursor.for_byte_line(|line| {
    lines.push(line.to_vec());
    Ok(true)
})?;
assert_eq!(lines.len(), 3);
assert_eq!(lines[0], "lorem".as_bytes());
assert_eq!(lines[1], "ipsum".as_bytes());
assert_eq!(lines[2], "dolor".as_bytes());

fn for_byte_line_with_terminator<F>(self, for_each_line: F) -> Result<()> where
    Self: Sized,
    F: FnMut(&[u8]) -> Result<bool>, 

Executes the given closure on each line in the underlying reader.

If the closure returns an error (or if the underlying reader returns an error), then iteration is stopped and the error is returned. If false is returned, then iteration is stopped and no error is returned.

Unlike for_byte_line, the lines given to the closure do include the line terminator, if one exists.

This routine is useful for iterating over lines as quickly as possible. Namely, a single allocation is reused for each line.

Examples

Basic usage:

use std::io;

use bstr::io::BufReadExt;

let cursor = io::Cursor::new(b"lorem\nipsum\r\ndolor");

let mut lines = vec![];
cursor.for_byte_line_with_terminator(|line| {
    lines.push(line.to_vec());
    Ok(true)
})?;
assert_eq!(lines.len(), 3);
assert_eq!(lines[0], "lorem\n".as_bytes());
assert_eq!(lines[1], "ipsum\r\n".as_bytes());
assert_eq!(lines[2], "dolor".as_bytes());

Loading content...

Implementors

impl<B: BufRead> BufReadExt for B

Loading content...