99use crate :: error:: { from_kind, ErrorKind , ShapeError } ;
1010use crate :: imp_prelude:: * ;
1111
12- /// Stack arrays along the given axis.
12+ /// Concatenate arrays along the given axis.
1313///
1414/// ***Errors*** if the arrays have mismatching shapes, apart from along `axis`.
1515/// (may be made more flexible in the future).<br>
@@ -29,10 +29,11 @@ use crate::imp_prelude::*;
2929/// [3., 3.]]))
3030/// );
3131/// ```
32- pub fn stack < ' a , A , D > (
33- axis : Axis ,
34- arrays : & [ ArrayView < ' a , A , D > ] ,
35- ) -> Result < Array < A , D > , ShapeError >
32+ #[ deprecated(
33+ since = "0.13.2" ,
34+ note = "Please use the `concatenate` function instead"
35+ ) ]
36+ pub fn stack < A , D > ( axis : Axis , arrays : & [ ArrayView < A , D > ] ) -> Result < Array < A , D > , ShapeError >
3637where
3738 A : Copy ,
3839 D : RemoveAxis ,
@@ -76,7 +77,103 @@ where
7677 Ok ( res)
7778}
7879
79- /// Stack arrays along the given axis.
80+ /// Concatenate arrays along the given axis.
81+ ///
82+ /// ***Errors*** if the arrays have mismatching shapes, apart from along `axis`.
83+ /// (may be made more flexible in the future).<br>
84+ /// ***Errors*** if `arrays` is empty, if `axis` is out of bounds,
85+ /// if the result is larger than is possible to represent.
86+ ///
87+ /// ```
88+ /// use ndarray::{arr2, Axis, concatenate};
89+ ///
90+ /// let a = arr2(&[[2., 2.],
91+ /// [3., 3.]]);
92+ /// assert!(
93+ /// concatenate(Axis(0), &[a.view(), a.view()])
94+ /// == Ok(arr2(&[[2., 2.],
95+ /// [3., 3.],
96+ /// [2., 2.],
97+ /// [3., 3.]]))
98+ /// );
99+ /// ```
100+ #[ allow( deprecated) ]
101+ pub fn concatenate < A , D > ( axis : Axis , arrays : & [ ArrayView < A , D > ] ) -> Result < Array < A , D > , ShapeError >
102+ where
103+ A : Copy ,
104+ D : RemoveAxis ,
105+ {
106+ stack ( axis, arrays)
107+ }
108+
109+ /// Stack arrays along the new axis.
110+ ///
111+ /// ***Errors*** if the arrays have mismatching shapes.
112+ /// ***Errors*** if `arrays` is empty, if `axis` is out of bounds,
113+ /// if the result is larger than is possible to represent.
114+ ///
115+ /// ```
116+ /// extern crate ndarray;
117+ ///
118+ /// use ndarray::{arr2, arr3, stack_new_axis, Axis};
119+ ///
120+ /// # fn main() {
121+ ///
122+ /// let a = arr2(&[[2., 2.],
123+ /// [3., 3.]]);
124+ /// assert!(
125+ /// stack_new_axis(Axis(0), &[a.view(), a.view()])
126+ /// == Ok(arr3(&[[[2., 2.],
127+ /// [3., 3.]],
128+ /// [[2., 2.],
129+ /// [3., 3.]]]))
130+ /// );
131+ /// # }
132+ /// ```
133+ pub fn stack_new_axis < A , D > (
134+ axis : Axis ,
135+ arrays : & [ ArrayView < A , D > ] ,
136+ ) -> Result < Array < A , D :: Larger > , ShapeError >
137+ where
138+ A : Copy ,
139+ D : Dimension ,
140+ D :: Larger : RemoveAxis ,
141+ {
142+ if arrays. is_empty ( ) {
143+ return Err ( from_kind ( ErrorKind :: Unsupported ) ) ;
144+ }
145+ let common_dim = arrays[ 0 ] . raw_dim ( ) ;
146+ // Avoid panic on `insert_axis` call, return an Err instead of it.
147+ if axis. index ( ) > common_dim. ndim ( ) {
148+ return Err ( from_kind ( ErrorKind :: OutOfBounds ) ) ;
149+ }
150+ let mut res_dim = common_dim. insert_axis ( axis) ;
151+
152+ if arrays. iter ( ) . any ( |a| a. raw_dim ( ) != common_dim) {
153+ return Err ( from_kind ( ErrorKind :: IncompatibleShape ) ) ;
154+ }
155+
156+ res_dim. set_axis ( axis, arrays. len ( ) ) ;
157+
158+ // we can safely use uninitialized values here because they are Copy
159+ // and we will only ever write to them
160+ let size = res_dim. size ( ) ;
161+ let mut v = Vec :: with_capacity ( size) ;
162+ unsafe {
163+ v. set_len ( size) ;
164+ }
165+ let mut res = Array :: from_shape_vec ( res_dim, v) ?;
166+
167+ res. axis_iter_mut ( axis)
168+ . zip ( arrays. into_iter ( ) )
169+ . for_each ( |( mut assign_view, array) | {
170+ assign_view. assign ( & array) ;
171+ } ) ;
172+
173+ Ok ( res)
174+ }
175+
176+ /// Concatenate arrays along the given axis.
80177///
81178/// Uses the [`stack`][1] function, calling `ArrayView::from(&a)` on each
82179/// argument `a`.
@@ -101,9 +198,81 @@ where
101198/// );
102199/// # }
103200/// ```
201+ #[ deprecated(
202+ since = "0.13.2" ,
203+ note = "Please use the `concatenate!` macro instead"
204+ ) ]
104205#[ macro_export]
105206macro_rules! stack {
106207 ( $axis: expr, $( $array: expr ) ,+ ) => {
107208 $crate:: stack( $axis, & [ $( $crate:: ArrayView :: from( & $array) ) ,* ] ) . unwrap( )
108209 }
109210}
211+
212+ /// Concatenate arrays along the given axis.
213+ ///
214+ /// Uses the [`concatenate`][1] function, calling `ArrayView::from(&a)` on each
215+ /// argument `a`.
216+ ///
217+ /// [1]: fn.concatenate.html
218+ ///
219+ /// ***Panics*** if the `concatenate` function would return an error.
220+ ///
221+ /// ```
222+ /// extern crate ndarray;
223+ ///
224+ /// use ndarray::{arr2, concatenate, Axis};
225+ ///
226+ /// # fn main() {
227+ ///
228+ /// let a = arr2(&[[2., 2.],
229+ /// [3., 3.]]);
230+ /// assert!(
231+ /// concatenate![Axis(0), a, a]
232+ /// == arr2(&[[2., 2.],
233+ /// [3., 3.],
234+ /// [2., 2.],
235+ /// [3., 3.]])
236+ /// );
237+ /// # }
238+ /// ```
239+ #[ macro_export]
240+ macro_rules! concatenate {
241+ ( $axis: expr, $( $array: expr ) ,+ ) => {
242+ $crate:: concatenate( $axis, & [ $( $crate:: ArrayView :: from( & $array) ) ,* ] ) . unwrap( )
243+ }
244+ }
245+
246+ /// Stack arrays along the new axis.
247+ ///
248+ /// Uses the [`stack_new_axis`][1] function, calling `ArrayView::from(&a)` on each
249+ /// argument `a`.
250+ ///
251+ /// [1]: fn.stack_new_axis.html
252+ ///
253+ /// ***Panics*** if the `stack` function would return an error.
254+ ///
255+ /// ```
256+ /// extern crate ndarray;
257+ ///
258+ /// use ndarray::{arr2, arr3, stack_new_axis, Axis};
259+ ///
260+ /// # fn main() {
261+ ///
262+ /// let a = arr2(&[[2., 2.],
263+ /// [3., 3.]]);
264+ /// assert!(
265+ /// stack_new_axis![Axis(0), a, a]
266+ /// == arr3(&[[[2., 2.],
267+ /// [3., 3.]],
268+ /// [[2., 2.],
269+ /// [3., 3.]]])
270+ /// );
271+ /// # }
272+ /// ```
273+ #[ macro_export]
274+ macro_rules! stack_new_axis {
275+ ( $axis: expr, $( $array: expr ) ,+ ) => {
276+ $crate:: stack_new_axis( $axis, & [ $( $crate:: ArrayView :: from( & $array) ) ,* ] ) . unwrap( )
277+ }
278+ }
0 commit comments