Struct BorrowedBuf 

pub struct BorrowedBuf<'data, T> { /* private fields */ }

A borrowed buffer of initially uninitialized elements, which is incrementally filled.

This type makes it safer to work with MaybeUninit buffers, such as to read into a buffer without having to initialize it first. It tracks the region of elements that have been filled and whether the unfilled region was initialized.

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

[                capacity                ]
[ filled | unfilled (may be initialized) ]

A BorrowedBuf is created around some existing elements (or capacity for elements) 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 elements.

The type is most commonly used to manage bytes, but can manage any type of elements.

Examples

use borrowed_buf::BorrowedBuf;
use core::mem::MaybeUninit;

let mut storage = [MaybeUninit::<u8>::uninit(); 8];
let mut buf = BorrowedBuf::from(&mut storage[..]);

buf.unfilled().append(b"abc");
assert_eq!(buf.filled(), b"abc");

buf.clear();
assert_eq!(buf.len(), 0);

Implementations

impl<'data, T> BorrowedBuf<'data, T>

pub fn capacity(&self) -> usize

Returns the total capacity of the buffer.

pub fn len(&self) -> usize

Returns the length of the filled part of the buffer.

pub fn is_init(&self) -> bool

Returns true if the buffer is initialized.

impl<'data, T: Copy> BorrowedBuf<'data, T>

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

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

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

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

pub fn into_filled(self) -> &'data [T]

Returns a shared reference to the filled portion of the buffer with its original lifetime.

pub fn into_filled_mut(self) -> &'data mut [T]

Returns a mutable reference to the filled portion of the buffer with its original lifetime.

use borrowed_buf::BorrowedBuf;
use core::mem::MaybeUninit;

fn fill(storage: &mut [MaybeUninit<u8>]) -> &mut [u8] {
    let mut buf = BorrowedBuf::from(storage);
    buf.unfilled().append(b"done");
    buf.into_filled_mut()
}

let mut storage = [MaybeUninit::uninit(); 8];
assert_eq!(fill(&mut storage), b"done");

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

Returns a cursor over the unfilled part of the buffer.

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

Clears the buffer, resetting the filled region to empty.

The contents of the buffer are not modified.

pub fn truncate(&mut self, len: usize) -> &mut Self

Shortens the filled region to len elements.

If len is greater than or equal to len, this has no effect. The contents of the buffer are not modified, and the elements cut off stay initialized, so is_init is unchanged.

This is not part of core::io::BorrowedBuf.

use borrowed_buf::BorrowedBuf;
use core::mem::MaybeUninit;

let mut storage = [MaybeUninit::uninit(); 8];
let mut buf = BorrowedBuf::<u8>::from(&mut storage[..]);
buf.unfilled().append(b"abcdef");
buf.truncate(2);
assert_eq!(buf.filled(), b"ab");
buf.unfilled().append(b"!");
assert_eq!(buf.filled(), b"ab!");

pub unsafe fn set_init(&mut self) -> &mut Self

Asserts that the unfilled part of the buffer is initialized.

Safety

All the elements of the buffer must be initialized.

use borrowed_buf::BorrowedBuf;
use core::mem::MaybeUninit;

let mut storage = [MaybeUninit::new(0u8); 4];
let mut buf = BorrowedBuf::<u8>::from(&mut storage[..]);
assert!(!buf.is_init());
// SAFETY: every element of `storage` was initialized above.
unsafe { buf.set_init() };
buf.unfilled().advance_checked(4);
assert_eq!(buf.filled(), &[0; 4]);

Trait Implementations

impl<T> Debug for BorrowedBuf<'_, T>

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

Formats the value using the given formatter.

impl<'data, T: Copy> From<&'data mut [MaybeUninit<T>]> for BorrowedBuf<'data, T>

Creates a new BorrowedBuf from an uninitialized buffer.

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

Converts to this type from the input type.

impl<'data, T: Copy> From<&'data mut [T]> for BorrowedBuf<'data, T>

Creates a new BorrowedBuf from a fully initialized slice.

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

Converts to this type from the input type.

impl<'data, T: Copy> From<BorrowedCursor<'data, T>> for BorrowedBuf<'data, T>

Creates a new BorrowedBuf from a cursor.

Use BorrowedCursor::with_unfilled_buf instead for a safer alternative.

fn from(buf: BorrowedCursor<'data, T>) -> BorrowedBuf<'data, T>

Converts to this type from the input type.