alloc::boxed - Rust
Description: API documentation for the Rust `boxed` mod in crate `alloc`.
Keywords: rust, rustlang, rust-lang, boxed

# 1.0.0[−][src]Module alloc::boxed

A pointer type for heap allocation.

`Box<T>`, casually referred to as a 'box', provides the simplest form of heap 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`:

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

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

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

Creating a recursive data structure:

    #[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:

ⓘThis example deliberately fails to compile

    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>`, 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. It is valid to convert both ways between a `Box` and a raw pointer allocated with the `Global` allocator, given that the `Layout` 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)`. Conversely, the memory backing a `value: *mut T` obtained from `Box::<T>::into_raw` may be deallocated using the `Global` allocator with `Layout::for_value(&*value)`.

## Structs

Box | A pointer type for heap allocation.