API: Deprecate Array::uninitialized. Use Array::uninit instead

Array::uninitialized is very hard to use correctly (internally and for
our users). Prefer the new API with Array::uninit using `MaybeUninit<_>`
instead.

Author: bluss

src/impl_constructors.rs

@@ -478,41 +478,6 @@ where
         }
     }
 
-    /// Create an array with uninitalized elements, shape `shape`.
-    ///
-    /// Prefer to use [`uninit()`](ArrayBase::uninit) if possible, because it is
-    /// easier to use correctly.
-    ///
-    /// **Panics** if the number of elements in `shape` would overflow isize.
-    ///
-    /// ### Safety
-    ///
-    /// Accessing uninitalized values is undefined behaviour. You must overwrite *all* the elements
-    /// in the array after it is created; for example using
-    /// [`raw_view_mut`](ArrayBase::raw_view_mut) or other low-level element access.
-    ///
-    /// The contents of the array is indeterminate before initialization and it
-    /// is an error to perform operations that use the previous values. For
-    /// example it would not be legal to use `a += 1.;` on such an array.
-    ///
-    /// This constructor is limited to elements where `A: Copy` (no destructors)
-    /// to avoid users shooting themselves too hard in the foot.
-    ///
-    /// (Also note that the constructors `from_shape_vec` and
-    /// `from_shape_vec_unchecked` allow the user yet more control, in the sense
-    /// that Arrays can be created from arbitrary vectors.)
-    pub unsafe fn uninitialized<Sh>(shape: Sh) -> Self
-    where
-        A: Copy,
-        Sh: ShapeBuilder<Dim = D>,
-    {
-        let shape = shape.into_shape();
-        let size = size_of_shape_checked_unwrap!(&shape.dim);
-        let mut v = Vec::with_capacity(size);
-        v.set_len(size);
-        Self::from_shape_vec_unchecked(shape, v)
-    }
-
     /// Create an array with uninitalized elements, shape `shape`.
     ///
     /// The uninitialized elements of type `A` are represented by the type `MaybeUninit<A>`,
@@ -619,6 +584,44 @@ where
         }
         array
     }
+
+    #[deprecated(note = "This method is hard to use correctly. Use `uninit` instead.",
+                 since = "0.15.0")]
+    /// Create an array with uninitalized elements, shape `shape`.
+    ///
+    /// Prefer to use [`uninit()`](ArrayBase::uninit) if possible, because it is
+    /// easier to use correctly.
+    ///
+    /// **Panics** if the number of elements in `shape` would overflow isize.
+    ///
+    /// ### Safety
+    ///
+    /// Accessing uninitalized values is undefined behaviour. You must overwrite *all* the elements
+    /// in the array after it is created; for example using
+    /// [`raw_view_mut`](ArrayBase::raw_view_mut) or other low-level element access.
+    ///
+    /// The contents of the array is indeterminate before initialization and it
+    /// is an error to perform operations that use the previous values. For
+    /// example it would not be legal to use `a += 1.;` on such an array.
+    ///
+    /// This constructor is limited to elements where `A: Copy` (no destructors)
+    /// to avoid users shooting themselves too hard in the foot.
+    ///
+    /// (Also note that the constructors `from_shape_vec` and
+    /// `from_shape_vec_unchecked` allow the user yet more control, in the sense
+    /// that Arrays can be created from arbitrary vectors.)
+    pub unsafe fn uninitialized<Sh>(shape: Sh) -> Self
+    where
+        A: Copy,
+        Sh: ShapeBuilder<Dim = D>,
+    {
+        let shape = shape.into_shape();
+        let size = size_of_shape_checked_unwrap!(&shape.dim);
+        let mut v = Vec::with_capacity(size);
+        v.set_len(size);
+        Self::from_shape_vec_unchecked(shape, v)
+    }
+
 }
 
 impl<S, A, D> ArrayBase<S, D>

tests/array-construct.rs

@@ -52,6 +52,7 @@ fn test_arcarray_thread_safe() {
 
 #[test]
 #[cfg(feature = "std")]
+#[allow(deprecated)] // uninitialized
 fn test_uninit() {
     unsafe {
         let mut a = Array::<f32, _>::uninitialized((3, 4).f());
@@ -192,12 +193,19 @@ fn deny_wraparound_from_shape_fn() {
 
 #[should_panic]
 #[test]
-fn deny_wraparound_uninit() {
+#[allow(deprecated)] // uninitialized
+fn deny_wraparound_uninitialized() {
     unsafe {
         let _five_large = Array::<f32, _>::uninitialized((3, 7, 29, 36760123, 823996703));
     }
 }
 
+#[should_panic]
+#[test]
+fn deny_wraparound_uninit() {
+    let _five_large = Array::<f32, _>::uninit((3, 7, 29, 36760123, 823996703));
+}
+
 
 #[test]
 fn maybe_uninit_1() {