1//! The `Box<T>` type for heap allocation.
2//!
3//! [`Box<T>`], casually referred to as a 'box', provides the simplest form of
4//! heap allocation in Rust. Boxes provide ownership for this allocation, and
5//! drop their contents when they go out of scope. Boxes also ensure that they
6//! never allocate more than `isize::MAX` bytes.
7//!
8//! # Examples
9//!
10//! Move a value from the stack to the heap by creating a [`Box`]:
11//!
12//! ```
13//! let val: u8 = 5;
14//! let boxed: Box<u8> = Box::new(val);
15//! ```
16//!
17//! Move a value from a [`Box`] back to the stack by [dereferencing]:
18//!
19//! ```
20//! let boxed: Box<u8> = Box::new(5);
21//! let val: u8 = *boxed;
22//! ```
23//!
24//! Creating a recursive data structure:
25//!
26//! ```
27//! # #[allow(dead_code)]
28//! #[derive(Debug)]
29//! enum List<T> {
30//! Cons(T, Box<List<T>>),
31//! Nil,
32//! }
33//!
34//! let list: List<i32> = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Nil))));
35//! println!("{list:?}");
36//! ```
37//!
38//! This will print `Cons(1, Cons(2, Nil))`.
39//!
40//! Recursive structures must be boxed, because if the definition of `Cons`
41//! looked like this:
42//!
43//! ```compile_fail,E0072
44//! # enum List<T> {
45//! Cons(T, List<T>),
46//! # }
47//! ```
48//!
49//! It wouldn't work. This is because the size of a `List` depends on how many
50//! elements are in the list, and so we don't know how much memory to allocate
51//! for a `Cons`. By introducing a [`Box<T>`], which has a defined size, we know how
52//! big `Cons` needs to be.
53//!
54//! # Memory layout
55//!
56//! For non-zero-sized values, a [`Box`] will use the [`Global`] allocator for its allocation. It is
57//! valid to convert both ways between a [`Box`] and a raw pointer allocated with the [`Global`]
58//! allocator, given that the [`Layout`] used with the allocator is correct for the type and the raw
59//! pointer points to a valid value of the right type. More precisely, a `value: *mut T` that has
60//! been allocated with the [`Global`] allocator with `Layout::for_value(&*value)` may be converted
61//! into a box using [`Box::<T>::from_raw(value)`]. Conversely, the memory backing a `value: *mut T`
62//! obtained from [`Box::<T>::into_raw`] may be deallocated using the [`Global`] allocator with
63//! [`Layout::for_value(&*value)`].
64//!
65//! For zero-sized values, the `Box` pointer has to be non-null and sufficiently aligned. The
66//! recommended way to build a Box to a ZST if `Box::new` cannot be used is to use
67//! [`ptr::NonNull::dangling`].
68//!
69//! On top of these basic layout requirements, a `Box<T>` must point to a valid value of `T`.
70//!
71//! So long as `T: Sized`, a `Box<T>` is guaranteed to be represented
72//! as a single pointer and is also ABI-compatible with C pointers
73//! (i.e. the C type `T*`). This means that if you have extern "C"
74//! Rust functions that will be called from C, you can define those
75//! Rust functions using `Box<T>` types, and use `T*` as corresponding
76//! type on the C side. As an example, consider this C header which
77//! declares functions that create and destroy some kind of `Foo`
78//! value:
79//!
80//! ```c
81//! /* C header */
82//!
83//! /* Returns ownership to the caller */
84//! struct Foo* foo_new(void);
85//!
86//! /* Takes ownership from the caller; no-op when invoked with null */
87//! void foo_delete(struct Foo*);
88//! ```
89//!
90//! These two functions might be implemented in Rust as follows. Here, the
91//! `struct Foo*` type from C is translated to `Box<Foo>`, which captures
92//! the ownership constraints. Note also that the nullable argument to
93//! `foo_delete` is represented in Rust as `Option<Box<Foo>>`, since `Box<Foo>`
94//! cannot be null.
95//!
96//! ```
97//! #[repr(C)]
98//! pub struct Foo;
99//!
100//! #[unsafe(no_mangle)]
101//! pub extern "C" fn foo_new() -> Box<Foo> {
102//! Box::new(Foo)
103//! }
104//!
105//! #[unsafe(no_mangle)]
106//! pub extern "C" fn foo_delete(_: Option<Box<Foo>>) {}
107//! ```
108//!
109//! Even though `Box<T>` has the same representation and C ABI as a C pointer,
110//! this does not mean that you can convert an arbitrary `T*` into a `Box<T>`
111//! and expect things to work. `Box<T>` values will always be fully aligned,
112//! non-null pointers. Moreover, the destructor for `Box<T>` will attempt to
113//! free the value with the global allocator. In general, the best practice
114//! is to only use `Box<T>` for pointers that originated from the global
115//! allocator.
116//!
117//! **Important.** At least at present, you should avoid using
118//! `Box<T>` types for functions that are defined in C but invoked
119//! from Rust. In those cases, you should directly mirror the C types
120//! as closely as possible. Using types like `Box<T>` where the C
121//! definition is just using `T*` can lead to undefined behavior, as
122//! described in [rust-lang/unsafe-code-guidelines#198][ucg#198].
123//!
124//! # Considerations for unsafe code
125//!
126//! **Warning: This section is not normative and is subject to change, possibly
127//! being relaxed in the future! It is a simplified summary of the rules
128//! currently implemented in the compiler.**
129//!
130//! The aliasing rules for `Box<T>` are the same as for `&mut T`. `Box<T>`
131//! asserts uniqueness over its content. Using raw pointers derived from a box
132//! after that box has been mutated through, moved or borrowed as `&mut T`
133//! is not allowed. For more guidance on working with box from unsafe code, see
134//! [rust-lang/unsafe-code-guidelines#326][ucg#326].
135//!
136//! # Editions
137//!
138//! A special case exists for the implementation of `IntoIterator` for arrays on the Rust 2021
139//! edition, as documented [here][array]. Unfortunately, it was later found that a similar
140//! workaround should be added for boxed slices, and this was applied in the 2024 edition.
141//!
142//! Specifically, `IntoIterator` is implemented for `Box<[T]>` on all editions, but specific calls
143//! to `into_iter()` for boxed slices will defer to the slice implementation on editions before
144//! 2024:
145//!
146//! ```rust,edition2021
147//! // Rust 2015, 2018, and 2021:
148//!
149//! # #![allow(boxed_slice_into_iter)] // override our `deny(warnings)`
150//! let boxed_slice: Box<[i32]> = vec![0; 3].into_boxed_slice();
151//!
152//! // This creates a slice iterator, producing references to each value.
153//! for item in boxed_slice.into_iter().enumerate() {
154//! let (i, x): (usize, &i32) = item;
155//! println!("boxed_slice[{i}] = {x}");
156//! }
157//!
158//! // The `boxed_slice_into_iter` lint suggests this change for future compatibility:
159//! for item in boxed_slice.iter().enumerate() {
160//! let (i, x): (usize, &i32) = item;
161//! println!("boxed_slice[{i}] = {x}");
162//! }
163//!
164//! // You can explicitly iterate a boxed slice by value using `IntoIterator::into_iter`
165//! for item in IntoIterator::into_iter(boxed_slice).enumerate() {
166//! let (i, x): (usize, i32) = item;
167//! println!("boxed_slice[{i}] = {x}");
168//! }
169//! ```
170//!
171//! Similar to the array implementation, this may be modified in the future to remove this override,
172//! and it's best to avoid relying on this edition-dependent behavior if you wish to preserve
173//! compatibility with future versions of the compiler.
174//!
175//! [ucg#198]: https://github.com/rust-lang/unsafe-code-guidelines/issues/198
176//! [ucg#326]: https://github.com/rust-lang/unsafe-code-guidelines/issues/326
177//! [dereferencing]: core::ops::Deref
178//! [`Box::<T>::from_raw(value)`]: Box::from_raw
179//! [`Global`]: crate::alloc::Global
180//! [`Layout`]: crate::alloc::Layout
181//! [`Layout::for_value(&*value)`]: crate::alloc::Layout::for_value
182//! [valid]: ptr#safety
183
184#![stable(feature = "rust1", since = "1.0.0")]
185
186use core::borrow::{Borrow, BorrowMut};
187use core::clone::CloneToUninit;
188use core::cmp::Ordering;
189use core::error::{self, Error};
190use core::fmt;
191use core::future::Future;
192use core::hash::{Hash, Hasher};
193use core::marker::{Tuple, Unsize};
194#[cfg(not(no_global_oom_handling))]
195use core::mem::MaybeUninit;
196use core::mem::{self, SizedTypeProperties};
197use core::ops::{
198 AsyncFn, AsyncFnMut, AsyncFnOnce, CoerceUnsized, Coroutine, CoroutineState, Deref, DerefMut,
199 DerefPure, DispatchFromDyn, LegacyReceiver,
200};
201#[cfg(not(no_global_oom_handling))]
202use core::ops::{Residual, Try};
203use core::pin::{Pin, PinCoerceUnsized};
204use core::ptr::{self, NonNull, Unique};
205use core::task::{Context, Poll};
206
207#[cfg(not(no_global_oom_handling))]
208use crate::alloc::handle_alloc_error;
209use crate::alloc::{AllocError, Allocator, Global, Layout};
210use crate::raw_vec::RawVec;
211#[cfg(not(no_global_oom_handling))]
212use crate::str::from_boxed_utf8_unchecked;
213
214/// Conversion related impls for `Box<_>` (`From`, `downcast`, etc)
215mod convert;
216/// Iterator related impls for `Box<_>`.
217mod iter;
218/// [`ThinBox`] implementation.
219mod thin;
220
221#[unstable(feature = "thin_box", issue = "92791")]
222pub use thin::ThinBox;
223
224/// A pointer type that uniquely owns a heap allocation of type `T`.
225///
226/// See the [module-level documentation](../../std/boxed/index.html) for more.
227#[lang = "owned_box"]
228#[fundamental]
229#[stable(feature = "rust1", since = "1.0.0")]
230#[rustc_insignificant_dtor]
231#[doc(search_unbox)]
232// The declaration of the `Box` struct must be kept in sync with the
233// compiler or ICEs will happen.
234pub struct Box<
235 T: ?Sized,
236 #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global,
237>(Unique<T>, A);
238
239/// Constructs a `Box<T>` by calling the `exchange_malloc` lang item and moving the argument into
240/// the newly allocated memory. This is an intrinsic to avoid unnecessary copies.
241///
242/// This is the surface syntax for `box <expr>` expressions.
243#[doc(hidden)]
244#[rustc_intrinsic]
245#[unstable(feature = "liballoc_internals", issue = "none")]
246pub fn box_new<T>(x: T) -> Box<T>;
247
248impl<T> Box<T> {
249 /// Allocates memory on the heap and then places `x` into it.
250 ///
251 /// This doesn't actually allocate if `T` is zero-sized.
252 ///
253 /// # Examples
254 ///
255 /// ```
256 /// let five = Box::new(5);
257 /// ```
258 #[cfg(not(no_global_oom_handling))]
259 #[inline(always)]
260 #[stable(feature = "rust1", since = "1.0.0")]
261 #[must_use]
262 #[rustc_diagnostic_item = "box_new"]
263 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
264 pub fn new(x: T) -> Self {
265 return box_new(x);
266 }
267
268 /// Constructs a new box with uninitialized contents.
269 ///
270 /// # Examples
271 ///
272 /// ```
273 /// let mut five = Box::<u32>::new_uninit();
274 /// // Deferred initialization:
275 /// five.write(5);
276 /// let five = unsafe { five.assume_init() };
277 ///
278 /// assert_eq!(*five, 5)
279 /// ```
280 #[cfg(not(no_global_oom_handling))]
281 #[stable(feature = "new_uninit", since = "1.82.0")]
282 #[must_use]
283 #[inline]
284 pub fn new_uninit() -> Box<mem::MaybeUninit<T>> {
285 Self::new_uninit_in(Global)
286 }
287
288 /// Constructs a new `Box` with uninitialized contents, with the memory
289 /// being filled with `0` bytes.
290 ///
291 /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage
292 /// of this method.
293 ///
294 /// # Examples
295 ///
296 /// ```
297 /// let zero = Box::<u32>::new_zeroed();
298 /// let zero = unsafe { zero.assume_init() };
299 ///
300 /// assert_eq!(*zero, 0)
301 /// ```
302 ///
303 /// [zeroed]: mem::MaybeUninit::zeroed
304 #[cfg(not(no_global_oom_handling))]
305 #[inline]
306 #[stable(feature = "new_zeroed_alloc", since = "1.92.0")]
307 #[must_use]
308 pub fn new_zeroed() -> Box<mem::MaybeUninit<T>> {
309 Self::new_zeroed_in(Global)
310 }
311
312 /// Constructs a new `Pin<Box<T>>`. If `T` does not implement [`Unpin`], then
313 /// `x` will be pinned in memory and unable to be moved.
314 ///
315 /// Constructing and pinning of the `Box` can also be done in two steps: `Box::pin(x)`
316 /// does the same as <code>[Box::into_pin]\([Box::new]\(x))</code>. Consider using
317 /// [`into_pin`](Box::into_pin) if you already have a `Box<T>`, or if you want to
318 /// construct a (pinned) `Box` in a different way than with [`Box::new`].
319 #[cfg(not(no_global_oom_handling))]
320 #[stable(feature = "pin", since = "1.33.0")]
321 #[must_use]
322 #[inline(always)]
323 pub fn pin(x: T) -> Pin<Box<T>> {
324 Box::new(x).into()
325 }
326
327 /// Allocates memory on the heap then places `x` into it,
328 /// returning an error if the allocation fails
329 ///
330 /// This doesn't actually allocate if `T` is zero-sized.
331 ///
332 /// # Examples
333 ///
334 /// ```
335 /// #![feature(allocator_api)]
336 ///
337 /// let five = Box::try_new(5)?;
338 /// # Ok::<(), std::alloc::AllocError>(())
339 /// ```
340 #[unstable(feature = "allocator_api", issue = "32838")]
341 #[inline]
342 pub fn try_new(x: T) -> Result<Self, AllocError> {
343 Self::try_new_in(x, Global)
344 }
345
346 /// Constructs a new box with uninitialized contents on the heap,
347 /// returning an error if the allocation fails
348 ///
349 /// # Examples
350 ///
351 /// ```
352 /// #![feature(allocator_api)]
353 ///
354 /// let mut five = Box::<u32>::try_new_uninit()?;
355 /// // Deferred initialization:
356 /// five.write(5);
357 /// let five = unsafe { five.assume_init() };
358 ///
359 /// assert_eq!(*five, 5);
360 /// # Ok::<(), std::alloc::AllocError>(())
361 /// ```
362 #[unstable(feature = "allocator_api", issue = "32838")]
363 #[inline]
364 pub fn try_new_uninit() -> Result<Box<mem::MaybeUninit<T>>, AllocError> {
365 Box::try_new_uninit_in(Global)
366 }
367
368 /// Constructs a new `Box` with uninitialized contents, with the memory
369 /// being filled with `0` bytes on the heap
370 ///
371 /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage
372 /// of this method.
373 ///
374 /// # Examples
375 ///
376 /// ```
377 /// #![feature(allocator_api)]
378 ///
379 /// let zero = Box::<u32>::try_new_zeroed()?;
380 /// let zero = unsafe { zero.assume_init() };
381 ///
382 /// assert_eq!(*zero, 0);
383 /// # Ok::<(), std::alloc::AllocError>(())
384 /// ```
385 ///
386 /// [zeroed]: mem::MaybeUninit::zeroed
387 #[unstable(feature = "allocator_api", issue = "32838")]
388 #[inline]
389 pub fn try_new_zeroed() -> Result<Box<mem::MaybeUninit<T>>, AllocError> {
390 Box::try_new_zeroed_in(Global)
391 }
392
393 /// Maps the value in a box, reusing the allocation if possible.
394 ///
395 /// `f` is called on the value in the box, and the result is returned, also boxed.
396 ///
397 /// Note: this is an associated function, which means that you have
398 /// to call it as `Box::map(b, f)` instead of `b.map(f)`. This
399 /// is so that there is no conflict with a method on the inner type.
400 ///
401 /// # Examples
402 ///
403 /// ```
404 /// #![feature(smart_pointer_try_map)]
405 ///
406 /// let b = Box::new(7);
407 /// let new = Box::map(b, |i| i + 7);
408 /// assert_eq!(*new, 14);
409 /// ```
410 #[cfg(not(no_global_oom_handling))]
411 #[unstable(feature = "smart_pointer_try_map", issue = "144419")]
412 pub fn map<U>(this: Self, f: impl FnOnce(T) -> U) -> Box<U> {
413 if size_of::<T>() == size_of::<U>() && align_of::<T>() == align_of::<U>() {
414 let (value, allocation) = Box::take(this);
415 Box::write(
416 unsafe { mem::transmute::<Box<MaybeUninit<T>>, Box<MaybeUninit<U>>>(allocation) },
417 f(value),
418 )
419 } else {
420 Box::new(f(*this))
421 }
422 }
423
424 /// Attempts to map the value in a box, reusing the allocation if possible.
425 ///
426 /// `f` is called on the value in the box, and if the operation succeeds, the result is
427 /// returned, also boxed.
428 ///
429 /// Note: this is an associated function, which means that you have
430 /// to call it as `Box::try_map(b, f)` instead of `b.try_map(f)`. This
431 /// is so that there is no conflict with a method on the inner type.
432 ///
433 /// # Examples
434 ///
435 /// ```
436 /// #![feature(smart_pointer_try_map)]
437 ///
438 /// let b = Box::new(7);
439 /// let new = Box::try_map(b, u32::try_from).unwrap();
440 /// assert_eq!(*new, 7);
441 /// ```
442 #[cfg(not(no_global_oom_handling))]
443 #[unstable(feature = "smart_pointer_try_map", issue = "144419")]
444 pub fn try_map<R>(
445 this: Self,
446 f: impl FnOnce(T) -> R,
447 ) -> <R::Residual as Residual<Box<R::Output>>>::TryType
448 where
449 R: Try,
450 R::Residual: Residual<Box<R::Output>>,
451 {
452 if size_of::<T>() == size_of::<R::Output>() && align_of::<T>() == align_of::<R::Output>() {
453 let (value, allocation) = Box::take(this);
454 try {
455 Box::write(
456 unsafe {
457 mem::transmute::<Box<MaybeUninit<T>>, Box<MaybeUninit<R::Output>>>(
458 allocation,
459 )
460 },
461 f(value)?,
462 )
463 }
464 } else {
465 try { Box::new(f(*this)?) }
466 }
467 }
468}
469
470impl<T, A: Allocator> Box<T, A> {
471 /// Allocates memory in the given allocator then places `x` into it.
472 ///
473 /// This doesn't actually allocate if `T` is zero-sized.
474 ///
475 /// # Examples
476 ///
477 /// ```
478 /// #![feature(allocator_api)]
479 ///
480 /// use std::alloc::System;
481 ///
482 /// let five = Box::new_in(5, System);
483 /// ```
484 #[cfg(not(no_global_oom_handling))]
485 #[unstable(feature = "allocator_api", issue = "32838")]
486 #[must_use]
487 #[inline]
488 pub fn new_in(x: T, alloc: A) -> Self
489 where
490 A: Allocator,
491 {
492 let mut boxed = Self::new_uninit_in(alloc);
493 boxed.write(x);
494 unsafe { boxed.assume_init() }
495 }
496
497 /// Allocates memory in the given allocator then places `x` into it,
498 /// returning an error if the allocation fails
499 ///
500 /// This doesn't actually allocate if `T` is zero-sized.
501 ///
502 /// # Examples
503 ///
504 /// ```
505 /// #![feature(allocator_api)]
506 ///
507 /// use std::alloc::System;
508 ///
509 /// let five = Box::try_new_in(5, System)?;
510 /// # Ok::<(), std::alloc::AllocError>(())
511 /// ```
512 #[unstable(feature = "allocator_api", issue = "32838")]
513 #[inline]
514 pub fn try_new_in(x: T, alloc: A) -> Result<Self, AllocError>
515 where
516 A: Allocator,
517 {
518 let mut boxed = Self::try_new_uninit_in(alloc)?;
519 boxed.write(x);
520 unsafe { Ok(boxed.assume_init()) }
521 }
522
523 /// Constructs a new box with uninitialized contents in the provided allocator.
524 ///
525 /// # Examples
526 ///
527 /// ```
528 /// #![feature(allocator_api)]
529 ///
530 /// use std::alloc::System;
531 ///
532 /// let mut five = Box::<u32, _>::new_uninit_in(System);
533 /// // Deferred initialization:
534 /// five.write(5);
535 /// let five = unsafe { five.assume_init() };
536 ///
537 /// assert_eq!(*five, 5)
538 /// ```
539 #[unstable(feature = "allocator_api", issue = "32838")]
540 #[cfg(not(no_global_oom_handling))]
541 #[must_use]
542 pub fn new_uninit_in(alloc: A) -> Box<mem::MaybeUninit<T>, A>
543 where
544 A: Allocator,
545 {
546 let layout = Layout::new::<mem::MaybeUninit<T>>();
547 // NOTE: Prefer match over unwrap_or_else since closure sometimes not inlineable.
548 // That would make code size bigger.
549 match Box::try_new_uninit_in(alloc) {
550 Ok(m) => m,
551 Err(_) => handle_alloc_error(layout),
552 }
553 }
554
555 /// Constructs a new box with uninitialized contents in the provided allocator,
556 /// returning an error if the allocation fails
557 ///
558 /// # Examples
559 ///
560 /// ```
561 /// #![feature(allocator_api)]
562 ///
563 /// use std::alloc::System;
564 ///
565 /// let mut five = Box::<u32, _>::try_new_uninit_in(System)?;
566 /// // Deferred initialization:
567 /// five.write(5);
568 /// let five = unsafe { five.assume_init() };
569 ///
570 /// assert_eq!(*five, 5);
571 /// # Ok::<(), std::alloc::AllocError>(())
572 /// ```
573 #[unstable(feature = "allocator_api", issue = "32838")]
574 pub fn try_new_uninit_in(alloc: A) -> Result<Box<mem::MaybeUninit<T>, A>, AllocError>
575 where
576 A: Allocator,
577 {
578 let ptr = if T::IS_ZST {
579 NonNull::dangling()
580 } else {
581 let layout = Layout::new::<mem::MaybeUninit<T>>();
582 alloc.allocate(layout)?.cast()
583 };
584 unsafe { Ok(Box::from_raw_in(ptr.as_ptr(), alloc)) }
585 }
586
587 /// Constructs a new `Box` with uninitialized contents, with the memory
588 /// being filled with `0` bytes in the provided allocator.
589 ///
590 /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage
591 /// of this method.
592 ///
593 /// # Examples
594 ///
595 /// ```
596 /// #![feature(allocator_api)]
597 ///
598 /// use std::alloc::System;
599 ///
600 /// let zero = Box::<u32, _>::new_zeroed_in(System);
601 /// let zero = unsafe { zero.assume_init() };
602 ///
603 /// assert_eq!(*zero, 0)
604 /// ```
605 ///
606 /// [zeroed]: mem::MaybeUninit::zeroed
607 #[unstable(feature = "allocator_api", issue = "32838")]
608 #[cfg(not(no_global_oom_handling))]
609 #[must_use]
610 pub fn new_zeroed_in(alloc: A) -> Box<mem::MaybeUninit<T>, A>
611 where
612 A: Allocator,
613 {
614 let layout = Layout::new::<mem::MaybeUninit<T>>();
615 // NOTE: Prefer match over unwrap_or_else since closure sometimes not inlineable.
616 // That would make code size bigger.
617 match Box::try_new_zeroed_in(alloc) {
618 Ok(m) => m,
619 Err(_) => handle_alloc_error(layout),
620 }
621 }
622
623 /// Constructs a new `Box` with uninitialized contents, with the memory
624 /// being filled with `0` bytes in the provided allocator,
625 /// returning an error if the allocation fails,
626 ///
627 /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage
628 /// of this method.
629 ///
630 /// # Examples
631 ///
632 /// ```
633 /// #![feature(allocator_api)]
634 ///
635 /// use std::alloc::System;
636 ///
637 /// let zero = Box::<u32, _>::try_new_zeroed_in(System)?;
638 /// let zero = unsafe { zero.assume_init() };
639 ///
640 /// assert_eq!(*zero, 0);
641 /// # Ok::<(), std::alloc::AllocError>(())
642 /// ```
643 ///
644 /// [zeroed]: mem::MaybeUninit::zeroed
645 #[unstable(feature = "allocator_api", issue = "32838")]
646 pub fn try_new_zeroed_in(alloc: A) -> Result<Box<mem::MaybeUninit<T>, A>, AllocError>
647 where
648 A: Allocator,
649 {
650 let ptr = if T::IS_ZST {
651 NonNull::dangling()
652 } else {
653 let layout = Layout::new::<mem::MaybeUninit<T>>();
654 alloc.allocate_zeroed(layout)?.cast()
655 };
656 unsafe { Ok(Box::from_raw_in(ptr.as_ptr(), alloc)) }
657 }
658
659 /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then
660 /// `x` will be pinned in memory and unable to be moved.
661 ///
662 /// Constructing and pinning of the `Box` can also be done in two steps: `Box::pin_in(x, alloc)`
663 /// does the same as <code>[Box::into_pin]\([Box::new_in]\(x, alloc))</code>. Consider using
664 /// [`into_pin`](Box::into_pin) if you already have a `Box<T, A>`, or if you want to
665 /// construct a (pinned) `Box` in a different way than with [`Box::new_in`].
666 #[cfg(not(no_global_oom_handling))]
667 #[unstable(feature = "allocator_api", issue = "32838")]
668 #[must_use]
669 #[inline(always)]
670 pub fn pin_in(x: T, alloc: A) -> Pin<Self>
671 where
672 A: 'static + Allocator,
673 {
674 Self::into_pin(Self::new_in(x, alloc))
675 }
676
677 /// Converts a `Box<T>` into a `Box<[T]>`
678 ///
679 /// This conversion does not allocate on the heap and happens in place.
680 #[unstable(feature = "box_into_boxed_slice", issue = "71582")]
681 pub fn into_boxed_slice(boxed: Self) -> Box<[T], A> {
682 let (raw, alloc) = Box::into_raw_with_allocator(boxed);
683 unsafe { Box::from_raw_in(raw as *mut [T; 1], alloc) }
684 }
685
686 /// Consumes the `Box`, returning the wrapped value.
687 ///
688 /// # Examples
689 ///
690 /// ```
691 /// #![feature(box_into_inner)]
692 ///
693 /// let c = Box::new(5);
694 ///
695 /// assert_eq!(Box::into_inner(c), 5);
696 /// ```
697 #[unstable(feature = "box_into_inner", issue = "80437")]
698 #[inline]
699 pub fn into_inner(boxed: Self) -> T {
700 *boxed
701 }
702
703 /// Consumes the `Box` without consuming its allocation, returning the wrapped value and a `Box`
704 /// to the uninitialized memory where the wrapped value used to live.
705 ///
706 /// This can be used together with [`write`](Box::write) to reuse the allocation for multiple
707 /// boxed values.
708 ///
709 /// # Examples
710 ///
711 /// ```
712 /// #![feature(box_take)]
713 ///
714 /// let c = Box::new(5);
715 ///
716 /// // take the value out of the box
717 /// let (value, uninit) = Box::take(c);
718 /// assert_eq!(value, 5);
719 ///
720 /// // reuse the box for a second value
721 /// let c = Box::write(uninit, 6);
722 /// assert_eq!(*c, 6);
723 /// ```
724 #[unstable(feature = "box_take", issue = "147212")]
725 pub fn take(boxed: Self) -> (T, Box<mem::MaybeUninit<T>, A>) {
726 unsafe {
727 let (raw, alloc) = Box::into_non_null_with_allocator(boxed);
728 let value = raw.read();
729 let uninit = Box::from_non_null_in(raw.cast_uninit(), alloc);
730 (value, uninit)
731 }
732 }
733}
734
735impl<T: ?Sized + CloneToUninit> Box<T> {
736 /// Allocates memory on the heap then clones `src` into it.
737 ///
738 /// This doesn't actually allocate if `src` is zero-sized.
739 ///
740 /// # Examples
741 ///
742 /// ```
743 /// #![feature(clone_from_ref)]
744 ///
745 /// let hello: Box<str> = Box::clone_from_ref("hello");
746 /// ```
747 #[cfg(not(no_global_oom_handling))]
748 #[unstable(feature = "clone_from_ref", issue = "149075")]
749 #[must_use]
750 #[inline]
751 pub fn clone_from_ref(src: &T) -> Box<T> {
752 Box::clone_from_ref_in(src, Global)
753 }
754
755 /// Allocates memory on the heap then clones `src` into it, returning an error if allocation fails.
756 ///
757 /// This doesn't actually allocate if `src` is zero-sized.
758 ///
759 /// # Examples
760 ///
761 /// ```
762 /// #![feature(clone_from_ref)]
763 /// #![feature(allocator_api)]
764 ///
765 /// let hello: Box<str> = Box::try_clone_from_ref("hello")?;
766 /// # Ok::<(), std::alloc::AllocError>(())
767 /// ```
768 #[unstable(feature = "clone_from_ref", issue = "149075")]
769 //#[unstable(feature = "allocator_api", issue = "32838")]
770 #[must_use]
771 #[inline]
772 pub fn try_clone_from_ref(src: &T) -> Result<Box<T>, AllocError> {
773 Box::try_clone_from_ref_in(src, Global)
774 }
775}
776
777impl<T: ?Sized + CloneToUninit, A: Allocator> Box<T, A> {
778 /// Allocates memory in the given allocator then clones `src` into it.
779 ///
780 /// This doesn't actually allocate if `src` is zero-sized.
781 ///
782 /// # Examples
783 ///
784 /// ```
785 /// #![feature(clone_from_ref)]
786 /// #![feature(allocator_api)]
787 ///
788 /// use std::alloc::System;
789 ///
790 /// let hello: Box<str, System> = Box::clone_from_ref_in("hello", System);
791 /// ```
792 #[cfg(not(no_global_oom_handling))]
793 #[unstable(feature = "clone_from_ref", issue = "149075")]
794 //#[unstable(feature = "allocator_api", issue = "32838")]
795 #[must_use]
796 #[inline]
797 pub fn clone_from_ref_in(src: &T, alloc: A) -> Box<T, A> {
798 let layout = Layout::for_value::<T>(src);
799 match Box::try_clone_from_ref_in(src, alloc) {
800 Ok(bx) => bx,
801 Err(_) => handle_alloc_error(layout),
802 }
803 }
804
805 /// Allocates memory in the given allocator then clones `src` into it, returning an error if allocation fails.
806 ///
807 /// This doesn't actually allocate if `src` is zero-sized.
808 ///
809 /// # Examples
810 ///
811 /// ```
812 /// #![feature(clone_from_ref)]
813 /// #![feature(allocator_api)]
814 ///
815 /// use std::alloc::System;
816 ///
817 /// let hello: Box<str, System> = Box::try_clone_from_ref_in("hello", System)?;
818 /// # Ok::<(), std::alloc::AllocError>(())
819 /// ```
820 #[unstable(feature = "clone_from_ref", issue = "149075")]
821 //#[unstable(feature = "allocator_api", issue = "32838")]
822 #[must_use]
823 #[inline]
824 pub fn try_clone_from_ref_in(src: &T, alloc: A) -> Result<Box<T, A>, AllocError> {
825 struct DeallocDropGuard<'a, A: Allocator>(Layout, &'a A, NonNull<u8>);
826 impl<'a, A: Allocator> Drop for DeallocDropGuard<'a, A> {
827 fn drop(&mut self) {
828 let &mut DeallocDropGuard(layout, alloc, ptr) = self;
829 // Safety: `ptr` was allocated by `*alloc` with layout `layout`
830 unsafe {
831 alloc.deallocate(ptr, layout);
832 }
833 }
834 }
835 let layout = Layout::for_value::<T>(src);
836 let (ptr, guard) = if layout.size() == 0 {
837 (layout.dangling_ptr(), None)
838 } else {
839 // Safety: layout is non-zero-sized
840 let ptr = alloc.allocate(layout)?.cast();
841 (ptr, Some(DeallocDropGuard(layout, &alloc, ptr)))
842 };
843 let ptr = ptr.as_ptr();
844 // Safety: `*ptr` is newly allocated, correctly aligned to `align_of_val(src)`,
845 // and is valid for writes for `size_of_val(src)`.
846 // If this panics, then `guard` will deallocate for us (if allocation occuured)
847 unsafe {
848 <T as CloneToUninit>::clone_to_uninit(src, ptr);
849 }
850 // Defuse the deallocate guard
851 core::mem::forget(guard);
852 // Safety: We just initialized `*ptr` as a clone of `src`
853 Ok(unsafe { Box::from_raw_in(ptr.with_metadata_of(src), alloc) })
854 }
855}
856
857impl<T> Box<[T]> {
858 /// Constructs a new boxed slice with uninitialized contents.
859 ///
860 /// # Examples
861 ///
862 /// ```
863 /// let mut values = Box::<[u32]>::new_uninit_slice(3);
864 /// // Deferred initialization:
865 /// values[0].write(1);
866 /// values[1].write(2);
867 /// values[2].write(3);
868 /// let values = unsafe { values.assume_init() };
869 ///
870 /// assert_eq!(*values, [1, 2, 3])
871 /// ```
872 #[cfg(not(no_global_oom_handling))]
873 #[stable(feature = "new_uninit", since = "1.82.0")]
874 #[must_use]
875 pub fn new_uninit_slice(len: usize) -> Box<[mem::MaybeUninit<T>]> {
876 unsafe { RawVec::with_capacity(len).into_box(len) }
877 }
878
879 /// Constructs a new boxed slice with uninitialized contents, with the memory
880 /// being filled with `0` bytes.
881 ///
882 /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage
883 /// of this method.
884 ///
885 /// # Examples
886 ///
887 /// ```
888 /// let values = Box::<[u32]>::new_zeroed_slice(3);
889 /// let values = unsafe { values.assume_init() };
890 ///
891 /// assert_eq!(*values, [0, 0, 0])
892 /// ```
893 ///
894 /// [zeroed]: mem::MaybeUninit::zeroed
895 #[cfg(not(no_global_oom_handling))]
896 #[stable(feature = "new_zeroed_alloc", since = "1.92.0")]
897 #[must_use]
898 pub fn new_zeroed_slice(len: usize) -> Box<[mem::MaybeUninit<T>]> {
899 unsafe { RawVec::with_capacity_zeroed(len).into_box(len) }
900 }
901
902 /// Constructs a new boxed slice with uninitialized contents. Returns an error if
903 /// the allocation fails.
904 ///
905 /// # Examples
906 ///
907 /// ```
908 /// #![feature(allocator_api)]
909 ///
910 /// let mut values = Box::<[u32]>::try_new_uninit_slice(3)?;
911 /// // Deferred initialization:
912 /// values[0].write(1);
913 /// values[1].write(2);
914 /// values[2].write(3);
915 /// let values = unsafe { values.assume_init() };
916 ///
917 /// assert_eq!(*values, [1, 2, 3]);
918 /// # Ok::<(), std::alloc::AllocError>(())
919 /// ```
920 #[unstable(feature = "allocator_api", issue = "32838")]
921 #[inline]
922 pub fn try_new_uninit_slice(len: usize) -> Result<Box<[mem::MaybeUninit<T>]>, AllocError> {
923 let ptr = if T::IS_ZST || len == 0 {
924 NonNull::dangling()
925 } else {
926 let layout = match Layout::array::<mem::MaybeUninit<T>>(len) {
927 Ok(l) => l,
928 Err(_) => return Err(AllocError),
929 };
930 Global.allocate(layout)?.cast()
931 };
932 unsafe { Ok(RawVec::from_raw_parts_in(ptr.as_ptr(), len, Global).into_box(len)) }
933 }
934
935 /// Constructs a new boxed slice with uninitialized contents, with the memory
936 /// being filled with `0` bytes. Returns an error if the allocation fails.
937 ///
938 /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage
939 /// of this method.
940 ///
941 /// # Examples
942 ///
943 /// ```
944 /// #![feature(allocator_api)]
945 ///
946 /// let values = Box::<[u32]>::try_new_zeroed_slice(3)?;
947 /// let values = unsafe { values.assume_init() };
948 ///
949 /// assert_eq!(*values, [0, 0, 0]);
950 /// # Ok::<(), std::alloc::AllocError>(())
951 /// ```
952 ///
953 /// [zeroed]: mem::MaybeUninit::zeroed
954 #[unstable(feature = "allocator_api", issue = "32838")]
955 #[inline]
956 pub fn try_new_zeroed_slice(len: usize) -> Result<Box<[mem::MaybeUninit<T>]>, AllocError> {
957 let ptr = if T::IS_ZST || len == 0 {
958 NonNull::dangling()
959 } else {
960 let layout = match Layout::array::<mem::MaybeUninit<T>>(len) {
961 Ok(l) => l,
962 Err(_) => return Err(AllocError),
963 };
964 Global.allocate_zeroed(layout)?.cast()
965 };
966 unsafe { Ok(RawVec::from_raw_parts_in(ptr.as_ptr(), len, Global).into_box(len)) }
967 }
968
969 /// Converts the boxed slice into a boxed array.
970 ///
971 /// This operation does not reallocate; the underlying array of the slice is simply reinterpreted as an array type.
972 ///
973 /// If `N` is not exactly equal to the length of `self`, then this method returns `None`.
974 #[unstable(feature = "alloc_slice_into_array", issue = "148082")]
975 #[inline]
976 #[must_use]
977 pub fn into_array<const N: usize>(self) -> Option<Box<[T; N]>> {
978 if self.len() == N {
979 let ptr = Self::into_raw(self) as *mut [T; N];
980
981 // SAFETY: The underlying array of a slice has the exact same layout as an actual array `[T; N]` if `N` is equal to the slice's length.
982 let me = unsafe { Box::from_raw(ptr) };
983 Some(me)
984 } else {
985 None
986 }
987 }
988}
989
990impl<T, A: Allocator> Box<[T], A> {
991 /// Constructs a new boxed slice with uninitialized contents in the provided allocator.
992 ///
993 /// # Examples
994 ///
995 /// ```
996 /// #![feature(allocator_api)]
997 ///
998 /// use std::alloc::System;
999 ///
1000 /// let mut values = Box::<[u32], _>::new_uninit_slice_in(3, System);
1001 /// // Deferred initialization:
1002 /// values[0].write(1);
1003 /// values[1].write(2);
1004 /// values[2].write(3);
1005 /// let values = unsafe { values.assume_init() };
1006 ///
1007 /// assert_eq!(*values, [1, 2, 3])
1008 /// ```
1009 #[cfg(not(no_global_oom_handling))]
1010 #[unstable(feature = "allocator_api", issue = "32838")]
1011 #[must_use]
1012 pub fn new_uninit_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit<T>], A> {
1013 unsafe { RawVec::with_capacity_in(len, alloc).into_box(len) }
1014 }
1015
1016 /// Constructs a new boxed slice with uninitialized contents in the provided allocator,
1017 /// with the memory being filled with `0` bytes.
1018 ///
1019 /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage
1020 /// of this method.
1021 ///
1022 /// # Examples
1023 ///
1024 /// ```
1025 /// #![feature(allocator_api)]
1026 ///
1027 /// use std::alloc::System;
1028 ///
1029 /// let values = Box::<[u32], _>::new_zeroed_slice_in(3, System);
1030 /// let values = unsafe { values.assume_init() };
1031 ///
1032 /// assert_eq!(*values, [0, 0, 0])
1033 /// ```
1034 ///
1035 /// [zeroed]: mem::MaybeUninit::zeroed
1036 #[cfg(not(no_global_oom_handling))]
1037 #[unstable(feature = "allocator_api", issue = "32838")]
1038 #[must_use]
1039 pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit<T>], A> {
1040 unsafe { RawVec::with_capacity_zeroed_in(len, alloc).into_box(len) }
1041 }
1042
1043 /// Constructs a new boxed slice with uninitialized contents in the provided allocator. Returns an error if
1044 /// the allocation fails.
1045 ///
1046 /// # Examples
1047 ///
1048 /// ```
1049 /// #![feature(allocator_api)]
1050 ///
1051 /// use std::alloc::System;
1052 ///
1053 /// let mut values = Box::<[u32], _>::try_new_uninit_slice_in(3, System)?;
1054 /// // Deferred initialization:
1055 /// values[0].write(1);
1056 /// values[1].write(2);
1057 /// values[2].write(3);
1058 /// let values = unsafe { values.assume_init() };
1059 ///
1060 /// assert_eq!(*values, [1, 2, 3]);
1061 /// # Ok::<(), std::alloc::AllocError>(())
1062 /// ```
1063 #[unstable(feature = "allocator_api", issue = "32838")]
1064 #[inline]
1065 pub fn try_new_uninit_slice_in(
1066 len: usize,
1067 alloc: A,
1068 ) -> Result<Box<[mem::MaybeUninit<T>], A>, AllocError> {
1069 let ptr = if T::IS_ZST || len == 0 {
1070 NonNull::dangling()
1071 } else {
1072 let layout = match Layout::array::<mem::MaybeUninit<T>>(len) {
1073 Ok(l) => l,
1074 Err(_) => return Err(AllocError),
1075 };
1076 alloc.allocate(layout)?.cast()
1077 };
1078 unsafe { Ok(RawVec::from_raw_parts_in(ptr.as_ptr(), len, alloc).into_box(len)) }
1079 }
1080
1081 /// Constructs a new boxed slice with uninitialized contents in the provided allocator, with the memory
1082 /// being filled with `0` bytes. Returns an error if the allocation fails.
1083 ///
1084 /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage
1085 /// of this method.
1086 ///
1087 /// # Examples
1088 ///
1089 /// ```
1090 /// #![feature(allocator_api)]
1091 ///
1092 /// use std::alloc::System;
1093 ///
1094 /// let values = Box::<[u32], _>::try_new_zeroed_slice_in(3, System)?;
1095 /// let values = unsafe { values.assume_init() };
1096 ///
1097 /// assert_eq!(*values, [0, 0, 0]);
1098 /// # Ok::<(), std::alloc::AllocError>(())
1099 /// ```
1100 ///
1101 /// [zeroed]: mem::MaybeUninit::zeroed
1102 #[unstable(feature = "allocator_api", issue = "32838")]
1103 #[inline]
1104 pub fn try_new_zeroed_slice_in(
1105 len: usize,
1106 alloc: A,
1107 ) -> Result<Box<[mem::MaybeUninit<T>], A>, AllocError> {
1108 let ptr = if T::IS_ZST || len == 0 {
1109 NonNull::dangling()
1110 } else {
1111 let layout = match Layout::array::<mem::MaybeUninit<T>>(len) {
1112 Ok(l) => l,
1113 Err(_) => return Err(AllocError),
1114 };
1115 alloc.allocate_zeroed(layout)?.cast()
1116 };
1117 unsafe { Ok(RawVec::from_raw_parts_in(ptr.as_ptr(), len, alloc).into_box(len)) }
1118 }
1119}
1120
1121impl<T, A: Allocator> Box<mem::MaybeUninit<T>, A> {
1122 /// Converts to `Box<T, A>`.
1123 ///
1124 /// # Safety
1125 ///
1126 /// As with [`MaybeUninit::assume_init`],
1127 /// it is up to the caller to guarantee that the value
1128 /// really is in an initialized state.
1129 /// Calling this when the content is not yet fully initialized
1130 /// causes immediate undefined behavior.
1131 ///
1132 /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init
1133 ///
1134 /// # Examples
1135 ///
1136 /// ```
1137 /// let mut five = Box::<u32>::new_uninit();
1138 /// // Deferred initialization:
1139 /// five.write(5);
1140 /// let five: Box<u32> = unsafe { five.assume_init() };
1141 ///
1142 /// assert_eq!(*five, 5)
1143 /// ```
1144 #[stable(feature = "new_uninit", since = "1.82.0")]
1145 #[inline]
1146 pub unsafe fn assume_init(self) -> Box<T, A> {
1147 let (raw, alloc) = Box::into_raw_with_allocator(self);
1148 unsafe { Box::from_raw_in(raw as *mut T, alloc) }
1149 }
1150
1151 /// Writes the value and converts to `Box<T, A>`.
1152 ///
1153 /// This method converts the box similarly to [`Box::assume_init`] but
1154 /// writes `value` into it before conversion thus guaranteeing safety.
1155 /// In some scenarios use of this method may improve performance because
1156 /// the compiler may be able to optimize copying from stack.
1157 ///
1158 /// # Examples
1159 ///
1160 /// ```
1161 /// let big_box = Box::<[usize; 1024]>::new_uninit();
1162 ///
1163 /// let mut array = [0; 1024];
1164 /// for (i, place) in array.iter_mut().enumerate() {
1165 /// *place = i;
1166 /// }
1167 ///
1168 /// // The optimizer may be able to elide this copy, so previous code writes
1169 /// // to heap directly.
1170 /// let big_box = Box::write(big_box, array);
1171 ///
1172 /// for (i, x) in big_box.iter().enumerate() {
1173 /// assert_eq!(*x, i);
1174 /// }
1175 /// ```
1176 #[stable(feature = "box_uninit_write", since = "1.87.0")]
1177 #[inline]
1178 pub fn write(mut boxed: Self, value: T) -> Box<T, A> {
1179 unsafe {
1180 (*boxed).write(value);
1181 boxed.assume_init()
1182 }
1183 }
1184}
1185
1186impl<T, A: Allocator> Box<[mem::MaybeUninit<T>], A> {
1187 /// Converts to `Box<[T], A>`.
1188 ///
1189 /// # Safety
1190 ///
1191 /// As with [`MaybeUninit::assume_init`],
1192 /// it is up to the caller to guarantee that the values
1193 /// really are in an initialized state.
1194 /// Calling this when the content is not yet fully initialized
1195 /// causes immediate undefined behavior.
1196 ///
1197 /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init
1198 ///
1199 /// # Examples
1200 ///
1201 /// ```
1202 /// let mut values = Box::<[u32]>::new_uninit_slice(3);
1203 /// // Deferred initialization:
1204 /// values[0].write(1);
1205 /// values[1].write(2);
1206 /// values[2].write(3);
1207 /// let values = unsafe { values.assume_init() };
1208 ///
1209 /// assert_eq!(*values, [1, 2, 3])
1210 /// ```
1211 #[stable(feature = "new_uninit", since = "1.82.0")]
1212 #[inline]
1213 pub unsafe fn assume_init(self) -> Box<[T], A> {
1214 let (raw, alloc) = Box::into_raw_with_allocator(self);
1215 unsafe { Box::from_raw_in(raw as *mut [T], alloc) }
1216 }
1217}
1218
1219impl<T: ?Sized> Box<T> {
1220 /// Constructs a box from a raw pointer.
1221 ///
1222 /// After calling this function, the raw pointer is owned by the
1223 /// resulting `Box`. Specifically, the `Box` destructor will call
1224 /// the destructor of `T` and free the allocated memory. For this
1225 /// to be safe, the memory must have been allocated in accordance
1226 /// with the [memory layout] used by `Box` .
1227 ///
1228 /// # Safety
1229 ///
1230 /// This function is unsafe because improper use may lead to
1231 /// memory problems. For example, a double-free may occur if the
1232 /// function is called twice on the same raw pointer.
1233 ///
1234 /// The raw pointer must point to a block of memory allocated by the global allocator.
1235 ///
1236 /// The safety conditions are described in the [memory layout] section.
1237 ///
1238 /// # Examples
1239 ///
1240 /// Recreate a `Box` which was previously converted to a raw pointer
1241 /// using [`Box::into_raw`]:
1242 /// ```
1243 /// let x = Box::new(5);
1244 /// let ptr = Box::into_raw(x);
1245 /// let x = unsafe { Box::from_raw(ptr) };
1246 /// ```
1247 /// Manually create a `Box` from scratch by using the global allocator:
1248 /// ```
1249 /// use std::alloc::{alloc, Layout};
1250 ///
1251 /// unsafe {
1252 /// let ptr = alloc(Layout::new::<i32>()) as *mut i32;
1253 /// // In general .write is required to avoid attempting to destruct
1254 /// // the (uninitialized) previous contents of `ptr`, though for this
1255 /// // simple example `*ptr = 5` would have worked as well.
1256 /// ptr.write(5);
1257 /// let x = Box::from_raw(ptr);
1258 /// }
1259 /// ```
1260 ///
1261 /// [memory layout]: self#memory-layout
1262 #[stable(feature = "box_raw", since = "1.4.0")]
1263 #[inline]
1264 #[must_use = "call `drop(Box::from_raw(ptr))` if you intend to drop the `Box`"]
1265 pub unsafe fn from_raw(raw: *mut T) -> Self {
1266 unsafe { Self::from_raw_in(raw, Global) }
1267 }
1268
1269 /// Constructs a box from a `NonNull` pointer.
1270 ///
1271 /// After calling this function, the `NonNull` pointer is owned by
1272 /// the resulting `Box`. Specifically, the `Box` destructor will call
1273 /// the destructor of `T` and free the allocated memory. For this
1274 /// to be safe, the memory must have been allocated in accordance
1275 /// with the [memory layout] used by `Box` .
1276 ///
1277 /// # Safety
1278 ///
1279 /// This function is unsafe because improper use may lead to
1280 /// memory problems. For example, a double-free may occur if the
1281 /// function is called twice on the same `NonNull` pointer.
1282 ///
1283 /// The non-null pointer must point to a block of memory allocated by the global allocator.
1284 ///
1285 /// The safety conditions are described in the [memory layout] section.
1286 ///
1287 /// # Examples
1288 ///
1289 /// Recreate a `Box` which was previously converted to a `NonNull`
1290 /// pointer using [`Box::into_non_null`]:
1291 /// ```
1292 /// #![feature(box_vec_non_null)]
1293 ///
1294 /// let x = Box::new(5);
1295 /// let non_null = Box::into_non_null(x);
1296 /// let x = unsafe { Box::from_non_null(non_null) };
1297 /// ```
1298 /// Manually create a `Box` from scratch by using the global allocator:
1299 /// ```
1300 /// #![feature(box_vec_non_null)]
1301 ///
1302 /// use std::alloc::{alloc, Layout};
1303 /// use std::ptr::NonNull;
1304 ///
1305 /// unsafe {
1306 /// let non_null = NonNull::new(alloc(Layout::new::<i32>()).cast::<i32>())
1307 /// .expect("allocation failed");
1308 /// // In general .write is required to avoid attempting to destruct
1309 /// // the (uninitialized) previous contents of `non_null`.
1310 /// non_null.write(5);
1311 /// let x = Box::from_non_null(non_null);
1312 /// }
1313 /// ```
1314 ///
1315 /// [memory layout]: self#memory-layout
1316 #[unstable(feature = "box_vec_non_null", issue = "130364")]
1317 #[inline]
1318 #[must_use = "call `drop(Box::from_non_null(ptr))` if you intend to drop the `Box`"]
1319 pub unsafe fn from_non_null(ptr: NonNull<T>) -> Self {
1320 unsafe { Self::from_raw(ptr.as_ptr()) }
1321 }
1322
1323 /// Consumes the `Box`, returning a wrapped raw pointer.
1324 ///
1325 /// The pointer will be properly aligned and non-null.
1326 ///
1327 /// After calling this function, the caller is responsible for the
1328 /// memory previously managed by the `Box`. In particular, the
1329 /// caller should properly destroy `T` and release the memory, taking
1330 /// into account the [memory layout] used by `Box`. The easiest way to
1331 /// do this is to convert the raw pointer back into a `Box` with the
1332 /// [`Box::from_raw`] function, allowing the `Box` destructor to perform
1333 /// the cleanup.
1334 ///
1335 /// Note: this is an associated function, which means that you have
1336 /// to call it as `Box::into_raw(b)` instead of `b.into_raw()`. This
1337 /// is so that there is no conflict with a method on the inner type.
1338 ///
1339 /// # Examples
1340 /// Converting the raw pointer back into a `Box` with [`Box::from_raw`]
1341 /// for automatic cleanup:
1342 /// ```
1343 /// let x = Box::new(String::from("Hello"));
1344 /// let ptr = Box::into_raw(x);
1345 /// let x = unsafe { Box::from_raw(ptr) };
1346 /// ```
1347 /// Manual cleanup by explicitly running the destructor and deallocating
1348 /// the memory:
1349 /// ```
1350 /// use std::alloc::{dealloc, Layout};
1351 /// use std::ptr;
1352 ///
1353 /// let x = Box::new(String::from("Hello"));
1354 /// let ptr = Box::into_raw(x);
1355 /// unsafe {
1356 /// ptr::drop_in_place(ptr);
1357 /// dealloc(ptr as *mut u8, Layout::new::<String>());
1358 /// }
1359 /// ```
1360 /// Note: This is equivalent to the following:
1361 /// ```
1362 /// let x = Box::new(String::from("Hello"));
1363 /// let ptr = Box::into_raw(x);
1364 /// unsafe {
1365 /// drop(Box::from_raw(ptr));
1366 /// }
1367 /// ```
1368 ///
1369 /// [memory layout]: self#memory-layout
1370 #[must_use = "losing the pointer will leak memory"]
1371 #[stable(feature = "box_raw", since = "1.4.0")]
1372 #[inline]
1373 pub fn into_raw(b: Self) -> *mut T {
1374 // Avoid `into_raw_with_allocator` as that interacts poorly with Miri's Stacked Borrows.
1375 let mut b = mem::ManuallyDrop::new(b);
1376 // We go through the built-in deref for `Box`, which is crucial for Miri to recognize this
1377 // operation for it's alias tracking.
1378 &raw mut **b
1379 }
1380
1381 /// Consumes the `Box`, returning a wrapped `NonNull` pointer.
1382 ///
1383 /// The pointer will be properly aligned.
1384 ///
1385 /// After calling this function, the caller is responsible for the
1386 /// memory previously managed by the `Box`. In particular, the
1387 /// caller should properly destroy `T` and release the memory, taking
1388 /// into account the [memory layout] used by `Box`. The easiest way to
1389 /// do this is to convert the `NonNull` pointer back into a `Box` with the
1390 /// [`Box::from_non_null`] function, allowing the `Box` destructor to
1391 /// perform the cleanup.
1392 ///
1393 /// Note: this is an associated function, which means that you have
1394 /// to call it as `Box::into_non_null(b)` instead of `b.into_non_null()`.
1395 /// This is so that there is no conflict with a method on the inner type.
1396 ///
1397 /// # Examples
1398 /// Converting the `NonNull` pointer back into a `Box` with [`Box::from_non_null`]
1399 /// for automatic cleanup:
1400 /// ```
1401 /// #![feature(box_vec_non_null)]
1402 ///
1403 /// let x = Box::new(String::from("Hello"));
1404 /// let non_null = Box::into_non_null(x);
1405 /// let x = unsafe { Box::from_non_null(non_null) };
1406 /// ```
1407 /// Manual cleanup by explicitly running the destructor and deallocating
1408 /// the memory:
1409 /// ```
1410 /// #![feature(box_vec_non_null)]
1411 ///
1412 /// use std::alloc::{dealloc, Layout};
1413 ///
1414 /// let x = Box::new(String::from("Hello"));
1415 /// let non_null = Box::into_non_null(x);
1416 /// unsafe {
1417 /// non_null.drop_in_place();
1418 /// dealloc(non_null.as_ptr().cast::<u8>(), Layout::new::<String>());
1419 /// }
1420 /// ```
1421 /// Note: This is equivalent to the following:
1422 /// ```
1423 /// #![feature(box_vec_non_null)]
1424 ///
1425 /// let x = Box::new(String::from("Hello"));
1426 /// let non_null = Box::into_non_null(x);
1427 /// unsafe {
1428 /// drop(Box::from_non_null(non_null));
1429 /// }
1430 /// ```
1431 ///
1432 /// [memory layout]: self#memory-layout
1433 #[must_use = "losing the pointer will leak memory"]
1434 #[unstable(feature = "box_vec_non_null", issue = "130364")]
1435 #[inline]
1436 pub fn into_non_null(b: Self) -> NonNull<T> {
1437 // SAFETY: `Box` is guaranteed to be non-null.
1438 unsafe { NonNull::new_unchecked(Self::into_raw(b)) }
1439 }
1440}
1441
1442impl<T: ?Sized, A: Allocator> Box<T, A> {
1443 /// Constructs a box from a raw pointer in the given allocator.
1444 ///
1445 /// After calling this function, the raw pointer is owned by the
1446 /// resulting `Box`. Specifically, the `Box` destructor will call
1447 /// the destructor of `T` and free the allocated memory. For this
1448 /// to be safe, the memory must have been allocated in accordance
1449 /// with the [memory layout] used by `Box` .
1450 ///
1451 /// # Safety
1452 ///
1453 /// This function is unsafe because improper use may lead to
1454 /// memory problems. For example, a double-free may occur if the
1455 /// function is called twice on the same raw pointer.
1456 ///
1457 /// The raw pointer must point to a block of memory allocated by `alloc`.
1458 ///
1459 /// # Examples
1460 ///
1461 /// Recreate a `Box` which was previously converted to a raw pointer
1462 /// using [`Box::into_raw_with_allocator`]:
1463 /// ```
1464 /// #![feature(allocator_api)]
1465 ///
1466 /// use std::alloc::System;
1467 ///
1468 /// let x = Box::new_in(5, System);
1469 /// let (ptr, alloc) = Box::into_raw_with_allocator(x);
1470 /// let x = unsafe { Box::from_raw_in(ptr, alloc) };
1471 /// ```
1472 /// Manually create a `Box` from scratch by using the system allocator:
1473 /// ```
1474 /// #![feature(allocator_api, slice_ptr_get)]
1475 ///
1476 /// use std::alloc::{Allocator, Layout, System};
1477 ///
1478 /// unsafe {
1479 /// let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;
1480 /// // In general .write is required to avoid attempting to destruct
1481 /// // the (uninitialized) previous contents of `ptr`, though for this
1482 /// // simple example `*ptr = 5` would have worked as well.
1483 /// ptr.write(5);
1484 /// let x = Box::from_raw_in(ptr, System);
1485 /// }
1486 /// # Ok::<(), std::alloc::AllocError>(())
1487 /// ```
1488 ///
1489 /// [memory layout]: self#memory-layout
1490 #[unstable(feature = "allocator_api", issue = "32838")]
1491 #[inline]
1492 pub unsafe fn from_raw_in(raw: *mut T, alloc: A) -> Self {
1493 Box(unsafe { Unique::new_unchecked(raw) }, alloc)
1494 }
1495
1496 /// Constructs a box from a `NonNull` pointer in the given allocator.
1497 ///
1498 /// After calling this function, the `NonNull` pointer is owned by
1499 /// the resulting `Box`. Specifically, the `Box` destructor will call
1500 /// the destructor of `T` and free the allocated memory. For this
1501 /// to be safe, the memory must have been allocated in accordance
1502 /// with the [memory layout] used by `Box` .
1503 ///
1504 /// # Safety
1505 ///
1506 /// This function is unsafe because improper use may lead to
1507 /// memory problems. For example, a double-free may occur if the
1508 /// function is called twice on the same raw pointer.
1509 ///
1510 /// The non-null pointer must point to a block of memory allocated by `alloc`.
1511 ///
1512 /// # Examples
1513 ///
1514 /// Recreate a `Box` which was previously converted to a `NonNull` pointer
1515 /// using [`Box::into_non_null_with_allocator`]:
1516 /// ```
1517 /// #![feature(allocator_api, box_vec_non_null)]
1518 ///
1519 /// use std::alloc::System;
1520 ///
1521 /// let x = Box::new_in(5, System);
1522 /// let (non_null, alloc) = Box::into_non_null_with_allocator(x);
1523 /// let x = unsafe { Box::from_non_null_in(non_null, alloc) };
1524 /// ```
1525 /// Manually create a `Box` from scratch by using the system allocator:
1526 /// ```
1527 /// #![feature(allocator_api, box_vec_non_null, slice_ptr_get)]
1528 ///
1529 /// use std::alloc::{Allocator, Layout, System};
1530 ///
1531 /// unsafe {
1532 /// let non_null = System.allocate(Layout::new::<i32>())?.cast::<i32>();
1533 /// // In general .write is required to avoid attempting to destruct
1534 /// // the (uninitialized) previous contents of `non_null`.
1535 /// non_null.write(5);
1536 /// let x = Box::from_non_null_in(non_null, System);
1537 /// }
1538 /// # Ok::<(), std::alloc::AllocError>(())
1539 /// ```
1540 ///
1541 /// [memory layout]: self#memory-layout
1542 #[unstable(feature = "allocator_api", issue = "32838")]
1543 // #[unstable(feature = "box_vec_non_null", issue = "130364")]
1544 #[inline]
1545 pub unsafe fn from_non_null_in(raw: NonNull<T>, alloc: A) -> Self {
1546 // SAFETY: guaranteed by the caller.
1547 unsafe { Box::from_raw_in(raw.as_ptr(), alloc) }
1548 }
1549
1550 /// Consumes the `Box`, returning a wrapped raw pointer and the allocator.
1551 ///
1552 /// The pointer will be properly aligned and non-null.
1553 ///
1554 /// After calling this function, the caller is responsible for the
1555 /// memory previously managed by the `Box`. In particular, the
1556 /// caller should properly destroy `T` and release the memory, taking
1557 /// into account the [memory layout] used by `Box`. The easiest way to
1558 /// do this is to convert the raw pointer back into a `Box` with the
1559 /// [`Box::from_raw_in`] function, allowing the `Box` destructor to perform
1560 /// the cleanup.
1561 ///
1562 /// Note: this is an associated function, which means that you have
1563 /// to call it as `Box::into_raw_with_allocator(b)` instead of `b.into_raw_with_allocator()`. This
1564 /// is so that there is no conflict with a method on the inner type.
1565 ///
1566 /// # Examples
1567 /// Converting the raw pointer back into a `Box` with [`Box::from_raw_in`]
1568 /// for automatic cleanup:
1569 /// ```
1570 /// #![feature(allocator_api)]
1571 ///
1572 /// use std::alloc::System;
1573 ///
1574 /// let x = Box::new_in(String::from("Hello"), System);
1575 /// let (ptr, alloc) = Box::into_raw_with_allocator(x);
1576 /// let x = unsafe { Box::from_raw_in(ptr, alloc) };
1577 /// ```
1578 /// Manual cleanup by explicitly running the destructor and deallocating
1579 /// the memory:
1580 /// ```
1581 /// #![feature(allocator_api)]
1582 ///
1583 /// use std::alloc::{Allocator, Layout, System};
1584 /// use std::ptr::{self, NonNull};
1585 ///
1586 /// let x = Box::new_in(String::from("Hello"), System);
1587 /// let (ptr, alloc) = Box::into_raw_with_allocator(x);
1588 /// unsafe {
1589 /// ptr::drop_in_place(ptr);
1590 /// let non_null = NonNull::new_unchecked(ptr);
1591 /// alloc.deallocate(non_null.cast(), Layout::new::<String>());
1592 /// }
1593 /// ```
1594 ///
1595 /// [memory layout]: self#memory-layout
1596 #[must_use = "losing the pointer will leak memory"]
1597 #[unstable(feature = "allocator_api", issue = "32838")]
1598 #[inline]
1599 pub fn into_raw_with_allocator(b: Self) -> (*mut T, A) {
1600 let mut b = mem::ManuallyDrop::new(b);
1601 // We carefully get the raw pointer out in a way that Miri's aliasing model understands what
1602 // is happening: using the primitive "deref" of `Box`. In case `A` is *not* `Global`, we
1603 // want *no* aliasing requirements here!
1604 // In case `A` *is* `Global`, this does not quite have the right behavior; `into_raw`
1605 // works around that.
1606 let ptr = &raw mut **b;
1607 let alloc = unsafe { ptr::read(&b.1) };
1608 (ptr, alloc)
1609 }
1610
1611 /// Consumes the `Box`, returning a wrapped `NonNull` pointer and the allocator.
1612 ///
1613 /// The pointer will be properly aligned.
1614 ///
1615 /// After calling this function, the caller is responsible for the
1616 /// memory previously managed by the `Box`. In particular, the
1617 /// caller should properly destroy `T` and release the memory, taking
1618 /// into account the [memory layout] used by `Box`. The easiest way to
1619 /// do this is to convert the `NonNull` pointer back into a `Box` with the
1620 /// [`Box::from_non_null_in`] function, allowing the `Box` destructor to
1621 /// perform the cleanup.
1622 ///
1623 /// Note: this is an associated function, which means that you have
1624 /// to call it as `Box::into_non_null_with_allocator(b)` instead of
1625 /// `b.into_non_null_with_allocator()`. This is so that there is no
1626 /// conflict with a method on the inner type.
1627 ///
1628 /// # Examples
1629 /// Converting the `NonNull` pointer back into a `Box` with
1630 /// [`Box::from_non_null_in`] for automatic cleanup:
1631 /// ```
1632 /// #![feature(allocator_api, box_vec_non_null)]
1633 ///
1634 /// use std::alloc::System;
1635 ///
1636 /// let x = Box::new_in(String::from("Hello"), System);
1637 /// let (non_null, alloc) = Box::into_non_null_with_allocator(x);
1638 /// let x = unsafe { Box::from_non_null_in(non_null, alloc) };
1639 /// ```
1640 /// Manual cleanup by explicitly running the destructor and deallocating
1641 /// the memory:
1642 /// ```
1643 /// #![feature(allocator_api, box_vec_non_null)]
1644 ///
1645 /// use std::alloc::{Allocator, Layout, System};
1646 ///
1647 /// let x = Box::new_in(String::from("Hello"), System);
1648 /// let (non_null, alloc) = Box::into_non_null_with_allocator(x);
1649 /// unsafe {
1650 /// non_null.drop_in_place();
1651 /// alloc.deallocate(non_null.cast::<u8>(), Layout::new::<String>());
1652 /// }
1653 /// ```
1654 ///
1655 /// [memory layout]: self#memory-layout
1656 #[must_use = "losing the pointer will leak memory"]
1657 #[unstable(feature = "allocator_api", issue = "32838")]
1658 // #[unstable(feature = "box_vec_non_null", issue = "130364")]
1659 #[inline]
1660 pub fn into_non_null_with_allocator(b: Self) -> (NonNull<T>, A) {
1661 let (ptr, alloc) = Box::into_raw_with_allocator(b);
1662 // SAFETY: `Box` is guaranteed to be non-null.
1663 unsafe { (NonNull::new_unchecked(ptr), alloc) }
1664 }
1665
1666 #[unstable(
1667 feature = "ptr_internals",
1668 issue = "none",
1669 reason = "use `Box::leak(b).into()` or `Unique::from(Box::leak(b))` instead"
1670 )]
1671 #[inline]
1672 #[doc(hidden)]
1673 pub fn into_unique(b: Self) -> (Unique<T>, A) {
1674 let (ptr, alloc) = Box::into_raw_with_allocator(b);
1675 unsafe { (Unique::from(&mut *ptr), alloc) }
1676 }
1677
1678 /// Returns a raw mutable pointer to the `Box`'s contents.
1679 ///
1680 /// The caller must ensure that the `Box` outlives the pointer this
1681 /// function returns, or else it will end up dangling.
1682 ///
1683 /// This method guarantees that for the purpose of the aliasing model, this method
1684 /// does not materialize a reference to the underlying memory, and thus the returned pointer
1685 /// will remain valid when mixed with other calls to [`as_ptr`] and [`as_mut_ptr`].
1686 /// Note that calling other methods that materialize references to the memory
1687 /// may still invalidate this pointer.
1688 /// See the example below for how this guarantee can be used.
1689 ///
1690 /// # Examples
1691 ///
1692 /// Due to the aliasing guarantee, the following code is legal:
1693 ///
1694 /// ```rust
1695 /// #![feature(box_as_ptr)]
1696 ///
1697 /// unsafe {
1698 /// let mut b = Box::new(0);
1699 /// let ptr1 = Box::as_mut_ptr(&mut b);
1700 /// ptr1.write(1);
1701 /// let ptr2 = Box::as_mut_ptr(&mut b);
1702 /// ptr2.write(2);
1703 /// // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
1704 /// ptr1.write(3);
1705 /// }
1706 /// ```
1707 ///
1708 /// [`as_mut_ptr`]: Self::as_mut_ptr
1709 /// [`as_ptr`]: Self::as_ptr
1710 #[unstable(feature = "box_as_ptr", issue = "129090")]
1711 #[rustc_never_returns_null_ptr]
1712 #[rustc_as_ptr]
1713 #[inline]
1714 pub fn as_mut_ptr(b: &mut Self) -> *mut T {
1715 // This is a primitive deref, not going through `DerefMut`, and therefore not materializing
1716 // any references.
1717 &raw mut **b
1718 }
1719
1720 /// Returns a raw pointer to the `Box`'s contents.
1721 ///
1722 /// The caller must ensure that the `Box` outlives the pointer this
1723 /// function returns, or else it will end up dangling.
1724 ///
1725 /// The caller must also ensure that the memory the pointer (non-transitively) points to
1726 /// is never written to (except inside an `UnsafeCell`) using this pointer or any pointer
1727 /// derived from it. If you need to mutate the contents of the `Box`, use [`as_mut_ptr`].
1728 ///
1729 /// This method guarantees that for the purpose of the aliasing model, this method
1730 /// does not materialize a reference to the underlying memory, and thus the returned pointer
1731 /// will remain valid when mixed with other calls to [`as_ptr`] and [`as_mut_ptr`].
1732 /// Note that calling other methods that materialize mutable references to the memory,
1733 /// as well as writing to this memory, may still invalidate this pointer.
1734 /// See the example below for how this guarantee can be used.
1735 ///
1736 /// # Examples
1737 ///
1738 /// Due to the aliasing guarantee, the following code is legal:
1739 ///
1740 /// ```rust
1741 /// #![feature(box_as_ptr)]
1742 ///
1743 /// unsafe {
1744 /// let mut v = Box::new(0);
1745 /// let ptr1 = Box::as_ptr(&v);
1746 /// let ptr2 = Box::as_mut_ptr(&mut v);
1747 /// let _val = ptr2.read();
1748 /// // No write to this memory has happened yet, so `ptr1` is still valid.
1749 /// let _val = ptr1.read();
1750 /// // However, once we do a write...
1751 /// ptr2.write(1);
1752 /// // ... `ptr1` is no longer valid.
1753 /// // This would be UB: let _val = ptr1.read();
1754 /// }
1755 /// ```
1756 ///
1757 /// [`as_mut_ptr`]: Self::as_mut_ptr
1758 /// [`as_ptr`]: Self::as_ptr
1759 #[unstable(feature = "box_as_ptr", issue = "129090")]
1760 #[rustc_never_returns_null_ptr]
1761 #[rustc_as_ptr]
1762 #[inline]
1763 pub fn as_ptr(b: &Self) -> *const T {
1764 // This is a primitive deref, not going through `DerefMut`, and therefore not materializing
1765 // any references.
1766 &raw const **b
1767 }
1768
1769 /// Returns a reference to the underlying allocator.
1770 ///
1771 /// Note: this is an associated function, which means that you have
1772 /// to call it as `Box::allocator(&b)` instead of `b.allocator()`. This
1773 /// is so that there is no conflict with a method on the inner type.
1774 #[unstable(feature = "allocator_api", issue = "32838")]
1775 #[inline]
1776 pub fn allocator(b: &Self) -> &A {
1777 &b.1
1778 }
1779
1780 /// Consumes and leaks the `Box`, returning a mutable reference,
1781 /// `&'a mut T`.
1782 ///
1783 /// Note that the type `T` must outlive the chosen lifetime `'a`. If the type
1784 /// has only static references, or none at all, then this may be chosen to be
1785 /// `'static`.
1786 ///
1787 /// This function is mainly useful for data that lives for the remainder of
1788 /// the program's life. Dropping the returned reference will cause a memory
1789 /// leak. If this is not acceptable, the reference should first be wrapped
1790 /// with the [`Box::from_raw`] function producing a `Box`. This `Box` can
1791 /// then be dropped which will properly destroy `T` and release the
1792 /// allocated memory.
1793 ///
1794 /// Note: this is an associated function, which means that you have
1795 /// to call it as `Box::leak(b)` instead of `b.leak()`. This
1796 /// is so that there is no conflict with a method on the inner type.
1797 ///
1798 /// # Examples
1799 ///
1800 /// Simple usage:
1801 ///
1802 /// ```
1803 /// let x = Box::new(41);
1804 /// let static_ref: &'static mut usize = Box::leak(x);
1805 /// *static_ref += 1;
1806 /// assert_eq!(*static_ref, 42);
1807 /// # // FIXME(https://github.com/rust-lang/miri/issues/3670):
1808 /// # // use -Zmiri-disable-leak-check instead of unleaking in tests meant to leak.
1809 /// # drop(unsafe { Box::from_raw(static_ref) });
1810 /// ```
1811 ///
1812 /// Unsized data:
1813 ///
1814 /// ```
1815 /// let x = vec![1, 2, 3].into_boxed_slice();
1816 /// let static_ref = Box::leak(x);
1817 /// static_ref[0] = 4;
1818 /// assert_eq!(*static_ref, [4, 2, 3]);
1819 /// # // FIXME(https://github.com/rust-lang/miri/issues/3670):
1820 /// # // use -Zmiri-disable-leak-check instead of unleaking in tests meant to leak.
1821 /// # drop(unsafe { Box::from_raw(static_ref) });
1822 /// ```
1823 #[stable(feature = "box_leak", since = "1.26.0")]
1824 #[inline]
1825 pub fn leak<'a>(b: Self) -> &'a mut T
1826 where
1827 A: 'a,
1828 {
1829 let (ptr, alloc) = Box::into_raw_with_allocator(b);
1830 mem::forget(alloc);
1831 unsafe { &mut *ptr }
1832 }
1833
1834 /// Converts a `Box<T>` into a `Pin<Box<T>>`. If `T` does not implement [`Unpin`], then
1835 /// `*boxed` will be pinned in memory and unable to be moved.
1836 ///
1837 /// This conversion does not allocate on the heap and happens in place.
1838 ///
1839 /// This is also available via [`From`].
1840 ///
1841 /// Constructing and pinning a `Box` with <code>Box::into_pin([Box::new]\(x))</code>
1842 /// can also be written more concisely using <code>[Box::pin]\(x)</code>.
1843 /// This `into_pin` method is useful if you already have a `Box<T>`, or you are
1844 /// constructing a (pinned) `Box` in a different way than with [`Box::new`].
1845 ///
1846 /// # Notes
1847 ///
1848 /// It's not recommended that crates add an impl like `From<Box<T>> for Pin<T>`,
1849 /// as it'll introduce an ambiguity when calling `Pin::from`.
1850 /// A demonstration of such a poor impl is shown below.
1851 ///
1852 /// ```compile_fail
1853 /// # use std::pin::Pin;
1854 /// struct Foo; // A type defined in this crate.
1855 /// impl From<Box<()>> for Pin<Foo> {
1856 /// fn from(_: Box<()>) -> Pin<Foo> {
1857 /// Pin::new(Foo)
1858 /// }
1859 /// }
1860 ///
1861 /// let foo = Box::new(());
1862 /// let bar = Pin::from(foo);
1863 /// ```
1864 #[stable(feature = "box_into_pin", since = "1.63.0")]
1865 pub fn into_pin(boxed: Self) -> Pin<Self>
1866 where
1867 A: 'static,
1868 {
1869 // It's not possible to move or replace the insides of a `Pin<Box<T>>`
1870 // when `T: !Unpin`, so it's safe to pin it directly without any
1871 // additional requirements.
1872 unsafe { Pin::new_unchecked(boxed) }
1873 }
1874}
1875
1876#[stable(feature = "rust1", since = "1.0.0")]
1877unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Box<T, A> {
1878 #[inline]
1879 fn drop(&mut self) {
1880 // the T in the Box is dropped by the compiler before the destructor is run
1881
1882 let ptr = self.0;
1883
1884 unsafe {
1885 let layout = Layout::for_value_raw(ptr.as_ptr());
1886 if layout.size() != 0 {
1887 self.1.deallocate(From::from(ptr.cast()), layout);
1888 }
1889 }
1890 }
1891}
1892
1893#[cfg(not(no_global_oom_handling))]
1894#[stable(feature = "rust1", since = "1.0.0")]
1895impl<T: Default> Default for Box<T> {
1896 /// Creates a `Box<T>`, with the `Default` value for `T`.
1897 #[inline]
1898 fn default() -> Self {
1899 let mut x: Box<mem::MaybeUninit<T>> = Box::new_uninit();
1900 unsafe {
1901 // SAFETY: `x` is valid for writing and has the same layout as `T`.
1902 // If `T::default()` panics, dropping `x` will just deallocate the Box as `MaybeUninit<T>`
1903 // does not have a destructor.
1904 //
1905 // We use `ptr::write` as `MaybeUninit::write` creates
1906 // extra stack copies of `T` in debug mode.
1907 //
1908 // See https://github.com/rust-lang/rust/issues/136043 for more context.
1909 ptr::write(&raw mut *x as *mut T, T::default());
1910 // SAFETY: `x` was just initialized above.
1911 x.assume_init()
1912 }
1913 }
1914}
1915
1916#[cfg(not(no_global_oom_handling))]
1917#[stable(feature = "rust1", since = "1.0.0")]
1918impl<T> Default for Box<[T]> {
1919 /// Creates an empty `[T]` inside a `Box`.
1920 #[inline]
1921 fn default() -> Self {
1922 let ptr: Unique<[T]> = Unique::<[T; 0]>::dangling();
1923 Box(ptr, Global)
1924 }
1925}
1926
1927#[cfg(not(no_global_oom_handling))]
1928#[stable(feature = "default_box_extra", since = "1.17.0")]
1929impl Default for Box<str> {
1930 #[inline]
1931 fn default() -> Self {
1932 // SAFETY: This is the same as `Unique::cast<U>` but with an unsized `U = str`.
1933 let ptr: Unique<str> = unsafe {
1934 let bytes: Unique<[u8]> = Unique::<[u8; 0]>::dangling();
1935 Unique::new_unchecked(bytes.as_ptr() as *mut str)
1936 };
1937 Box(ptr, Global)
1938 }
1939}
1940
1941#[cfg(not(no_global_oom_handling))]
1942#[stable(feature = "pin_default_impls", since = "1.91.0")]
1943impl<T> Default for Pin<Box<T>>
1944where
1945 T: ?Sized,
1946 Box<T>: Default,
1947{
1948 #[inline]
1949 fn default() -> Self {
1950 Box::into_pin(boxed:Box::<T>::default())
1951 }
1952}
1953
1954#[cfg(not(no_global_oom_handling))]
1955#[stable(feature = "rust1", since = "1.0.0")]
1956impl<T: Clone, A: Allocator + Clone> Clone for Box<T, A> {
1957 /// Returns a new box with a `clone()` of this box's contents.
1958 ///
1959 /// # Examples
1960 ///
1961 /// ```
1962 /// let x = Box::new(5);
1963 /// let y = x.clone();
1964 ///
1965 /// // The value is the same
1966 /// assert_eq!(x, y);
1967 ///
1968 /// // But they are unique objects
1969 /// assert_ne!(&*x as *const i32, &*y as *const i32);
1970 /// ```
1971 #[inline]
1972 fn clone(&self) -> Self {
1973 // Pre-allocate memory to allow writing the cloned value directly.
1974 let mut boxed = Self::new_uninit_in(self.1.clone());
1975 unsafe {
1976 (**self).clone_to_uninit(boxed.as_mut_ptr().cast());
1977 boxed.assume_init()
1978 }
1979 }
1980
1981 /// Copies `source`'s contents into `self` without creating a new allocation.
1982 ///
1983 /// # Examples
1984 ///
1985 /// ```
1986 /// let x = Box::new(5);
1987 /// let mut y = Box::new(10);
1988 /// let yp: *const i32 = &*y;
1989 ///
1990 /// y.clone_from(&x);
1991 ///
1992 /// // The value is the same
1993 /// assert_eq!(x, y);
1994 ///
1995 /// // And no allocation occurred
1996 /// assert_eq!(yp, &*y);
1997 /// ```
1998 #[inline]
1999 fn clone_from(&mut self, source: &Self) {
2000 (**self).clone_from(&(**source));
2001 }
2002}
2003
2004#[cfg(not(no_global_oom_handling))]
2005#[stable(feature = "box_slice_clone", since = "1.3.0")]
2006impl<T: Clone, A: Allocator + Clone> Clone for Box<[T], A> {
2007 fn clone(&self) -> Self {
2008 let alloc = Box::allocator(self).clone();
2009 self.to_vec_in(alloc).into_boxed_slice()
2010 }
2011
2012 /// Copies `source`'s contents into `self` without creating a new allocation,
2013 /// so long as the two are of the same length.
2014 ///
2015 /// # Examples
2016 ///
2017 /// ```
2018 /// let x = Box::new([5, 6, 7]);
2019 /// let mut y = Box::new([8, 9, 10]);
2020 /// let yp: *const [i32] = &*y;
2021 ///
2022 /// y.clone_from(&x);
2023 ///
2024 /// // The value is the same
2025 /// assert_eq!(x, y);
2026 ///
2027 /// // And no allocation occurred
2028 /// assert_eq!(yp, &*y);
2029 /// ```
2030 fn clone_from(&mut self, source: &Self) {
2031 if self.len() == source.len() {
2032 self.clone_from_slice(&source);
2033 } else {
2034 *self = source.clone();
2035 }
2036 }
2037}
2038
2039#[cfg(not(no_global_oom_handling))]
2040#[stable(feature = "box_slice_clone", since = "1.3.0")]
2041impl Clone for Box<str> {
2042 fn clone(&self) -> Self {
2043 // this makes a copy of the data
2044 let buf: Box<[u8]> = self.as_bytes().into();
2045 unsafe { from_boxed_utf8_unchecked(buf) }
2046 }
2047}
2048
2049#[stable(feature = "rust1", since = "1.0.0")]
2050impl<T: ?Sized + PartialEq, A: Allocator> PartialEq for Box<T, A> {
2051 #[inline]
2052 fn eq(&self, other: &Self) -> bool {
2053 PartialEq::eq(&**self, &**other)
2054 }
2055 #[inline]
2056 fn ne(&self, other: &Self) -> bool {
2057 PartialEq::ne(&**self, &**other)
2058 }
2059}
2060
2061#[stable(feature = "rust1", since = "1.0.0")]
2062impl<T: ?Sized + PartialOrd, A: Allocator> PartialOrd for Box<T, A> {
2063 #[inline]
2064 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
2065 PartialOrd::partial_cmp(&**self, &**other)
2066 }
2067 #[inline]
2068 fn lt(&self, other: &Self) -> bool {
2069 PartialOrd::lt(&**self, &**other)
2070 }
2071 #[inline]
2072 fn le(&self, other: &Self) -> bool {
2073 PartialOrd::le(&**self, &**other)
2074 }
2075 #[inline]
2076 fn ge(&self, other: &Self) -> bool {
2077 PartialOrd::ge(&**self, &**other)
2078 }
2079 #[inline]
2080 fn gt(&self, other: &Self) -> bool {
2081 PartialOrd::gt(&**self, &**other)
2082 }
2083}
2084
2085#[stable(feature = "rust1", since = "1.0.0")]
2086impl<T: ?Sized + Ord, A: Allocator> Ord for Box<T, A> {
2087 #[inline]
2088 fn cmp(&self, other: &Self) -> Ordering {
2089 Ord::cmp(&**self, &**other)
2090 }
2091}
2092
2093#[stable(feature = "rust1", since = "1.0.0")]
2094impl<T: ?Sized + Eq, A: Allocator> Eq for Box<T, A> {}
2095
2096#[stable(feature = "rust1", since = "1.0.0")]
2097impl<T: ?Sized + Hash, A: Allocator> Hash for Box<T, A> {
2098 fn hash<H: Hasher>(&self, state: &mut H) {
2099 (**self).hash(state);
2100 }
2101}
2102
2103#[stable(feature = "indirect_hasher_impl", since = "1.22.0")]
2104impl<T: ?Sized + Hasher, A: Allocator> Hasher for Box<T, A> {
2105 fn finish(&self) -> u64 {
2106 (**self).finish()
2107 }
2108 fn write(&mut self, bytes: &[u8]) {
2109 (**self).write(bytes)
2110 }
2111 fn write_u8(&mut self, i: u8) {
2112 (**self).write_u8(i)
2113 }
2114 fn write_u16(&mut self, i: u16) {
2115 (**self).write_u16(i)
2116 }
2117 fn write_u32(&mut self, i: u32) {
2118 (**self).write_u32(i)
2119 }
2120 fn write_u64(&mut self, i: u64) {
2121 (**self).write_u64(i)
2122 }
2123 fn write_u128(&mut self, i: u128) {
2124 (**self).write_u128(i)
2125 }
2126 fn write_usize(&mut self, i: usize) {
2127 (**self).write_usize(i)
2128 }
2129 fn write_i8(&mut self, i: i8) {
2130 (**self).write_i8(i)
2131 }
2132 fn write_i16(&mut self, i: i16) {
2133 (**self).write_i16(i)
2134 }
2135 fn write_i32(&mut self, i: i32) {
2136 (**self).write_i32(i)
2137 }
2138 fn write_i64(&mut self, i: i64) {
2139 (**self).write_i64(i)
2140 }
2141 fn write_i128(&mut self, i: i128) {
2142 (**self).write_i128(i)
2143 }
2144 fn write_isize(&mut self, i: isize) {
2145 (**self).write_isize(i)
2146 }
2147 fn write_length_prefix(&mut self, len: usize) {
2148 (**self).write_length_prefix(len)
2149 }
2150 fn write_str(&mut self, s: &str) {
2151 (**self).write_str(s)
2152 }
2153}
2154
2155#[stable(feature = "rust1", since = "1.0.0")]
2156impl<T: fmt::Display + ?Sized, A: Allocator> fmt::Display for Box<T, A> {
2157 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2158 fmt::Display::fmt(&**self, f)
2159 }
2160}
2161
2162#[stable(feature = "rust1", since = "1.0.0")]
2163impl<T: fmt::Debug + ?Sized, A: Allocator> fmt::Debug for Box<T, A> {
2164 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2165 fmt::Debug::fmt(&**self, f)
2166 }
2167}
2168
2169#[stable(feature = "rust1", since = "1.0.0")]
2170impl<T: ?Sized, A: Allocator> fmt::Pointer for Box<T, A> {
2171 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2172 // It's not possible to extract the inner Uniq directly from the Box,
2173 // instead we cast it to a *const which aliases the Unique
2174 let ptr: *const T = &**self;
2175 fmt::Pointer::fmt(&ptr, f)
2176 }
2177}
2178
2179#[stable(feature = "rust1", since = "1.0.0")]
2180impl<T: ?Sized, A: Allocator> Deref for Box<T, A> {
2181 type Target = T;
2182
2183 fn deref(&self) -> &T {
2184 &**self
2185 }
2186}
2187
2188#[stable(feature = "rust1", since = "1.0.0")]
2189impl<T: ?Sized, A: Allocator> DerefMut for Box<T, A> {
2190 fn deref_mut(&mut self) -> &mut T {
2191 &mut **self
2192 }
2193}
2194
2195#[unstable(feature = "deref_pure_trait", issue = "87121")]
2196unsafe impl<T: ?Sized, A: Allocator> DerefPure for Box<T, A> {}
2197
2198#[unstable(feature = "legacy_receiver_trait", issue = "none")]
2199impl<T: ?Sized, A: Allocator> LegacyReceiver for Box<T, A> {}
2200
2201#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
2202impl<Args: Tuple, F: FnOnce<Args> + ?Sized, A: Allocator> FnOnce<Args> for Box<F, A> {
2203 type Output = <F as FnOnce<Args>>::Output;
2204
2205 extern "rust-call" fn call_once(self, args: Args) -> Self::Output {
2206 <F as FnOnce<Args>>::call_once(*self, args)
2207 }
2208}
2209
2210#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
2211impl<Args: Tuple, F: FnMut<Args> + ?Sized, A: Allocator> FnMut<Args> for Box<F, A> {
2212 extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output {
2213 <F as FnMut<Args>>::call_mut(self, args)
2214 }
2215}
2216
2217#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
2218impl<Args: Tuple, F: Fn<Args> + ?Sized, A: Allocator> Fn<Args> for Box<F, A> {
2219 extern "rust-call" fn call(&self, args: Args) -> Self::Output {
2220 <F as Fn<Args>>::call(self, args)
2221 }
2222}
2223
2224#[stable(feature = "async_closure", since = "1.85.0")]
2225impl<Args: Tuple, F: AsyncFnOnce<Args> + ?Sized, A: Allocator> AsyncFnOnce<Args> for Box<F, A> {
2226 type Output = F::Output;
2227 type CallOnceFuture = F::CallOnceFuture;
2228
2229 extern "rust-call" fn async_call_once(self, args: Args) -> Self::CallOnceFuture {
2230 F::async_call_once(*self, args)
2231 }
2232}
2233
2234#[stable(feature = "async_closure", since = "1.85.0")]
2235impl<Args: Tuple, F: AsyncFnMut<Args> + ?Sized, A: Allocator> AsyncFnMut<Args> for Box<F, A> {
2236 type CallRefFuture<'a>
2237 = F::CallRefFuture<'a>
2238 where
2239 Self: 'a;
2240
2241 extern "rust-call" fn async_call_mut(&mut self, args: Args) -> Self::CallRefFuture<'_> {
2242 F::async_call_mut(self, args)
2243 }
2244}
2245
2246#[stable(feature = "async_closure", since = "1.85.0")]
2247impl<Args: Tuple, F: AsyncFn<Args> + ?Sized, A: Allocator> AsyncFn<Args> for Box<F, A> {
2248 extern "rust-call" fn async_call(&self, args: Args) -> Self::CallRefFuture<'_> {
2249 F::async_call(self, args)
2250 }
2251}
2252
2253#[unstable(feature = "coerce_unsized", issue = "18598")]
2254impl<T: ?Sized + Unsize<U>, U: ?Sized, A: Allocator> CoerceUnsized<Box<U, A>> for Box<T, A> {}
2255
2256#[unstable(feature = "pin_coerce_unsized_trait", issue = "150112")]
2257unsafe impl<T: ?Sized, A: Allocator> PinCoerceUnsized for Box<T, A> {}
2258
2259// It is quite crucial that we only allow the `Global` allocator here.
2260// Handling arbitrary custom allocators (which can affect the `Box` layout heavily!)
2261// would need a lot of codegen and interpreter adjustments.
2262#[unstable(feature = "dispatch_from_dyn", issue = "none")]
2263impl<T: ?Sized + Unsize<U>, U: ?Sized> DispatchFromDyn<Box<U>> for Box<T, Global> {}
2264
2265#[stable(feature = "box_borrow", since = "1.1.0")]
2266impl<T: ?Sized, A: Allocator> Borrow<T> for Box<T, A> {
2267 fn borrow(&self) -> &T {
2268 &**self
2269 }
2270}
2271
2272#[stable(feature = "box_borrow", since = "1.1.0")]
2273impl<T: ?Sized, A: Allocator> BorrowMut<T> for Box<T, A> {
2274 fn borrow_mut(&mut self) -> &mut T {
2275 &mut **self
2276 }
2277}
2278
2279#[stable(since = "1.5.0", feature = "smart_ptr_as_ref")]
2280impl<T: ?Sized, A: Allocator> AsRef<T> for Box<T, A> {
2281 fn as_ref(&self) -> &T {
2282 &**self
2283 }
2284}
2285
2286#[stable(since = "1.5.0", feature = "smart_ptr_as_ref")]
2287impl<T: ?Sized, A: Allocator> AsMut<T> for Box<T, A> {
2288 fn as_mut(&mut self) -> &mut T {
2289 &mut **self
2290 }
2291}
2292
2293/* Nota bene
2294 *
2295 * We could have chosen not to add this impl, and instead have written a
2296 * function of Pin<Box<T>> to Pin<T>. Such a function would not be sound,
2297 * because Box<T> implements Unpin even when T does not, as a result of
2298 * this impl.
2299 *
2300 * We chose this API instead of the alternative for a few reasons:
2301 * - Logically, it is helpful to understand pinning in regard to the
2302 * memory region being pointed to. For this reason none of the
2303 * standard library pointer types support projecting through a pin
2304 * (Box<T> is the only pointer type in std for which this would be
2305 * safe.)
2306 * - It is in practice very useful to have Box<T> be unconditionally
2307 * Unpin because of trait objects, for which the structural auto
2308 * trait functionality does not apply (e.g., Box<dyn Foo> would
2309 * otherwise not be Unpin).
2310 *
2311 * Another type with the same semantics as Box but only a conditional
2312 * implementation of `Unpin` (where `T: Unpin`) would be valid/safe, and
2313 * could have a method to project a Pin<T> from it.
2314 */
2315#[stable(feature = "pin", since = "1.33.0")]
2316impl<T: ?Sized, A: Allocator> Unpin for Box<T, A> {}
2317
2318#[unstable(feature = "coroutine_trait", issue = "43122")]
2319impl<G: ?Sized + Coroutine<R> + Unpin, R, A: Allocator> Coroutine<R> for Box<G, A> {
2320 type Yield = G::Yield;
2321 type Return = G::Return;
2322
2323 fn resume(mut self: Pin<&mut Self>, arg: R) -> CoroutineState<Self::Yield, Self::Return> {
2324 G::resume(Pin::new(&mut *self), arg)
2325 }
2326}
2327
2328#[unstable(feature = "coroutine_trait", issue = "43122")]
2329impl<G: ?Sized + Coroutine<R>, R, A: Allocator> Coroutine<R> for Pin<Box<G, A>>
2330where
2331 A: 'static,
2332{
2333 type Yield = G::Yield;
2334 type Return = G::Return;
2335
2336 fn resume(mut self: Pin<&mut Self>, arg: R) -> CoroutineState<Self::Yield, Self::Return> {
2337 G::resume((*self).as_mut(), arg)
2338 }
2339}
2340
2341#[stable(feature = "futures_api", since = "1.36.0")]
2342impl<F: ?Sized + Future + Unpin, A: Allocator> Future for Box<F, A> {
2343 type Output = F::Output;
2344
2345 fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
2346 F::poll(Pin::new(&mut *self), cx)
2347 }
2348}
2349
2350#[stable(feature = "box_error", since = "1.8.0")]
2351impl<E: Error> Error for Box<E> {
2352 #[allow(deprecated)]
2353 fn cause(&self) -> Option<&dyn Error> {
2354 Error::cause(&**self)
2355 }
2356
2357 fn source(&self) -> Option<&(dyn Error + 'static)> {
2358 Error::source(&**self)
2359 }
2360
2361 fn provide<'b>(&'b self, request: &mut error::Request<'b>) {
2362 Error::provide(&**self, request);
2363 }
2364}
2365
2366#[unstable(feature = "allocator_api", issue = "32838")]
2367unsafe impl<T: ?Sized + Allocator, A: Allocator> Allocator for Box<T, A> {
2368 #[inline]
2369 fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
2370 (**self).allocate(layout)
2371 }
2372
2373 #[inline]
2374 fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
2375 (**self).allocate_zeroed(layout)
2376 }
2377
2378 #[inline]
2379 unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout) {
2380 // SAFETY: the safety contract must be upheld by the caller
2381 unsafe { (**self).deallocate(ptr, layout) }
2382 }
2383
2384 #[inline]
2385 unsafe fn grow(
2386 &self,
2387 ptr: NonNull<u8>,
2388 old_layout: Layout,
2389 new_layout: Layout,
2390 ) -> Result<NonNull<[u8]>, AllocError> {
2391 // SAFETY: the safety contract must be upheld by the caller
2392 unsafe { (**self).grow(ptr, old_layout, new_layout) }
2393 }
2394
2395 #[inline]
2396 unsafe fn grow_zeroed(
2397 &self,
2398 ptr: NonNull<u8>,
2399 old_layout: Layout,
2400 new_layout: Layout,
2401 ) -> Result<NonNull<[u8]>, AllocError> {
2402 // SAFETY: the safety contract must be upheld by the caller
2403 unsafe { (**self).grow_zeroed(ptr, old_layout, new_layout) }
2404 }
2405
2406 #[inline]
2407 unsafe fn shrink(
2408 &self,
2409 ptr: NonNull<u8>,
2410 old_layout: Layout,
2411 new_layout: Layout,
2412 ) -> Result<NonNull<[u8]>, AllocError> {
2413 // SAFETY: the safety contract must be upheld by the caller
2414 unsafe { (**self).shrink(ptr, old_layout, new_layout) }
2415 }
2416}
2417