# [−][src]Module alloc_wg::boxed

A pointer type for heap allocation.

`Box<T, A>`, casually referred to as a 'box', provides the simplest form of allocation in Rust. Boxes provide ownership for this allocation, and drop their contents when they go out of scope.

# Examples

Move a value from the stack to the heap by creating a `Box`:

```use alloc_wg::boxed::Box;

let val: u8 = 5;
let boxed: Box<u8> = Box::new(val);```

Move a value from a `Box` back to the stack by dereferencing:

```use alloc_wg::boxed::Box;

let boxed: Box<u8> = Box::new(5);
let val: u8 = *boxed;```

Creating a recursive data structure:

```use alloc_wg::boxed::Box;

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

let list: List<i32> = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Nil))));
println!("{:?}", list);```

This will print `Cons(1, Cons(2, Nil))`.

Recursive structures must be boxed, because if the definition of `Cons` looked like this:

`Cons(T, List<T>),`

It wouldn't work. This is because the size of a `List` depends on how many elements are in the list, and so we don't know how much memory to allocate for a `Cons`. By introducing a [`Box<T, D>`], which has a defined size, we know how big `Cons` needs to be.

# Memory layout

For non-zero-sized values, a `Box` will use the `Global` allocator for its allocation if no allocator was specified. It is valid to convert both ways between a `Box` and a raw pointer allocated with the same allocator, given that the `NonZeroLayout` used with the allocator is correct for the type. More precisely, a `value: *mut T` that has been allocated with the `Global` allocator with `Layout::for_value(&*value)` may be converted into a box using `Box::<T>::from_raw(value)`. For other allocators, [`Box::<T>::from_raw_in(value, alloc)`] may be used. Conversely, the memory backing a `value: *mut T` obtained from `Box::<T>::into_raw` may be deallocated using the specific allocator with `NonZeroLayout::for_value(&*value)`.

## Structs

 Box A pointer type for heap allocation.