Macro array_init

macro_rules! array_init {
    (
    /* safe initializations */

    // safe array initialization in the stack
    safe_init [$T:ty; $LEN:expr], $init:expr) => { ... };
    (
    // safe array initialization in the heap
    safe_init_heap [$T:ty; $LEN:expr], $init:expr) => { ... };
    (
    // safe array initialization in the stack, compile-time friendly.
    safe_const_init [$T:ty; $LEN:expr], $const_init:expr, $copiable:expr) => { ... };
    (

    /* unsafe initializations */

    // unsafe array initialization in the stack
    unsafe_init [$T:ty; $LEN:expr], $init:expr) => { ... };
    (
    // unsafe array initialization in the heap
    unsafe_init_heap [$T:ty; $LEN:expr], $init:expr) => { ... };
    (
    // unsafe array initialization in the stack, compile-time friendly.
    unsafe_const_init [$T:ty; $LEN:expr], $const_init:expr) => { ... };
    (

    /* safety-agnostic initializations */

    // initialize an array in the stack
    init [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $init:expr) => { ... };
    (
    // initialize an array in the heap
    init_heap [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $init:expr) => { ... };
    (
    // initialize an array the stack, compile-time friendly.
    // $copiable is only used by the safe version as temporary placeholder.
    const_init
    [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $const_init:expr, $copiable:expr) => { ... };
    (

    // initialize an array in the stack by cloning $clonable
    clone [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $clonable:expr) => { ... };
    (
    // initialize an array in the heap, by cloning $clonable
    clone_heap [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $clonable:expr) => { ... };
    (

    // initialize an array in the stack with $T: Default::default()
    default [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal) => { ... };
    (
    // initialize an array in the heap, with $T: Default::default()
    default_heap [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal) => { ... };
    (
    // initialize an array in the stack with $T: ConstDefault::DEFAULT
    const_default [$T:ty; $LEN:expr]) => { ... };
    (

    // initialize an array in the stack with an IntoIterator<Item = $T> and with
    // $T::default() in case the iterator length is < $LEN, for the remaining elements.
    iter [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $intoiter:expr) => { ... };
    (
    // initialize an array in the heap with an IntoIterator<Item = $T> and with
    // $T::default() in case the iterator length is < $LEN, for the remaining elements.
    iter_heap [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $intoiter:expr) => { ... };
    (

    // initialize an array by applying $op (in safe mode it first clones $pre)
    // and propagates errors both from $pre and $op.
    preop [$T:ty; $LEN:expr]?, $fsafe:literal, $funsafe:literal, $pre:expr, $op:expr) => { ... };
}

Initializes a [$T; $LEN] array in multiple ways.

Arguments

• [$T; $LEN]: the array’s elements’ type and length.
• $init: a function with an usize argument that returns $T.
• $const_init: a const fn with an usize argument that returns $T: Copy.
• $copiable: an expression that returns an element of type $T: Copy.
• $clonable: an expression that returns an element of type $T: Clone.
• $fsafe: a feature that forbids the use of unsafe when enabled.
• $funsafe: a feature that enables the use of unsafe when enabled.
• $intoiter: an item that implements IntoIterator.

Examples

assert_eq![[2,4,6], array_init![safe_init [i32; 3], |n| (n as i32 + 1) * 2]];
#[cfg(feature = "unsafe_array")]
assert_eq![[3,6,9], array_init![unsafe_init [i32; 3], |n| (n as i32 + 1) * 3]];

assert_eq![[2,4,6], array_init![init [i32; 3], "safe", "unsafe_array",
    |n| (n as i32 + 1) * 2]];
#[cfg(feature = "alloc")]
assert_eq![Box::new([2,4,6]), array_init![init_heap [i32; 3], "safe", "unsafe_array",
    |n| (n as i32 + 1) * 2]];

assert_eq![[7,7,7], array_init![clone [i32; 3], "safe", "unsafe_array", 7]];
assert_eq![[0,0,0], array_init![default [i32; 3], "safe", "unsafe_array"]];
assert_eq![[4,5,6], array_init![iter [i32; 3], "safe", "unsafe_array", vec![4,5,6,7,8]]];
assert_eq![[4,0,0], array_init![iter [i32; 3], "safe", "unsafe_array", vec![4]]];

const fn init(n: usize) -> i32 { (n as i32 + 1) * 4 }
const ARRAY1: [i32; 3] = array_init![const_init [i32; 3], "safe", "unsafe_array", init, 0];
assert_eq![[4, 8, 12], ARRAY1];

const ARRAY2: [i32; 3] = array_init![const_default [i32; 3]];
assert_eq![[0, 0, 0], ARRAY2];

Features

The unsafe version uses MaybeUninit in the case of stack allocation or Box::from_raw in the case of heap allocation.

For the const_init, clone, default and iter versions, if the given $funsafe is enabled and the given $fsafe is disabled, it will use unsafe initialization.