Struct io_streams::BufReaderLineWriter

pub struct BufReaderLineWriter<Inner: HalfDuplex> { /* private fields */ }

Wraps a reader and writer and buffers input and output to and from it, flushing the writer whenever a newline (0x0a, '\n') is detected on output.

The BufDuplexer struct wraps a reader and writer and buffers their input and output. But it only does this batched write when it goes out of scope, or when the internal buffer is full. Sometimes, you’d prefer to write each line as it’s completed, rather than the entire buffer at once. Enter BufReaderLineWriter. It does exactly that.

Like BufDuplexer, a BufReaderLineWriter’s buffer will also be flushed when the BufReaderLineWriter goes out of scope or when its internal buffer is full.

If there’s still a partial line in the buffer when the BufReaderLineWriter is dropped, it will flush those contents.

Examples

We can use BufReaderLineWriter to write one line at a time, significantly reducing the number of actual writes to the file.

use char_device::CharDevice;
use io_streams::BufReaderLineWriter;
use std::fs;
use std::io::prelude::*;

fn main() -> std::io::Result<()> {
    let road_not_taken = b"I shall be telling this with a sigh
Somewhere ages and ages hence:
Two roads diverged in a wood, and I -
I took the one less traveled by,
And that has made all the difference.";

    let file = CharDevice::open("/dev/tty")?;
    let mut file = BufReaderLineWriter::new(file);

    file.write_all(b"I shall be telling this with a sigh")?;

    // No bytes are written until a newline is encountered (or
    // the internal buffer is filled).
    assert_eq!(fs::read_to_string("poem.txt")?, "");
    file.write_all(b"\n")?;
    assert_eq!(
        fs::read_to_string("poem.txt")?,
        "I shall be telling this with a sigh\n",
    );

    // Write the rest of the poem.
    file.write_all(
        b"Somewhere ages and ages hence:
Two roads diverged in a wood, and I -
I took the one less traveled by,
And that has made all the difference.",
    )?;

    // The last line of the poem doesn't end in a newline, so
    // we have to flush or drop the `BufReaderLineWriter` to finish
    // writing.
    file.flush()?;

    // Confirm the whole poem was written.
    assert_eq!(fs::read("poem.txt")?, &road_not_taken[..]);
    Ok(())
}

Implementations

impl<Inner: HalfDuplex> BufReaderLineWriter<Inner>

pub fn new(inner: Inner) -> Self

Creates a new BufReaderLineWriter.

Examples

use char_device::CharDevice;
use io_streams::BufReaderLineWriter;

fn main() -> std::io::Result<()> {
    let file = CharDevice::open("/dev/tty")?;
    let file = BufReaderLineWriter::new(file);
    Ok(())
}

pub fn with_capacities( reader_capacity: usize, writer_capacity: usize, inner: Inner, ) -> Self

Creates a new BufReaderLineWriter with a specified capacities for the internal buffers.

Examples

use char_device::CharDevice;
use io_streams::BufReaderLineWriter;

fn main() -> std::io::Result<()> {
    let file = CharDevice::open("/dev/tty")?;
    let file = BufReaderLineWriter::with_capacities(10, 100, file);
    Ok(())
}

pub fn get_ref(&self) -> &Inner

Gets a reference to the underlying writer.

Examples

use char_device::CharDevice;
use io_streams::BufReaderLineWriter;

fn main() -> std::io::Result<()> {
    let file = CharDevice::open("/dev/tty")?;
    let file = BufReaderLineWriter::new(file);

    let reference = file.get_ref();
    Ok(())
}

pub fn get_mut(&mut self) -> &mut Inner

Gets a mutable reference to the underlying writer.

Caution must be taken when calling methods on the mutable reference returned as extra writes could corrupt the output stream.

Examples

use char_device::CharDevice;
use io_streams::BufReaderLineWriter;

fn main() -> std::io::Result<()> {
    let file = CharDevice::open("/dev/tty")?;
    let mut file = BufReaderLineWriter::new(file);

    // we can use reference just like file
    let reference = file.get_mut();
    Ok(())
}

pub fn into_inner(self) -> Result<Inner, IntoInnerError<Self>>

Unwraps this BufReaderLineWriter, returning the underlying writer.

The internal buffer is written out before returning the writer.

Errors

An Err will be returned if an error occurs while flushing the buffer.

Examples

use char_device::CharDevice;
use io_streams::BufReaderLineWriter;

fn main() -> std::io::Result<()> {
    let file = CharDevice::open("/dev/tty")?;

    let writer: BufReaderLineWriter<CharDevice> = BufReaderLineWriter::new(file);

    let file: CharDevice = writer.into_inner()?;
    Ok(())
}

Trait Implementations

impl<Inner: HalfDuplex AsFd> AsFd for BufReaderLineWriter<Inner>

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl<Inner: HalfDuplex AsRawFd> AsRawFd for BufReaderLineWriter<Inner>

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl<Inner: HalfDuplex> BufRead for BufReaderLineWriter<Inner>

fn fill_buf(&mut self) -> Result<&[u8]>

Returns the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(&mut self, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to read.

fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize>

Reads all bytes into buf until the delimiter byte or EOF is reached.

fn read_line(&mut self, buf: &mut String) -> Result<usize>

Reads all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn has_data_left(&mut self) -> Result<bool, Error>

🔬This is a nightly-only experimental API. (buf_read_has_data_left)

Checks if the underlying Read has any data left to be read.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

🔬This is a nightly-only experimental API. (bufread_skip_until)

Skips all bytes until the delimiter byte or EOF is reached.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

impl<Inner> Debug for BufReaderLineWriter<Inner>

where Inner: Debug HalfDuplex,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Inner: HalfDuplex> Read for BufReaderLineWriter<Inner>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<Inner: HalfDuplex> Write for BufReaderLineWriter<Inner>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.