Struct possibly_uninit::slice::Cursor

pub struct Cursor<Item, Arr: BorrowOutSlice<Item> + ?Sized> { /* fields omitted */ }

Wraps a (maybe uninitialized) slice as a BorrowOutSlice, tracking the position. This allows you to work with readers and uninitialized memory completely safely.

Note that this type doesn’t implement traits like Deref, Borrow, AsRef, BorrowUninitSlice. This isn’t a gross negligence, it’s done on purpose. Basically, it acts as if it contained two or even three buffers! Which buffer should be returned? One might kinda reasonably claim it should be first part for [Item] slices, second part for [MaybeUninit]. But that would be extremely confusing, especially considering that [Item] can be used where [MaybeUniniti] is expected.

This looks like a huge freaking footgun that I’m unwilling to create. However I’d like to implement wrapper type in the future that will make it explicit. E.g. something like Cursed<Written, T>, Cursed<Uninit, T>, Cursed<Entire, T>. :) PRs welcome!

Important: This wrapper currently doesn’t care about leaking! If you want to avoid leaks, it’s recommended to use it only with buffers containing MaybeUninit<T> or with Copy types.

This may change in future versions.

Implementations

impl<Item, Arr: BorrowOutSlice<Item>> Cursor<Item, Arr>

pub fn new(buf: Arr) -> Self

Creates Cursor initialized with position 0

impl<Item, Arr: BorrowOutSlice<Item> + ?Sized> Cursor<Item, Arr>

pub fn push(&mut self, item: Item) -> Result<&mut Item, Item>

Pushes an item at the end of the array

pub fn push_iter<I>(&mut self, iter: I) -> &mut [Item] where
    I: IntoIterator,
    I::Item: TakeItem<Item>, 

Pushes up to .remaining_count() items from the iterator and returns a subslice corresponding to just written items.

If you want to access everything that has been written so far, use the written() method after call to this one.

pub fn remaining_count(&self) -> usize

Returns the number of items that can be written to this cursor.

pub fn reset(&mut self)

Resets the position to 0.

pub fn written(&self) -> &[Item]

Access the written slice.

pub fn written_mut(&mut self) -> &mut [Item]

Mutably access the written slice.

pub fn pop(&mut self) -> Option<Item> where
    Item: Copy, 

Attempts to “remove” the last item and return it.

This can be implemented for Copy types safely, as swapping the place with uninitialized memory would cause corruption if the slice was actually not MaybeUninit.

pub fn pop_slice(&mut self, max: usize) -> &mut [Item]

“Removes” up to max slice from the buffer and returns them as slice.

Empty slice is returned if the position is zero, of course.

pub fn try_pop_slice(&mut self, required: usize) -> Option<&mut [Item]>

Attempts to “remove” required number of slice from the buffer and return them as slice. Keeps the cursor unchanged in case of failure.

Empty slice is returned if the position is zero, of course.

pub fn split_mut(&mut self) -> (&mut [Item], &mut OutSlice<Item>)

Splits the internal buffer at current position and returns both initialized and uninitialized part.

pub fn try_cast_initialized(self) -> Result<<Arr as InitTc<Item>>::Output, Self> where
    Arr: Sized + InitTc<Item>, 

Tries to cast the underlying data into initialized version of the container, if the entire slice was filled.

Trait Implementations

impl<Item, Arr: BorrowOutSlice<Item>> From<Arr> for Cursor<Item, Arr>

fn from(value: Arr) -> Self

Performs the conversion.