Struct inplace_it::UninitializedSliceMemoryGuard

pub struct UninitializedSliceMemoryGuard<'a, T> { /* fields omitted */ }

Guard-struct used to own uninitialized memory and provide functions for initializing it. Usually, you should not use this struct to handle your memory.

Initializing functions spawns SliceMemoryGuard which will provide access to initialized memory. It also means memory can be used again after SliceMemoryGuard is dropped.

Safety

If you use this struct manually, remember: &mut [MaybeUninit<T>]'s content will be overwriten while initialization. So it is not safe to apply this struct to already initialized data and it can lead to memory leaks.

Example

use inplace_it::UninitializedSliceMemoryGuard;
use std::mem::MaybeUninit;

// Placing uninitialized memory
let mut memory: [MaybeUninit<usize>; 100] = unsafe { MaybeUninit::uninit().assume_init() };
// Initializing guard
let mut uninit_memory_guard = unsafe { UninitializedSliceMemoryGuard::new(&mut memory) };

{
    // Initializing memory
    let mut memory_guard = uninit_memory_guard
        // we need to call .borrow() because out init-API consumes uninit-guard
        .borrow()
        // then passing initialize closure and the guard is ok
        .init(|index| index * 2);
    // For now, memory contains content like [0, 2, 4, 6, ..., 196, 198]

    // Using memory
    // Sum of [0, 2, 4, 6, ..., 196, 198] = sum of [0, 1, 2, 3, ..., 98, 99] * 2 = ( 99 * (99+1) ) / 2 * 2
    let sum: usize = memory_guard.iter().sum();
    assert_eq!(sum, 99 * 100);
    // memory_guard dropped here
}

// uninit_memory_guard is available again now

{
    // Initializing memory
    let mut memory_guard = uninit_memory_guard.init(|index| index * index);
    // For now, memory contains content like [0, 1, 4, 9, ..., 9604, 9801]

    // Using memory
    // Sum of [0, 1, 4, 9, ..., 9604, 9801] = 99 * (99 + 1) * (2 * 99 + 1) / 6
    let sum: usize = memory_guard.iter().sum();
    assert_eq!(sum, 99 * (99 + 1) * (2 * 99 + 1) / 6);
    // memory_guard dropped here
}

Implementations

impl<'a, T> UninitializedSliceMemoryGuard<'a, T>

pub unsafe fn new(memory: &'a mut [MaybeUninit<T>]) -> Self

Initialize memory guard

pub fn len(&self) -> usize

Get the length of memory slice

pub fn slice(self, range: impl RangeBounds<usize>) -> Self

Construct new memory guard with new bounds.

Can be used to shrink memory.

Panics

Panic can be reached when given range is out of memory's range.

pub fn init(self, init: impl FnMut(usize) -> T) -> SliceMemoryGuard<'a, T>

Initialize memory and make new guard of initialized memory. Given init closure will be used to initialize elements of memory slice.

pub fn init_copy_of(self, source: &[T]) -> SliceMemoryGuard<'a, T> where
    T: Clone, 

Initialize memory and make new guard of initialized memory. Given source slice will be used to initialize elements of memory slice. Returned guard will contain sliced memory to source's length.

Panics

Panic can be reached when given source's range is out of memory's range.

pub fn init_with_iter(
    self,
    mut iter: impl ExactSizeIterator<Item = T>
) -> SliceMemoryGuard<'a, T>

Initialize memory and make new guard of initialized memory. Given iter exact-size iterator will be used to initialize elements of memory slice. Returned guard will contain sliced memory to iter's length.

Panics

Panic can be reached when given iter's length is out of memory's range.

pub fn init_with_dyn_iter(
    self,
    iter: impl Iterator<Item = T>
) -> Result<SliceMemoryGuard<'a, T>, Vec<T>>

Initialize memory guard using given iterator. Automatically shrink's memory to given items' count. Ok(guard) will be returned in this case.

If items' count is too large to place in memory, moves it into new Vec and continue collecting into it. Err(vec) will be returned in this case.

pub fn borrow(&mut self) -> UninitializedSliceMemoryGuard<'_, T>

Create new uninit memory guard with less or equal lifetime to original guard's lifetime. This function should be used to reuse memory because init-API consumes the guard.