1.0.0[−][src]Module std::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.
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).
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);Run
Move a value from a Box back to the stack by dereferencing:
let boxed: Box<u8> = Box::new(5); let val: u8 = *boxed;Run
Creating a recursive data structure:
#[derive(Debug)] enum List<T> { Cons(T, Box<List<T>>), Nil, } fn main() { let list: List<i32> = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Nil)))); println!("{:?}", list); }Run
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>),Run
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, which has a defined size, we know how
big Cons needs to be.
Structs
| Box | A pointer type for heap allocation. |
Traits
| FnBox | Experimental
|