Struct static_alloc::boxed::Box

pub struct Box<'a, T> { /* fields omitted */ }

An allocated instance of a type.

Example

The basic usage are allocated recursive data structures. Here is a standard example using a Slab with 'static storage duration as the allocator:

use static_alloc::{Box, Slab};

#[derive(Debug)]
enum List<T> {
    Nil,
    Cons(T, Box<'static, List<T>>),
}

static SLAB: Slab<[u8; 1024]> = Slab::uninit();

let base = SLAB.boxed(List::Nil).unwrap();
let one = SLAB.boxed(List::Cons(0, base)).unwrap();
let two = SLAB.boxed(List::Cons(1, one)).unwrap();

// We can destruct the value (not with `*` but comparable).
match Box::take(two).0 {
    List::Cons(val, _)  => assert_eq!(val, 1), // Got the value back.
    _ => unreachable!(),
}

Downsides

Unfortunately, this Box does not yet support unsizing. This is very unfortunate as it means you can't use it for type erasure.

Design

You will likely notice quickly that this has different semantics than the std::boxed::Box. Its inner pointer may be larger and it does not allocate nor deallocate memory on its own. This only wraps a fully initialized Uninit in a RAII/Drop interface.

Of course, there is a reason for this choice. The standard Box, storing only the raw pointer (as a Unique), requires its underlying allocation to have the exact same size and align (Layout) as the value and the layout needs to be recalculated when deallocating. Without a dependency on an allocator it would seem that the underlying layout becomes less important and can be thrown away but the opposite is the case. Many converters for the std::boxed::Box rely on being able to reallocate into a suitably constructed new allocation on will. Not having this luxury at our disposal means there should be a mechanism to cope with mismatching allocations anyways. So we simply store the full Uninit provided, relying on the library user to manage other aspects of allocation for us.

Instead, this Box can offer additional ways to manipulate and massage the underlying allocation. It should be possible to restore the exact allocation Box semantics (albeit with one usize more space usage) via a wrapper when an allocator is available.

Methods

impl<'a, T> Box<'a, T>

pub fn new(val: T, into: Uninit<'a, T>) -> Self

Place val into a provided allocation.

pub unsafe fn from_raw(init: Uninit<'a, T>) -> Self

Create a box from an pointer to an already initialized value.

Ensures that an already initialized value is properly dropped at the end of the lifetime of the Box.

Safety

The pointed-to location must have already been initialized via external means. This is as unsafe as init.as_mut().

pub fn into_raw(b: Self) -> Uninit<'a, T>

Unwrap the contained Uninit.

The value stays initialized but that information is no longer statically available. If you simply want to avoid the Drop call, consider ManuallyDrop instead.

pub fn leak(b: Self) -> &'a mut T

Consumes and leaks the Box, returning a mutable reference, &'a mut T.

Compared to a standard Box it should be noted that the reference alone is not enough to invoke Box::from_raw.

pub fn take(b: Self) -> (T, Uninit<'a, T>)

Take out the value and return the allocation.

This function is the opposite of new.

Trait Implementations

impl<'_, T: Debug> Debug for Box<'_, T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a, 'b, T: PartialEq> PartialEq<Box<'b, T>> for Box<'a, T>

fn eq(&self, other: &Box<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Box<T>) -> bool

This method tests for !=.

impl<'_, T: Eq> Eq for Box<'_, T>

impl<'_, T: Ord> Ord for Box<'_, T>

fn cmp(&self, other: &Box<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<'a, 'b, T: PartialOrd> PartialOrd<Box<'b, T>> for Box<'a, T>

fn partial_cmp(&self, other: &Box<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Box<T>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Box<T>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn ge(&self, other: &Box<T>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

fn gt(&self, other: &Box<T>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

impl<'_, T> Deref for Box<'_, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'_, T> DerefMut for Box<'_, T>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<'_, T> Drop for Box<'_, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'_, T: Hash> Hash for Box<'_, T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<'_, T> AsRef<T> for Box<'_, T>

fn as_ref(&self) -> &T

Performs the conversion.

impl<'_, T> AsMut<T> for Box<'_, T>

fn as_mut(&mut self) -> &mut T

Performs the conversion.

impl<'_, T> Pointer for Box<'_, T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'_, T> Borrow<T> for Box<'_, T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<'_, T> BorrowMut<T> for Box<'_, T>

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value.