Struct alloc_wg::boxed::Box

pub struct Box<T: ?Sized, B: BuildAlloc = AbortAlloc<Global>>(_, _, _);

A pointer type for heap allocation.

See the module-level documentation for more.

Methods

impl<T> Box<T>

pub fn new(x: T) -> Self

Allocates memory on the heap and then places x into it.

This doesn't actually allocate if T is zero-sized.

Example

use alloc_wg::boxed::Box;

let five = Box::new(5);

pub fn new_uninit() -> Box<MaybeUninit<T>>

Constructs a new box with uninitialized contents.

Example

use alloc_wg::boxed::Box;

let mut five = Box::<u32>::new_uninit();

let five = unsafe {
    // Deferred initialization:
    five.as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5)

pub fn pin(x: T) -> Pin<Self>

Constructs a new Pin<Box<T>>. If T does not implement Unpin, then x will be pinned in memory and unable to be moved.

impl<T, B: BuildAlloc> Box<T, B> where
    B::Ref: AllocRef, 

pub fn new_in(x: T, a: B::Ref) -> Self where
    B::Ref: AllocRef<Error = Never>, 

Allocates memory with the given allocator and then places x into it.

This doesn't actually allocate if T is zero-sized.

Example

use alloc_wg::{
    alloc::{AbortAlloc, Global},
    boxed::Box,
};

let five: Box<_, AbortAlloc<Global>> = Box::new_in(5, AbortAlloc(Global));

pub fn try_new_in(x: T, a: B::Ref) -> Result<Self, <B::Ref as AllocRef>::Error>

Tries to allocate memory with the given allocator and then places x into it.

This doesn't actually allocate if T is zero-sized.

Example

use alloc_wg::{alloc::Global, boxed::Box};

let five: Box<_, Global> = Box::try_new_in(5, Global)?;

pub fn new_uninit_in(a: B::Ref) -> Box<MaybeUninit<T>, B> where
    B::Ref: AllocRef<Error = Never>, 

Constructs a new box with uninitialized contents in a specified allocator.

Example

use alloc_wg::{
    alloc::{AbortAlloc, Global},
    boxed::Box,
};

let mut five = Box::<u32, AbortAlloc<Global>>::new_uninit_in(AbortAlloc(Global));

let five = unsafe {
    // Deferred initialization:
    five.as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5)

pub fn try_new_uninit_in(
    a: B::Ref
) -> Result<Box<MaybeUninit<T>, B>, <B::Ref as AllocRef>::Error>

Tries to construct a new box with uninitialized contents in a specified allocator.

Example

use alloc_wg::{alloc::Global, boxed::Box};

let mut five = Box::<u32, Global>::try_new_uninit_in(Global)?;

let five = unsafe {
    // Deferred initialization:
    five.as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5);

pub fn pin_in(x: T, a: B::Ref) -> Pin<Self> where
    B::Ref: AllocRef<Error = Never>, 

Constructs a new Pin<Box<T, A>> with the specified allocator. If T does not implement Unpin, then x will be pinned in memory and unable to be moved.

pub fn try_pin_in(
    x: T,
    a: B::Ref
) -> Result<Pin<Self>, <B::Ref as AllocRef>::Error>

Constructs a new Pin<Box<T, A>> with the specified allocator. If T does not implement Unpin, then x will be pinned in memory and unable to be moved.

impl<T> Box<[T]>

pub fn new_uninit_slice(len: usize) -> Box<[MaybeUninit<T>]>

Construct a new boxed slice with uninitialized contents.

Example

use alloc_wg::boxed::Box;

let mut values = Box::<[u32]>::new_uninit_slice(3);

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);

    values.assume_init()
};

assert_eq!(*values, [1, 2, 3]);

impl<T, B: BuildAlloc> Box<[T], B> where
    B::Ref: AllocRef, 

pub fn new_uninit_slice_in(len: usize, a: B::Ref) -> Box<[MaybeUninit<T>], B> where
    B::Ref: AllocRef<Error = Never>, 

Construct a new boxed slice with uninitialized contents with the spoecified allocator.

Example

use alloc_wg::{
    alloc::{AbortAlloc, Global},
    boxed::Box,
};

let mut values = Box::<[u32], AbortAlloc<Global>>::new_uninit_slice_in(3, AbortAlloc(Global));

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);

    values.assume_init()
};

assert_eq!(*values, [1, 2, 3]);

pub fn try_new_uninit_slice_in(
    len: usize,
    a: B::Ref
) -> Result<Box<[MaybeUninit<T>], B>, CollectionAllocErr<B>>

Tries to construct a new boxed slice with uninitialized contents with the spoecified allocator.

Example

use alloc_wg::{alloc::Global, boxed::Box};

let mut values = Box::<[u32], Global>::try_new_uninit_slice_in(3, Global)?;

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);

    values.assume_init()
};

assert_eq!(*values, [1, 2, 3]);

impl<T, B: BuildAlloc> Box<MaybeUninit<T>, B>

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

Converts to Box<T, B>.

Safety

As with MaybeUninit::assume_init, it is up to the caller to guarantee that the value really is in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

Example

use alloc_wg::boxed::Box;

let mut five = Box::<u32>::new_uninit();

let five = unsafe {
    // Deferred initialization:
    five.as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5)

impl<T, B: BuildAlloc> Box<[MaybeUninit<T>], B>

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

Converts to Box<[T], B>.

Safety

As with MaybeUninit::assume_init, it is up to the caller to guarantee that the values really are in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

Example

use alloc_wg::boxed::Box;

let mut values = Box::<[u32]>::new_uninit_slice(3);

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);

    values.assume_init()
};

assert_eq!(*values, [1, 2, 3])

impl<T: ?Sized> Box<T>

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

Constructs a box from a raw pointer.

After calling this function, the raw pointer is owned by the resulting Box.2 Specifically, the Box destructor will call the destructor of T and free the allocated memory. For this to be safe, the memory must have been allocated in accordance with the memory layout used by Box .

Safety

This function is unsafe because improper use may lead to memory problems. For example, a double-free may occur if the function is called twice on the same raw pointer.

Examples

Recreate a Box which was previously converted to a raw pointer using Box::into_raw:

use alloc_wg::boxed::Box;

let x = Box::new(5);
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };

Manually create a Box from scratch by using the global allocator:

use alloc_wg::{
    alloc::{alloc, Layout},
    boxed::Box,
};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    *ptr = 5;
    let x = Box::from_raw(ptr);
}

impl<T: ?Sized, B: BuildAlloc> Box<T, B>

pub unsafe fn from_raw_in(raw: *mut T, d: B) -> Self

Constructs a box from a raw pointer.

After calling this function, the raw pointer is owned by the resulting Box. Specifically, the Box destructor will call the destructor of T and free the allocated memory. For this to be safe, the memory must have been allocated in accordance with the [memory layout] used by Box .

Safety

This function is unsafe because improper use may lead to memory problems. For example, a double-free may occur if the function is called twice on the same raw pointer.

Example

Manually create a Box from scratch by using the global allocator:

use alloc_wg::{
    alloc::{alloc, Global, Layout},
    boxed::Box,
};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    *ptr = 5;
    let x: Box<_, Global> = Box::from_raw_in(ptr, Global);
}

pub fn alloc_builder(&self) -> &B

pub fn alloc_builder_mut(&mut self) -> &mut B

pub fn alloc_ref(&mut self) -> B::Ref

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

Consumes the Box, returning a wrapped raw pointer.

The pointer will be properly aligned and non-null.

After calling this function, the caller is responsible for the memory previously managed by the Box. In particular, the caller should properly destroy T and release the memory, taking into account the memory layout used by Box. The easiest way to do this is to convert the raw pointer back into a Box with the Box::from_raw function, allowing the Box destructor to perform the cleanup.

Note: this is an associated function, which means that you have to call it as Box::into_raw(b) instead of b.into_raw(). This is so that there is no conflict with a method on the inner type.

Examples

Converting the raw pointer back into a Box with Box::from_raw for automatic cleanup:

use alloc_wg::boxed::Box;

let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };

Manual cleanup by explicitly running the destructor and deallocating the memory:

use alloc_wg::{
    alloc::{dealloc, Layout},
    boxed::Box,
};
use core::ptr;

let x = Box::new(String::from("Hello"));
let p = Box::into_raw(x);
unsafe {
    ptr::drop_in_place(p);
    dealloc(p as *mut u8, Layout::new::<String>());
}

pub fn into_raw_alloc(b: Self) -> (*mut T, B)

pub fn into_raw_non_null(b: Self) -> NonNull<T>

Consumes the Box, returning the wrapped pointer as NonNull<T>.

After calling this function, the caller is responsible for the memory previously managed by the Box. In particular, the caller should properly destroy T and release the memory. The easiest way to do so is to convert the NonNull<T> pointer into a raw pointer and back into a Box with the Box::from_raw function.

Note: this is an associated function, which means that you have to call it as Box::into_raw_non_null(b) instead of b.into_raw_non_null(). This is so that there is no conflict with a method on the inner type.

Examples

use alloc_wg::boxed::Box;

let x = Box::new(5);
let ptr = Box::into_raw_non_null(x);

// Clean up the memory by converting the NonNull pointer back
// into a Box and letting the Box be dropped.
let x = unsafe { Box::from_raw(ptr.as_ptr()) };

pub fn into_raw_non_null_alloc(b: Self) -> (NonNull<T>, B)

pub fn leak<'a>(b: Self) -> &'a mut T where
    T: 'a, 

Consumes and leaks the Box, returning a mutable reference, &'a mut T. Note that the type T must outlive the chosen lifetime 'a. If the type has only static references, or none at all, then this may be chosen to be 'static.

This function is mainly useful for data that lives for the remainder of the program's life. Dropping the returned reference will cause a memory leak. If this is not acceptable, the reference should first be wrapped with the Box::from_raw function producing a Box. This Box can then be dropped which will properly destroy T and release the allocated memory.

Note: this is an associated function, which means that you have to call it as Box::leak(b) instead of b.leak(). This is so that there is no conflict with a method on the inner type.

Examples

Simple usage:

use alloc_wg::boxed::Box;

let x = Box::new(41);
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);

pub fn into_pin(boxed: Self) -> Pin<Self>

Converts a Box<T, B> into a Pin<Box<T, B>>

This conversion does not allocate and happens in place.

This is also available via From.

Trait Implementations

impl<T: ?Sized, B: BuildAlloc> Drop for Box<T, B>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: ?Sized, B: BuildAlloc> AsRef<T> for Box<T, B>

fn as_ref(&self) -> &T

Performs the conversion.

impl<T: ?Sized, B: BuildAlloc> AsMut<T> for Box<T, B>

fn as_mut(&mut self) -> &mut T

Performs the conversion.

impl<T: ?Sized, B: BuildAlloc> From<Box<T, B>> for Pin<Box<T, B>>

fn from(boxed: Box<T, B>) -> Self

Converts a Box<T, B> into a Pin<Box<T, B>>

This conversion does not allocate on the heap and happens in place.

impl<T: Display + ?Sized, B: BuildAlloc> Display for Box<T, B>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: Debug + ?Sized, B: BuildAlloc> Debug for Box<T, B>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: ?Sized, B: BuildAlloc> Deref for Box<T, B>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: ?Sized, B: BuildAlloc> DerefMut for Box<T, B>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.