Attempts to downcast the box to a concrete type.

§Examples

usestd::any::Any;fnprint_if_string(value: Box<dynAny>) {if letOk(string) = value.downcast::<String>() {println!("String ({}): {}", string.len(), string);    }}letmy_string ="Hello World".to_string();print_if_string(Box::new(my_string));print_if_string(Box::new(0i8));

Downcasts the box to a concrete type.

For a safe alternative seedowncast.

§Examples

#![feature(downcast_unchecked)]usestd::any::Any;letx: Box<dynAny> = Box::new(1_usize);unsafe{assert_eq!(*x.downcast_unchecked::<usize>(),1);}

§Safety

The contained value must be of typeT. Calling this methodwith the incorrect type isundefined behavior.

Attempts to downcast the box to a concrete type.

§Examples

usestd::any::Any;fnprint_if_string(value: Box<dynAny + Send>) {if letOk(string) = value.downcast::<String>() {println!("String ({}): {}", string.len(), string);    }}letmy_string ="Hello World".to_string();print_if_string(Box::new(my_string));print_if_string(Box::new(0i8));

Downcasts the box to a concrete type.

For a safe alternative seedowncast.

§Examples

#![feature(downcast_unchecked)]usestd::any::Any;letx: Box<dynAny + Send> = Box::new(1_usize);unsafe{assert_eq!(*x.downcast_unchecked::<usize>(),1);}

§Safety

The contained value must be of typeT. Calling this methodwith the incorrect type isundefined behavior.

Attempts to downcast the box to a concrete type.

§Examples

usestd::any::Any;fnprint_if_string(value: Box<dynAny + Send + Sync>) {if letOk(string) = value.downcast::<String>() {println!("String ({}): {}", string.len(), string);    }}letmy_string ="Hello World".to_string();print_if_string(Box::new(my_string));print_if_string(Box::new(0i8));

Downcasts the box to a concrete type.

For a safe alternative seedowncast.

§Examples

#![feature(downcast_unchecked)]usestd::any::Any;letx: Box<dynAny + Send + Sync> = Box::new(1_usize);unsafe{assert_eq!(*x.downcast_unchecked::<usize>(),1);}

§Safety

The contained value must be of typeT. Calling this methodwith the incorrect type isundefined behavior.

Allocates memory on the heap and then placesx into it.

This doesn’t actually allocate ifT is zero-sized.

§Examples

letfive = Box::new(5);

Constructs a new box with uninitialized contents.

§Examples

letmutfive = Box::<u32>::new_uninit();// Deferred initialization:five.write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5)

Constructs a newBox with uninitialized contents, with the memorybeing filled with0 bytes.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

letzero = Box::<u32>::new_zeroed();letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0)

Constructs a newPin<Box<T>>. IfT does not implementUnpin, thenx will be pinned in memory and unable to be moved.

Constructing and pinning of theBox can also be done in two steps:Box::pin(x)does the same asBox::into_pin(Box::new(x)). Consider usinginto_pin if you already have aBox<T>, or if you want toconstruct a (pinned)Box in a different way than withBox::new.

Allocates memory on the heap then placesx into it,returning an error if the allocation fails

This doesn’t actually allocate ifT is zero-sized.

§Examples

#![feature(allocator_api)]letfive = Box::try_new(5)?;

Constructs a new box with uninitialized contents on the heap,returning an error if the allocation fails

§Examples

#![feature(allocator_api)]letmutfive = Box::<u32>::try_new_uninit()?;// Deferred initialization:five.write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5);

Constructs a newBox with uninitialized contents, with the memorybeing filled with0 bytes on the heap

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature(allocator_api)]letzero = Box::<u32>::try_new_zeroed()?;letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0);

Maps the value in a box, reusing the allocation if possible.

f is called on the value in the box, and the result is returned, also boxed.

Note: this is an associated function, which means that you haveto call it asBox::map(b, f) instead ofb.map(f). Thisis so that there is no conflict with a method on the inner type.

§Examples

#![feature(smart_pointer_try_map)]letb = Box::new(7);letnew = Box::map(b, |i| i +7);assert_eq!(*new,14);

Attempts to map the value in a box, reusing the allocation if possible.

f is called on the value in the box, and if the operation succeeds, the result isreturned, also boxed.

Note: this is an associated function, which means that you haveto call it asBox::try_map(b, f) instead ofb.try_map(f). Thisis so that there is no conflict with a method on the inner type.

§Examples

#![feature(smart_pointer_try_map)]letb = Box::new(7);letnew = Box::try_map(b, u32::try_from).unwrap();assert_eq!(*new,7);

Allocates memory in the given allocator then placesx into it.

This doesn’t actually allocate ifT is zero-sized.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letfive = Box::new_in(5, System);

Allocates memory in the given allocator then placesx into it,returning an error if the allocation fails

This doesn’t actually allocate ifT is zero-sized.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letfive = Box::try_new_in(5, System)?;

Constructs a new box with uninitialized contents in the provided allocator.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letmutfive = Box::<u32,_>::new_uninit_in(System);// Deferred initialization:five.write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5)

Constructs a new box with uninitialized contents in the provided allocator,returning an error if the allocation fails

§Examples

#![feature(allocator_api)]usestd::alloc::System;letmutfive = Box::<u32,_>::try_new_uninit_in(System)?;// Deferred initialization:five.write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5);

Constructs a newBox with uninitialized contents, with the memorybeing filled with0 bytes in the provided allocator.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letzero = Box::<u32,_>::new_zeroed_in(System);letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0)

Constructs a newBox with uninitialized contents, with the memorybeing filled with0 bytes in the provided allocator,returning an error if the allocation fails,

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letzero = Box::<u32,_>::try_new_zeroed_in(System)?;letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0);

Constructs a newPin<Box<T, A>>. IfT does not implementUnpin, thenx will be pinned in memory and unable to be moved.

Constructing and pinning of theBox can also be done in two steps:Box::pin_in(x, alloc)does the same asBox::into_pin(Box::new_in(x, alloc)). Consider usinginto_pin if you already have aBox<T, A>, or if you want toconstruct a (pinned)Box in a different way than withBox::new_in.

Converts aBox<T> into aBox<[T]>

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

Consumes theBox, returning the wrapped value.

§Examples

#![feature(box_into_inner)]letc = Box::new(5);assert_eq!(Box::into_inner(c),5);

Consumes theBox without consuming its allocation, returning the wrapped value and aBoxto the uninitialized memory where the wrapped value used to live.

This can be used together withwrite to reuse the allocation for multipleboxed values.

§Examples

#![feature(box_take)]letc = Box::new(5);// take the value out of the boxlet(value, uninit) = Box::take(c);assert_eq!(value,5);// reuse the box for a second valueletc = Box::write(uninit,6);assert_eq!(*c,6);

Allocates memory on the heap then clonessrc into it.

This doesn’t actually allocate ifsrc is zero-sized.

§Examples

#![feature(clone_from_ref)]lethello: Box<str> = Box::clone_from_ref("hello");

Allocates memory on the heap then clonessrc into it, returning an error if allocation fails.

This doesn’t actually allocate ifsrc is zero-sized.

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]lethello: Box<str> = Box::try_clone_from_ref("hello")?;

Allocates memory in the given allocator then clonessrc into it.

This doesn’t actually allocate ifsrc is zero-sized.

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]usestd::alloc::System;lethello: Box<str, System> = Box::clone_from_ref_in("hello", System);

Allocates memory in the given allocator then clonessrc into it, returning an error if allocation fails.

This doesn’t actually allocate ifsrc is zero-sized.

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]usestd::alloc::System;lethello: Box<str, System> = Box::try_clone_from_ref_in("hello", System)?;

Constructs a new boxed slice with uninitialized contents.

§Examples

letmutvalues = Box::<[u32]>::new_uninit_slice(3);// Deferred initialization:values[0].write(1);values[1].write(2);values[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3])

Constructs a new boxed slice with uninitialized contents, with the memorybeing filled with0 bytes.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

letvalues = Box::<[u32]>::new_zeroed_slice(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [0,0,0])

Constructs a new boxed slice with uninitialized contents. Returns an error ifthe allocation fails.

§Examples

#![feature(allocator_api)]letmutvalues = Box::<[u32]>::try_new_uninit_slice(3)?;// Deferred initialization:values[0].write(1);values[1].write(2);values[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3]);

Constructs a new boxed slice with uninitialized contents, with the memorybeing filled with0 bytes. Returns an error if the allocation fails.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature(allocator_api)]letvalues = Box::<[u32]>::try_new_zeroed_slice(3)?;letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [0,0,0]);

Converts the boxed slice into a boxed array.

This operation does not reallocate; the underlying array of the slice is simply reinterpreted as an array type.

IfN is not exactly equal to the length ofself, then this method returnsNone.

Constructs a new boxed slice with uninitialized contents in the provided allocator.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letmutvalues = Box::<[u32],_>::new_uninit_slice_in(3, System);// Deferred initialization:values[0].write(1);values[1].write(2);values[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3])

Constructs a new boxed slice with uninitialized contents in the provided allocator,with the memory being filled with0 bytes.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letvalues = Box::<[u32],_>::new_zeroed_slice_in(3, System);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [0,0,0])

Constructs a new boxed slice with uninitialized contents in the provided allocator. Returns an error ifthe allocation fails.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letmutvalues = Box::<[u32],_>::try_new_uninit_slice_in(3, System)?;// Deferred initialization:values[0].write(1);values[1].write(2);values[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3]);

Constructs a new boxed slice with uninitialized contents in the provided allocator, with the memorybeing filled with0 bytes. Returns an error if the allocation fails.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature(allocator_api)]usestd::alloc::System;letvalues = Box::<[u32],_>::try_new_zeroed_slice_in(3, System)?;letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [0,0,0]);

Converts toBox<T, A>.

§Safety

As withMaybeUninit::assume_init,it is up to the caller to guarantee that the valuereally is in an initialized state.Calling this when the content is not yet fully initializedcauses immediate undefined behavior.

§Examples

letmutfive = Box::<u32>::new_uninit();// Deferred initialization:five.write(5);letfive: Box<u32> =unsafe{ five.assume_init() };assert_eq!(*five,5)

Writes the value and converts toBox<T, A>.

This method converts the box similarly toBox::assume_init butwritesvalue into it before conversion thus guaranteeing safety.In some scenarios use of this method may improve performance becausethe compiler may be able to optimize copying from stack.

§Examples

letbig_box = Box::<[usize;1024]>::new_uninit();letmutarray = [0;1024];for(i, place)inarray.iter_mut().enumerate() {*place = i;}// The optimizer may be able to elide this copy, so previous code writes// to heap directly.letbig_box = Box::write(big_box, array);for(i, x)inbig_box.iter().enumerate() {assert_eq!(*x, i);}

Converts toBox<[T], A>.

§Safety

As withMaybeUninit::assume_init,it is up to the caller to guarantee that the valuesreally are in an initialized state.Calling this when the content is not yet fully initializedcauses immediate undefined behavior.

§Examples

letmutvalues = Box::<[u32]>::new_uninit_slice(3);// Deferred initialization:values[0].write(1);values[1].write(2);values[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3])

Constructs a box from a raw pointer.

After calling this function, the raw pointer is owned by theresultingBox. Specifically, theBox destructor will callthe destructor ofT and free the allocated memory. For thisto be safe, the memory must have been allocated in accordancewith thememory layout used byBox .

§Safety

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

The raw pointer must point to a block of memory allocated by the global allocator.

The safety conditions are described in thememory layout section.

§Examples

Recreate aBox which was previously converted to a raw pointerusingBox::into_raw:

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

Manually create aBox from scratch by using the global allocator:

usestd::alloc::{alloc, Layout};unsafe{letptr = alloc(Layout::new::<i32>())as*muti32;// In general .write is required to avoid attempting to destruct    // the (uninitialized) previous contents of `ptr`, though for this    // simple example `*ptr = 5` would have worked as well.ptr.write(5);letx = Box::from_raw(ptr);}

Constructs a box from aNonNull pointer.

After calling this function, theNonNull pointer is owned bythe resultingBox. Specifically, theBox destructor will callthe destructor ofT and free the allocated memory. For thisto be safe, the memory must have been allocated in accordancewith thememory layout used byBox .

§Safety

This function is unsafe because improper use may lead tomemory problems. For example, a double-free may occur if thefunction is called twice on the sameNonNull pointer.

The non-null pointer must point to a block of memory allocated by the global allocator.

The safety conditions are described in thememory layout section.

§Examples

Recreate aBox which was previously converted to aNonNullpointer usingBox::into_non_null:

#![feature(box_vec_non_null)]letx = Box::new(5);letnon_null = Box::into_non_null(x);letx =unsafe{ Box::from_non_null(non_null) };

Manually create aBox from scratch by using the global allocator:

#![feature(box_vec_non_null)]usestd::alloc::{alloc, Layout};usestd::ptr::NonNull;unsafe{letnon_null = NonNull::new(alloc(Layout::new::<i32>()).cast::<i32>())        .expect("allocation failed");// In general .write is required to avoid attempting to destruct    // the (uninitialized) previous contents of `non_null`.non_null.write(5);letx = Box::from_non_null(non_null);}

Consumes theBox, returning a wrapped raw pointer.

The pointer will be properly aligned and non-null.

After calling this function, the caller is responsible for thememory previously managed by theBox. In particular, thecaller should properly destroyT and release the memory, takinginto account thememory layout used byBox. The easiest way todo this is to convert the raw pointer back into aBox with theBox::from_raw function, allowing theBox destructor to performthe cleanup.

Note: this is an associated function, which means that you haveto call it asBox::into_raw(b) instead ofb.into_raw(). Thisis so that there is no conflict with a method on the inner type.

§Examples

Converting the raw pointer back into aBox withBox::from_rawfor automatic cleanup:

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

Manual cleanup by explicitly running the destructor and deallocatingthe memory:

usestd::alloc::{dealloc, Layout};usestd::ptr;letx = Box::new(String::from("Hello"));letptr = Box::into_raw(x);unsafe{    ptr::drop_in_place(ptr);    dealloc(ptras*mutu8, Layout::new::<String>());}

Note: This is equivalent to the following:

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

Consumes theBox, returning a wrappedNonNull pointer.

The pointer will be properly aligned.

After calling this function, the caller is responsible for thememory previously managed by theBox. In particular, thecaller should properly destroyT and release the memory, takinginto account thememory layout used byBox. The easiest way todo this is to convert theNonNull pointer back into aBox with theBox::from_non_null function, allowing theBox destructor toperform the cleanup.

Note: this is an associated function, which means that you haveto call it asBox::into_non_null(b) instead ofb.into_non_null().This is so that there is no conflict with a method on the inner type.

§Examples

Converting theNonNull pointer back into aBox withBox::from_non_nullfor automatic cleanup:

#![feature(box_vec_non_null)]letx = Box::new(String::from("Hello"));letnon_null = Box::into_non_null(x);letx =unsafe{ Box::from_non_null(non_null) };

Manual cleanup by explicitly running the destructor and deallocatingthe memory:

#![feature(box_vec_non_null)]usestd::alloc::{dealloc, Layout};letx = Box::new(String::from("Hello"));letnon_null = Box::into_non_null(x);unsafe{    non_null.drop_in_place();    dealloc(non_null.as_ptr().cast::<u8>(), Layout::new::<String>());}

Note: This is equivalent to the following:

#![feature(box_vec_non_null)]letx = Box::new(String::from("Hello"));letnon_null = Box::into_non_null(x);unsafe{    drop(Box::from_non_null(non_null));}

Constructs a box from a raw pointer in the given allocator.

After calling this function, the raw pointer is owned by theresultingBox. Specifically, theBox destructor will callthe destructor ofT and free the allocated memory. For thisto be safe, the memory must have been allocated in accordancewith thememory layout used byBox .

§Safety

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

The raw pointer must point to a block of memory allocated byalloc.

§Examples

Recreate aBox which was previously converted to a raw pointerusingBox::into_raw_with_allocator:

#![feature(allocator_api)]usestd::alloc::System;letx = Box::new_in(5, System);let(ptr, alloc) = Box::into_raw_with_allocator(x);letx =unsafe{ Box::from_raw_in(ptr, alloc) };

Manually create aBox from scratch by using the system allocator:

#![feature(allocator_api, slice_ptr_get)]usestd::alloc::{Allocator, Layout, System};unsafe{letptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr()as*muti32;// In general .write is required to avoid attempting to destruct    // the (uninitialized) previous contents of `ptr`, though for this    // simple example `*ptr = 5` would have worked as well.ptr.write(5);letx = Box::from_raw_in(ptr, System);}

Constructs a box from aNonNull pointer in the given allocator.

After calling this function, theNonNull pointer is owned bythe resultingBox. Specifically, theBox destructor will callthe destructor ofT and free the allocated memory. For thisto be safe, the memory must have been allocated in accordancewith thememory layout used byBox .

§Safety

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

The non-null pointer must point to a block of memory allocated byalloc.

§Examples

Recreate aBox which was previously converted to aNonNull pointerusingBox::into_non_null_with_allocator:

#![feature(allocator_api, box_vec_non_null)]usestd::alloc::System;letx = Box::new_in(5, System);let(non_null, alloc) = Box::into_non_null_with_allocator(x);letx =unsafe{ Box::from_non_null_in(non_null, alloc) };

Manually create aBox from scratch by using the system allocator:

#![feature(allocator_api, box_vec_non_null, slice_ptr_get)]usestd::alloc::{Allocator, Layout, System};unsafe{letnon_null = System.allocate(Layout::new::<i32>())?.cast::<i32>();// In general .write is required to avoid attempting to destruct    // the (uninitialized) previous contents of `non_null`.non_null.write(5);letx = Box::from_non_null_in(non_null, System);}

Consumes theBox, returning a wrapped raw pointer and the allocator.

The pointer will be properly aligned and non-null.

After calling this function, the caller is responsible for thememory previously managed by theBox. In particular, thecaller should properly destroyT and release the memory, takinginto account thememory layout used byBox. The easiest way todo this is to convert the raw pointer back into aBox with theBox::from_raw_in function, allowing theBox destructor to performthe cleanup.

Note: this is an associated function, which means that you haveto call it asBox::into_raw_with_allocator(b) instead ofb.into_raw_with_allocator(). Thisis so that there is no conflict with a method on the inner type.

§Examples

Converting the raw pointer back into aBox withBox::from_raw_infor automatic cleanup:

#![feature(allocator_api)]usestd::alloc::System;letx = Box::new_in(String::from("Hello"), System);let(ptr, alloc) = Box::into_raw_with_allocator(x);letx =unsafe{ Box::from_raw_in(ptr, alloc) };

Manual cleanup by explicitly running the destructor and deallocatingthe memory:

#![feature(allocator_api)]usestd::alloc::{Allocator, Layout, System};usestd::ptr::{self, NonNull};letx = Box::new_in(String::from("Hello"), System);let(ptr, alloc) = Box::into_raw_with_allocator(x);unsafe{    ptr::drop_in_place(ptr);letnon_null = NonNull::new_unchecked(ptr);    alloc.deallocate(non_null.cast(), Layout::new::<String>());}

Consumes theBox, returning a wrappedNonNull pointer and the allocator.

The pointer will be properly aligned.

After calling this function, the caller is responsible for thememory previously managed by theBox. In particular, thecaller should properly destroyT and release the memory, takinginto account thememory layout used byBox. The easiest way todo this is to convert theNonNull pointer back into aBox with theBox::from_non_null_in function, allowing theBox destructor toperform the cleanup.

Note: this is an associated function, which means that you haveto call it asBox::into_non_null_with_allocator(b) instead ofb.into_non_null_with_allocator(). This is so that there is noconflict with a method on the inner type.

§Examples

Converting theNonNull pointer back into aBox withBox::from_non_null_in for automatic cleanup:

#![feature(allocator_api, box_vec_non_null)]usestd::alloc::System;letx = Box::new_in(String::from("Hello"), System);let(non_null, alloc) = Box::into_non_null_with_allocator(x);letx =unsafe{ Box::from_non_null_in(non_null, alloc) };

Manual cleanup by explicitly running the destructor and deallocatingthe memory:

#![feature(allocator_api, box_vec_non_null)]usestd::alloc::{Allocator, Layout, System};letx = Box::new_in(String::from("Hello"), System);let(non_null, alloc) = Box::into_non_null_with_allocator(x);unsafe{    non_null.drop_in_place();    alloc.deallocate(non_null.cast::<u8>(), Layout::new::<String>());}

Returns a raw mutable pointer to theBox’s contents.

The caller must ensure that theBox outlives the pointer thisfunction returns, or else it will end up dangling.

This method guarantees that for the purpose of the aliasing model, this methoddoes not materialize a reference to the underlying memory, and thus the returned pointerwill remain valid when mixed with other calls toas_ptr andas_mut_ptr.Note that calling other methods that materialize references to the memorymay still invalidate this pointer.See the example below for how this guarantee can be used.

§Examples

Due to the aliasing guarantee, the following code is legal:

#![feature(box_as_ptr)]unsafe{letmutb = Box::new(0);letptr1 = Box::as_mut_ptr(&mutb);    ptr1.write(1);letptr2 = Box::as_mut_ptr(&mutb);    ptr2.write(2);// Notably, the write to `ptr2` did *not* invalidate `ptr1`:ptr1.write(3);}

Returns a raw pointer to theBox’s contents.

The caller must ensure that theBox outlives the pointer thisfunction returns, or else it will end up dangling.

The caller must also ensure that the memory the pointer (non-transitively) points tois never written to (except inside anUnsafeCell) using this pointer or any pointerderived from it. If you need to mutate the contents of theBox, useas_mut_ptr.

This method guarantees that for the purpose of the aliasing model, this methoddoes not materialize a reference to the underlying memory, and thus the returned pointerwill remain valid when mixed with other calls toas_ptr andas_mut_ptr.Note that calling other methods that materialize mutable references to the memory,as well as writing to this memory, may still invalidate this pointer.See the example below for how this guarantee can be used.

§Examples

Due to the aliasing guarantee, the following code is legal:

#![feature(box_as_ptr)]unsafe{letmutv = Box::new(0);letptr1 = Box::as_ptr(&v);letptr2 = Box::as_mut_ptr(&mutv);let_val = ptr2.read();// No write to this memory has happened yet, so `ptr1` is still valid.let_val = ptr1.read();// However, once we do a write...ptr2.write(1);// ... `ptr1` is no longer valid.    // This would be UB: let _val = ptr1.read();}

Returns a reference to the underlying allocator.

Note: this is an associated function, which means that you haveto call it asBox::allocator(&b) instead ofb.allocator(). Thisis so that there is no conflict with a method on the inner type.

Consumes and leaks theBox, returning a mutable reference,&'a mut T.

Note that the typeT must outlive the chosen lifetime'a. If the typehas 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 ofthe program’s life. Dropping the returned reference will cause a memoryleak. If this is not acceptable, the reference should first be wrappedwith theBox::from_raw function producing aBox. ThisBox canthen be dropped which will properly destroyT and release theallocated memory.

Note: this is an associated function, which means that you haveto call it asBox::leak(b) instead ofb.leak(). Thisis so that there is no conflict with a method on the inner type.

§Examples

Simple usage:

letx = Box::new(41);letstatic_ref:&'staticmutusize = Box::leak(x);*static_ref +=1;assert_eq!(*static_ref,42);

Unsized data:

letx =vec![1,2,3].into_boxed_slice();letstatic_ref = Box::leak(x);static_ref[0] =4;assert_eq!(*static_ref, [4,2,3]);

Converts aBox<T> into aPin<Box<T>>. IfT does not implementUnpin, then*boxed will be pinned in memory and unable to be moved.

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

This is also available viaFrom.

Constructing and pinning aBox withBox::into_pin(Box::new(x))can also be written more concisely usingBox::pin(x).Thisinto_pin method is useful if you already have aBox<T>, or you areconstructing a (pinned)Box in a different way than withBox::new.

§Notes

It’s not recommended that crates add an impl likeFrom<Box<T>> for Pin<T>,as it’ll introduce an ambiguity when callingPin::from.A demonstration of such a poor impl is shown below.

structFoo;// A type defined in this crate.implFrom<Box<()>>forPin<Foo> {fnfrom(_: Box<()>) -> Pin<Foo> {        Pin::new(Foo)    }}letfoo = Box::new(());letbar = Pin::from(foo);

Copiessource’s contents intoself without creating a new allocation,so long as the two are of the same length.

§Examples

letx = Box::new([5,6,7]);letmuty = Box::new([8,9,10]);letyp:*const[i32] =&*y;y.clone_from(&x);// The value is the sameassert_eq!(x, y);// And no allocation occurredassert_eq!(yp,&*y);

Returns a new box with aclone() of this box’s contents.

§Examples

letx = Box::new(5);lety = x.clone();// The value is the sameassert_eq!(x, y);// But they are unique objectsassert_ne!(&*xas*consti32,&*yas*consti32);

Copiessource’s contents intoself without creating a new allocation.

§Examples

letx = Box::new(5);letmuty = Box::new(10);letyp:*consti32 =&*y;y.clone_from(&x);// The value is the sameassert_eq!(x, y);// And no allocation occurredassert_eq!(yp,&*y);

Creates an empty[T] inside aBox.

Creates aBox<T>, with theDefault value forT.

Converts a&[T] into aBox<[T]>

This conversion allocates on the heapand performs a copy ofslice and its contents.

§Examples

// create a &[u8] which will be used to create a Box<[u8]>letslice:&[u8] =&[104,101,108,108,111];letboxed_slice: Box<[u8]> = Box::from(slice);println!("{boxed_slice:?}");

Converts a&CStr into aBox<CStr>,by copying the contents into a newly allocatedBox.

Copies the string into a newly allocatedBox<OsStr>.

Creates a boxedPath from a reference.

This will allocate and clonepath to it.

Converts a&mut [T] into aBox<[T]>

This conversion allocates on the heapand performs a copy ofslice and its contents.

§Examples

// create a &mut [u8] which will be used to create a Box<[u8]>letmutarray = [104,101,108,108,111];letslice:&mut[u8] =&mutarray;letboxed_slice: Box<[u8]> = Box::from(slice);println!("{boxed_slice:?}");

Converts a&mut CStr into aBox<CStr>,by copying the contents into a newly allocatedBox.

Copies the string into a newly allocatedBox<OsStr>.

Creates a boxedPath from a reference.

This will allocate and clonepath to it.

Converts a&mut str into aBox<str>

This conversion allocates on the heapand performs a copy ofs.

§Examples

letmutoriginal = String::from("hello");letoriginal:&mutstr =&mutoriginal;letboxed: Box<str> = Box::from(original);println!("{boxed}");

Converts astr into a box of dynError.

§Examples

usestd::error::Error;leta_str_error ="a str error";leta_boxed_error = Box::<dynError>::from(a_str_error);assert!(size_of::<Box<dynError>>() == size_of_val(&a_boxed_error))

Converts astr into a box of dynError +Send +Sync.

§Examples

usestd::error::Error;leta_str_error ="a str error";leta_boxed_error = Box::<dynError + Send + Sync>::from(a_str_error);assert!(    size_of::<Box<dynError + Send + Sync>>() == size_of_val(&a_boxed_error))

Converts a&str into aBox<str>

This conversion allocates on the heapand performs a copy ofs.

§Examples

letboxed: Box<str> = Box::from("hello");println!("{boxed}");

Converts a[T; N] into aBox<[T]>

This conversion moves the array to newly heap-allocated memory.

§Examples

letboxed: Box<[u8]> = Box::from([4,2]);println!("{boxed:?}");

Converts a boxed slice into a vector by transferring ownership ofthe existing heap allocation.

§Examples

letb: Box<[i32]> =vec![1,2,3].into_boxed_slice();assert_eq!(Vec::from(b),vec![1,2,3]);

Converts aBox<CStr> into aCString without copying or allocating.

Converts aBox<OsStr> into anOsString without copying orallocating.

Converts aBox<Path> into aPathBuf.

This conversion does not allocate or copy memory.

Move a boxed object to a new, reference-counted allocation.

§Example

letunique: Box<str> = Box::from("eggplant");letshared: Arc<str> = Arc::from(unique);assert_eq!("eggplant",&shared[..]);

Converts aBox<T> into aPin<Box<T>>. IfT does not implementUnpin, then*boxed will be pinned in memory and unable to be moved.

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

This is also available viaBox::into_pin.

Constructing and pinning aBox with<Pin<Box<T>>>::from(Box::new(x))can also be written more concisely usingBox::pin(x).ThisFrom implementation is useful if you already have aBox<T>, or you areconstructing a (pinned)Box in a different way than withBox::new.

Move a boxed object to a new, reference counted, allocation.

§Example

letoriginal: Box<i32> = Box::new(1);letshared: Rc<i32> = Rc::from(original);assert_eq!(1,*shared);

Converts the given boxedstr slice to aString.It is notable that thestr slice is owned.

§Examples

lets1: String = String::from("hello world");lets2: Box<str> = s1.into_boxed_str();lets3: String = String::from(s2);assert_eq!("hello world", s3)

Converts aBox<str> into aBox<[u8]>

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

§Examples

// create a Box<str> which will be used to create a Box<[u8]>letboxed: Box<str> = Box::from("hello");letboxed_str: Box<[u8]> = Box::from(boxed);// create a &[u8] which will be used to create a Box<[u8]>letslice:&[u8] =&[104,101,108,108,111];letboxed_slice = Box::from(slice);assert_eq!(boxed_slice, boxed_str);

Converts aCString into aBox<CStr> without copying or allocating.

Converts aCow<'_, [T]> into aBox<[T]>

Whencow is theCow::Borrowed variant, thisconversion allocates on the heap and copies theunderlying slice. Otherwise, it will try to reuse the ownedVec’s allocation.

Converts aCow<'a, CStr> into aBox<CStr>,by copying the contents if they are borrowed.

Converts aCow<'a, OsStr> into aBox<OsStr>,by copying the contents if they are borrowed.

Creates a boxedPath from a clone-on-write pointer.

Converting from aCow::Owned does not clone or allocate.

Converts aCow<'_, str> into aBox<str>

Whencow is theCow::Borrowed variant, thisconversion allocates on the heap and copies theunderlyingstr. Otherwise, it will try to reuse the ownedString’s allocation.

§Examples

usestd::borrow::Cow;letunboxed = Cow::Borrowed("hello");letboxed: Box<str> = Box::from(unboxed);println!("{boxed}");

letunboxed = Cow::Owned("hello".to_string());letboxed: Box<str> = Box::from(unboxed);println!("{boxed}");

Converts aCow into a box of dynError.

§Examples

usestd::error::Error;usestd::borrow::Cow;leta_cow_str_error = Cow::from("a str error");leta_boxed_error = Box::<dynError>::from(a_cow_str_error);assert!(size_of::<Box<dynError>>() == size_of_val(&a_boxed_error))

Converts aCow into a box of dynError +Send +Sync.

§Examples

usestd::error::Error;usestd::borrow::Cow;leta_cow_str_error = Cow::from("a str error");leta_boxed_error = Box::<dynError + Send + Sync>::from(a_cow_str_error);assert!(    size_of::<Box<dynError + Send + Sync>>() == size_of_val(&a_boxed_error))

Converts a type ofError into a box of dynError.

§Examples

usestd::error::Error;usestd::fmt;#[derive(Debug)]structAnError;implfmt::DisplayforAnError {fnfmt(&self, f:&mutfmt::Formatter<'_>) -> fmt::Result {write!(f,"An error")    }}implErrorforAnError {}letan_error = AnError;assert!(0== size_of_val(&an_error));leta_boxed_error = Box::<dynError>::from(an_error);assert!(size_of::<Box<dynError>>() == size_of_val(&a_boxed_error))

Converts a type ofError +Send +Sync into a box ofdynError +Send +Sync.

§Examples

usestd::error::Error;usestd::fmt;#[derive(Debug)]structAnError;implfmt::DisplayforAnError {fnfmt(&self, f:&mutfmt::Formatter<'_>) -> fmt::Result {write!(f,"An error")    }}implErrorforAnError {}unsafe implSendforAnError {}unsafe implSyncforAnError {}letan_error = AnError;assert!(0== size_of_val(&an_error));leta_boxed_error = Box::<dynError + Send + Sync>::from(an_error);assert!(    size_of::<Box<dynError + Send + Sync>>() == size_of_val(&a_boxed_error))

Converts anOsString into aBox<OsStr> without copying or allocating.

Converts aPathBuf into aBox<Path>.

This conversion currently should not allocate memory,but this behavior is not guaranteed on all platforms or in all future versions.

Converts aString into a box of dynError.

§Examples

usestd::error::Error;leta_string_error ="a string error".to_string();leta_boxed_error = Box::<dynError>::from(a_string_error);assert!(size_of::<Box<dynError>>() == size_of_val(&a_boxed_error))

Converts aString into a box of dynError +Send +Sync.

§Examples

usestd::error::Error;leta_string_error ="a string error".to_string();leta_boxed_error = Box::<dynError + Send + Sync>::from(a_string_error);assert!(    size_of::<Box<dynError + Send + Sync>>() == size_of_val(&a_boxed_error))

Converts the givenString to a boxedstr slice that is owned.

§Examples

lets1: String = String::from("hello world");lets2: Box<str> = Box::from(s1);lets3: String = String::from(s2);assert_eq!("hello world", s3)

Converts aT into aBox<T>

The conversion allocates on the heap and movestfrom the stack into it.

§Examples

letx =5;letboxed = Box::new(5);assert_eq!(Box::from(x), boxed);

Converts a vector into a boxed slice.

Before doing the conversion, this method discards excess capacity likeVec::shrink_to_fit.

§Examples

assert_eq!(Box::from(vec![1,2,3]),vec![1,2,3].into_boxed_slice());

Any excess capacity is removed:

letmutvec = Vec::with_capacity(10);vec.extend([1,2,3]);assert_eq!(Box::from(vec),vec![1,2,3].into_boxed_slice());