Struct BorrowedCursor 

pub struct BorrowedCursor<'a, T> { /* private fields */ }

A writeable view of the unfilled portion of a BorrowedBuf.

The unfilled portion may be uninitialized; see BorrowedBuf for details.

Data can be written directly to the cursor by using append or indirectly by getting a slice of part or all of the cursor and writing into the slice. In the indirect case, the caller must call advance after writing to inform the cursor how many elements have been written.

Once elements are written to the cursor, they become part of the filled portion of the underlying BorrowedBuf and can no longer be accessed or re-written by the cursor. In other words, the cursor tracks the unfilled part of the underlying BorrowedBuf.

The lifetime 'a is a bound on the lifetime of the underlying buffer (which means it is a bound on the elements in that buffer by transitivity).

Examples

use borrowed_buf::{BorrowedBuf, BorrowedCursor};
use core::mem::MaybeUninit;

// A producer that only sees the free space.
fn produce(mut cursor: BorrowedCursor<'_, u32>) {
    let n = cursor.capacity().min(3);
    // SAFETY: only initialized values are written.
    let out = unsafe { cursor.as_mut() };
    for (i, slot) in out[..n].iter_mut().enumerate() {
        slot.write(i as u32 * 10);
    }
    // SAFETY: the first `n` elements of the cursor were just written.
    unsafe { cursor.advance(n) };
}

let mut storage = [MaybeUninit::uninit(); 4];
let mut buf = BorrowedBuf::from(&mut storage[..]);
buf.unfilled().append(&[7]);
produce(buf.unfilled());
assert_eq!(buf.filled(), &[7, 0, 10, 20]);

Implementations

impl<'a, T: Copy> BorrowedCursor<'a, T>

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

Reborrows this cursor by cloning it with a smaller lifetime.

Since a cursor maintains unique access to its underlying buffer, the borrowed cursor is not accessible while the new cursor exists.

pub fn capacity(&self) -> usize

Returns the available space in the cursor.

pub fn written(&self) -> usize

Returns the number of elements written to the BorrowedBuf this cursor was created from.

In particular, the count returned is shared by all reborrows of the cursor.

pub fn is_init(&self) -> bool

Returns true if the buffer is initialized.

pub unsafe fn set_init(&mut self)

Set the buffer as fully initialized.

Safety

All the elements of the cursor must be initialized.

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

let mut storage = [MaybeUninit::<u8>::uninit(); 4];
let mut buf = BorrowedBuf::from(&mut storage[..]);
let mut cursor = buf.unfilled();
// SAFETY: only initialized values are written.
unsafe { cursor.as_mut() }.fill(MaybeUninit::new(b'x'));
// SAFETY: every element of the cursor was just written.
unsafe { cursor.set_init() };
cursor.advance_checked(4);
assert_eq!(buf.filled(), b"xxxx");

pub unsafe fn as_mut(&mut self) -> &mut [MaybeUninit<T>]

Returns a mutable reference to the whole cursor.

Safety

The caller must not uninitialize any elements of the cursor if it is initialized.

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

Advances the cursor by asserting that n elements have been filled.

After advancing, the n elements are no longer accessible via the cursor and can only be accessed via the underlying buffer. I.e., the buffer’s filled portion grows by n elements and its unfilled portion (and the capacity of this cursor) shrinks by n elements.

If less than n elements initialized (by the cursor’s point of view), set_init should be called first.

Panics

Panics if there are less than n elements initialized.

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

Advances the cursor by asserting that n elements have been filled.

After advancing, the n elements are no longer accessible via the cursor and can only be accessed via the underlying buffer. I.e., the buffer’s filled portion grows by n elements and its unfilled portion (and the capacity of this cursor) shrinks by n elements.

Safety

The caller must ensure that the first n elements of the cursor have been initialized.

pub fn append(&mut self, buf: &[T])

Append elements to the cursor, advancing position within its buffer.

Panics

Panics if self.capacity() is less than buf.len().

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

let mut storage = [MaybeUninit::uninit(); 4];
let mut buf = BorrowedBuf::from(&mut storage[..]);
buf.unfilled().append(&[1u64, 2]);
buf.unfilled().append(&[3]);
assert_eq!(buf.filled(), &[1, 2, 3]);

pub fn append_fill(&mut self, n: usize, value: T)

Appends n copies of value to the cursor, advancing position within its buffer.

Like append, this writes each element once and leaves the rest of the cursor untouched. It does not need a source slice of n elements.

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

Panics

Panics if self.capacity() is less than n.

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

let mut storage = [MaybeUninit::uninit(); 8];
let mut buf = BorrowedBuf::<u8>::from(&mut storage[..]);
let mut cursor = buf.unfilled();
cursor.append(b"ab");
cursor.append_fill(3, b'-');
assert_eq!(buf.filled(), b"ab---");
assert!(!buf.is_init());

pub fn with_unfilled_buf<R>( &mut self, f: impl FnOnce(&mut BorrowedBuf<'_, T>) -> R, ) -> R

Runs the given closure with a BorrowedBuf containing the unfilled part of the cursor.

This enables inspecting what was written to the cursor.

Panics

Panics if the BorrowedBuf given to the closure is replaced by another one.

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

let mut storage = [MaybeUninit::uninit(); 8];
let mut buf = BorrowedBuf::from(&mut storage[..]);
let mut cursor = buf.unfilled();
cursor.append(b"ab");
let fresh = cursor.with_unfilled_buf(|sub| {
    sub.unfilled().append(b"cd");
    sub.filled().to_vec()
});
assert_eq!(fresh, b"cd");
assert_eq!(buf.filled(), b"abcd");

impl<'a, T: Default + Copy> BorrowedCursor<'a, T>

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

Initializes all elements in the cursor with their default value and returns them.

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

let mut storage = [MaybeUninit::<f32>::uninit(); 4];
let mut buf = BorrowedBuf::from(&mut storage[..]);
let mut cursor = buf.unfilled();

let out = cursor.ensure_init();
assert_eq!(out, &[0.0; 4]);
out[0] = 1.5;
cursor.advance_checked(1);
assert_eq!(buf.filled(), &[1.5]);

Trait Implementations

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

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

Formats the value using the given formatter.

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.

impl<T: Send> Send for BorrowedCursor<'_, T>

impl<T: Sync> Sync for BorrowedCursor<'_, T>

impl Write for BorrowedCursor<'_, u8>

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

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

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

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

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

Attempts to write an entire buffer into this writer.

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

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

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.