Struct std::io::readbuf::BorrowedBuf

pub struct BorrowedBuf<'data> {
    buf: &'data mut [MaybeUninit<u8>],
    filled: usize,
    init: usize,
}

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

A borrowed byte buffer which is incrementally filled and initialized.

This type is a sort of “double cursor”. It tracks three regions in the buffer: a region at the beginning of the buffer that has been logically filled with data, a region that has been initialized at some point but not yet logically filled, and a region at the end that is fully uninitialized. The filled region is guaranteed to be a subset of the initialized region.

In summary, the contents of the buffer can be visualized as:

[             capacity              ]
[ filled |         unfilled         ]
[    initialized    | uninitialized ]

A BorrowedBuf is created around some existing data (or capacity for data) via a unique reference (&mut). The BorrowedBuf can be configured (e.g., using clear or set_init), but cannot be directly written. To write into the buffer, use unfilled to create a BorrowedCursor. The cursor has write-only access to the unfilled portion of the buffer (you can think of it as a write-only iterator).

The lifetime 'data is a bound on the lifetime of the underlying data.

Fields

buf: &'data mut [MaybeUninit<u8>]

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

The buffer’s underlying data.

filled: usize

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

The length of self.buf which is known to be filled.

init: usize

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

The length of self.buf which is known to be initialized.

Implementations

impl<'data> BorrowedBuf<'data>

pub fn capacity(&self) -> usize

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

Returns the total capacity of the buffer.

pub fn len(&self) -> usize

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

Returns the length of the filled part of the buffer.

pub fn init_len(&self) -> usize

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

Returns the length of the initialized part of the buffer.

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

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

Returns a shared reference to the filled portion of the buffer.

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

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

Returns a mutable reference to the filled portion of the buffer.

pub fn unfilled<'this>(&'this mut self) -> BorrowedCursor<'this>

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

Returns a cursor over the unfilled part of the buffer.

pub fn clear(&mut self) -> &mut Self

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

Clears the buffer, resetting the filled region to empty.

The number of initialized bytes is not changed, and the contents of the buffer are not modified.

pub unsafe fn set_init(&mut self, n: usize) -> &mut Self

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

Asserts that the first n bytes of the buffer are initialized.

BorrowedBuf assumes that bytes are never de-initialized, so this method does nothing when called with fewer bytes than are already known to be initialized.

Safety

The caller must ensure that the first n unfilled bytes of the buffer have already been initialized.

Trait Implementations

impl Debug for BorrowedBuf<'_>

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

Formats the value using the given formatter.

impl<'data> From<&'data mut [MaybeUninit<u8>]> for BorrowedBuf<'data>

Create a new BorrowedBuf from an uninitialized buffer.

Use set_init if part of the buffer is known to be already initialized.

fn from(buf: &'data mut [MaybeUninit<u8>]) -> BorrowedBuf<'data>

Converts to this type from the input type.

impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data>

Create a new BorrowedBuf from a fully initialized slice.

fn from(slice: &'data mut [u8]) -> BorrowedBuf<'data>

Converts to this type from the input type.