Rollup merge of #156810 - Teufelchen1:fix_doc_typo, r=SimonSapin

Fix doc typo in Vec::into_array and convert Arc/Box/Rc::into_arry to -> Result

Hello 🪼,

the first commit fixes a documentation mistake added in the recent PR #156234

The second commit addresses three function signature changes as defined by the tracking issue #148082
It converts all `.into_array() -> Option<>` into `.into_array() -> Result<>`

The third commit is a fixup for the second. The change is needed as calling `unwrap()` on `Err(E)` requires `E` to implement `Debug`. I thought `Vec<T, A> where T: Debug` is not an acceptable solution, so I tried to come up with my own. I am *NOT* confident in my `unsafe {}`  code due to lack of expierence, please check extra carefully.

Appreciating feedback & greetings from the RustWeek,
Thanks!

Author: jhpratt

library/alloc/src/boxed.rs

@@ -1142,7 +1142,9 @@ impl<T, A: Allocator> Box<[T], A> {
     ///
     /// This operation does not reallocate; the underlying array of the slice is simply reinterpreted as an array type.
     ///
-    /// If `N` is not exactly equal to the length of `self`, then this method returns `None`.
+    /// # Errors
+    ///
+    /// Returns the original `Box<[T]>` in the `Err` variant if `self.len()` does not equal `N`.
     ///
     /// # Examples
     ///
@@ -1155,16 +1157,16 @@ impl<T, A: Allocator> Box<[T], A> {
     #[unstable(feature = "alloc_slice_into_array", issue = "148082")]
     #[inline]
     #[must_use]
-    pub fn into_array<const N: usize>(self) -> Option<Box<[T; N], A>> {
+    pub fn into_array<const N: usize>(self) -> Result<Box<[T; N], A>, Self> {
         if self.len() == N {
             let (ptr, alloc) = Self::into_raw_with_allocator(self);
             let ptr = ptr as *mut [T; N];
 
             // 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.
             let me = unsafe { Box::from_raw_in(ptr, alloc) };
-            Some(me)
+            Ok(me)
         } else {
-            None
+            Err(self)
         }
     }
 }

library/alloc/src/rc.rs

@@ -1245,7 +1245,9 @@ impl<T, A: Allocator> Rc<[T], A> {
     ///
     /// This operation does not reallocate; the underlying array of the slice is simply reinterpreted as an array type.
     ///
-    /// If `N` is not exactly equal to the length of `self`, then this method returns `None`.
+    /// # Errors
+    ///
+    /// Returns the original `Rc<[T]>` in the `Err` variant if `self.len()` does not equal `N`.
     ///
     /// # Examples
     ///
@@ -1260,16 +1262,16 @@ impl<T, A: Allocator> Rc<[T], A> {
     #[unstable(feature = "alloc_slice_into_array", issue = "148082")]
     #[inline]
     #[must_use]
-    pub fn into_array<const N: usize>(self) -> Option<Rc<[T; N], A>> {
+    pub fn into_array<const N: usize>(self) -> Result<Rc<[T; N], A>, Self> {
         if self.len() == N {
             let (ptr, alloc) = Self::into_raw_with_allocator(self);
             let ptr = ptr as *const [T; N];
 
             // 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.
             let me = unsafe { Rc::from_raw_in(ptr, alloc) };
-            Some(me)
+            Ok(me)
         } else {
-            None
+            Err(self)
         }
     }
 }

library/alloc/src/sync.rs

@@ -1392,7 +1392,9 @@ impl<T, A: Allocator> Arc<[T], A> {
     ///
     /// This operation does not reallocate; the underlying array of the slice is simply reinterpreted as an array type.
     ///
-    /// If `N` is not exactly equal to the length of `self`, then this method returns `None`.
+    /// # Errors
+    ///
+    /// Returns the original `Arc<[T]>` in the `Err` variant if `self.len()` does not equal `N`.
     ///
     /// # Examples
     ///
@@ -1407,16 +1409,16 @@ impl<T, A: Allocator> Arc<[T], A> {
     #[unstable(feature = "alloc_slice_into_array", issue = "148082")]
     #[inline]
     #[must_use]
-    pub fn into_array<const N: usize>(self) -> Option<Arc<[T; N], A>> {
+    pub fn into_array<const N: usize>(self) -> Result<Arc<[T; N], A>, Self> {
         if self.len() == N {
             let (ptr, alloc) = Self::into_raw_with_allocator(self);
             let ptr = ptr as *const [T; N];
 
             // 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.
             let me = unsafe { Arc::from_raw_in(ptr, alloc) };
-            Some(me)
+            Ok(me)
         } else {
-            None
+            Err(self)
         }
     }
 }

library/alloc/src/vec/mod.rs

@@ -1740,10 +1740,13 @@ impl<T, A: Allocator> Vec<T, A> {
         }
     }
 
-    /// Converts the Vec into a boxed array. This conversion will discard any spare capacity, if there is any, see [`Vec::shrink_to_fit`].
+    /// Converts the Vec into a boxed array. This conversion will discard any spare capacity,
+    /// if there is any, see [`Vec::shrink_to_fit`].
     /// If you merely wish for a reference to an array, use [`as_array`](https://doc.rust-lang.org/stable/std/primitive.slice.html#method.as_array).
     ///
-    /// If `N` is not exactly equal to [`Vec::len`], then this method returns `None`.
+    /// # Errors
+    ///
+    /// Returns the original `Vec<T>` in the `Err` variant if [`Vec::len`] does not equal `N`.
     ///
     /// # Examples
     ///
@@ -1758,7 +1761,11 @@ impl<T, A: Allocator> Vec<T, A> {
     #[unstable(feature = "alloc_slice_into_array", issue = "148082")]
     #[must_use]
     pub fn into_array<const N: usize>(self) -> Result<Box<[T; N], A>, Self> {
-        if self.len() == N { Ok(self.into_boxed_slice().into_array().unwrap()) } else { Err(self) }
+        if self.len() == N {
+            Ok(self.into_boxed_slice().into_array().ok().unwrap())
+        } else {
+            Err(self)
+        }
     }
 
     /// Shortens the vector, keeping the first `len` elements and dropping