1.0.0[−][src]Struct std::boxed::Box
A pointer type for heap allocation.
See the module-level documentation for more.
Methods
impl<T> Box<T>
[src][−]
ⓘImportant traits for Box<I>pub fn new(x: T) -> Box<T>
[src][−]
Allocates memory on the heap and then places x
into it.
This doesn't actually allocate if T
is zero-sized.
Examples
let five = Box::new(5);Run
ⓘImportant traits for Pin<P>pub fn pin(x: T) -> Pin<Box<T>>
1.33.0[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> Box<T> where
T: ?Sized,
[src][−]
T: ?Sized,
ⓘImportant traits for Box<I>pub unsafe fn from_raw(raw: *mut T) -> Box<T>
1.4.0[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.
Examples
Recreate a Box
which was previously converted to a raw pointer
using Box::into_raw
:
let x = Box::new(5); let ptr = Box::into_raw(x); let x = unsafe { Box::from_raw(ptr) };Run
Manually create a Box
from scratch by using the global allocator:
use std::alloc::{alloc, Layout}; unsafe { let ptr = alloc(Layout::new::<i32>()) as *mut i32; *ptr = 5; let x = Box::from_raw(ptr); }Run
pub fn into_raw(b: Box<T>) -> *mut T
1.4.0[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:
let x = Box::new(String::from("Hello")); let ptr = Box::into_raw(x); let x = unsafe { Box::from_raw(ptr) };Run
Manual cleanup by explicitly running the destructor and deallocating the memory:
use std::alloc::{dealloc, Layout}; use std::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>()); }Run
pub fn into_raw_non_null(b: Box<T>) -> 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
#![feature(box_into_raw_non_null)] fn main() { 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()) }; }Run
ⓘImportant traits for &'_ mut Fpub fn leak<'a>(b: Box<T>) -> &'a mut T where
T: 'a,
1.26.0[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:
fn main() { let x = Box::new(41); let static_ref: &'static mut usize = Box::leak(x); *static_ref += 1; assert_eq!(*static_ref, 42); }Run
Unsized data:
fn main() { let x = vec![1, 2, 3].into_boxed_slice(); let static_ref = Box::leak(x); static_ref[0] = 4; assert_eq!(*static_ref, [4, 2, 3]); }Run
ⓘImportant traits for Pin<P>pub fn into_pin(boxed: Box<T>) -> Pin<Box<T>>
[src][−]
Converts a Box<T>
into a Pin<Box<T>>
This conversion does not allocate on the heap and happens in place.
This is also available via From
.
impl Box<dyn Any + 'static>
[src][−]
pub fn downcast<T>(self) -> Result<Box<T>, Box<dyn Any + 'static>> where
T: Any,
[src][−]
T: Any,
Attempt to downcast the box to a concrete type.
Examples
use std::any::Any; fn print_if_string(value: Box<dyn Any>) { if let Ok(string) = value.downcast::<String>() { println!("String ({}): {}", string.len(), string); } } fn main() { let my_string = "Hello World".to_string(); print_if_string(Box::new(my_string)); print_if_string(Box::new(0i8)); }Run
impl Box<dyn Any + 'static + Send>
[src][−]
pub fn downcast<T>(self) -> Result<Box<T>, Box<dyn Any + 'static + Send>> where
T: Any,
[src][−]
T: Any,
Attempt to downcast the box to a concrete type.
Examples
use std::any::Any; fn print_if_string(value: Box<dyn Any + Send>) { if let Ok(string) = value.downcast::<String>() { println!("String ({}): {}", string.len(), string); } } fn main() { let my_string = "Hello World".to_string(); print_if_string(Box::new(my_string)); print_if_string(Box::new(0i8)); }Run
Trait Implementations
impl<T, U> DispatchFromDyn<Box<U>> for Box<T> where
T: Unsize<U> + ?Sized,
U: ?Sized,
[src]
T: Unsize<U> + ?Sized,
U: ?Sized,
impl<G> Generator for Box<G> where
G: Unpin + Generator + ?Sized,
[src][+]
G: Unpin + Generator + ?Sized,
impl<I> FusedIterator for Box<I> where
I: FusedIterator + ?Sized,
1.26.0[src]
I: FusedIterator + ?Sized,
impl<A, F> FnMut<A> for Box<F> where
F: FnMut<A> + ?Sized,
1.35.0[src][+]
F: FnMut<A> + ?Sized,
impl<T> Eq for Box<T> where
T: Eq + ?Sized,
[src]
T: Eq + ?Sized,
impl<T> PartialOrd<Box<T>> for Box<T> where
T: PartialOrd<T> + ?Sized,
[src][+]
T: PartialOrd<T> + ?Sized,
impl<T> Hash for Box<T> where
T: Hash + ?Sized,
[src][+]
T: Hash + ?Sized,
impl<I> ExactSizeIterator for Box<I> where
I: ExactSizeIterator + ?Sized,
[src][+]
I: ExactSizeIterator + ?Sized,
impl From<Box<str>> for Box<[u8]>
1.19.0[src][+]
impl<T> From<Vec<T>> for Box<[T]>
1.20.0[src][+]
impl<'_> From<&'_ str> for Box<str>
1.17.0[src][+]
impl<T> From<T> for Box<T>
1.6.0[src][+]
impl From<String> for Box<str>
1.20.0[src][+]
impl<'_, T> From<&'_ [T]> for Box<[T]> where
T: Copy,
1.17.0[src][+]
T: Copy,
impl<T> From<Box<[T]>> for Vec<T>
1.18.0[src][+]
impl<T> From<Box<T>> for Pin<Box<T>> where
T: ?Sized,
1.33.0[src][+]
T: ?Sized,
impl<T> From<Box<T>> for Rc<T> where
T: ?Sized,
1.21.0[src][+]
T: ?Sized,
impl From<Box<str>> for String
1.18.0[src][+]
impl<T> From<Box<T>> for Arc<T> where
T: ?Sized,
1.21.0[src][+]
T: ?Sized,
impl<A, F> FnOnce<A> for Box<F> where
F: FnOnce<A> + ?Sized,
1.35.0[src][+]
F: FnOnce<A> + ?Sized,
impl<T> AsMut<T> for Box<T> where
T: ?Sized,
1.5.0[src][+]
T: ?Sized,
impl<T> Ord for Box<T> where
T: Ord + ?Sized,
[src][+]
T: Ord + ?Sized,
impl<T> Pointer for Box<T> where
T: ?Sized,
[src][+]
T: ?Sized,
impl<I> Iterator for Box<I> where
I: Iterator + ?Sized,
[src][+]
I: Iterator + ?Sized,
impl<T> Hasher for Box<T> where
T: Hasher + ?Sized,
1.22.0[src][+]
T: Hasher + ?Sized,
impl<T> DerefMut for Box<T> where
T: ?Sized,
[src][+]
T: ?Sized,
impl<T> PartialEq<Box<T>> for Box<T> where
T: PartialEq<T> + ?Sized,
[src][+]
T: PartialEq<T> + ?Sized,
impl<A, F> Fn<A> for Box<F> where
F: Fn<A> + ?Sized,
1.35.0[src][+]
F: Fn<A> + ?Sized,
impl<T> Clone for Box<T> where
T: Clone,
[src][+]
T: Clone,
impl<T> Clone for Box<[T]> where
T: Clone,
1.3.0[src][+]
T: Clone,
impl Clone for Box<str>
1.3.0[src][+]
impl<T> Default for Box<T> where
T: Default,
[src][+]
T: Default,
impl<T> Default for Box<[T]>
[src][+]
impl Default for Box<str>
1.17.0[src][+]
impl<T> Drop for Box<T> where
T: ?Sized,
[src][+]
T: ?Sized,
impl<T> Display for Box<T> where
T: Display + ?Sized,
[src][+]
T: Display + ?Sized,
impl<T> Debug for Box<T> where
T: Debug + ?Sized,
[src][+]
T: Debug + ?Sized,
impl<T> Borrow<T> for Box<T> where
T: ?Sized,
1.1.0[src][+]
T: ?Sized,
impl<T, U> CoerceUnsized<Box<U>> for Box<T> where
T: Unsize<U> + ?Sized,
U: ?Sized,
[src]
T: Unsize<U> + ?Sized,
U: ?Sized,
impl<T> AsRef<T> for Box<T> where
T: ?Sized,
1.5.0[src][+]
T: ?Sized,
impl<I> DoubleEndedIterator for Box<I> where
I: DoubleEndedIterator + ?Sized,
[src][+]
I: DoubleEndedIterator + ?Sized,
impl<T> BorrowMut<T> for Box<T> where
T: ?Sized,
1.1.0[src][+]
T: ?Sized,
impl<A> FromIterator<A> for Box<[A]>
1.32.0[src][+]
impl<F> Future for Box<F> where
F: Unpin + Future + ?Sized,
1.36.0[src][+]
F: Unpin + Future + ?Sized,
impl<T> Deref for Box<T> where
T: ?Sized,
[src][+]
T: ?Sized,
impl<T> Unpin for Box<T> where
T: ?Sized,
1.33.0[src]
T: ?Sized,
impl<T: Error> Error for Box<T>
1.8.0[src][+]
impl<R: Read + ?Sized> Read for Box<R>
[src][+]
impl<W: Write + ?Sized> Write for Box<W>
[src][+]
impl<S: Seek + ?Sized> Seek for Box<S>
[src][+]
impl<B: BufRead + ?Sized> BufRead for Box<B>
[src][+]
impl<'a, E: Error + 'a> From<E> for Box<dyn Error + 'a>
[src][+]
impl<'a, E: Error + Send + Sync + 'a> From<E> for Box<dyn Error + Send + Sync + 'a>
[src][+]
impl From<String> for Box<dyn Error + Send + Sync>
[src][+]
impl From<String> for Box<dyn Error>
1.6.0[src][+]
impl<'a, '_> From<&'_ str> for Box<dyn Error + Send + Sync + 'a>
[src][+]
impl<'_> From<&'_ str> for Box<dyn Error>
1.6.0[src][+]
impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a>
1.22.0[src][+]
impl<'a> From<Cow<'a, str>> for Box<dyn Error>
1.22.0[src][+]
impl<'_> From<&'_ CStr> for Box<CStr>
1.17.0[src][+]
impl From<Box<CStr>> for CString
1.18.0[src][+]
impl From<CString> for Box<CStr>
1.20.0[src][+]
impl<'_> From<&'_ OsStr> for Box<OsStr>
1.17.0[src][+]
impl From<Box<OsStr>> for OsString
1.18.0[src][+]
impl From<OsString> for Box<OsStr>
1.20.0[src][+]
impl<'_> From<&'_ Path> for Box<Path>
1.17.0[src][+]
impl From<Box<Path>> for PathBuf
1.18.0[src][+]
impl From<PathBuf> for Box<Path>
1.20.0[src][+]
impl Clone for Box<CStr>
1.29.0[src][+]
impl Clone for Box<OsStr>
1.29.0[src][+]
impl Clone for Box<Path>
1.29.0[src][+]
impl Default for Box<CStr>
1.17.0[src][+]
impl Default for Box<OsStr>
1.17.0[src][+]
Auto Trait Implementations
Blanket Implementations
impl<'a, F> Pattern<'a> for F where
F: FnMut(char) -> bool,
[src][+]
F: FnMut(char) -> bool,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src][+]
U: Into<T>,
impl<I> IntoIterator for I where
I: Iterator,
[src][+]
I: Iterator,
impl<T, U> Into<U> for T where
U: From<T>,
[src][+]
U: From<T>,
impl<T> From<T> for T
[src][+]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src][+]
U: TryFrom<T>,
impl<T> Borrow<T> for T where
T: ?Sized,
[src][+]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src][+]
T: ?Sized,
impl<T> Any for T where
T: 'static + ?Sized,
[src][+]
T: 'static + ?Sized,
impl<A, F> FnBox<A> for F where
F: FnOnce<A>,
[src][+]
F: FnOnce<A>,
impl<T> ToOwned for T where
T: Clone,
[src][+]
T: Clone,
impl<T> ToString for T where
T: Display + ?Sized,
[src][+]
T: Display + ?Sized,