Struct buf_redux::Buffer

pub struct Buffer { /* private fields */ }

A deque-like datastructure for managing bytes.

Supports interacting via I/O traits like Read and Write, and direct access.

Implementations

impl Buffer

pub fn new() -> Self

Create a new buffer with a default capacity.

pub fn with_capacity(cap: usize) -> Self

Create a new buffer with at least the given capacity.

If the global allocator returns extra capacity, Buffer will use all of it.

pub fn new_ringbuf() -> Self

Allocate a buffer with a default capacity that never needs to move data to make room (consuming from the head simultaneously makes more room at the tail).

The default capacity varies based on the target platform:

• Unix-derivative platforms; Linux, OS X, BSDs, etc: 8KiB (the default buffer size for std::io buffered types)
• Windows: 64KiB because of legacy reasons, of course (see below)

Only available on platforms with virtual memory support and with the slice-deque feature enabled. The current platforms that are supported/tested are listed in the README for the slice-deque crate.

pub fn with_capacity_ringbuf(cap: usize) -> Self

Allocate a buffer with at least the given capacity that never needs to move data to make room (consuming from the head simultaneously makes more room at the tail).

The capacity will be rounded up to the minimum size for the current target:

• Unix-derivative platforms; Linux, OS X, BSDs, etc: the next multiple of the page size (typically 4KiB but can vary based on system configuration)
• Windows: the next muliple of 64KiB; see this Microsoft dev blog post for why it’s 64KiB and not the page size (TL;DR: Alpha AXP needs it and it’s applied on all targets for consistency/portability)

Only available on platforms with virtual memory support and with the slice-deque feature enabled. The current platforms that are supported/tested are listed in the README for the slice-deque crate.

pub fn is_ringbuf(&self) -> bool

Return true if this is a ringbuffer.

pub fn len(&self) -> usize

Return the number of bytes currently in this buffer.

Equivalent to self.buf().len().

pub fn usable_space(&self) -> usize

Return the number of bytes that can be read into this buffer before it needs to grow or the data in the buffer needs to be moved.

This may not constitute all free space in the buffer if bytes have been consumed from the head. Use free_space() to determine the total free space in the buffer.

pub fn free_space(&self) -> usize

Returns the total amount of free space in the buffer, including bytes already consumed from the head.

This will be greater than or equal to usable_space(). On supported platforms with the slice-deque feature enabled, it should be equal.

pub fn capacity(&self) -> usize

Return the total capacity of this buffer.

pub fn is_empty(&self) -> bool

Returns true if there are no bytes in the buffer, false otherwise.

pub fn make_room(&mut self)

Move bytes down in the buffer to maximize usable space.

This is a no-op on supported platforms with the slice-deque feature enabled.

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

Ensure space for at least additional more bytes in the buffer.

This is a no-op if usable_space() >= additional. Note that this will reallocate even if there is enough free space at the head of the buffer for additional bytes, because that free space is not at the tail where it can be read into. If you prefer copying data down in the buffer before attempting to reallocate you may wish to call .make_room() first.

Panics

If self.capacity() + additional overflows.

pub fn buf(&self) -> &[u8]

Get an immutable slice of the available bytes in this buffer.

Call .consume() to remove bytes from the beginning of this slice.

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

Get a mutable slice representing the available bytes in this buffer.

Call .consume() to remove bytes from the beginning of this slice.

pub fn read_from<R: Read + ?Sized>(&mut self, rdr: &mut R) -> Result<usize>

Read from rdr, returning the number of bytes read or any errors.

If there is no more room at the head of the buffer, this will return Ok(0).

Uses Read::initializer() to initialize the buffer if the nightly feature is enabled, otherwise the buffer is zeroed if it has never been written.

Panics

If the returned count from rdr.read() overflows the tail cursor of this buffer.

pub fn copy_from_slice(&mut self, src: &[u8]) -> usize

Copy from src to the tail of this buffer. Returns the number of bytes copied.

This will not grow the buffer if src is larger than self.usable_space(); instead, it will fill the usable space and return the number of bytes copied. If there is no usable space, this returns 0.

pub fn write_to<W: Write + ?Sized>(&mut self, wrt: &mut W) -> Result<usize>

Write bytes from this buffer to wrt. Returns the number of bytes written or any errors.

If the buffer is empty, returns Ok(0).

Panics

If the count returned by wrt.write() would cause the head cursor to overflow or pass the tail cursor if added to it.

pub fn write_max<W: Write + ?Sized>(
    &mut self,
    max: usize,
    wrt: &mut W
) -> Result<()>

Write, at most, the given number of bytes from this buffer to wrt, continuing to write and ignoring interrupts until the number is reached or the buffer is empty.

Panics

If the count returned by wrt.write() would cause the head cursor to overflow or pass the tail cursor if added to it.

pub fn write_all<W: Write + ?Sized>(&mut self, wrt: &mut W) -> Result<()>

Write all bytes in this buffer to wrt, ignoring interrupts. Continues writing until the buffer is empty or an error is returned.

Panics

If self.write_to(wrt) panics.

pub fn copy_to_slice(&mut self, out: &mut [u8]) -> usize

Copy bytes to out from this buffer, returning the number of bytes written.

pub fn push_bytes(&mut self, bytes: &[u8])

Push bytes to the end of the buffer, growing it if necessary.

If you prefer moving bytes down in the buffer to reallocating, you may wish to call .make_room() first.

pub fn consume(&mut self, amt: usize)

Consume amt bytes from the head of this buffer.

pub fn clear(&mut self)

Empty this buffer by consuming all bytes.

Trait Implementations

impl Debug for Buffer

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

Formats the value using the given formatter.