Add insert/index_axis_inplace for IxDyn arrays

Without these methods, users must have ownership of
dynamic-dimensional arrays to insert/remove axes, which is
unnecessarily restrictive.

Author: jturner314

src/impl_dyn.rs

@@ -0,0 +1,58 @@
+// Copyright 2018 bluss and ndarray developers.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Methods for dynamic-dimensional arrays.
+use imp_prelude::*;
+
+/// # Methods for Dynamic-Dimensional Arrays
+impl<A, S> ArrayBase<S, IxDyn>
+where
+    S: Data<Elem = A>,
+{
+    /// Insert new array axis of length 1 at `axis`, modifying the shape and
+    /// strides in-place.
+    ///
+    /// **Panics** if the axis is out of bounds.
+    ///
+    /// ```
+    /// use ndarray::{Axis, arr2, arr3};
+    ///
+    /// let mut a = arr2(&[[1, 2, 3], [4, 5, 6]]).into_dyn();
+    /// assert_eq!(a.shape(), &[2, 3]);
+    ///
+    /// a.insert_axis_inplace(Axis(1));
+    /// assert_eq!(a, arr3(&[[[1, 2, 3]], [[4, 5, 6]]]).into_dyn());
+    /// assert_eq!(a.shape(), &[2, 1, 3]);
+    /// ```
+    pub fn insert_axis_inplace(&mut self, axis: Axis) {
+        assert!(axis.index() <= self.ndim());
+        self.dim = self.dim.insert_axis(axis);
+        self.strides = self.strides.insert_axis(axis);
+    }
+
+    /// Collapses the array to `index` along the axis and removes the axis,
+    /// modifying the shape and strides in-place.
+    ///
+    /// **Panics** if `axis` or `index` is out of bounds.
+    ///
+    /// ```
+    /// use ndarray::{Axis, arr1, arr2};
+    ///
+    /// let mut a = arr2(&[[1, 2, 3], [4, 5, 6]]).into_dyn();
+    /// assert_eq!(a.shape(), &[2, 3]);
+    ///
+    /// a.index_axis_inplace(Axis(1), 1);
+    /// assert_eq!(a, arr1(&[2, 5]).into_dyn());
+    /// assert_eq!(a.shape(), &[2]);
+    /// ```
+    pub fn index_axis_inplace(&mut self, axis: Axis, index: usize) {
+        self.collapse_axis(axis, index);
+        self.dim = self.dim.remove_axis(axis);
+        self.strides = self.strides.remove_axis(axis);
+    }
+}

src/lib.rs

@@ -242,6 +242,7 @@ pub type Ixs = isize;
 /// + [Methods For All Array Types](#methods-for-all-array-types)
 /// + [Methods For 1-D Arrays](#methods-for-1-d-arrays)
 /// + [Methods For 2-D Arrays](#methods-for-2-d-arrays)
+/// + [Methods for Dynamic-Dimensional Arrays](#methods-for-dynamic-dimensional-arrays)
 /// + [Numerical Methods for Arrays](#numerical-methods-for-arrays)
 ///
 /// ## `Array`
@@ -522,11 +523,12 @@ pub type Ixs = isize;
 ///
 /// Subview methods allow you to restrict the array view while removing one
 /// axis from the array. Methods for selecting individual subviews include
-/// [`.index_axis()`], [`.index_axis_mut()`], and [`.index_axis_move()`]. You
-/// can also select a subview by using a single index instead of a range when
-/// slicing. Some other methods, such as [`.fold_axis()`], [`.axis_iter()`],
-/// [`.axis_iter_mut()`], [`.outer_iter()`], and [`.outer_iter_mut()`] operate
-/// on all the subviews along an axis.
+/// [`.index_axis()`], [`.index_axis_mut()`], [`.index_axis_move()`], and
+/// [`.index_axis_inplace()`]. You can also select a subview by using a single
+/// index instead of a range when slicing. Some other methods, such as
+/// [`.fold_axis()`], [`.axis_iter()`], [`.axis_iter_mut()`],
+/// [`.outer_iter()`], and [`.outer_iter_mut()`] operate on all the subviews
+/// along an axis.
 ///
 /// A related method is [`.collapse_axis()`], which modifies the view in the
 /// same way as [`.index_axis()`] except for removing the collapsed axis, since
@@ -539,6 +541,7 @@ pub type Ixs = isize;
 /// [`.axis_iter_mut()`]: #method.axis_iter_mut
 /// [`.fold_axis()`]: #method.fold_axis
 /// [`.index_axis()`]: #method.index_axis
+/// [`.index_axis_inplace()`]: #method.index_axis_inplace
 /// [`.index_axis_mut()`]: #method.index_axis_mut
 /// [`.index_axis_move()`]: #method.index_axis_move
 /// [`.collapse_axis()`]: #method.collapse_axis
@@ -1143,6 +1146,7 @@ impl<A, S, D> ArrayBase<S, D>
 
 mod impl_1d;
 mod impl_2d;
+mod impl_dyn;
 
 mod numeric;