Crate inplace_it

Inplace it!

Place small arrays on the stack with a low cost!

The only price you should pay for this is the price of choosing a type based on the size of the requested array! This is just one match!

What?

This crate is created for one purpose: allocating small arrays on the stack. The simplest way to use it is:

use inplace_it::inplace_array;

inplace_array(
    150, // size of needed array to allocate
    4096, // limit in bytes allowed to allocate on the stack
          // if the limit is exceeded then Vec<T> will be used
    |index| index * 2, // initializer will be called for every item in the array
    |memory: &mut [usize]| { // and this is consumer of initialized memory
        assert_eq!(memory.len(), 150);
    }
)

More details you can find in inplace_array description.

You can also place copy of some array.

use inplace_it::inplace_copy_of;

let source = [1, 2, 3, 4, 10];

inplace_copy_of(
    &source, //source for copy
    4096, // limit of allowed stack allocation in bytes
    |memory: &mut [usize]| { // consumer which will use our allocated array
        // Given reference will contains exactly copy of given array.
        assert_eq!(*memory, source);
    }
);

More details you can find in inplace_copy_of description.

You can also place uninitialized array. This operation is faster because of it haven't initializing overhead but you should use it with care.

use inplace_it::inplace_array_uninitialized;

unsafe {
    inplace_array_uninitialized(
        228, //size of array
        4096, // limit of allowed stack allocation in bytes
        |memory: &mut [usize]| { // consumer which will use our allocated array
            // Unsafely placed array sometimes can be more that you need.
            assert!(memory.len() >= 228);
            // In secret, the size will be equal to the nearest multiple of 32 (upwards, of course).
            assert_eq!(memory.len(), 256);
        }
    );
}

More details you can find in inplace_array_uninitialized description.

Why?

Because allocation on the stack (i.e. placing variables) is MUCH FASTER then usual allocating in the heap.

Traits

FixedArray

This trait is a extended copy of unstable core::array::FixedSizeArray.

Functions

alloc_array⚠	alloc_array is used when inplace_array realize that the size of requested array of T is too large and should be replaced in the heap.
inplace⚠	Places uninitialized memory for the T type on the stack and passes the reference to it into the consumer closure.
inplace_array	inplace_array trying to place an array of T on the stack, then initialize it using the init closure and finally pass the reference to it into the consumer closure. size argument sets the requested size of an array. consumer's result will be returned.
inplace_array_uninitialized⚠	inplace_array_uninitialized is unsafe API which is being used by inplace_array and inplace_copy_of internally. It's trying to place an array of T on the stack and pass the reference to it into the consumer closure. size argument sets the requested size of an array. consumer's result will be returned.
inplace_copy_of	inplace_copy_of trying to place an array of T on the stack, then initialize it by copying from the source slice and finally pass the reference to it into the consumer closure. Length of source argument sets the requested size of an array. consumer's result will be returned.