Struct Box

Source

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

Expand description

A pointer type that uniquely owns an allocation of type T.

Implementations§

Source §

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

Source

pub fn new(value: T) -> Box<T, A>

Allocates in the associated allocator and then places value into it. This doesn’t actually allocate if T is zero-sized.

Source

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

Allocates uninitialized memory in the associated allocator. This doesn’t actually allocate if T is zero-sized.

Source

pub fn try_new(value: T) -> Result<Box<T, A>, StorageError>

Tries to allocate in the associated allocator and then places value into it. This doesn’t actually allocate if T is zero-sized.

Source

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

Tries to allocate uninitialized memory in the associated allocator. This doesn’t actually allocate if T is zero-sized.

Source

pub fn into_inner(boxed: Self) -> T

Unwraps this Box into its contained value.

Source §

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

Source

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

Allocate uninitialized memory in the associated allocator. This doesn’t actually allocate if T is zero-sized.

Source

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

Tries to allocate uninitialized memory in the associated allocator. This doesn’t actually allocate if T is zero-sized.

Source §

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

Source

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. Specifically, the box destructor will call the destructor of T and free the allocated memory.

§Safety

The memory must have been allocated in accordance with the memory layout used by Box.

Source

pub fn into_raw(boxed: 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.

Source §

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

Source

pub fn new_in(value: T, alloc_in: I) -> Box<T, A>
where I: AllocateIn<Alloc = A>,

Allocates in the associated allocation target and then places value into it. This doesn’t actually allocate if T is zero-sized.

Source

pub fn new_uninit_in(alloc_in: I) -> Box<MaybeUninit<T>, A>
where I: AllocateIn<Alloc = A>,

Allocates uninitialized memory in the associated allocation target. This doesn’t actually allocate if T is zero-sized.

Source

pub fn try_new_in(value: T, alloc_in: I) -> Result<Box<T, A>, StorageError>
where I: AllocateIn<Alloc = A>,

Tries to allocate in the associated allocation target and then places value into it. This doesn’t actually allocate if T is zero-sized.

Source

pub fn try_new_uninit_in( alloc_in: I, ) -> Result<Box<MaybeUninit<T>, A>, StorageError>
where I: AllocateIn<Alloc = A>,

Tries to allocate uninitialized memory in the associated allocation target. This doesn’t actually allocate if T is zero-sized.

Source §

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

Source

pub fn new_uninit_slice_in( len: usize, alloc_in: I, ) -> Box<[MaybeUninit<T>], A>
where I: AllocateIn<Alloc = A>,

Allocates uninitialized memory in the associated allocation target. This doesn’t actually allocate if T is zero-sized.

Source

pub fn try_new_uninit_slice_in( len: usize, alloc_in: I, ) -> Result<Box<[MaybeUninit<T>], A>, StorageError>
where I: AllocateIn<Alloc = A>,

Tries to allocates uninitialized memory in the associated allocation target. This doesn’t actually allocate if T is zero-sized.

Source

pub fn into_vec(self) -> Vec<T, A>

Convert this boxed slice into a Vec<T, A> without reallocating.

Source §

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

Source

pub fn from_utf8(boxed: Box<[u8], A>) -> Result<Self, Utf8Error>

Convert a boxed slice of bytes into a Box<str>.

If you are sure that the byte slice is valid UTF-8, and you don’t want to incur the overhead of the validity check, there is an unsafe version of this function, Box::from_utf8_unchecked, which has the same behavior but skips the check.

Source

pub unsafe fn from_utf8_unchecked(boxed: Box<[u8], A>) -> Self

Convert a boxed slice of bytes into a Box<str>.

§Safety

The contained bytes must be valid UTF-8.

Source §

impl<T: Clone, A: AllocatorDefault> Box<[T], A>

Source

pub fn from_slice(data: &[T]) -> Self

Create a boxed slice by cloning a slice reference.

Source

pub fn try_from_slice(data: &[T]) -> Result<Self, StorageError>

Try to create a boxed slice by cloning a slice reference.

Source §

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

Source

pub fn from_slice_in(data: &[T], alloc_in: I) -> Self
where I: AllocateIn<Alloc = A>,

Create a boxed slice directly in an allocation target by cloning a slice reference.

Source

pub fn try_from_slice_in( data: &[T], alloc_in: I, ) -> Result<Self, StorageError>
where I: AllocateIn<Alloc = A>,

Try to create a boxed slice directly in an allocation target by cloning a slice reference.

Source §

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

Source

pub fn allocator(&self) -> &A

Obtain a reference to the contained allocator instance.

Source

pub fn as_ptr(&self) -> *const T

Get a read pointer to the beginning of the data allocation. This may be a dangling pointer if T is zero sized or the current capacity is zero.

Source

pub fn as_mut_ptr(&mut self) -> *mut T

Get a mutable pointer to the beginning of the data allocation. This may be a dangling pointer if T is zero sized or the current capacity is zero.

Source

pub unsafe fn from_raw_in(raw: *mut T, alloc: A) -> Self

Constructs a box from a raw pointer and an allocator instance.

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.

§Safety

The memory must have been allocated in accordance with the memory layout used by Box.

Source

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

Consumes the Box, returning a wrapped raw pointer and an allocator instance.

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_in 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_with_allocator(b) instead of b.into_raw_with_allocator(). This is so that there is no conflict with a method on the inner type.

Source

pub fn leak<'a>(boxed: Self) -> &'a mut T
where A: '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.

Source §

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

Source

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

Converts to Box<T, A>.

§Safety

The contents of the box must be initialized prior to calling, or else undefined behavior may result from the use of uninitialized memory.

Source

pub fn write(boxed: Self, value: T) -> Box<T, A>

Writes the value and converts to Box<T, A>.

This method converts the box similarly to Box::assume_init but writes value into it before conversion, thus guaranteeing safety. In some scenarios use of this method may improve performance because the compiler may be able to optimize copying from stack.

Source §