Trait bstr::io::BufReadExt
source · pub trait BufReadExt: BufRead {
// Provided methods
fn byte_lines(self) -> ByteLines<Self> ⓘ
where Self: Sized { ... }
fn byte_records(self, terminator: u8) -> ByteRecords<Self> ⓘ
where Self: Sized { ... }
fn for_byte_line<F>(&mut self, for_each_line: F) -> Result<()>
where Self: Sized,
F: FnMut(&[u8]) -> Result<bool> { ... }
fn for_byte_record<F>(
&mut self,
terminator: u8,
for_each_record: F
) -> Result<()>
where Self: Sized,
F: FnMut(&[u8]) -> Result<bool> { ... }
fn for_byte_line_with_terminator<F>(
&mut self,
for_each_line: F
) -> Result<()>
where Self: Sized,
F: FnMut(&[u8]) -> Result<bool> { ... }
fn for_byte_record_with_terminator<F>(
&mut self,
terminator: u8,
for_each_record: F
) -> Result<()>
where Self: Sized,
F: FnMut(&[u8]) -> Result<bool> { ... }
}
Expand description
An extension trait for
std::io::BufRead
which provides convenience APIs for dealing with byte strings.
Provided Methods§
sourcefn byte_lines(self) -> ByteLines<Self> ⓘwhere
Self: Sized,
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 mut 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());
sourcefn byte_records(self, terminator: u8) -> ByteRecords<Self> ⓘwhere
Self: Sized,
fn byte_records(self, terminator: u8) -> ByteRecords<Self> ⓘwhere Self: Sized,
Returns an iterator over byte-terminated records of this reader, where each record 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 record in the iterator is returned. The record does not contain its trailing terminator.
Note that calling byte_records(b'\n')
differs from byte_lines()
in
that it has no special handling for \r
.
Examples
Basic usage:
use std::io;
use bstr::io::BufReadExt;
let mut cursor = io::Cursor::new(b"lorem\x00ipsum\x00dolor");
let mut records = vec![];
for result in cursor.byte_records(b'\x00') {
let record = result?;
records.push(record);
}
assert_eq!(records.len(), 3);
assert_eq!(records[0], "lorem".as_bytes());
assert_eq!(records[1], "ipsum".as_bytes());
assert_eq!(records[2], "dolor".as_bytes());
sourcefn for_byte_line<F>(&mut self, for_each_line: F) -> Result<()>where
Self: Sized,
F: FnMut(&[u8]) -> Result<bool>,
fn for_byte_line<F>(&mut 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 mut 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());
sourcefn for_byte_record<F>(
&mut self,
terminator: u8,
for_each_record: F
) -> Result<()>where
Self: Sized,
F: FnMut(&[u8]) -> Result<bool>,
fn for_byte_record<F>( &mut self, terminator: u8, for_each_record: F ) -> Result<()>where Self: Sized, F: FnMut(&[u8]) -> Result<bool>,
Executes the given closure on each byte-terminated record 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_records
iterator. Namely, records do not contain a trailing terminator byte.
This routine is useful for iterating over records as quickly as possible. Namely, a single allocation is reused for each record.
Examples
Basic usage:
use std::io;
use bstr::io::BufReadExt;
let mut cursor = io::Cursor::new(b"lorem\x00ipsum\x00dolor");
let mut records = vec![];
cursor.for_byte_record(b'\x00', |record| {
records.push(record.to_vec());
Ok(true)
})?;
assert_eq!(records.len(), 3);
assert_eq!(records[0], "lorem".as_bytes());
assert_eq!(records[1], "ipsum".as_bytes());
assert_eq!(records[2], "dolor".as_bytes());
sourcefn for_byte_line_with_terminator<F>(&mut self, for_each_line: F) -> Result<()>where
Self: Sized,
F: FnMut(&[u8]) -> Result<bool>,
fn for_byte_line_with_terminator<F>(&mut 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.
This is identical to for_byte_record_with_terminator
with a
terminator of \n
.
Examples
Basic usage:
use std::io;
use bstr::io::BufReadExt;
let mut 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());
sourcefn for_byte_record_with_terminator<F>(
&mut self,
terminator: u8,
for_each_record: F
) -> Result<()>where
Self: Sized,
F: FnMut(&[u8]) -> Result<bool>,
fn for_byte_record_with_terminator<F>( &mut self, terminator: u8, for_each_record: F ) -> Result<()>where Self: Sized, F: FnMut(&[u8]) -> Result<bool>,
Executes the given closure on each byte-terminated record 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_record
,
the lines given to the closure do include the record terminator, if
one exists.
This routine is useful for iterating over records as quickly as possible. Namely, a single allocation is reused for each record.
Examples
Basic usage:
use std::io;
use bstr::{io::BufReadExt, B};
let mut cursor = io::Cursor::new(b"lorem\x00ipsum\x00dolor");
let mut records = vec![];
cursor.for_byte_record_with_terminator(b'\x00', |record| {
records.push(record.to_vec());
Ok(true)
})?;
assert_eq!(records.len(), 3);
assert_eq!(records[0], B(b"lorem\x00"));
assert_eq!(records[1], B("ipsum\x00"));
assert_eq!(records[2], B("dolor"));