Struct BorrowedCursor

pub struct BorrowedCursor<'a, T> { pub(in ::io::borrowed_buf) buf: NonNull<MaybeUninit<T>>, pub(in ::io::borrowed_buf) borrowed_buf: NonNull<BorrowedBuf<'a, T>> }

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).

Fields

buf: NonNull<MaybeUninit<T>>

The start of the elements of the buffer this cursor was created from. Safety invariant: this points to the start of the whole buffer of *borrowed_buf and is valid for reads and writes of (*borrowed_buf).buf.len() elements, so that (*borrowed_buf).filled indexes into it.

borrowed_buf: NonNull<BorrowedBuf<'a, T>>

The buffer this cursor was created from. Safety invariants:

  1. (*borrowed_buf).buf is never accessed by the owner of the pointee while the buf field above is alive, because there is a &mut of the pointee while the cursor is alive.
  2. We promise to only access the filled and init fields and the metadata of the buf field through the borrowed_buf pointer, never triggering any retag of buf's pointer, as the buf field above holds a reborrow of it and reaching the parent again would be a foreign access for that reborrow. This includes not making a reference to the whole pointee out of borrowed_buf, but only accessing those fields directly through pointer manipulation.

Implementations

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

fn buf_mut(&mut self) -> &mut [MaybeUninit<T>]
fn buf_len(&self) -> usize
fn unfilled_slice(&mut self) -> &mut [MaybeUninit<T>]
fn filled(&self) -> usize
fn is_buf_init(&self) -> bool
unsafe fn set_buf_init(&mut self, init: bool)

Safety

In case of true all the elements of the cursor must be initialized.

unsafe fn add_filled(&mut self, n: usize)

Safety

The next n elements of the cursor must be initialized.

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

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.

fn capacity(&self) -> usize

Returns the available space in the cursor.

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.

fn is_init(&self) -> bool

Returns true if the buffer is initialized.

unsafe fn set_init(&mut self)

Set the buffer as fully initialized.

Safety

All the elements of the cursor must be initialized.

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.

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.

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.

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().

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.

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

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

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

Trait Implementations

impl<'a> Write for BorrowedCursor<'a, u8>

fn write(&mut self, buf: &[u8]) -> Result<usize>
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>
fn is_write_vectored(&self) -> bool
fn write_all(&mut self, buf: &[u8]) -> Result<()>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>
fn flush(&mut self) -> Result<()>

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

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

Auto Trait Implementations

impl<'a, T> !Send for BorrowedCursor<'a, T>

impl<'a, T> !Sync for BorrowedCursor<'a, T>

impl<'a, T> Freeze for BorrowedCursor<'a, T> where NonNull<MaybeUninit<T>>: Freeze, NonNull<BorrowedBuf<'a, T>>: Freeze,

impl<'a, T> RefUnwindSafe for BorrowedCursor<'a, T> where NonNull<MaybeUninit<T>>: RefUnwindSafe, NonNull<BorrowedBuf<'a, T>>: RefUnwindSafe,

impl<'a, T> Unpin for BorrowedCursor<'a, T> where NonNull<MaybeUninit<T>>: Unpin, NonNull<BorrowedBuf<'a, T>>: Unpin,

impl<'a, T> UnsafeUnpin for BorrowedCursor<'a, T> where NonNull<MaybeUninit<T>>: UnsafeUnpin, NonNull<BorrowedBuf<'a, T>>: UnsafeUnpin,

impl<'a, T> UnwindSafe for BorrowedCursor<'a, T> where NonNull<MaybeUninit<T>>: UnwindSafe, NonNull<BorrowedBuf<'a, T>>: UnwindSafe,

Blanket Implementations

impl<T> Any for BorrowedCursor<'a, T> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for BorrowedCursor<'a, T> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for BorrowedCursor<'a, T> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for BorrowedCursor<'a, T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> SizeHint for BorrowedCursor<'a, T> where T: ?Sized,

fn lower_bound(&self) -> usize
fn upper_bound(&self) -> Option<usize>

impl<T> SizedTypeProperties for BorrowedCursor<'a, T>

impl<T, U> Into<U> for BorrowedCursor<'a, T> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for BorrowedCursor<'a, T> where U: Into<T>,

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for BorrowedCursor<'a, T> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>