[−][src]Struct alloc_wg::boxed::Box
A pointer type for heap allocation.
See the module-level documentation for more.
Methods
impl<T> Box<T>
[src]
pub fn new(x: T) -> Self
[src]
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>>
[src]
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>
[src]
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: BuildDealloc> Box<T, B> where
B: BuildAlloc,
[src]
B: BuildAlloc,
pub fn new_in(x: T, a: B::AllocRef) -> Self where
B::AllocRef: AllocRef<Error = Never>,
[src]
B::AllocRef: 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::AllocRef
) -> Result<Self, <B::AllocRef as AllocRef>::Error>
[src]
x: T,
a: B::AllocRef
) -> Result<Self, <B::AllocRef 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::AllocRef) -> Box<MaybeUninit<T>, B> where
B::AllocRef: AllocRef<Error = Never>,
[src]
B::AllocRef: 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::AllocRef
) -> Result<Box<MaybeUninit<T>, B>, <B::AllocRef as AllocRef>::Error>
[src]
a: B::AllocRef
) -> Result<Box<MaybeUninit<T>, B>, <B::AllocRef 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::AllocRef) -> Pin<Self> where
B::AllocRef: AllocRef<Error = Never>,
[src]
B::AllocRef: 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::AllocRef
) -> Result<Pin<Self>, <B::AllocRef as AllocRef>::Error>
[src]
x: T,
a: B::AllocRef
) -> Result<Pin<Self>, <B::AllocRef 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]>
[src]
pub fn new_uninit_slice(len: usize) -> Box<[MaybeUninit<T>]>
[src]
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: BuildDealloc> Box<[T], B> where
B: BuildAlloc,
B::AllocRef: AllocRef<Error = Never>,
[src]
B: BuildAlloc,
B::AllocRef: AllocRef<Error = Never>,
pub fn new_uninit_slice_in(
len: usize,
a: B::AllocRef
) -> Box<[MaybeUninit<T>], B>
[src]
len: usize,
a: B::AllocRef
) -> Box<[MaybeUninit<T>], B>
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]);
impl<T, B: BuildDealloc> Box<[T], B> where
B: BuildAlloc,
[src]
B: BuildAlloc,
pub fn try_new_uninit_slice_in(
len: usize,
a: B::AllocRef
) -> Result<Box<[MaybeUninit<T>], B>, <B::AllocRef as AllocRef>::Error>
[src]
len: usize,
a: B::AllocRef
) -> Result<Box<[MaybeUninit<T>], B>, <B::AllocRef as AllocRef>::Error>
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: BuildDealloc> Box<MaybeUninit<T>, B>
[src]
pub unsafe fn assume_init(self) -> Box<T, B>
[src]
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: BuildDealloc> Box<[MaybeUninit<T>], B>
[src]
pub unsafe fn assume_init(self) -> Box<[T], B>
[src]
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>
[src]
pub unsafe fn from_raw(raw: *mut T) -> Self
[src]
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: BuildDealloc> Box<T, B>
[src]
pub unsafe fn from_raw_in(raw: *mut T, d: B::DeallocRef) -> Self
[src]
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 get_alloc(&mut self) -> B::DeallocRef
[src]
pub fn into_raw(b: Self) -> *mut T
[src]
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_non_null(b: Self) -> NonNull<T>
[src]
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 leak<'a>(b: Self) -> &'a mut T where
T: 'a,
[src]
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>
[src]
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: BuildDealloc> From<Box<T, B>> for Pin<Box<T, B>>
[src]
fn from(boxed: Box<T, B>) -> Self
[src]
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: ?Sized, B: BuildDealloc> AsMut<T> for Box<T, B>
[src]
impl<T: ?Sized, B: BuildDealloc> AsRef<T> for Box<T, B>
[src]
impl<T: ?Sized, B: BuildDealloc> Drop for Box<T, B>
[src]
impl<T: ?Sized, B: BuildDealloc> Deref for Box<T, B>
[src]
impl<T: ?Sized, B: BuildDealloc> DerefMut for Box<T, B>
[src]
impl<T: Debug + ?Sized, B: BuildDealloc> Debug for Box<T, B>
[src]
impl<T: Display + ?Sized, B: BuildDealloc> Display for Box<T, B>
[src]
Auto Trait Implementations
impl<T, B = AbortAlloc<Global>> !Send for Box<T, B>
impl<T, B = AbortAlloc<Global>> !Sync for Box<T, B>
impl<T: ?Sized, B> Unpin for Box<T, B> where
B: Unpin,
T: Unpin,
B: Unpin,
T: Unpin,
impl<T: ?Sized, B> RefUnwindSafe for Box<T, B> where
B: RefUnwindSafe,
T: RefUnwindSafe,
B: RefUnwindSafe,
T: RefUnwindSafe,
impl<T: ?Sized, B> UnwindSafe for Box<T, B> where
B: UnwindSafe,
T: RefUnwindSafe + UnwindSafe,
B: UnwindSafe,
T: RefUnwindSafe + UnwindSafe,
Blanket Implementations
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToString for T where
T: Display + ?Sized,
[src]
T: Display + ?Sized,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,