Lines Matching full:box
5 //! [`Box<T>`], casually referred to as a 'box', provides the simplest form of
12 //! Move a value from the stack to the heap by creating a [`Box`]:
16 //! let boxed: Box<u8> = Box::new(val);
19 //! Move a value from a [`Box`] back to the stack by [dereferencing]:
22 //! let boxed: Box<u8> = Box::new(5);
31 //! Cons(T, Box<List<T>>),
35 //! let list: List<i32> = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Nil))));
52 //! for a `Cons`. By introducing a [`Box<T>`], which has a defined size, we know how
57 //! For non-zero-sized values, a [`Box`] will use the [`Global`] allocator for
58 //! its allocation. It is valid to convert both ways between a [`Box`] and a
62 //! with `Layout::for_value(&*value)` may be converted into a box using
63 //! [`Box::<T>::from_raw(value)`]. Conversely, the memory backing a `value: *mut
64 //! T` obtained from [`Box::<T>::into_raw`] may be deallocated using the
67 //! For zero-sized values, the `Box` pointer still has to be [valid] for reads
71 //! not valid. The recommended way to build a Box to a ZST if `Box::new` cannot
74 //! So long as `T: Sized`, a `Box<T>` is guaranteed to be represented
78 //! Rust functions using `Box<T>` types, and use `T*` as corresponding
94 //! `struct Foo*` type from C is translated to `Box<Foo>`, which captures
96 //! `foo_delete` is represented in Rust as `Option<Box<Foo>>`, since `Box<Foo>`
104 //! pub extern "C" fn foo_new() -> Box<Foo> {
105 //! Box::new(Foo)
109 //! pub extern "C" fn foo_delete(_: Option<Box<Foo>>) {}
112 //! Even though `Box<T>` has the same representation and C ABI as a C pointer,
113 //! this does not mean that you can convert an arbitrary `T*` into a `Box<T>`
114 //! and expect things to work. `Box<T>` values will always be fully aligned,
115 //! non-null pointers. Moreover, the destructor for `Box<T>` will attempt to
117 //! is to only use `Box<T>` for pointers that originated from the global
121 //! `Box<T>` types for functions that are defined in C but invoked
123 //! as closely as possible. Using types like `Box<T>` where the C
129 //! [`Box::<T>::from_raw(value)`]: Box::from_raw
181 // The declaration of the `Box` struct must be kept in sync with the
184 pub struct Box< struct
189 impl<T> Box<T> { impl
197 /// let five = Box::new(5);
204 box x in new()
207 /// Constructs a new box with uninitialized contents.
214 /// let mut five = Box::<u32>::new_uninit();
229 pub fn new_uninit() -> Box<mem::MaybeUninit<T>> { in new_uninit()
233 /// Constructs a new `Box` with uninitialized contents, with the memory
244 /// let zero = Box::<u32>::new_zeroed();
255 pub fn new_zeroed() -> Box<mem::MaybeUninit<T>> { in new_zeroed()
259 /// Constructs a new `Pin<Box<T>>`. If `T` does not implement `Unpin`, then
265 pub fn pin(x: T) -> Pin<Box<T>> { in pin()
266 (box x).into() in pin()
279 /// let five = Box::try_new(5)?;
288 /// Constructs a new box with uninitialized contents on the heap,
296 /// let mut five = Box::<u32>::try_new_uninit()?;
311 pub fn try_new_uninit() -> Result<Box<mem::MaybeUninit<T>>, AllocError> { in try_new_uninit()
312 Box::try_new_uninit_in(Global) in try_new_uninit()
315 /// Constructs a new `Box` with uninitialized contents, with the memory
326 /// let zero = Box::<u32>::try_new_zeroed()?;
337 pub fn try_new_zeroed() -> Result<Box<mem::MaybeUninit<T>>, AllocError> { in try_new_zeroed()
338 Box::try_new_zeroed_in(Global) in try_new_zeroed()
342 impl<T, A: Allocator> Box<T, A> { impl
354 /// let five = Box::new_in(5, System);
384 /// let five = Box::try_new_in(5, System)?;
402 /// Constructs a new box with uninitialized contents in the provided allocator.
411 /// let mut five = Box::<u32, _>::new_uninit_in(System);
427 pub const fn new_uninit_in(alloc: A) -> Box<mem::MaybeUninit<T>, A> in new_uninit_in()
434 match Box::try_new_uninit_in(alloc) { in new_uninit_in()
440 /// Constructs a new box with uninitialized contents in the provided allocator,
450 /// let mut five = Box::<u32, _>::try_new_uninit_in(System)?;
465 pub const fn try_new_uninit_in(alloc: A) -> Result<Box<mem::MaybeUninit<T>, A>, AllocError> in try_new_uninit_in()
471 unsafe { Ok(Box::from_raw_in(ptr.as_ptr(), alloc)) } in try_new_uninit_in()
474 /// Constructs a new `Box` with uninitialized contents, with the memory
487 /// let zero = Box::<u32, _>::new_zeroed_in(System);
499 pub const fn new_zeroed_in(alloc: A) -> Box<mem::MaybeUninit<T>, A> in new_zeroed_in()
506 match Box::try_new_zeroed_in(alloc) { in new_zeroed_in()
512 /// Constructs a new `Box` with uninitialized contents, with the memory
526 /// let zero = Box::<u32, _>::try_new_zeroed_in(System)?;
537 pub const fn try_new_zeroed_in(alloc: A) -> Result<Box<mem::MaybeUninit<T>, A>, AllocError> in try_new_zeroed_in()
543 unsafe { Ok(Box::from_raw_in(ptr.as_ptr(), alloc)) } in try_new_zeroed_in()
546 /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement `Unpin`, then
560 /// Converts a `Box<T>` into a `Box<[T]>`
565 pub const fn into_boxed_slice(boxed: Self) -> Box<[T], A> { in into_boxed_slice()
566 let (raw, alloc) = Box::into_raw_with_allocator(boxed); in into_boxed_slice()
567 unsafe { Box::from_raw_in(raw as *mut [T; 1], alloc) } in into_boxed_slice()
570 /// Consumes the `Box`, returning the wrapped value.
577 /// let c = Box::new(5);
579 /// assert_eq!(Box::into_inner(c), 5);
592 impl<T> Box<[T]> { impl
600 /// let mut values = Box::<[u32]>::new_uninit_slice(3);
616 pub fn new_uninit_slice(len: usize) -> Box<[mem::MaybeUninit<T>]> { in new_uninit_slice()
631 /// let values = Box::<[u32]>::new_zeroed_slice(3);
641 pub fn new_zeroed_slice(len: usize) -> Box<[mem::MaybeUninit<T>]> { in new_zeroed_slice()
653 /// let mut values = Box::<[u32]>::try_new_uninit_slice(3)?;
667 pub fn try_new_uninit_slice(len: usize) -> Result<Box<[mem::MaybeUninit<T>]>, AllocError> { in try_new_uninit_slice()
689 /// let values = Box::<[u32]>::try_new_zeroed_slice(3)?;
699 pub fn try_new_zeroed_slice(len: usize) -> Result<Box<[mem::MaybeUninit<T>]>, AllocError> { in try_new_zeroed_slice()
711 impl<T, A: Allocator> Box<[T], A> { impl
721 /// let mut values = Box::<[u32], _>::new_uninit_slice_in(3, System);
738 pub fn new_uninit_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit<T>], A> { in new_uninit_slice_in()
755 /// let values = Box::<[u32], _>::new_zeroed_slice_in(3, System);
766 pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit<T>], A> { in new_zeroed_slice_in()
771 impl<T, A: Allocator> Box<mem::MaybeUninit<T>, A> { impl
772 /// Converts to `Box<T, A>`.
789 /// let mut five = Box::<u32>::new_uninit();
791 /// let five: Box<u32> = unsafe {
803 pub const unsafe fn assume_init(self) -> Box<T, A> { in assume_init()
804 let (raw, alloc) = Box::into_raw_with_allocator(self); in assume_init()
805 unsafe { Box::from_raw_in(raw as *mut T, alloc) } in assume_init()
808 /// Writes the value and converts to `Box<T, A>`.
810 /// This method converts the box similarly to [`Box::assume_init`] but
820 /// let big_box = Box::<[usize; 1024]>::new_uninit();
829 /// let big_box = Box::write(big_box, array);
838 pub const fn write(mut boxed: Self, value: T) -> Box<T, A> { in write()
846 impl<T, A: Allocator> Box<[mem::MaybeUninit<T>], A> { impl
847 /// Converts to `Box<[T], A>`.
864 /// let mut values = Box::<[u32]>::new_uninit_slice(3);
879 pub unsafe fn assume_init(self) -> Box<[T], A> { in assume_init()
880 let (raw, alloc) = Box::into_raw_with_allocator(self); in assume_init()
881 unsafe { Box::from_raw_in(raw as *mut [T], alloc) } in assume_init()
885 impl<T: ?Sized> Box<T> { impl
886 /// Constructs a box from a raw pointer.
889 /// resulting `Box`. Specifically, the `Box` destructor will call
892 /// with the [memory layout] used by `Box` .
904 /// Recreate a `Box` which was previously converted to a raw pointer
905 /// using [`Box::into_raw`]:
907 /// let x = Box::new(5);
908 /// let ptr = Box::into_raw(x);
909 /// let x = unsafe { Box::from_raw(ptr) };
911 /// Manually create a `Box` from scratch by using the global allocator:
921 /// let x = Box::from_raw(ptr);
934 impl<T: ?Sized, A: Allocator> Box<T, A> { impl
935 /// Constructs a box from a raw pointer in the given allocator.
938 /// resulting `Box`. Specifically, the `Box` destructor will call
941 /// with the [memory layout] used by `Box` .
952 /// Recreate a `Box` which was previously converted to a raw pointer
953 /// using [`Box::into_raw_with_allocator`]:
959 /// let x = Box::new_in(5, System);
960 /// let (ptr, alloc) = Box::into_raw_with_allocator(x);
961 /// let x = unsafe { Box::from_raw_in(ptr, alloc) };
963 /// Manually create a `Box` from scratch by using the system allocator:
975 /// let x = Box::from_raw_in(ptr, System);
986 Box(unsafe { Unique::new_unchecked(raw) }, alloc) in from_raw_in()
989 /// Consumes the `Box`, returning a wrapped raw pointer.
994 /// memory previously managed by the `Box`. In particular, the
996 /// into account the [memory layout] used by `Box`. The easiest way to
997 /// do this is to convert the raw pointer back into a `Box` with the
998 /// [`Box::from_raw`] function, allowing the `Box` destructor to perform
1002 /// to call it as `Box::into_raw(b)` instead of `b.into_raw()`. This
1006 /// Converting the raw pointer back into a `Box` with [`Box::from_raw`]
1009 /// let x = Box::new(String::from("Hello"));
1010 /// let ptr = Box::into_raw(x);
1011 /// let x = unsafe { Box::from_raw(ptr) };
1019 /// let x = Box::new(String::from("Hello"));
1020 /// let p = Box::into_raw(x);
1034 /// Consumes the `Box`, returning a wrapped raw pointer and the allocator.
1039 /// memory previously managed by the `Box`. In particular, the
1041 /// into account the [memory layout] used by `Box`. The easiest way to
1042 /// do this is to convert the raw pointer back into a `Box` with the
1043 /// [`Box::from_raw_in`] function, allowing the `Box` destructor to perform
1047 … /// to call it as `Box::into_raw_with_allocator(b)` instead of `b.into_raw_with_allocator()`. This
1051 /// Converting the raw pointer back into a `Box` with [`Box::from_raw_in`]
1058 /// let x = Box::new_in(String::from("Hello"), System);
1059 /// let (ptr, alloc) = Box::into_raw_with_allocator(x);
1060 /// let x = unsafe { Box::from_raw_in(ptr, alloc) };
1070 /// let x = Box::new_in(String::from("Hello"), System);
1071 /// let (ptr, alloc) = Box::into_raw_with_allocator(x);
1084 let (leaked, alloc) = Box::into_unique(b); in into_raw_with_allocator()
1091 reason = "use `Box::leak(b).into()` or `Unique::from(Box::leak(b))` instead"
1097 // Box is recognized as a "unique pointer" by Stacked Borrows, but internally it is a in into_unique()
1100 … // so all raw pointer methods have to go through `Box::leak`. Turning *that* to a raw pointer in into_unique()
1103 (Unique::from(Box::leak(b)), alloc) in into_unique()
1109 /// to call it as `Box::allocator(&b)` instead of `b.allocator()`. This
1118 /// Consumes and leaks the `Box`, returning a mutable reference,
1126 /// with the [`Box::from_raw`] function producing a `Box`. This `Box` can
1131 /// to call it as `Box::leak(b)` instead of `b.leak()`. This
1139 /// let x = Box::new(41);
1140 /// let static_ref: &'static mut usize = Box::leak(x);
1149 /// let static_ref = Box::leak(x);
1163 /// Converts a `Box<T>` into a `Pin<Box<T>>`
1174 // It's not possible to move or replace the insides of a `Pin<Box<T>>` in into_pin()
1182 unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Box<T, A> { implementation
1190 impl<T: Default> Default for Box<T> { implementation
1191 /// Creates a `Box<T>`, with the `Default` value for T.
1193 box T::default() in default()
1200 impl<T> const Default for Box<[T]> { implementation
1203 Box(ptr, Global) in default()
1210 impl const Default for Box<str> { implementation
1217 Box(ptr, Global) in default()
1223 impl<T: Clone, A: Allocator + Clone> Clone for Box<T, A> { implementation
1224 /// Returns a new box with a `clone()` of this box's contents.
1229 /// let x = Box::new(5);
1253 /// let x = Box::new(5);
1254 /// let mut y = Box::new(10);
1273 impl Clone for Box<str> { implementation
1276 let buf: Box<[u8]> = self.as_bytes().into(); in clone()
1282 impl<T: ?Sized + PartialEq, A: Allocator> PartialEq for Box<T, A> { implementation
1293 impl<T: ?Sized + PartialOrd, A: Allocator> PartialOrd for Box<T, A> { implementation
1316 impl<T: ?Sized + Ord, A: Allocator> Ord for Box<T, A> { implementation
1323 impl<T: ?Sized + Eq, A: Allocator> Eq for Box<T, A> {} implementation
1326 impl<T: ?Sized + Hash, A: Allocator> Hash for Box<T, A> { implementation
1333 impl<T: ?Sized + Hasher, A: Allocator> Hasher for Box<T, A> { implementation
1386 impl<T> From<T> for Box<T> { implementation
1387 /// Converts a `T` into a `Box<T>`
1396 /// let boxed = Box::new(5);
1398 /// assert_eq!(Box::from(x), boxed);
1401 Box::new(t) in from()
1407 impl<T: ?Sized, A: Allocator> const From<Box<T, A>> for Pin<Box<T, A>>
1411 /// Converts a `Box<T>` into a `Pin<Box<T>>`
1414 fn from(boxed: Box<T, A>) -> Self { in from()
1415 Box::into_pin(boxed) in from()
1421 impl<T: Copy> From<&[T]> for Box<[T]> { implementation
1422 /// Converts a `&[T]` into a `Box<[T]>`
1429 /// // create a &[u8] which will be used to create a Box<[u8]>
1431 /// let boxed_slice: Box<[u8]> = Box::from(slice);
1435 fn from(slice: &[T]) -> Box<[T]> { in from()
1447 impl<T: Copy> From<Cow<'_, [T]>> for Box<[T]> { implementation
1448 /// Converts a `Cow<'_, [T]>` into a `Box<[T]>`
1455 fn from(cow: Cow<'_, [T]>) -> Box<[T]> { in from()
1457 Cow::Borrowed(slice) => Box::from(slice), in from()
1458 Cow::Owned(slice) => Box::from(slice), in from()
1465 impl From<&str> for Box<str> { implementation
1466 /// Converts a `&str` into a `Box<str>`
1474 /// let boxed: Box<str> = Box::from("hello");
1478 fn from(s: &str) -> Box<str> { in from()
1479 unsafe { from_boxed_utf8_unchecked(Box::from(s.as_bytes())) } in from()
1485 impl From<Cow<'_, str>> for Box<str> { implementation
1486 /// Converts a `Cow<'_, str>` into a `Box<str>`
1499 /// let boxed: Box<str> = Box::from(unboxed);
1506 /// let boxed: Box<str> = Box::from(unboxed);
1510 fn from(cow: Cow<'_, str>) -> Box<str> { in from()
1512 Cow::Borrowed(s) => Box::from(s), in from()
1513 Cow::Owned(s) => Box::from(s), in from()
1519 impl<A: Allocator> From<Box<str, A>> for Box<[u8], A> { implementation
1520 /// Converts a `Box<str>` into a `Box<[u8]>`
1526 /// // create a Box<str> which will be used to create a Box<[u8]>
1527 /// let boxed: Box<str> = Box::from("hello");
1528 /// let boxed_str: Box<[u8]> = Box::from(boxed);
1530 /// // create a &[u8] which will be used to create a Box<[u8]>
1532 /// let boxed_slice = Box::from(slice);
1537 fn from(s: Box<str, A>) -> Self { in from()
1538 let (raw, alloc) = Box::into_raw_with_allocator(s); in from()
1539 unsafe { Box::from_raw_in(raw as *mut [u8], alloc) } in from()
1545 impl<T, const N: usize> From<[T; N]> for Box<[T]> { implementation
1546 /// Converts a `[T; N]` into a `Box<[T]>`
1553 /// let boxed: Box<[u8]> = Box::from([4, 2]);
1556 fn from(array: [T; N]) -> Box<[T]> { in from()
1557 box array
1562 impl<T, const N: usize> TryFrom<Box<[T]>> for Box<[T; N]> { implementation
1563 type Error = Box<[T]>;
1565 /// Attempts to convert a `Box<[T]>` into a `Box<[T; N]>`.
1572 /// Returns the old `Box<[T]>` in the `Err` variant if
1574 fn try_from(boxed_slice: Box<[T]>) -> Result<Self, Self::Error> { in try_from()
1576 Ok(unsafe { Box::from_raw(Box::into_raw(boxed_slice) as *mut [T; N]) }) in try_from()
1583 impl<A: Allocator> Box<dyn Any, A> { impl
1584 /// Attempt to downcast the box to a concrete type.
1591 /// fn print_if_string(value: Box<dyn Any>) {
1598 /// print_if_string(Box::new(my_string));
1599 /// print_if_string(Box::new(0i8));
1603 pub fn downcast<T: Any>(self) -> Result<Box<T, A>, Self> { in downcast()
1607 /// Downcasts the box to a concrete type.
1618 /// let x: Box<dyn Any> = Box::new(1_usize);
1633 pub unsafe fn downcast_unchecked<T: Any>(self) -> Box<T, A> { in downcast_unchecked()
1636 let (raw, alloc): (*mut dyn Any, _) = Box::into_raw_with_allocator(self); in downcast_unchecked()
1637 Box::from_raw_in(raw as *mut T, alloc) in downcast_unchecked()
1642 impl<A: Allocator> Box<dyn Any + Send, A> { implementation
1643 /// Attempt to downcast the box to a concrete type.
1650 /// fn print_if_string(value: Box<dyn Any + Send>) {
1657 /// print_if_string(Box::new(my_string));
1658 /// print_if_string(Box::new(0i8));
1662 pub fn downcast<T: Any>(self) -> Result<Box<T, A>, Self> { in downcast()
1666 /// Downcasts the box to a concrete type.
1677 /// let x: Box<dyn Any + Send> = Box::new(1_usize);
1692 pub unsafe fn downcast_unchecked<T: Any>(self) -> Box<T, A> { in downcast_unchecked()
1695 let (raw, alloc): (*mut (dyn Any + Send), _) = Box::into_raw_with_allocator(self); in downcast_unchecked()
1696 Box::from_raw_in(raw as *mut T, alloc) in downcast_unchecked()
1701 impl<A: Allocator> Box<dyn Any + Send + Sync, A> { impl
1702 /// Attempt to downcast the box to a concrete type.
1709 /// fn print_if_string(value: Box<dyn Any + Send + Sync>) {
1716 /// print_if_string(Box::new(my_string));
1717 /// print_if_string(Box::new(0i8));
1721 pub fn downcast<T: Any>(self) -> Result<Box<T, A>, Self> { in downcast()
1725 /// Downcasts the box to a concrete type.
1736 /// let x: Box<dyn Any + Send + Sync> = Box::new(1_usize);
1751 pub unsafe fn downcast_unchecked<T: Any>(self) -> Box<T, A> { in downcast_unchecked()
1755 Box::into_raw_with_allocator(self); in downcast_unchecked()
1756 Box::from_raw_in(raw as *mut T, alloc) in downcast_unchecked()
1762 impl<T: fmt::Display + ?Sized, A: Allocator> fmt::Display for Box<T, A> { implementation
1769 impl<T: fmt::Debug + ?Sized, A: Allocator> fmt::Debug for Box<T, A> { implementation
1776 impl<T: ?Sized, A: Allocator> fmt::Pointer for Box<T, A> { implementation
1778 // It's not possible to extract the inner Uniq directly from the Box, in fmt()
1787 impl<T: ?Sized, A: Allocator> const Deref for Box<T, A> { implementation
1797 impl<T: ?Sized, A: Allocator> const DerefMut for Box<T, A> { implementation
1804 impl<T: ?Sized, A: Allocator> Receiver for Box<T, A> {} implementation
1807 impl<I: Iterator + ?Sized, A: Allocator> Iterator for Box<I, A> { implementation
1828 impl<I: Iterator + ?Sized, A: Allocator> BoxIter for Box<I, A> { implementation
1843 impl<I: Iterator, A: Allocator> BoxIter for Box<I, A> { implementation
1850 impl<I: DoubleEndedIterator + ?Sized, A: Allocator> DoubleEndedIterator for Box<I, A> { implementation
1859 impl<I: ExactSizeIterator + ?Sized, A: Allocator> ExactSizeIterator for Box<I, A> { implementation
1869 impl<I: FusedIterator + ?Sized, A: Allocator> FusedIterator for Box<I, A> {} implementation
1872 impl<Args, F: FnOnce<Args> + ?Sized, A: Allocator> FnOnce<Args> for Box<F, A> { implementation
1881 impl<Args, F: FnMut<Args> + ?Sized, A: Allocator> FnMut<Args> for Box<F, A> { implementation
1888 impl<Args, F: Fn<Args> + ?Sized, A: Allocator> Fn<Args> for Box<F, A> { implementation
1895 impl<T: ?Sized + Unsize<U>, U: ?Sized, A: Allocator> CoerceUnsized<Box<U, A>> for Box<T, A> {} implementation
1898 impl<T: ?Sized + Unsize<U>, U: ?Sized> DispatchFromDyn<Box<U>> for Box<T, Global> {} implementation
1902 impl<I> FromIterator<I> for Box<[I]> { implementation
1910 impl<T: Clone, A: Allocator + Clone> Clone for Box<[T], A> { implementation
1912 let alloc = Box::allocator(self).clone(); in clone()
1926 impl<T: ?Sized, A: Allocator> borrow::Borrow<T> for Box<T, A> { implementation
1933 impl<T: ?Sized, A: Allocator> borrow::BorrowMut<T> for Box<T, A> { implementation
1940 impl<T: ?Sized, A: Allocator> AsRef<T> for Box<T, A> { implementation
1947 impl<T: ?Sized, A: Allocator> AsMut<T> for Box<T, A> { implementation
1956 * function of Pin<Box<T>> to Pin<T>. Such a function would not be sound,
1957 * because Box<T> implements Unpin even when T does not, as a result of
1964 * (Box<T> is the only pointer type in std for which this would be
1966 * - It is in practice very useful to have Box<T> be unconditionally
1968 * trait functionality does not apply (e.g., Box<dyn Foo> would
1971 * Another type with the same semantics as Box but only a conditional
1977 impl<T: ?Sized, A: Allocator> const Unpin for Box<T, A> where A: 'static {} implementation
1980 impl<G: ?Sized + Generator<R> + Unpin, R, A: Allocator> Generator<R> for Box<G, A> implementation
1993 impl<G: ?Sized + Generator<R>, R, A: Allocator> Generator<R> for Pin<Box<G, A>>
2006 impl<F: ?Sized + Future + Unpin, A: Allocator> Future for Box<F, A> implementation
2018 impl<S: ?Sized + AsyncIterator + Unpin> AsyncIterator for Box<S> { implementation