stackbox 0.2.2

`&own`ing references in stable Rust - no_std-friendly Box
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

use crate::prelude::*;

use ::core::{
    // marker::PhantomData,
    mem,
};

/// Same as [`Slot::VACANT`], but using function call syntax to avoid firing
/// the [trigger-happy `const_item_mutation` lint](
/// https://github.com/rust-lang/rust/pull/75573).
///
/// A so-created `&mut Slot<T>` is then to be used to derive a
/// [`StackBox`]`<'slot, T>` out of it, by feeding a value to the slot:
///
///   - either by using [`StackBox::new_in()`],
///
///   - or the equivalent [`.stackbox()`] convenience method on [`Slot`]s.
///
/// [`.stackbox()`]: `Slot::stackbox`
#[inline(always)]
pub
const
fn mk_slot<T> ()
  -> Slot<T>
{
    Slot::VACANT
}

/// A `Sized` and [`uninit`][`::core::mem::MaybeUninit`] slot to
/// manually handle the scope of [`StackBox`]'s backing inline allocations.
///
/// If needed, multiple such slots can be defined within the local scope and
/// bound to a variadic number of identifiers (variable names) using the
/// [`mk_slots!`][`crate::mk_slots`] macro.
pub
struct Slot<T> {
    place: mem::MaybeUninit<T>,
    // /// Invariant lifetime just in case.
    // _borrow_mut_once: PhantomData<fn(&()) -> &mut &'frame ()>,
}

impl<T> Slot<T> {
    /// A vacant slot, to be used to derive a [`StackBox`]`<'slot, T>` out of
    /// it, by feeding a value to the slot:
    ///
    ///   - either by using [`StackBox::new_in()`],
    ///
    ///   - or the equivalent [`.stackbox()`] convenience method on [`Slot`]s.
    ///
    /// [`.stackbox()`]: `Slot::stackbox`
    pub
    const VACANT: Self = Slot {
        place: mem::MaybeUninit::uninit(),
        // _borrow_mut_once: PhantomData,
    };

    /// Convenience shortcut for [`StackBox::new_in()`].
    #[inline(always)]
    pub
    fn stackbox<'frame> (self: &'frame mut Slot<T>, value: T)
      -> StackBox<'frame, T>
    where
        T : 'frame,
    {
        let ptr = Self::__init_raw(self, value);
        unsafe {
            // Safety: `mem::MaybeUninit` does not drop it.
            StackBox::assume_owns(ptr)
        }
    }

    #[doc(hidden)] /** Not part of the public API */ pub
    fn __init_raw<'frame> (this: &'frame mut Slot<T>, value: T)
      -> &'frame mut ::core::mem::ManuallyDrop<T>
    {
        this.place = mem::MaybeUninit::new(value);
        unsafe {
            // Safety: value has been initialized.
            mem::transmute::<
                &'_ mut mem::MaybeUninit<T>,
                &'_ mut mem::ManuallyDrop<T>,
            >(
                &mut this.place,
            )
        }
    }
}

/// Convenience macro to batch-create multiple [`Slot`]s.
///
/// ```rust
/// # use ::stackbox::prelude::*;
/// mk_slots!(foo, bar, baz);
/// # drop::<[&mut ::stackbox::Slot<()>; 3]>([foo, bar, baz]);
/// ```
///
/// is a shorthand for multiple [`mk_slot()`][`mk_slot`] calls:
///
/// ```rust
/// # use ::stackbox::prelude::*;
/// let foo = &mut mk_slot();
/// let bar = &mut mk_slot();
/// let baz = &mut mk_slot();
/// # drop::<[&mut ::stackbox::Slot<()>; 3]>([foo, bar, baz]);
/// ```
///
/// A so-created `&mut Slot<T>` is then to be used to derive a
/// [`StackBox`]`<'slot, T>` out of it, by feeding a value to the slot:
///
///   - either by using [`StackBox::new_in()`],
///
///   - or the equivalent [`.stackbox()`] convenience method on [`Slot`]s.
///
/// [`.stackbox()`]: `Slot::stackbox`
#[macro_export]
macro_rules! mk_slots {(
    $($var_name:ident),+ $(,)?
) => (
    $(
        let ref mut $var_name = $crate::prelude::mk_slot();
    )+
)}