malloc-array - Vec<T> like malloc() wrapper

This crate provides a vec!-like macro, heap! for creating arrays managed with malloc() and free(). It also provides the container type HeapArray<T> as a safe wrapper around these.

See documentation for more details.

Macro usage

Creating zero-initialised arrays.

These are created with calloc().

heap![Type, size];

Note that if Type does not support zero-initialisation it is undefined behaviour to drop or access any element of the returned array. To assign without dropping see the associated function replace_and_forget:

let mut array = heap![String; 3];
array.replace_and_forget(0, format!("snibbedy"));
array.replace_and_forget(1, format!("snab"));
array.replace_and_forget(2, format!(":D"));

drop(array); // This is now safe.

Creating initialised arrays.

These are created with malloc() and set with replace_and_forget (or, for the special case of u8 sized types, memset).

heap![expression; size];

Creating n-element arrays.

These are created with malloc() and set with replace_and_forget.

heap![expression_one, expression_two];

Creating empty arrays.

These are created with either malloc(0), or if the zst_noalloc feature is enabled they do not allocate.

heap![];

zst_noalloc is enabled by default and causes instances with len_bytes() == 0 to have NULL internal pointers instead of dangling ones returned by malloc(0). This behaviour my not be desireable and if it is not, disable the default featues.

Dropping on free

Arrays created this way are dropped in a way that ensures each element is also dropped. For anything implementing the Copy trait, this is redundant. To avoid this, pass the keyword unsafe to any of the above macro definitions:

let bytes = heap![unsafe u8; 32]; //`u8` does not need to be dropped. 
let references = heap![unsafe ":D"; 10]; //Neither does `&'static str`.

Note that if the type does implement the Drop trait, then unless the elements are dropped manually (see into_iter) dropping the array can cause a resource leak.

License

GPL'd with love <3