Struct buf_redux::BufWriter

pub struct BufWriter<W: Write, P = StdPolicy> { /* fields omitted */ }

A drop-in replacement for std::io::BufWriter with more functionality.

Original method names/signatures and implemented traits are left untouched, making replacement as simple as swapping the import of the type.

By default this type implements the behavior of its std counterpart: it only flushes the buffer if an incoming write is larger than the remaining space.

To change this type's behavior, change the policy with .set_policy() using a type from the policy module or your own implentation of WriterPolicy.

Policies that perform alternating writes and flushes without completely emptying the buffer may benefit from using a ringbuffer via the new_ringbuf() and with_capacity_ringbuf() constructors. Ringbuffers are only available on supported platforms with the slice-deque feature and have some caveats; see the docs at the crate root for more details.

Methods

impl<W: Write> BufWriter<W>

pub fn new(inner: W) -> Self

Create a new BufWriter wrapping inner with the default buffer capacity and WriterPolicy.

pub fn with_capacity(cap: usize, inner: W) -> Self

Create a new BufWriter wrapping inner, utilizing a buffer with a capacity of at least cap bytes and the default WriterPolicy.

The actual capacity of the buffer may vary based on implementation details of the global allocator.

pub fn new_ringbuf(inner: W) -> Self

Create a new BufWriter wrapping inner, utilizing a ringbuffer with the default capacity and WriterPolicy.

A ringbuffer never has to move data to make room; consuming bytes from the head simultaneously makes room at the tail. This is useful in conjunction with a policy like FlushExact to ensure there is always room to write more data if necessary, without expensive copying operations.

Only available on platforms with virtual memory support and with the slice-deque feature enabled. The default capacity will differ between Windows and Unix-derivative targets. See Buffer::new_ringbuf() or the crate root docs for more info.

pub fn with_capacity_ringbuf(cap: usize, inner: W) -> Self

Create a new BufWriter wrapping inner, utilizing a ringbuffer with at least cap capacity and the default WriterPolicy.

A ringbuffer never has to move data to make room; consuming bytes from the head simultaneously makes room at the tail. This is useful in conjunction with a policy like FlushExact to ensure there is always room to write more data if necessary, without expensive copying operations.

Only available on platforms with virtual memory support and with the slice-deque feature enabled. The capacity will be rounded up to the minimum size for the target platform. See Buffer::with_capacity_ringbuf() or the crate root docs for more info.

Important traits for BufWriter<W, P>

impl<W: Write, P: WriterPolicy> Write for BufWriter<W, P>

pub fn with_buffer(buf: Buffer, inner: W) -> BufWriter<W>

Create a new BufWriter wrapping inner, utilizing the existing Buffer instance and the default WriterPolicy.

Note

Does not clear the buffer first! If there is data already in the buffer it will be written out on the next flush!

impl<W: Write, P> BufWriter<W, P>

Important traits for BufWriter<W, P>

impl<W: Write, P: WriterPolicy> Write for BufWriter<W, P>

pub fn set_policy<P_: WriterPolicy>(self, policy: P_) -> BufWriter<W, P_>

Set a new WriterPolicy, returning the transformed type.

pub fn policy_mut(&mut self) -> &mut P

Mutate the current WriterPolicy.

pub fn policy(&self) -> &P

Inspect the current WriterPolicy.

pub fn get_ref(&self) -> &W

Get a reference to the inner writer.

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

Get a mutable reference to the inner writer.

Note

If the buffer has not been flushed, writing directly to the inner type will cause data inconsistency.

pub fn capacity(&self) -> usize

Get the capacty of the inner buffer.

pub fn buf_len(&self) -> usize

Get the number of bytes currently in the buffer.

pub fn reserve(&mut self, additional: usize)

Reserve space in the buffer for at least additional bytes. May not be quite exact due to implementation details of the buffer's allocator.

pub fn make_room(&mut self)

Move data to the start of the buffer, making room at the end for more writing.

This is a no-op with the *_ringbuf() constructors (requires slice-deque feature).

pub fn into_inner_with_buffer(self) -> (W, Buffer)

Consume self and return both the underlying writer and the buffer

impl<W: Write, P: WriterPolicy> BufWriter<W, P>

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

Flush the buffer and unwrap, returning the inner writer on success, or a type wrapping self plus the error otherwise.

pub fn into_inner_with_err(self) -> (W, Option<Error>)

Flush the buffer and unwrap, returning the inner writer and any error encountered during flushing.

Trait Implementations

impl<W: Write, P> Drop for BufWriter<W, P>

Attempt to flush the buffer to the underlying writer.

If an error occurs, the thread-local handler is invoked, if one was previously set by set_drop_err_handler for this thread.

fn drop(&mut self)

Executes the destructor for this type.

impl<W: Write + Debug, P: Debug> Debug for BufWriter<W, P>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<W: Write, P: WriterPolicy> Write for BufWriter<W, P>

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

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

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

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

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

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

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

Attempts to write an entire buffer into this writer.

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

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

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

Creates a "by reference" adaptor for this instance of Write.

impl<W: Write + Seek, P: WriterPolicy> Seek for BufWriter<W, P>

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to the ofPet, in bytes, in the underlying writer.

Seeking always writes out the internal buffer before seeking.

fn stream_len(&mut self) -> Result<u64, Error>

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

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

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

Returns the current seek position from the start of the stream.