From b089e79562aff01cee9b6246f9352ffecef4b3b9 Mon Sep 17 00:00:00 2001 From: daniellimws Date: Mon, 29 Oct 2018 19:15:22 +0800 Subject: [PATCH 1/4] Add documentation for From impls --- src/liballoc/boxed.rs | 53 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs index f989e701913a5..da4651ca7793b 100644 --- a/src/liballoc/boxed.rs +++ b/src/liballoc/boxed.rs @@ -438,6 +438,18 @@ impl Hasher for Box { #[stable(feature = "from_for_ptrs", since = "1.6.0")] impl From for Box { + /// Converts a generic type `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) } @@ -445,6 +457,9 @@ impl From for Box { #[unstable(feature = "pin", issue = "49150")] impl From> for Pin> { + /// Converts a `Box` into a `Pin>` + /// + /// This conversion does not allocate on the heap and happens in place. fn from(boxed: Box) -> Self { // It's not possible to move or replace the insides of a `Pin>` // when `T: !Unpin`, so it's safe to pin it directly without any @@ -455,6 +470,19 @@ impl From> for Pin> { #[stable(feature = "box_from_slice", since = "1.17.0")] impl<'a, T: Copy> From<&'a [T]> for Box<[T]> { + /// Converts a `&[T]` into a `Box<[T]>` + /// + /// This conversion does not allocate on the heap + /// but performs a copy of `slice`. + /// + /// # 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::from(slice); + /// + /// println!({:?}, boxed_slice); + /// ``` fn from(slice: &'a [T]) -> Box<[T]> { let mut boxed = unsafe { RawVec::with_capacity(slice.len()).into_box() }; boxed.copy_from_slice(slice); @@ -464,6 +492,15 @@ impl<'a, T: Copy> From<&'a [T]> for Box<[T]> { #[stable(feature = "box_from_slice", since = "1.17.0")] impl<'a> From<&'a str> for Box { + /// Converts a `&str` into a `Box` + /// + /// This conversion does not allocate on the heap and happens in place. + /// + /// # Examples + /// ```rust + /// let boxed: Box = Box::from("hello"); + /// println!("{}", boxed); + /// ``` #[inline] fn from(s: &'a str) -> Box { unsafe { from_boxed_utf8_unchecked(Box::from(s.as_bytes())) } @@ -472,6 +509,22 @@ impl<'a> From<&'a str> for Box { #[stable(feature = "boxed_str_conv", since = "1.19.0")] impl From> for Box<[u8]> { + /// 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 { unsafe { Box::from_raw(Box::into_raw(s) as *mut [u8]) } From 15334e03b757c13578d15f49c5950eab21956437 Mon Sep 17 00:00:00 2001 From: daniellimws Date: Mon, 29 Oct 2018 19:37:58 +0800 Subject: [PATCH 2/4] Fix documentation for those that allocate on heap --- src/liballoc/boxed.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs index da4651ca7793b..8826a836a913a 100644 --- a/src/liballoc/boxed.rs +++ b/src/liballoc/boxed.rs @@ -472,8 +472,8 @@ impl From> for Pin> { impl<'a, T: Copy> From<&'a [T]> for Box<[T]> { /// Converts a `&[T]` into a `Box<[T]>` /// - /// This conversion does not allocate on the heap - /// but performs a copy of `slice`. + /// This conversion allocates on the heap + /// and performs a copy of `slice`. /// /// # Examples /// ```rust @@ -494,7 +494,8 @@ impl<'a, T: Copy> From<&'a [T]> for Box<[T]> { impl<'a> From<&'a str> for Box { /// Converts a `&str` into a `Box` /// - /// This conversion does not allocate on the heap and happens in place. + /// This conversion allocates on the heap + /// and performs a copy of `s`. /// /// # Examples /// ```rust From 6e099a698699d81eb2d18bf467ca75041a78bf4c Mon Sep 17 00:00:00 2001 From: daniellimws Date: Sat, 17 Nov 2018 00:21:23 +0800 Subject: [PATCH 3/4] Add double quotes to resolve error --- src/liballoc/boxed.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs index 8826a836a913a..1f1a4f249c727 100644 --- a/src/liballoc/boxed.rs +++ b/src/liballoc/boxed.rs @@ -481,7 +481,7 @@ impl<'a, T: Copy> From<&'a [T]> for Box<[T]> { /// let slice: &[u8] = &[104, 101, 108, 108, 111]; /// let boxed_slice = Box::from(slice); /// - /// println!({:?}, boxed_slice); + /// println!("{:?}", boxed_slice); /// ``` fn from(slice: &'a [T]) -> Box<[T]> { let mut boxed = unsafe { RawVec::with_capacity(slice.len()).into_box() }; From 5e2bfda19af0f00707ff0c19547127f902d36b97 Mon Sep 17 00:00:00 2001 From: daniellimws Date: Wed, 5 Dec 2018 23:31:35 +0800 Subject: [PATCH 4/4] Fix error in example by adding type annotation --- src/liballoc/boxed.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs index 1f1a4f249c727..c920dbc0c9566 100644 --- a/src/liballoc/boxed.rs +++ b/src/liballoc/boxed.rs @@ -479,7 +479,7 @@ impl<'a, T: Copy> From<&'a [T]> for Box<[T]> { /// ```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::from(slice); + /// let boxed_slice: Box<[u8]> = Box::from(slice); /// /// println!("{:?}", boxed_slice); /// ```