FEAT: Add constructor method build_uninit

This method allows creating any owned array and initializing it - the
method helps by giving mutable access even to normally copy-on-write
arrays, because when first created, the array is unshared.

Author: bluss

src/data_traits.rs

@@ -402,6 +402,13 @@ unsafe impl<'a, A> DataMut for ViewRepr<&'a mut A> {}
 /// A representation that is a unique or shared owner of its data.
 ///
 /// ***Internal trait, see `Data`.***
+// The owned storage represents the ownership and allocation of the array's elements.
+// The storage may be unique or shared ownership style; it must be an aliasable owner
+// (permit aliasing pointers, such as our separate array head pointer).
+//
+// The array storage must be initially mutable - copy on write arrays may require copying for
+// unsharing storage before mutating it. The initially allocated storage must be mutable so
+// that it can be mutated directly - through .raw_view_mut_unchecked() - for initialization.
 pub unsafe trait DataOwned: Data {
     /// Corresponding owned data with MaybeUninit elements
     type MaybeUninit: DataOwned<Elem = MaybeUninit<Self::Elem>>

src/impl_constructors.rs

@@ -586,6 +586,39 @@ where
             ArrayBase::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>`,
+    /// an easier way to handle uninit values correctly.
+    ///
+    /// The `builder` closure gets unshared access to the array through a raw view
+    /// and can use it to modify the array before it is returned. This allows initializing
+    /// the array for any owned array type (avoiding clone requirements for copy-on-write,
+    /// because the array is unshared when initially created).
+    ///
+    /// Only *when* the array is completely initialized with valid elements, can it be
+    /// converted to an array of `A` elements using [`.assume_init()`].
+    ///
+    /// **Panics** if the number of elements in `shape` would overflow isize.
+    ///
+    /// ### Safety
+    ///
+    /// The whole of the array must be initialized before it is converted
+    /// using [`.assume_init()`] or otherwise traversed.
+    ///
+    pub(crate) fn build_uninit<Sh, F>(shape: Sh, builder: F) -> ArrayBase<S::MaybeUninit, D>
+    where
+        Sh: ShapeBuilder<Dim = D>,
+        F: FnOnce(RawArrayViewMut<MaybeUninit<A>, D>),
+    {
+        let mut array = Self::uninit(shape);
+        // Safe because: the array is unshared here
+        unsafe {
+            builder(array.raw_view_mut_unchecked());
+        }
+        array
+    }
 }
 
 impl<S, A, D> ArrayBase<S, D>

src/impl_methods.rs

@@ -1383,6 +1383,17 @@ where
         unsafe { RawArrayViewMut::new(self.ptr, self.dim.clone(), self.strides.clone()) }
     }
 
+    /// Return a raw mutable view of the array.
+    ///
+    /// Safety: The caller must ensure that the owned array is unshared when this is called
+    #[inline]
+    pub(crate) unsafe fn raw_view_mut_unchecked(&mut self) -> RawArrayViewMut<A, D>
+    where
+        S: DataOwned,
+    {
+        RawArrayViewMut::new(self.ptr, self.dim.clone(), self.strides.clone())
+    }
+
     /// Return the array’s data as a slice, if it is contiguous and in standard order.
     /// Return `None` otherwise.
     ///