Struct BufferedByteOutput 

pub struct BufferedByteOutput<W> { /* private fields */ }

Buffered byte output over a wrapped writer.

This type keeps a fixed-size byte buffer in front of an underlying writer so small byte writes can be accumulated before they are written to the I/O target. Large writes may bypass the buffer after pending buffered bytes have been flushed.

BufferedByteOutput is deliberately byte-oriented. It performs no binary encoding, text encoding, or record framing. Higher-level writers can either use the standard Write implementation or write directly into Self::spare_buffer_mut or Self::spare_raw_parts_mut and then call Self::advance or Self::advance_unchecked after validating the range they initialized. Callers that need to recover the wrapped writer should call Write::flush first, then use Self::into_parts.

Implementations

impl<W> BufferedByteOutput<W>

pub fn new(inner: W) -> Self

Creates a buffered byte output with the default capacity.

Parameters

• inner - The writer that receives bytes when the internal buffer is flushed.

Returns

A new buffered byte output using DEFAULT_BUFFER_CAPACITY.

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

Creates a buffered byte output with at least the requested capacity.

Parameters

• inner - The writer that receives bytes when the internal buffer is flushed.
• capacity - The requested internal buffer capacity in bytes.

Returns

A new buffered byte output whose actual buffer capacity is capacity.max(1).

pub const fn inner(&self) -> &W

Returns a shared reference to the wrapped writer.

Returns

An immutable reference to the underlying writer. Pending bytes may still be present in the internal buffer and are not flushed by this method.

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

Returns an exclusive reference to the wrapped writer.

Pending bytes may still be present in the internal buffer and are not flushed by this method.

Returns

A mutable reference to the underlying writer.

pub fn capacity(&self) -> usize

Returns the internal buffer capacity.

Returns

The total number of bytes that can be held by the internal buffer.

pub fn spare_capacity(&self) -> usize

Returns the unused capacity in the internal buffer.

Returns

The number of bytes that can still be appended to the internal buffer before it must be flushed.

pub fn spare_buffer_mut(&mut self) -> &mut [u8]

Returns the unused portion of the internal buffer.

Callers may write initialized bytes into the returned slice and then call Self::advance with the number of bytes written.

Returns

A mutable slice over the spare buffer capacity.

pub fn spare_raw_parts_mut(&mut self) -> (&mut [u8], usize, usize)

Returns raw spare-buffer parts for hot-path callers.

The returned slice is the full internal backing storage. index is the start of the spare byte window, and count is the number of spare bytes. Callers that need a slice can use &mut buffer[index..index + count]; callers that already validated bounds can pass buffer and index directly to indexed unchecked codecs.

Mutating bytes outside index..index + count changes pending output bytes and may corrupt the logical stream.

Returns

The backing storage, the spare start index, and the spare byte count.

pub fn advance(&mut self, count: usize)

Marks count bytes from Self::spare_buffer_mut as written.

Parameters

• count - Number of bytes initialized by the caller.

Panics

Panics when count exceeds Self::spare_capacity.

pub unsafe fn advance_unchecked(&mut self, count: usize)

Marks spare bytes as written without checking bounds.

Parameters

• count - Number of initialized spare bytes to make pending for output.

Safety

The caller must guarantee that count <= self.spare_capacity() and that the corresponding bytes returned by Self::spare_buffer_mut have been initialized.

impl<W> BufferedByteOutput<W>

where W: Write,

pub fn into_parts(self) -> (W, Vec<u8>)

Consumes this buffered output without flushing pending bytes.

This method performs no I/O. Pending bytes that have been accepted into the internal buffer but not written to the wrapped writer are returned as the second tuple item.

Returns

The wrapped writer and pending bytes in logical write order.

pub fn ensure_spare_capacity(&mut self, count: usize) -> Result<()>

Ensures that at least count bytes are available in the spare buffer.

Parameters

• count - Number of spare bytes required.

Errors

Returns any non-interrupted I/O error produced while flushing buffered bytes. Returns ErrorKind::InvalidInput if count exceeds the buffer capacity. Returns ErrorKind::InvalidData if the wrapped writer reports more bytes than the pending buffer range contained.

pub fn flush_buffer(&mut self) -> Result<()>

Flushes buffered bytes to the wrapped writer.

The method retries interrupted writes. If an error occurs after some bytes have been written, the already-written bytes are removed from the front of the buffer and the unwritten suffix is kept for a later retry.

Returns

Ok(()) once all currently buffered bytes have been written to the wrapped writer.

Errors

Returns any non-interrupted I/O error produced by the wrapped writer. Returns ErrorKind::WriteZero if the writer reports a zero-length write before all buffered bytes are drained. Returns ErrorKind::InvalidData if the writer reports more bytes than the pending buffer range contained.

Trait Implementations

impl<W: Debug> Debug for BufferedByteOutput<W>

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

Formats the value using the given formatter.

impl<W> Seek for BufferedByteOutput<W>

where W: Write + Seek,

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

Flushes pending bytes before seeking the wrapped writer.

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

Rewind to the beginning of a stream.

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

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

Returns the length of this stream (in bytes).

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

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

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.

impl<W> Write for BufferedByteOutput<W>

where W: Write,

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

Writes bytes through the internal buffer.

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

Writes all bytes through the internal buffer.

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

Flushes the internal buffer and then the wrapped writer.

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

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_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

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

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.