Struct Box 

pub struct Box<T: ?Sized, A: Allocator = DefaultAllocator> { /* private fields */ }

A custom Box type appropriate for fallible allocation.

Implementations

impl<T: ?Sized, A: Allocator> Box<T, A>

pub const unsafe fn from_raw_in(ptr: *mut T, allocator: A) -> Self

Creates a Box from a raw pointer.

This does NOT allocate any memory. It simply takes ownership of the memory pointed to by ptr.

Safety

• For non-zero-sized types, the pointer must be valid and have been allocated by the same allocator.
• For zero-sized types (ZSTs), the pointer must be non-null and properly aligned. Consider using NonNull::dangling() to obtain such a pointer.

pub const unsafe fn from_non_null_in(ptr: NonNull<T>, allocator: A) -> Self

Constructs a box from a NonNull pointer.

Safety

• For non-zero-sized types, the pointer must be valid and have been allocated by the same allocator.
• For zero-sized types (ZSTs), the pointer must be non-null and properly aligned. Consider using NonNull::dangling() to obtain such a pointer.

pub fn as_ptr(this: &Self) -> *mut T

Returns the raw pointer.

pub fn into_raw_with_allocator(this: Self) -> (*mut T, A)

Consumes the Box, returning a mutable reference to T.

The memory will be leaked, and never deallocated.

Note

The allocator A is also leaked. This is intentional and matches the behavior of std::boxed::Box::leak, ensuring that a stateful allocator remains valid as long as the leaked reference. Consumes the Box, returning a raw pointer and the allocator.

The memory will be leaked, and never deallocated unless reconstructed.

impl<T: ?Sized> Box<T, DefaultAllocator>

pub const unsafe fn from_raw(ptr: *mut T) -> Self

Creates a Box from a raw pointer using the default allocator.

Safety

• For non-zero-sized types, the pointer must be valid and have been allocated by the default allocator.
• For zero-sized types (ZSTs), the pointer must be non-null and properly aligned. Consider using NonNull::dangling() to obtain such a pointer.

pub const unsafe fn from_non_null(ptr: NonNull<T>) -> Self

Constructs a box from a NonNull pointer using the default allocator.

Safety

• For non-zero-sized types, the pointer must be valid and have been allocated by the default allocator.
• For zero-sized types (ZSTs), the pointer must be non-null and properly aligned. Consider using NonNull::dangling() to obtain such a pointer.

pub fn into_raw(this: Self) -> *mut T

Consumes the Box, returning a raw pointer.

The memory will be leaked, and never deallocated unless reconstructed.

impl<T, A: Allocator> Box<[T], A>

pub const fn empty_slice_in(allocator: A) -> Self

Creates an empty slice Box.

Infallible because it doesn’t allocate memory.

pub fn try_new_uninit_slice_in( len: usize, allocator: A, ) -> Result<Box<[MaybeUninit<T>], A>, AllocError>

Tries to allocate a new slice of the given length.

pub fn try_new_zeroed_slice_in( len: usize, allocator: A, ) -> Result<Box<[MaybeUninit<T>], A>, AllocError>

Tries to allocate a new zeroed slice of the given length.

impl<T> Box<[T], DefaultAllocator>

pub const fn empty_slice() -> Self

pub fn try_new_uninit_slice( len: usize, ) -> Result<Box<[MaybeUninit<T>], DefaultAllocator>, AllocError>

pub fn try_new_zeroed_slice( len: usize, ) -> Result<Box<[MaybeUninit<T>], DefaultAllocator>, AllocError>

impl<T, A: Allocator> Box<[MaybeUninit<T>], A>

pub unsafe fn assume_init(self) -> Box<[T], A>

Converts to Box<[T], A>.

Safety

The caller must guarantee that the values are initialized.

pub fn try_grow(this: &mut Self, new_len: usize) -> Result<(), AllocError>

Tries to grow the slice to a new length. Returns Err if allocation fails, and the box is unchanged.

pub unsafe fn try_shrink( this: &mut Self, new_len: usize, ) -> Result<(), AllocError>

Tries to shrink the slice to a new length. If new_len is 0, the box becomes empty and memory is freed. Returns Err if allocation fails, and the box is unchanged.

Safety

The caller must guarantee that any elements above new_len are either uninitialized or have already been dropped. This method discards them without running their destructors.

impl<T, A: Allocator> Box<T, A>

pub fn try_new_in(value: T, allocator: A) -> Result<Self, AllocError>

Tries to allocate a new instance of T and move the value into it.

pub fn try_new_uninit_in( allocator: A, ) -> Result<Box<MaybeUninit<T>, A>, AllocError>

Constructs a new box with uninitialized contents on the heap.

pub fn try_new_zeroed_in( allocator: A, ) -> Result<Box<MaybeUninit<T>, A>, AllocError>

Constructs a new box with uninitialized contents, filled with 0 bytes.

impl<T> Box<T, DefaultAllocator>

pub fn try_new(value: T) -> Result<Self, AllocError>

pub fn try_new_uninit() -> Result<Box<MaybeUninit<T>>, AllocError>

pub fn try_new_zeroed() -> Result<Box<MaybeUninit<T>>, AllocError>

impl<T, A: Allocator> Box<MaybeUninit<T>, A>

pub unsafe fn assume_init(self) -> Box<T, A>

Converts to Box<T, A>.

Safety

The caller must guarantee that the value is initialized.

Trait Implementations

impl<T> Default for Box<[T]>

fn default() -> Self

Returns the “default value” for a type.

impl<T: ?Sized, A: Allocator> Deref for Box<T, A>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: ?Sized, A: Allocator> DerefMut for Box<T, A>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: ?Sized, A: Allocator> Drop for Box<T, A>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.