Module alloc::boxed [] [src]

A pointer type for heap allocation.

Box<T>`Box`, 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

Creating a box:

let x = Box::new(5);

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);
}

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

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

Cons(T, List<T>),

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

Structs

Box

A pointer type for heap allocation.

Statics

HEAP [Unstable]

A value that represents the heap. This is the default place that the box`box` keyword allocates into when no place is supplied.

Traits

FnBox [Unstable]

FnBox`FnBoxis a version of the` is a version of the FnOnce`FnOnceintended for use with boxed closure objects. The idea is that where one would normally store a` intended for use with boxed closure objects. The idea is that where one would normally store a Box<FnOnce()>`Boxin a data structure, you should use` in a data structure, you should use Box<FnBox()>`Box. The two traits behave essentially the same, except that a`. The two traits behave essentially the same, except that a FnBox`FnBoxclosure can only be called if it is boxed. (Note that` closure can only be called if it is boxed. (Note that FnBox`FnBoxmay be deprecated in the future if` may be deprecated in the future if Box<FnOnce()>`Box` closures become directly usable.)

Functions

into_raw [Unstable]

Consumes the Box`Box`, returning the wrapped raw pointer.