use core::any::Any; use core::error::Error; use core::mem; use core::pin::Pin; #[cfg(not(no_global_oom_handling))] use core::{fmt, ptr}; use crate::alloc::Allocator; #[cfg(not(no_global_oom_handling))] use crate::borrow::Cow; use crate::boxed::Box; #[cfg(not(no_global_oom_handling))] use crate::raw_vec::RawVec; #[cfg(not(no_global_oom_handling))] use crate::str::from_boxed_utf8_unchecked; #[cfg(not(no_global_oom_handling))] use crate::string::String; #[cfg(not(no_global_oom_handling))] use crate::vec::Vec; #[cfg(not(no_global_oom_handling))] #[stable(feature = "from_for_ptrs", since = "1.6.0")] impl From for Box { /// Converts a `T` into a `Box` /// /// The conversion allocates on the heap and moves `t` /// from the stack into it. /// /// # Examples /// /// ```rust /// let x = 5; /// let boxed = Box::new(5); /// /// assert_eq!(Box::from(x), boxed); /// ``` fn from(t: T) -> Self { Box::new(t) } } #[stable(feature = "pin", since = "1.33.0")] impl From> for Pin> where A: 'static, { /// Converts a `Box` into a `Pin>`. If `T` does not implement [`Unpin`], then /// `*boxed` will be pinned in memory and unable to be moved. /// /// This conversion does not allocate on the heap and happens in place. /// /// This is also available via [`Box::into_pin`]. /// /// Constructing and pinning a `Box` with >>::from([Box::new]\(x)) /// can also be written more concisely using [Box::pin]\(x). /// This `From` implementation is useful if you already have a `Box`, or you are /// constructing a (pinned) `Box` in a different way than with [`Box::new`]. fn from(boxed: Box) -> Self { Box::into_pin(boxed) } } /// Specialization trait used for `From<&[T]>`. #[cfg(not(no_global_oom_handling))] trait BoxFromSlice { fn from_slice(slice: &[T]) -> Self; } #[cfg(not(no_global_oom_handling))] impl BoxFromSlice for Box<[T]> { #[inline] default fn from_slice(slice: &[T]) -> Self { slice.to_vec().into_boxed_slice() } } #[cfg(not(no_global_oom_handling))] impl BoxFromSlice for Box<[T]> { #[inline] fn from_slice(slice: &[T]) -> Self { let len = slice.len(); let buf = RawVec::with_capacity(len); unsafe { ptr::copy_nonoverlapping(slice.as_ptr(), buf.ptr(), len); buf.into_box(slice.len()).assume_init() } } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "box_from_slice", since = "1.17.0")] impl From<&[T]> for Box<[T]> { /// Converts a `&[T]` into a `Box<[T]>` /// /// This conversion allocates on the heap /// and performs a copy of `slice` and its contents. /// /// # Examples /// ```rust /// // create a &[u8] which will be used to create a Box<[u8]> /// let slice: &[u8] = &[104, 101, 108, 108, 111]; /// let boxed_slice: Box<[u8]> = Box::from(slice); /// /// println!("{boxed_slice:?}"); /// ``` #[inline] fn from(slice: &[T]) -> Box<[T]> { >::from_slice(slice) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "box_from_mut_slice", since = "1.84.0")] impl From<&mut [T]> for Box<[T]> { /// Converts a `&mut [T]` into a `Box<[T]>` /// /// This conversion allocates on the heap /// and performs a copy of `slice` and its contents. /// /// # Examples /// ```rust /// // create a &mut [u8] which will be used to create a Box<[u8]> /// let mut array = [104, 101, 108, 108, 111]; /// let slice: &mut [u8] = &mut array; /// let boxed_slice: Box<[u8]> = Box::from(slice); /// /// println!("{boxed_slice:?}"); /// ``` #[inline] fn from(slice: &mut [T]) -> Box<[T]> { Self::from(&*slice) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "box_from_cow", since = "1.45.0")] impl From> for Box<[T]> { /// Converts a `Cow<'_, [T]>` into a `Box<[T]>` /// /// When `cow` is the `Cow::Borrowed` variant, this /// conversion allocates on the heap and copies the /// underlying slice. Otherwise, it will try to reuse the owned /// `Vec`'s allocation. #[inline] fn from(cow: Cow<'_, [T]>) -> Box<[T]> { match cow { Cow::Borrowed(slice) => Box::from(slice), Cow::Owned(slice) => Box::from(slice), } } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "box_from_slice", since = "1.17.0")] impl From<&str> for Box { /// Converts a `&str` into a `Box` /// /// This conversion allocates on the heap /// and performs a copy of `s`. /// /// # Examples /// /// ```rust /// let boxed: Box = Box::from("hello"); /// println!("{boxed}"); /// ``` #[inline] fn from(s: &str) -> Box { unsafe { from_boxed_utf8_unchecked(Box::from(s.as_bytes())) } } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "box_from_mut_slice", since = "1.84.0")] impl From<&mut str> for Box { /// Converts a `&mut str` into a `Box` /// /// This conversion allocates on the heap /// and performs a copy of `s`. /// /// # Examples /// /// ```rust /// let mut original = String::from("hello"); /// let original: &mut str = &mut original; /// let boxed: Box = Box::from(original); /// println!("{boxed}"); /// ``` #[inline] fn from(s: &mut str) -> Box { Self::from(&*s) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "box_from_cow", since = "1.45.0")] impl From> for Box { /// Converts a `Cow<'_, str>` into a `Box` /// /// When `cow` is the `Cow::Borrowed` variant, this /// conversion allocates on the heap and copies the /// underlying `str`. Otherwise, it will try to reuse the owned /// `String`'s allocation. /// /// # Examples /// /// ```rust /// use std::borrow::Cow; /// /// let unboxed = Cow::Borrowed("hello"); /// let boxed: Box = Box::from(unboxed); /// println!("{boxed}"); /// ``` /// /// ```rust /// # use std::borrow::Cow; /// let unboxed = Cow::Owned("hello".to_string()); /// let boxed: Box = Box::from(unboxed); /// println!("{boxed}"); /// ``` #[inline] fn from(cow: Cow<'_, str>) -> Box { match cow { Cow::Borrowed(s) => Box::from(s), Cow::Owned(s) => Box::from(s), } } } #[stable(feature = "boxed_str_conv", since = "1.19.0")] impl From> for Box<[u8], A> { /// Converts a `Box` into a `Box<[u8]>` /// /// This conversion does not allocate on the heap and happens in place. /// /// # Examples /// ```rust /// // create a Box which will be used to create a Box<[u8]> /// let boxed: Box = Box::from("hello"); /// let boxed_str: Box<[u8]> = Box::from(boxed); /// /// // create a &[u8] which will be used to create a Box<[u8]> /// let slice: &[u8] = &[104, 101, 108, 108, 111]; /// let boxed_slice = Box::from(slice); /// /// assert_eq!(boxed_slice, boxed_str); /// ``` #[inline] fn from(s: Box) -> Self { let (raw, alloc) = Box::into_raw_with_allocator(s); unsafe { Box::from_raw_in(raw as *mut [u8], alloc) } } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "box_from_array", since = "1.45.0")] impl From<[T; N]> for Box<[T]> { /// Converts a `[T; N]` into a `Box<[T]>` /// /// This conversion moves the array to newly heap-allocated memory. /// /// # Examples /// /// ```rust /// let boxed: Box<[u8]> = Box::from([4, 2]); /// println!("{boxed:?}"); /// ``` fn from(array: [T; N]) -> Box<[T]> { Box::new(array) } } /// Casts a boxed slice to a boxed array. /// /// # Safety /// /// `boxed_slice.len()` must be exactly `N`. unsafe fn boxed_slice_as_array_unchecked( boxed_slice: Box<[T], A>, ) -> Box<[T; N], A> { debug_assert_eq!(boxed_slice.len(), N); let (ptr, alloc) = Box::into_raw_with_allocator(boxed_slice); // SAFETY: Pointer and allocator came from an existing box, // and our safety condition requires that the length is exactly `N` unsafe { Box::from_raw_in(ptr as *mut [T; N], alloc) } } #[stable(feature = "boxed_slice_try_from", since = "1.43.0")] impl TryFrom> for Box<[T; N]> { type Error = Box<[T]>; /// Attempts to convert a `Box<[T]>` into a `Box<[T; N]>`. /// /// The conversion occurs in-place and does not require a /// new memory allocation. /// /// # Errors /// /// Returns the old `Box<[T]>` in the `Err` variant if /// `boxed_slice.len()` does not equal `N`. fn try_from(boxed_slice: Box<[T]>) -> Result { if boxed_slice.len() == N { Ok(unsafe { boxed_slice_as_array_unchecked(boxed_slice) }) } else { Err(boxed_slice) } } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "boxed_array_try_from_vec", since = "1.66.0")] impl TryFrom> for Box<[T; N]> { type Error = Vec; /// Attempts to convert a `Vec` into a `Box<[T; N]>`. /// /// Like [`Vec::into_boxed_slice`], this is in-place if `vec.capacity() == N`, /// but will require a reallocation otherwise. /// /// # Errors /// /// Returns the original `Vec` in the `Err` variant if /// `boxed_slice.len()` does not equal `N`. /// /// # Examples /// /// This can be used with [`vec!`] to create an array on the heap: /// /// ``` /// let state: Box<[f32; 100]> = vec![1.0; 100].try_into().unwrap(); /// assert_eq!(state.len(), 100); /// ``` fn try_from(vec: Vec) -> Result { if vec.len() == N { let boxed_slice = vec.into_boxed_slice(); Ok(unsafe { boxed_slice_as_array_unchecked(boxed_slice) }) } else { Err(vec) } } } impl Box { /// Attempts to downcast the box to a concrete type. /// /// # Examples /// /// ``` /// use std::any::Any; /// /// fn print_if_string(value: Box) { /// if let Ok(string) = value.downcast::() { /// println!("String ({}): {}", string.len(), string); /// } /// } /// /// let my_string = "Hello World".to_string(); /// print_if_string(Box::new(my_string)); /// print_if_string(Box::new(0i8)); /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn downcast(self) -> Result, Self> { if self.is::() { unsafe { Ok(self.downcast_unchecked::()) } } else { Err(self) } } /// Downcasts the box to a concrete type. /// /// For a safe alternative see [`downcast`]. /// /// # Examples /// /// ``` /// #![feature(downcast_unchecked)] /// /// use std::any::Any; /// /// let x: Box = Box::new(1_usize); /// /// unsafe { /// assert_eq!(*x.downcast_unchecked::(), 1); /// } /// ``` /// /// # Safety /// /// The contained value must be of type `T`. Calling this method /// with the incorrect type is *undefined behavior*. /// /// [`downcast`]: Self::downcast #[inline] #[unstable(feature = "downcast_unchecked", issue = "90850")] pub unsafe fn downcast_unchecked(self) -> Box { debug_assert!(self.is::()); unsafe { let (raw, alloc): (*mut dyn Any, _) = Box::into_raw_with_allocator(self); Box::from_raw_in(raw as *mut T, alloc) } } } impl Box { /// Attempts to downcast the box to a concrete type. /// /// # Examples /// /// ``` /// use std::any::Any; /// /// fn print_if_string(value: Box) { /// if let Ok(string) = value.downcast::() { /// println!("String ({}): {}", string.len(), string); /// } /// } /// /// let my_string = "Hello World".to_string(); /// print_if_string(Box::new(my_string)); /// print_if_string(Box::new(0i8)); /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn downcast(self) -> Result, Self> { if self.is::() { unsafe { Ok(self.downcast_unchecked::()) } } else { Err(self) } } /// Downcasts the box to a concrete type. /// /// For a safe alternative see [`downcast`]. /// /// # Examples /// /// ``` /// #![feature(downcast_unchecked)] /// /// use std::any::Any; /// /// let x: Box = Box::new(1_usize); /// /// unsafe { /// assert_eq!(*x.downcast_unchecked::(), 1); /// } /// ``` /// /// # Safety /// /// The contained value must be of type `T`. Calling this method /// with the incorrect type is *undefined behavior*. /// /// [`downcast`]: Self::downcast #[inline] #[unstable(feature = "downcast_unchecked", issue = "90850")] pub unsafe fn downcast_unchecked(self) -> Box { debug_assert!(self.is::()); unsafe { let (raw, alloc): (*mut (dyn Any + Send), _) = Box::into_raw_with_allocator(self); Box::from_raw_in(raw as *mut T, alloc) } } } impl Box { /// Attempts to downcast the box to a concrete type. /// /// # Examples /// /// ``` /// use std::any::Any; /// /// fn print_if_string(value: Box) { /// if let Ok(string) = value.downcast::() { /// println!("String ({}): {}", string.len(), string); /// } /// } /// /// let my_string = "Hello World".to_string(); /// print_if_string(Box::new(my_string)); /// print_if_string(Box::new(0i8)); /// ``` #[inline] #[stable(feature = "box_send_sync_any_downcast", since = "1.51.0")] pub fn downcast(self) -> Result, Self> { if self.is::() { unsafe { Ok(self.downcast_unchecked::()) } } else { Err(self) } } /// Downcasts the box to a concrete type. /// /// For a safe alternative see [`downcast`]. /// /// # Examples /// /// ``` /// #![feature(downcast_unchecked)] /// /// use std::any::Any; /// /// let x: Box = Box::new(1_usize); /// /// unsafe { /// assert_eq!(*x.downcast_unchecked::(), 1); /// } /// ``` /// /// # Safety /// /// The contained value must be of type `T`. Calling this method /// with the incorrect type is *undefined behavior*. /// /// [`downcast`]: Self::downcast #[inline] #[unstable(feature = "downcast_unchecked", issue = "90850")] pub unsafe fn downcast_unchecked(self) -> Box { debug_assert!(self.is::()); unsafe { let (raw, alloc): (*mut (dyn Any + Send + Sync), _) = Box::into_raw_with_allocator(self); Box::from_raw_in(raw as *mut T, alloc) } } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "rust1", since = "1.0.0")] impl<'a, E: Error + 'a> From for Box { /// Converts a type of [`Error`] into a box of dyn [`Error`]. /// /// # Examples /// /// ``` /// use std::error::Error; /// use std::fmt; /// /// #[derive(Debug)] /// struct AnError; /// /// impl fmt::Display for AnError { /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { /// write!(f, "An error") /// } /// } /// /// impl Error for AnError {} /// /// let an_error = AnError; /// assert!(0 == size_of_val(&an_error)); /// let a_boxed_error = Box::::from(an_error); /// assert!(size_of::>() == size_of_val(&a_boxed_error)) /// ``` fn from(err: E) -> Box { Box::new(err) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "rust1", since = "1.0.0")] impl<'a, E: Error + Send + Sync + 'a> From for Box { /// Converts a type of [`Error`] + [`Send`] + [`Sync`] into a box of /// dyn [`Error`] + [`Send`] + [`Sync`]. /// /// # Examples /// /// ``` /// use std::error::Error; /// use std::fmt; /// /// #[derive(Debug)] /// struct AnError; /// /// impl fmt::Display for AnError { /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { /// write!(f, "An error") /// } /// } /// /// impl Error for AnError {} /// /// unsafe impl Send for AnError {} /// /// unsafe impl Sync for AnError {} /// /// let an_error = AnError; /// assert!(0 == size_of_val(&an_error)); /// let a_boxed_error = Box::::from(an_error); /// assert!( /// size_of::>() == size_of_val(&a_boxed_error)) /// ``` fn from(err: E) -> Box { Box::new(err) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "rust1", since = "1.0.0")] impl<'a> From for Box { /// Converts a [`String`] into a box of dyn [`Error`] + [`Send`] + [`Sync`]. /// /// # Examples /// /// ``` /// use std::error::Error; /// /// let a_string_error = "a string error".to_string(); /// let a_boxed_error = Box::::from(a_string_error); /// assert!( /// size_of::>() == size_of_val(&a_boxed_error)) /// ``` #[inline] fn from(err: String) -> Box { struct StringError(String); impl Error for StringError { #[allow(deprecated)] fn description(&self) -> &str { &self.0 } } impl fmt::Display for StringError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fmt::Display::fmt(&self.0, f) } } // Purposefully skip printing "StringError(..)" impl fmt::Debug for StringError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fmt::Debug::fmt(&self.0, f) } } Box::new(StringError(err)) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "string_box_error", since = "1.6.0")] impl<'a> From for Box { /// Converts a [`String`] into a box of dyn [`Error`]. /// /// # Examples /// /// ``` /// use std::error::Error; /// /// let a_string_error = "a string error".to_string(); /// let a_boxed_error = Box::::from(a_string_error); /// assert!(size_of::>() == size_of_val(&a_boxed_error)) /// ``` fn from(str_err: String) -> Box { let err1: Box = From::from(str_err); let err2: Box = err1; err2 } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "rust1", since = "1.0.0")] impl<'a> From<&str> for Box { /// Converts a [`str`] into a box of dyn [`Error`] + [`Send`] + [`Sync`]. /// /// [`str`]: prim@str /// /// # Examples /// /// ``` /// use std::error::Error; /// /// let a_str_error = "a str error"; /// let a_boxed_error = Box::::from(a_str_error); /// assert!( /// size_of::>() == size_of_val(&a_boxed_error)) /// ``` #[inline] fn from(err: &str) -> Box { From::from(String::from(err)) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "string_box_error", since = "1.6.0")] impl<'a> From<&str> for Box { /// Converts a [`str`] into a box of dyn [`Error`]. /// /// [`str`]: prim@str /// /// # Examples /// /// ``` /// use std::error::Error; /// /// let a_str_error = "a str error"; /// let a_boxed_error = Box::::from(a_str_error); /// assert!(size_of::>() == size_of_val(&a_boxed_error)) /// ``` fn from(err: &str) -> Box { From::from(String::from(err)) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "cow_box_error", since = "1.22.0")] impl<'a, 'b> From> for Box { /// Converts a [`Cow`] into a box of dyn [`Error`] + [`Send`] + [`Sync`]. /// /// # Examples /// /// ``` /// use std::error::Error; /// use std::borrow::Cow; /// /// let a_cow_str_error = Cow::from("a str error"); /// let a_boxed_error = Box::::from(a_cow_str_error); /// assert!( /// size_of::>() == size_of_val(&a_boxed_error)) /// ``` fn from(err: Cow<'b, str>) -> Box { From::from(String::from(err)) } } #[cfg(not(no_global_oom_handling))] #[stable(feature = "cow_box_error", since = "1.22.0")] impl<'a, 'b> From> for Box { /// Converts a [`Cow`] into a box of dyn [`Error`]. /// /// # Examples /// /// ``` /// use std::error::Error; /// use std::borrow::Cow; /// /// let a_cow_str_error = Cow::from("a str error"); /// let a_boxed_error = Box::::from(a_cow_str_error); /// assert!(size_of::>() == size_of_val(&a_boxed_error)) /// ``` fn from(err: Cow<'b, str>) -> Box { From::from(String::from(err)) } } impl dyn Error { /// Attempts to downcast the box to a concrete type. #[inline] #[stable(feature = "error_downcast", since = "1.3.0")] #[rustc_allow_incoherent_impl] pub fn downcast(self: Box) -> Result, Box> { if self.is::() { unsafe { let raw: *mut dyn Error = Box::into_raw(self); Ok(Box::from_raw(raw as *mut T)) } } else { Err(self) } } } impl dyn Error + Send { /// Attempts to downcast the box to a concrete type. #[inline] #[stable(feature = "error_downcast", since = "1.3.0")] #[rustc_allow_incoherent_impl] pub fn downcast(self: Box) -> Result, Box> { let err: Box = self; ::downcast(err).map_err(|s| unsafe { // Reapply the `Send` marker. mem::transmute::, Box>(s) }) } } impl dyn Error + Send + Sync { /// Attempts to downcast the box to a concrete type. #[inline] #[stable(feature = "error_downcast", since = "1.3.0")] #[rustc_allow_incoherent_impl] pub fn downcast(self: Box) -> Result, Box> { let err: Box = self; ::downcast(err).map_err(|s| unsafe { // Reapply the `Send + Sync` markers. mem::transmute::, Box>(s) }) } }