append: Add try_append_row and try_append_column

For Array2 specifically, and only when the memory layout lines up for
efficient and simple append, allow appending rows and/or columns to an
array.

Author: bluss

src/data_repr.rs

@@ -6,6 +6,8 @@ use alloc::borrow::ToOwned;
 use alloc::vec::Vec;
 use crate::extension::nonnull;
 
+use rawpointer::PointerExt;
+
 /// Array's representation.
 ///
 /// *Don’t use this type directly—use the type alias
@@ -55,6 +57,37 @@ impl<A> OwnedRepr<A> {
         self.ptr
     }
 
+    /// Return end pointer
+    pub(crate) fn as_end_nonnull(&self) -> NonNull<A> {
+        unsafe {
+            self.ptr.add(self.len)
+        }
+    }
+
+    /// Reserve `additional` elements; return the new pointer
+    /// 
+    /// ## Safety
+    ///
+    /// Note that existing pointers into the data are invalidated
+    #[must_use = "must use new pointer to update existing pointers"]
+    pub(crate) fn reserve(&mut self, additional: usize) -> NonNull<A> {
+        self.modify_as_vec(|mut v| {
+            v.reserve(additional);
+            v
+        });
+        self.as_nonnull_mut()
+    }
+
+    /// Set the valid length of the data
+    ///
+    /// ## Safety
+    ///
+    /// The first `new_len` elements of the data should be valid.
+    pub(crate) unsafe fn set_len(&mut self, new_len: usize) {
+        debug_assert!(new_len <= self.capacity);
+        self.len = new_len;
+    }
+
     /// Cast self into equivalent repr of other element type
     ///
     /// ## Safety
@@ -72,6 +105,11 @@ impl<A> OwnedRepr<A> {
         }
     }
 
+    fn modify_as_vec(&mut self, f: impl FnOnce(Vec<A>) -> Vec<A>) {
+        let v = self.take_as_vec();
+        *self = Self::from(f(v));
+    }
+
     fn take_as_vec(&mut self) -> Vec<A> {
         let capacity = self.capacity;
         let len = self.len;

src/impl_owned_array.rs

@@ -1,6 +1,11 @@
 
 use alloc::vec::Vec;
+
 use crate::imp_prelude::*;
+use crate::dimension;
+use crate::error::{ErrorKind, ShapeError};
+use crate::OwnedRepr;
+use crate::Zip;
 
 /// Methods specific to `Array0`.
 ///
@@ -59,3 +64,142 @@ where
         self.data.into_vec()
     }
 }
+
+/// Methods specific to `Array2`.
+///
+/// ***See also all methods for [`ArrayBase`]***
+///
+/// [`ArrayBase`]: struct.ArrayBase.html
+impl<A> Array<A, Ix2> {
+    /// Append a row to an array with row major memory layout.
+    ///
+    /// ***Errors*** with a layout error if the array is not in standard order or
+    /// if it has holes, even exterior holes (from slicing). <br>
+    /// ***Errors*** with shape error if the length of the input row does not match
+    /// the length of the rows in the array. <br>
+    ///
+    /// The memory layout matters, since it determines in which direction the array can easily
+    /// grow. Notice that an empty array is compatible both ways. The amortized average
+    /// complexity of the append is O(m) where *m* is the length of the row.
+    ///
+    /// ```rust
+    /// use ndarray::{Array, ArrayView, array};
+    ///
+    /// // create an empty array and append
+    /// let mut a = Array::zeros((0, 4));
+    /// a.try_append_row(ArrayView::from(&[ 1.,  2.,  3.,  4.])).unwrap();
+    /// a.try_append_row(ArrayView::from(&[-1., -2., -3., -4.])).unwrap();
+    ///
+    /// assert_eq!(
+    ///     a,
+    ///     array![[ 1.,  2.,  3.,  4.],
+    ///            [-1., -2., -3., -4.]]);
+    /// ```
+    pub fn try_append_row(&mut self, row: ArrayView<A, Ix1>) -> Result<(), ShapeError>
+    where
+        A: Clone,
+    {
+        let row_len = row.len();
+        if row_len != self.len_of(Axis(1)) {
+            return Err(ShapeError::from_kind(ErrorKind::IncompatibleShape));
+        }
+        let mut res_dim = self.raw_dim();
+        res_dim[0] += 1;
+        let new_len = dimension::size_of_shape_checked(&res_dim)?;
+
+        // array must be c-contiguous and be "full" (have no exterior holes)
+        if !self.is_standard_layout() || self.len() != self.data.len() {
+            return Err(ShapeError::from_kind(ErrorKind::IncompatibleLayout));
+        }
+
+        unsafe {
+            // grow backing storage and update head ptr
+            debug_assert_eq!(self.data.as_ptr(), self.as_ptr());
+            self.ptr = self.data.reserve(row_len);  // because we are standard order
+
+            // recompute strides - if the array was previously empty, it could have
+            // zeros in strides.
+            let strides = res_dim.default_strides();
+
+            // copy elements from view to the array now
+            //
+            // make a raw view with the new row
+            // safe because the data was "full"
+            let tail_ptr = self.data.as_end_nonnull();
+            let tail_view = RawArrayViewMut::new(tail_ptr, Ix1(row_len), Ix1(1));
+
+            struct SetLenOnDrop<'a, A: 'a> {
+                len: usize,
+                data: &'a mut OwnedRepr<A>,
+            }
+
+            let mut length_guard = SetLenOnDrop {
+                len: self.data.len(),
+                data: &mut self.data,
+            };
+
+            impl<A> Drop for SetLenOnDrop<'_, A> {
+                fn drop(&mut self) {
+                    unsafe {
+                        self.data.set_len(self.len);
+                    }
+                }
+            }
+
+            // assign the new elements
+            Zip::from(tail_view).and(row)
+                .for_each(|to, from| {
+                    to.write(from.clone());
+                    length_guard.len += 1;
+                });
+
+            drop(length_guard);
+
+            // update array dimension
+            self.strides = strides;
+            self.dim[0] += 1;
+
+        }
+        // multiple assertions after pointer & dimension update
+        debug_assert_eq!(self.data.len(), self.len());
+        debug_assert_eq!(self.len(), new_len);
+        debug_assert!(self.is_standard_layout());
+
+        Ok(())
+    }
+
+    /// Append a column to an array with column major memory layout.
+    ///
+    /// ***Errors*** with a layout error if the array is not in column major order or
+    /// if it has holes, even exterior holes (from slicing). <br>
+    /// ***Errors*** with shape error if the length of the input column does not match
+    /// the length of the columns in the array.<br>
+    ///
+    /// The memory layout matters, since it determines in which direction the array can easily
+    /// grow. Notice that an empty array is compatible both ways. The amortized average
+    /// complexity of the append is O(m) where *m* is the length of the column.
+    ///
+    /// ```rust
+    /// use ndarray::{Array, ArrayView, array};
+    ///
+    /// // create an empty array and append
+    /// let mut a = Array::zeros((2, 0));
+    /// a.try_append_column(ArrayView::from(&[1., 2.])).unwrap();
+    /// a.try_append_column(ArrayView::from(&[-1., -2.])).unwrap();
+    ///
+    /// assert_eq!(
+    ///     a,
+    ///     array![[1., -1.],
+    ///            [2., -2.]]);
+    /// ```
+    pub fn try_append_column(&mut self, column: ArrayView<A, Ix1>) -> Result<(), ShapeError>
+    where
+        A: Clone,
+    {
+        self.swap_axes(0, 1);
+        let ret = self.try_append_row(column);
+        self.swap_axes(0, 1);
+        ret
+    }
+}
+

src/lib.rs

@@ -235,8 +235,8 @@ pub type Ixs = isize;
 
 /// An *n*-dimensional array.
 ///
-/// The array is a general container of elements. It cannot grow or shrink, but
-/// can be sliced into subsets of its data.
+/// The array is a general container of elements. It cannot grow or shrink (with some exceptions),
+/// but can be sliced into subsets of its data.
 /// The array supports arithmetic operations by applying them elementwise.
 ///
 /// In *n*-dimensional we include for example 1-dimensional rows or columns,

tests/append.rs

@@ -0,0 +1,84 @@
+
+use ndarray::prelude::*;
+use ndarray::{ShapeError, ErrorKind};
+
+#[test]
+fn append_row() {
+    let mut a = Array::zeros((0, 4));
+    a.try_append_row(aview1(&[0., 1., 2., 3.])).unwrap();
+    a.try_append_row(aview1(&[4., 5., 6., 7.])).unwrap();
+    assert_eq!(a.shape(), &[2, 4]);
+
+    assert_eq!(a,
+        array![[0., 1., 2., 3.],
+               [4., 5., 6., 7.]]);
+
+    assert_eq!(a.try_append_row(aview1(&[1.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleShape)));
+    assert_eq!(a.try_append_column(aview1(&[1.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleShape)));
+    assert_eq!(a.try_append_column(aview1(&[1., 2.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleLayout)));
+}
+
+#[test]
+fn append_row_error() {
+    let mut a = Array::zeros((3, 4));
+
+    assert_eq!(a.try_append_row(aview1(&[1.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleShape)));
+    assert_eq!(a.try_append_column(aview1(&[1.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleShape)));
+    assert_eq!(a.try_append_column(aview1(&[1., 2., 3.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleLayout)));
+}
+
+#[test]
+fn append_row_existing() {
+    let mut a = Array::zeros((1, 4));
+    a.try_append_row(aview1(&[0., 1., 2., 3.])).unwrap();
+    a.try_append_row(aview1(&[4., 5., 6., 7.])).unwrap();
+    assert_eq!(a.shape(), &[3, 4]);
+
+    assert_eq!(a,
+        array![[0., 0., 0., 0.],
+               [0., 1., 2., 3.],
+               [4., 5., 6., 7.]]);
+
+    assert_eq!(a.try_append_row(aview1(&[1.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleShape)));
+    assert_eq!(a.try_append_column(aview1(&[1.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleShape)));
+    assert_eq!(a.try_append_column(aview1(&[1., 2., 3.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleLayout)));
+}
+
+#[test]
+fn append_row_col_len_1() {
+    // Test appending 1 row and then cols from shape 1 x 1
+    let mut a = Array::zeros((1, 1));
+    a.try_append_row(aview1(&[1.])).unwrap(); // shape 2 x 1
+    a.try_append_column(aview1(&[2., 3.])).unwrap(); // shape 2 x 2
+    assert_eq!(a.try_append_row(aview1(&[1.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleShape)));
+    assert_eq!(a.try_append_row(aview1(&[1., 2.])),
+        Err(ShapeError::from_kind(ErrorKind::IncompatibleLayout)));
+    a.try_append_column(aview1(&[4., 5.])).unwrap(); // shape 2 x 3
+    assert_eq!(a.shape(), &[2, 3]);
+
+    assert_eq!(a,
+        array![[0., 2., 4.],
+               [1., 3., 5.]]);
+}
+
+#[test]
+fn append_column() {
+    let mut a = Array::zeros((4, 0));
+    a.try_append_column(aview1(&[0., 1., 2., 3.])).unwrap();
+    a.try_append_column(aview1(&[4., 5., 6., 7.])).unwrap();
+    assert_eq!(a.shape(), &[4, 2]);
+
+    assert_eq!(a.t(),
+        array![[0., 1., 2., 3.],
+               [4., 5., 6., 7.]]);
+}