Introduced concatenate function, deprecated stack function since 0.13.0

Author: andrei.papou

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, stack_new_axis};
+pub use crate::stacking::{concatenate, stack, stack_new_axis};
 
 pub use crate::impl_views::IndexLonger;
 pub use crate::shape_builder::ShapeBuilder;

src/stacking.rs

@@ -9,7 +9,7 @@
 use crate::error::{from_kind, ErrorKind, ShapeError};
 use crate::imp_prelude::*;
 
-/// Stack arrays along the given axis.
+/// Concatenate arrays along the given axis.
 ///
 /// ***Errors*** if the arrays have mismatching shapes, apart from along `axis`.
 /// (may be made more flexible in the future).<br>
@@ -29,6 +29,10 @@ use crate::imp_prelude::*;
 ///                  [3., 3.]]))
 /// );
 /// ```
+#[deprecated(
+    since = "0.13.0",
+    note = "Please use the `concatenate` function instead"
+)]
 pub fn stack<A, D>(axis: Axis, arrays: &[ArrayView<A, D>]) -> Result<Array<A, D>, ShapeError>
 where
     A: Copy,
@@ -73,6 +77,34 @@ where
     Ok(res)
 }
 
+/// Concatenate arrays along the given axis.
+///
+/// ***Errors*** if the arrays have mismatching shapes, apart from along `axis`.
+/// (may be made more flexible in the future).<br>
+/// ***Errors*** if `arrays` is empty, if `axis` is out of bounds,
+/// if the result is larger than is possible to represent.
+///
+/// ```
+/// use ndarray::{arr2, Axis, concatenate};
+///
+/// let a = arr2(&[[2., 2.],
+///                [3., 3.]]);
+/// assert!(
+///     concatenate(Axis(0), &[a.view(), a.view()])
+///     == Ok(arr2(&[[2., 2.],
+///                  [3., 3.],
+///                  [2., 2.],
+///                  [3., 3.]]))
+/// );
+/// ```
+pub fn concatenate<A, D>(axis: Axis, arrays: &[ArrayView<A, D>]) -> Result<Array<A, D>, ShapeError>
+where
+    A: Copy,
+    D: RemoveAxis,
+{
+    stack(axis, arrays)
+}
+
 pub fn stack_new_axis<A, D>(
     axis: Axis,
     arrays: Vec<ArrayView<A, D>>,
@@ -123,7 +155,7 @@ where
 ///
 /// [1]: fn.stack.html
 ///
-/// ***Panics*** if the `concatenate` function would return an error.
+/// ***Panics*** if the `stack` function would return an error.
 ///
 /// ```
 /// extern crate ndarray;
@@ -150,6 +182,40 @@ macro_rules! stack {
     }
 }
 
+/// Concatenate arrays along the given axis.
+///
+/// Uses the [`concatenate`][1] function, calling `ArrayView::from(&a)` on each
+/// argument `a`.
+///
+/// [1]: fn.concatenate.html
+///
+/// ***Panics*** if the `concatenate` function would return an error.
+///
+/// ```
+/// extern crate ndarray;
+///
+/// use ndarray::{arr2, concatenate, Axis};
+///
+/// # fn main() {
+///
+/// let a = arr2(&[[2., 2.],
+///                [3., 3.]]);
+/// assert!(
+///     concatenate![Axis(0), a, a]
+///     == arr2(&[[2., 2.],
+///               [3., 3.],
+///               [2., 2.],
+///               [3., 3.]])
+/// );
+/// # }
+/// ```
+#[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_new_axis`][1] function, calling `ArrayView::from(&a)` on each

tests/stacking.rs

@@ -1,4 +1,4 @@
-use ndarray::{arr2, arr3, aview1, stack, Array2, Axis, ErrorKind, Ix1};
+use ndarray::{arr2, arr3, aview1, concatenate, stack, Array2, Axis, ErrorKind, Ix1};
 
 #[test]
 fn concatenating() {
@@ -23,6 +23,28 @@ fn concatenating() {
 
     let res: Result<Array2<f64>, _> = ndarray::stack(Axis(0), &[]);
     assert_eq!(res.unwrap_err().kind(), ErrorKind::Unsupported);
+
+    let a = arr2(&[[2., 2.], [3., 3.]]);
+    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 = concatenate![Axis(0), a, b];
+    assert_eq!(
+        c,
+        arr2(&[[2., 2.], [3., 3.], [2., 2.], [3., 3.], [2., 2.], [3., 3.]])
+    );
+
+    let d = concatenate![Axis(0), a.row(0), &[9., 9.]];
+    assert_eq!(d, aview1(&[2., 2., 9., 9.]));
+
+    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]