From 6a52fb730310cdfec267b1da5cc48cce073647e3 Mon Sep 17 00:00:00 2001 From: Tim McNamara Date: Fri, 8 Oct 2021 21:40:25 +1300 Subject: [PATCH 1/3] Add documentation to boxed conversions Among other changes, documents whether allocations are necessary to complete the type conversion. Part of #51430 Co-authored-by: Giacomo Stevanato Co-authored-by: Joshua Nelson --- library/alloc/src/boxed.rs | 41 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/library/alloc/src/boxed.rs b/library/alloc/src/boxed.rs index 2b3a18a439fc9..1eff1f9e3078a 100644 --- a/library/alloc/src/boxed.rs +++ b/library/alloc/src/boxed.rs @@ -1277,6 +1277,7 @@ impl From for Box { /// from the stack into it. /// /// # Examples + /// /// ```rust /// let x = 5; /// let boxed = Box::new(5); @@ -1330,6 +1331,12 @@ impl From<&[T]> for Box<[T]> { #[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 performs a copy of the + /// underlying slice. Otherwise, it will try to re-use the owned + /// vec's allocation. #[inline] fn from(cow: Cow<'_, [T]>) -> Box<[T]> { match cow { @@ -1348,6 +1355,7 @@ impl From<&str> for Box { /// and performs a copy of `s`. /// /// # Examples + /// /// ```rust /// let boxed: Box = Box::from("hello"); /// println!("{}", boxed); @@ -1361,6 +1369,29 @@ impl From<&str> for Box { #[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 performs a copy of the + /// underlying `str`. Otherwise, it will try to re-use 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 { @@ -1403,6 +1434,7 @@ impl From<[T; N]> for Box<[T]> { /// This conversion moves the array to newly heap-allocated memory. /// /// # Examples + /// /// ```rust /// let boxed: Box<[u8]> = Box::from([4, 2]); /// println!("{:?}", boxed); @@ -1416,6 +1448,15 @@ impl From<[T; N]> for Box<[T]> { 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 { Box::from_raw(Box::into_raw(boxed_slice) as *mut [T; N]) }) From fa5a2128963177b050958077f78699ca80370204 Mon Sep 17 00:00:00 2001 From: Tim McNamara Date: Sat, 9 Oct 2021 20:51:36 +1300 Subject: [PATCH 2/3] Simplify wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Josh Triplett Co-authored-by: Laurențiu Nicola --- library/alloc/src/boxed.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/library/alloc/src/boxed.rs b/library/alloc/src/boxed.rs index 1eff1f9e3078a..f47be50898367 100644 --- a/library/alloc/src/boxed.rs +++ b/library/alloc/src/boxed.rs @@ -1334,9 +1334,9 @@ 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 performs a copy of the - /// underlying slice. Otherwise, it will try to re-use the owned - /// vec's allocation. + /// 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 { @@ -1372,7 +1372,7 @@ 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 performs a copy of the + /// conversion allocates on the heap and copies the /// underlying `str`. Otherwise, it will try to re-use the owned /// `String`'s allocation. /// From 020ec0a03967f16ca5a4ba2a33472a8da912986d Mon Sep 17 00:00:00 2001 From: Tim McNamara Date: Sat, 9 Oct 2021 21:44:07 +1300 Subject: [PATCH 3/3] Remove unnecessary hyphen MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Laurențiu Nicola --- library/alloc/src/boxed.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/alloc/src/boxed.rs b/library/alloc/src/boxed.rs index f47be50898367..85f908a7f5c7b 100644 --- a/library/alloc/src/boxed.rs +++ b/library/alloc/src/boxed.rs @@ -1373,7 +1373,7 @@ impl From> for Box { /// /// When `cow` is the `Cow::Borrowed` variant, this /// conversion allocates on the heap and copies the - /// underlying `str`. Otherwise, it will try to re-use the owned + /// underlying `str`. Otherwise, it will try to reuse the owned /// `String`'s allocation. /// /// # Examples