Renamed stack to concatenate and added numpy-compliant stack

function

Author: andrei-papou

src/doc/ndarray_for_numpy_users/mod.rs

@@ -532,7 +532,8 @@
 //! ------|-----------|------
 //! `a[:] = 3.` | [`a.fill(3.)`][.fill()] | set all array elements to the same scalar value
 //! `a[:] = b` | [`a.assign(&b)`][.assign()] | copy the data from array `b` into array `a`
-//! `np.concatenate((a,b), axis=1)` | [`stack![Axis(1), a, b]`][stack!] or [`stack(Axis(1), &[a.view(), b.view()])`][stack()] | concatenate arrays `a` and `b` along axis 1
+//! `np.concatenate((a,b), axis=1)` | [`concatenate![Axis(1), a, b]`][concatenate!] or [`concatenate(Axis(1), &[a.view(), b.view()])`][concatenate()] | concatenate arrays `a` and `b` along axis 1
+//! `np.stack((a,b), axis=1)` | [`stack![Axis(1), a, b]`][stack!] or [`stack(Axis(1), vec![a.view(), b.view()])`][stack()] | stack arrays `a` and `b` along axis 1
 //! `a[:,np.newaxis]` or `np.expand_dims(a, axis=1)` | [`a.insert_axis(Axis(1))`][.insert_axis()] | create an array from `a`, inserting a new axis 1
 //! `a.transpose()` or `a.T` | [`a.t()`][.t()] or [`a.reversed_axes()`][.reversed_axes()] | transpose of array `a` (view for `.t()` or by-move for `.reversed_axes()`)
 //! `np.diag(a)` | [`a.diag()`][.diag()] | view the diagonal of `a`
@@ -640,6 +641,8 @@
 //! [.slice_move()]: ../../struct.ArrayBase.html#method.slice_move
 //! [.slice_mut()]: ../../struct.ArrayBase.html#method.slice_mut
 //! [.shape()]: ../../struct.ArrayBase.html#method.shape
+//! [concatenate!]: ../../macro.concatenate.html
+//! [concatenate()]: ../../fn.concatenate.html
 //! [stack!]: ../../macro.stack.html
 //! [stack()]: ../../fn.stack.html
 //! [.strides()]: ../../struct.ArrayBase.html#method.strides

src/impl_methods.rs

@@ -28,7 +28,7 @@ use crate::iter::{
     IndexedIter, IndexedIterMut, Iter, IterMut, Lanes, LanesMut, Windows,
 };
 use crate::slice::MultiSlice;
-use crate::stacking::stack;
+use crate::stacking::concatenate;
 use crate::{NdIndex, Slice, SliceInfo, SliceOrIndex};
 
 /// # Methods For All Array Types
@@ -840,7 +840,7 @@ where
             dim.set_axis(axis, 0);
             unsafe { Array::from_shape_vec_unchecked(dim, vec![]) }
         } else {
-            stack(axis, &subs).unwrap()
+            concatenate(axis, &subs).unwrap()
         }
     }
 

src/lib.rs

@@ -131,7 +131,7 @@ use crate::iterators::{ElementsBase, ElementsBaseMut, Iter, IterMut, Lanes, Lane
 
 pub use crate::arraytraits::AsArray;
 pub use crate::linalg_traits::{LinalgScalar, NdFloat};
-pub use crate::stacking::stack;
+pub use crate::stacking::{concatenate, stack};
 
 pub use crate::impl_views::IndexLonger;
 pub use crate::shape_builder::ShapeBuilder;

src/stacking.rs

@@ -17,21 +17,21 @@ use crate::imp_prelude::*;
 /// if the result is larger than is possible to represent.
 ///
 /// ```
-/// use ndarray::{arr2, Axis, stack};
+/// use ndarray::{arr2, Axis, concatenate};
 ///
 /// let a = arr2(&[[2., 2.],
 ///                [3., 3.]]);
 /// assert!(
-///     stack(Axis(0), &[a.view(), a.view()])
+///     concatenate(Axis(0), &[a.view(), a.view()])
 ///     == Ok(arr2(&[[2., 2.],
 ///                  [3., 3.],
 ///                  [2., 2.],
 ///                  [3., 3.]]))
 /// );
 /// ```
-pub fn stack<'a, A, D>(
+pub fn concatenate<A, D>(
     axis: Axis,
-    arrays: &[ArrayView<'a, A, D>],
+    arrays: &[ArrayView<A, D>],
 ) -> Result<Array<A, D>, ShapeError>
 where
     A: Copy,
@@ -76,26 +76,45 @@ where
     Ok(res)
 }
 
-/// Stack arrays along the given axis.
+pub fn stack<A, D>(
+    axis: Axis,
+    arrays: Vec<ArrayView<A, D>>,
+) -> Result<Array<A, D::Larger>, ShapeError>
+where
+    A: Copy,
+    D: Dimension,
+    D::Larger: RemoveAxis,
+{
+    if let Some(ndim) = D::NDIM {
+        if axis.index() > ndim {
+            return Err(from_kind(ErrorKind::OutOfBounds));
+        }
+    }
+    let arrays: Vec<ArrayView<A, D::Larger>> = arrays.into_iter()
+        .map(|a| a.insert_axis(axis)).collect();
+    concatenate(axis, &arrays)
+}
+
+/// Concatenate arrays along the given axis.
 ///
-/// Uses the [`stack`][1] function, calling `ArrayView::from(&a)` on each
+/// Uses the [`concatenate`][1] function, calling `ArrayView::from(&a)` on each
 /// argument `a`.
 ///
-/// [1]: fn.stack.html
+/// [1]: fn.concatenate.html
 ///
-/// ***Panics*** if the `stack` function would return an error.
+/// ***Panics*** if the `concatenate` function would return an error.
 ///
 /// ```
 /// extern crate ndarray;
 ///
-/// use ndarray::{arr2, stack, Axis};
+/// use ndarray::{arr2, concatenate, Axis};
 ///
 /// # fn main() {
 ///
 /// let a = arr2(&[[2., 2.],
 ///                [3., 3.]]);
 /// assert!(
-///     stack![Axis(0), a, a]
+///     concatenate![Axis(0), a, a]
 ///     == arr2(&[[2., 2.],
 ///               [3., 3.],
 ///               [2., 2.],
@@ -104,8 +123,42 @@ where
 /// # }
 /// ```
 #[macro_export]
+macro_rules! concatenate {
+    ($axis:expr, $( $array:expr ),+ ) => {
+        $crate::concatenate($axis, &[ $($crate::ArrayView::from(&$array) ),* ]).unwrap()
+    }
+}
+
+/// Stack arrays along the new axis.
+///
+/// Uses the [`stack`][1] function, calling `ArrayView::from(&a)` on each
+/// argument `a`.
+///
+/// [1]: fn.concatenate.html
+///
+/// ***Panics*** if the `stack` function would return an error.
+///
+/// ```
+/// extern crate ndarray;
+///
+/// use ndarray::{arr2, arr3, stack, Axis};
+///
+/// # fn main() {
+///
+/// let a = arr2(&[[2., 2.],
+///                [3., 3.]]);
+/// assert!(
+///     stack![Axis(0), a, a]
+///     == arr3(&[[[2., 2.],
+///                [3., 3.]],
+///               [[2., 2.],
+///                [3., 3.]]])
+/// );
+/// # }
+/// ```
+#[macro_export]
 macro_rules! stack {
     ($axis:expr, $( $array:expr ),+ ) => {
-        $crate::stack($axis, &[ $($crate::ArrayView::from(&$array) ),* ]).unwrap()
+        $crate::stack($axis, vec![ $($crate::ArrayView::from(&$array) ),* ]).unwrap()
     }
 }

tests/stacking.rs

@@ -1,26 +1,43 @@
-use ndarray::{arr2, aview1, stack, Array2, Axis, ErrorKind};
+use ndarray::{arr2, arr3, aview1, concatenate, Array2, Axis, ErrorKind, Ix1};
 
 #[test]
-fn stacking() {
+fn concatenating() {
     let a = arr2(&[[2., 2.], [3., 3.]]);
-    let b = ndarray::stack(Axis(0), &[a.view(), a.view()]).unwrap();
+    let b = ndarray::concatenate(Axis(0), &[a.view(), a.view()]).unwrap();
     assert_eq!(b, arr2(&[[2., 2.], [3., 3.], [2., 2.], [3., 3.]]));
 
-    let c = stack![Axis(0), a, b];
+    let c = concatenate![Axis(0), a, b];
     assert_eq!(
         c,
         arr2(&[[2., 2.], [3., 3.], [2., 2.], [3., 3.], [2., 2.], [3., 3.]])
     );
 
-    let d = stack![Axis(0), a.row(0), &[9., 9.]];
+    let d = concatenate![Axis(0), a.row(0), &[9., 9.]];
     assert_eq!(d, aview1(&[2., 2., 9., 9.]));
 
-    let res = ndarray::stack(Axis(1), &[a.view(), c.view()]);
+    let res = ndarray::concatenate(Axis(1), &[a.view(), c.view()]);
+    assert_eq!(res.unwrap_err().kind(), ErrorKind::IncompatibleShape);
+
+    let res = ndarray::concatenate(Axis(2), &[a.view(), c.view()]);
+    assert_eq!(res.unwrap_err().kind(), ErrorKind::OutOfBounds);
+
+    let res: Result<Array2<f64>, _> = ndarray::concatenate(Axis(0), &[]);
+    assert_eq!(res.unwrap_err().kind(), ErrorKind::Unsupported);
+}
+
+#[test]
+fn stacking() {
+    let a = arr2(&[[2., 2.], [3., 3.]]);
+    let b = ndarray::stack(Axis(0), vec![a.view(), a.view()]).unwrap();
+    assert_eq!(b, arr3(&[[[2., 2.], [3., 3.]], [[2., 2.], [3., 3.]]]));
+
+    let c = arr2(&[[3., 2., 3.], [2., 3., 2.]]);
+    let res = ndarray::stack(Axis(1), vec![a.view(), c.view()]);
     assert_eq!(res.unwrap_err().kind(), ErrorKind::IncompatibleShape);
 
-    let res = ndarray::stack(Axis(2), &[a.view(), c.view()]);
+    let res = ndarray::stack(Axis(3), vec![a.view(), a.view()]);
     assert_eq!(res.unwrap_err().kind(), ErrorKind::OutOfBounds);
 
-    let res: Result<Array2<f64>, _> = ndarray::stack(Axis(0), &[]);
+    let res: Result<Array2<f64>, _> = ndarray::stack::<_, Ix1>(Axis(0), vec![]);
     assert_eq!(res.unwrap_err().kind(), ErrorKind::Unsupported);
 }