devela/data/list/array/
init.rs

Help
1// devela::data::list::array::init
2//
3//! Defines the [`array_init!`] macro.
4//
5// WAIT: [Stack overflow with Boxed array](https://github.com/rust-lang/rust/issues/53827)
6//
7// TODO
8// - add tests
9// - check if we can make `unsafe_init` const & remove `unsafe_const_init`
10//   - https://doc.rust-lang.org/std/mem/union.MaybeUninit.html#method.uninit_array
11//   - DONE: [const_maybe_uninit_assume_init](https://github.com/rust-lang/rust/issues/86722)
12//   - since 1.85 write is const. Only remainders are for loop, and iterators.
13//   - MAYBE just bench. If performant enough just use the const version renamed, delete the other
14
15/// Initializes a [`[$T; $LEN]`][array] array in multiple ways.
16///
17/// # Arguments
18/// - `[$T; $LEN]`: the array's elements' type and length.
19/// - `$init`: a function with an `usize` argument that returns `$T`.
20/// - `$const_init`: a const fn with an `usize` argument that returns `$T: Copy`.
21/// - `$copiable`: an expression that returns an element of type `$T: Copy`.
22/// - `$clonable`: an expression that returns an element of type `$T: Clone`.
23/// - `$fsafe`: a feature that forbids the use of `unsafe` when enabled.
24/// - `$funsafe`: a feature that enables the use of `unsafe` when enabled.
25/// - `$intoiter`: an item that implements [`IntoIterator`].
26///
27/// # Examples
28/// ```
29/// # use devela::array_init;
30/// assert_eq![[2,4,6], array_init![safe_init [i32; 3], |n| (n as i32 + 1) * 2]];
31/// #[cfg(feature = "unsafe_array")]
32/// assert_eq![[3,6,9], array_init![unsafe_init [i32; 3], |n| (n as i32 + 1) * 3]];
33///
34/// assert_eq![[2,4,6], array_init![init [i32; 3], "safe", "unsafe_array",
35///     |n| (n as i32 + 1) * 2]];
36/// #[cfg(feature = "alloc")]
37/// assert_eq![Box::new([2,4,6]), array_init![init_heap [i32; 3], "safe", "unsafe_array",
38///     |n| (n as i32 + 1) * 2]];
39///
40/// assert_eq![[7,7,7], array_init![clone [i32; 3], "safe", "unsafe_array", 7]];
41/// assert_eq![[0,0,0], array_init![default [i32; 3], "safe", "unsafe_array"]];
42/// assert_eq![[4,5,6], array_init![iter [i32; 3], "safe", "unsafe_array", vec![4,5,6,7,8]]];
43/// assert_eq![[4,0,0], array_init![iter [i32; 3], "safe", "unsafe_array", vec![4]]];
44///
45/// const fn init(n: usize) -> i32 { (n as i32 + 1) * 4 }
46/// const ARRAY1: [i32; 3] = array_init![const_init [i32; 3], "safe", "unsafe_array", init, 0];
47/// assert_eq![[4, 8, 12], ARRAY1];
48///
49/// const ARRAY2: [i32; 3] = array_init![const_default [i32; 3]];
50/// assert_eq![[0, 0, 0], ARRAY2];
51/// ```
52///
53/// # Features
54/// The unsafe version uses [`MaybeUninit`][crate::MaybeUninit] in the case
55/// of stack allocation or [`Box::from_raw`] in the case of heap allocation.
56///
57/// For the `const_init`, `clone`, `default` and `iter` versions, if the given
58/// `$funsafe` is enabled and the given `$fsafe` is disabled, it will use unsafe
59/// initialization.
60// WAIT [array_repeat](https://github.com/rust-lang/rust/issues/126695)
61// WAIT [array_try_from_fn](https://github.com/rust-lang/rust/issues/89379)
62#[macro_export]
63#[cfg_attr(cargo_primary_package, doc(hidden))]
64macro_rules! array_init {
65    (
66    /* safe initializations */
67
68    // safe array initialization in the stack
69    safe_init [$T:ty; $LEN:expr], $init:expr) => {{
70        #[allow(clippy::redundant_closure_call, reason  = "macro arg isn't redundant")]
71        core::array::from_fn(|i| $init(i))
72    }};
73    (
74    // safe array initialization in the stack, compile-time friendly.
75    safe_const_init [$T:ty; $LEN:expr], $const_init:expr, $copiable:expr) => {{
76        let mut arr: [$T; $LEN] = [$copiable; $LEN];
77        let mut i = 0;
78        while i < $LEN {
79            // WAIT: [const_closures](https://github.com/rust-lang/rust/issues/106003)
80            arr[i] = $const_init(i);
81            i += 1;
82        }
83        arr
84    }};
85    (
86    // safe array initialization in the heap
87    safe_init_heap [$T:ty; $LEN:expr], $init:expr) => {{
88        let mut v = $crate::Vec::<$T>::with_capacity($LEN);
89        for i in 0..$LEN {
90            #[allow(clippy::redundant_closure_call, reason  = "macro arg isn't redundant")]
91            v.push($init(i));
92        }
93        v.into_boxed_slice().try_into().unwrap_or_else(|_| {
94            panic!("Can't turn the boxed slice into a boxed array")
95        })
96    }};
97    (
98
99    /* unsafe initializations */
100
101    // unsafe array initialization in the stack
102    unsafe_init [$T:ty; $LEN:expr], $init:expr) => {{
103        let mut arr: [$crate::MaybeUninit<$T>; $LEN] =
104            // SAFETY: array will be fully initialized in the subsequent loop
105            unsafe { $crate::MaybeUninit::uninit().assume_init() };
106        for (i, e) in &mut arr[..].iter_mut().enumerate() {
107            #[allow(clippy::redundant_closure_call, reason  = "macro arg isn't redundant")]
108            let _ = e.write($init(i)); // NOTE: const since 1.85
109        }
110        // Can't use transmute for now, have to use transmute_copy:
111        // - WAIT: [const generics transmute](https://github.com/rust-lang/rust/issues/61956)
112        //   - https://github.com/rust-lang/rust/issues/62875 (duplicate)
113        // unsafe { $crate::transmute::<_, [T; LEN]>(&arr) }
114        // SAFETY: we've initialized all the elements
115        unsafe { ::core::mem::transmute_copy::<_, [$T; $LEN]>(&arr) }
116    }};
117    (
118    // unsafe array initialization in the stack, compile-time friendly.
119    unsafe_const_init [$T:ty; $LEN:expr], $const_init:expr) => {{
120        // WAIT: [maybe_uninit_uninit_array](https://github.com/rust-lang/rust/issues/96097)
121        let mut arr: [$crate::MaybeUninit<$T>; $LEN] =
122            // SAFETY: array will be fully initialized in the subsequent loop
123            unsafe { $crate::MaybeUninit::uninit().assume_init() };
124        let mut i = 0;
125        while i < $LEN {
126            arr[i] = $crate::MaybeUninit::new($const_init(i));
127            i += 1;
128        }
129        // SAFETY: we've initialized all the elements
130        unsafe { ::core::mem::transmute_copy::<_, [$T; $LEN]>(&arr) }
131    }};
132    (
133    // unsafe array initialization in the heap
134    unsafe_init_heap [$T:ty; $LEN:expr], $init:expr) => {{
135        let mut v = $crate::Vec::<$T>::with_capacity($LEN);
136        #[allow(clippy::redundant_closure_call, reason  = "macro arg isn't redundant")]
137        for i in 0..$LEN { v.push($init(i)); }
138        let slice = v.into_boxed_slice();
139        let raw_slice = Box::into_raw(slice);
140        // SAFETY: pointer comes from using `into_raw`, and capacity is right.
141        unsafe { Box::from_raw(raw_slice as *mut [$T; $LEN]) }
142    }};
143    (
144
145    /* safety-agnostic initializations */
146
147    // initialize an array in the stack
148    init [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $init:expr) => {{
149        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
150        { $crate::array_init![safe_init [$T; $LEN], $init] }
151        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
152        { $crate::array_init![unsafe_init [$T; $LEN], $init] }
153    }};
154    (
155    // initialize an array the stack, compile-time friendly.
156    // $copiable is only used by the safe version as temporary placeholder.
157    const_init
158    [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $const_init:expr, $copiable:expr) => {{
159        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
160        { $crate::array_init![safe_const_init [$T; $LEN], $const_init, $copiable] }
161        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
162        { $crate::array_init![unsafe_const_init [$T; $LEN], $const_init ] }
163    }};
164    (
165    // initialize an array in the heap
166    init_heap [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $init:expr) => {{
167        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
168        { $crate::array_init![safe_init_heap [$T; $LEN], $init] }
169        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
170        { $crate::array_init![unsafe_init_heap [$T; $LEN], $init] }
171    }};
172    (
173
174    // initialize an array in the stack by cloning $clonable
175    clone [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $clonable:expr) => {{
176        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
177        { $crate::array_init![safe_init [$T; $LEN], |_| $clonable.clone()] }
178        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
179        { $crate::array_init![unsafe_init [$T; $LEN], |_| $clonable.clone()] }
180    }};
181    (
182    // initialize an array in the heap, by cloning $clonable
183    clone_heap [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $clonable:expr) => {{
184        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
185        { $crate::array_init![safe_init_heap [$T; $LEN], |_| $clonable.clone()] }
186        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
187        { $crate::array_init![unsafe_init_heap [$T; $LEN], |_| $clonable.clone()] }
188    }};
189    (
190
191    // initialize an array in the stack with $T: Default::default()
192    default [$T:ty; $LEN:expr]) => {{
193        { $crate::array_init![safe_init [$T; $LEN], |_| <$T>::default()] }
194    }};
195    (
196    // initialize an array in the stack with $T: Default::default()
197    default [$T:ty; $LEN:expr], unsafe: $funsafe:literal) => {{
198        #[cfg(not(feature = $funsafe))]
199        { $crate::array_init![safe_init [$T; $LEN], |_| <$T>::default()] }
200        #[cfg(feature = $funsafe)]
201        { $crate::array_init![unsafe_init [$T; $LEN], |_| <$T>::default()] }
202    }};
203    (
204    // initialize an array in the stack with $T: Default::default()
205    default [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal) => {{
206
207        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
208        { $crate::array_init![safe_init [$T; $LEN], |_| <$T>::default()] }
209        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
210        { $crate::array_init![unsafe_init [$T; $LEN], |_| <$T>::default()] }
211    }};
212    (
213    // initialize an array in the stack with $T: ConstDefault::DEFAULT
214    const_default [$T:ty; $LEN:expr]) => {{
215        [<$T as $crate::ConstDefault>::DEFAULT; $LEN]
216    }};
217    (
218    // initialize an array in the heap, with $T: Default::default()
219    default_heap [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal) => {{
220        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
221        { $crate::array_init![safe_init_heap [$T; $LEN], |_| <$T>::default()] }
222        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
223        { $crate::array_init![unsafe_init_heap [$T; $LEN], |_| <$T>::default()] }
224    }};
225    (
226
227    // initialize an array in the stack with an IntoIterator<Item = $T> and with
228    // $T::default() in case the iterator length is < $LEN, for the remaining elements.
229    iter [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $intoiter:expr) => {{
230        let mut iterator = $intoiter.into_iter();
231        let mut init_closure = |_| {
232            if let Some(e) = iterator.next() { e } else { <$T>::default() }
233        };
234        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
235        { $crate::array_init![safe_init [$T; $LEN], init_closure] }
236        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
237        { $crate::array_init![unsafe_init [$T; $LEN], init_closure] }
238    }};
239    (
240    // initialize an array in the heap with an IntoIterator<Item = $T> and with
241    // $T::default() in case the iterator length is < $LEN, for the remaining elements.
242    iter_heap [$T:ty; $LEN:expr], $fsafe:literal, $funsafe:literal, $intoiter:expr) => {{
243
244        let mut iterator = $intoiter.into_iter();
245        let mut init_closure = |_| {
246            if let Some(e) = iterator.next() { e } else { <$T>::default() }
247        };
248        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
249        { $crate::array_init![safe_init_heap [$T; $LEN], init_closure] }
250        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
251        { $crate::array_init![unsafe_init_heap [$T; $LEN], init_closure] }
252    }};
253    (
254
255    // initialize an array by applying $op (in safe mode it first clones $pre)
256    // and propagates errors both from $pre and $op.
257    preop [$T:ty; $LEN:expr]?, $fsafe:literal, $funsafe:literal, $pre:expr, $op:expr) => {{
258
259        #[cfg(any(feature = $fsafe, not(feature = $funsafe)))]
260        {
261            let init_value = $pre?; // error prone initial value
262            let mut arr: [$T; $LEN] = core::array::from_fn(|_| init_value.clone());
263            for (i, data) in $op.enumerate() {
264                arr[i] = data?;
265            }
266            arr
267        }
268        #[cfg(all(not(feature = $fsafe), feature = $funsafe))]
269        {
270            let mut arr: [$crate::MaybeUninit<$T>; $LEN] =
271                // SAFETY: array will be fully initialized in the subsequent loop
272                unsafe { $crate::MaybeUninit::uninit().assume_init() };
273            for (i, data) in $op.enumerate() {
274                arr[i].write(data?);
275            }
276            // SAFETY: we've initialized all the elements
277            unsafe { ::core::mem::transmute_copy::<_, [$T; $LEN]>(&arr) }
278        }
279    }};
280}
281#[doc(inline)]
282pub use array_init;
devela/data/list/array/init.rs

devela/data/list/array/
init.rs
