Rename subview to index_axis

Author: jturner314

examples/sort-axis.rs

@@ -110,7 +110,7 @@ impl<A, D> PermuteArray for Array<A, D>
             for i in 0..axis_len {
                 let perm_i = perm.indices[i];
                 Zip::from(result.index_axis_mut(axis, perm_i))
-                    .and(self.subview(axis, i))
+                    .and(self.index_axis(axis, i))
                     .apply(|to, from| {
                         copy_nonoverlapping(from, to, 1)
                     });

src/doc/ndarray_for_numpy_users/mod.rs

@@ -238,7 +238,7 @@
 //! ------|-----------|------
 //! `a[-1]` | [`a[a.len() - 1]`][.index()] | access the last element in 1-D array `a`
 //! `a[1, 4]` | [`a[[1, 4]]`][.index()] | access the element in row 1, column 4
-//! `a[1]` or `a[1, :, :]` | [`a.slice(s![1, .., ..])`][.slice()] or [`a.subview(Axis(0), 1)`][.subview()] | get a 2-D subview of a 3-D array at index 1 of axis 0
+//! `a[1]` or `a[1, :, :]` | [`a.slice(s![1, .., ..])`][.slice()] or [`a.index_axis(Axis(0), 1)`][.index_axis()] | get a 2-D subview of a 3-D array at index 1 of axis 0
 //! `a[0:5]` or `a[:5]` or `a[0:5, :]` | [`a.slice(s![0..5, ..])`][.slice()] or [`a.slice(s![..5, ..])`][.slice()] or [`a.slice_axis(Axis(0), Slice::from(0..5))`][.slice_axis()] | get the first 5 rows of a 2-D array
 //! `a[-5:]` or `a[-5:, :]` | [`a.slice(s![-5.., ..])`][.slice()] or [`a.slice_axis(Axis(0), Slice::from(-5..))`][.slice_axis()] | get the last 5 rows of a 2-D array
 //! `a[:3, 4:9]` | [`a.slice(s![..3, 4..9])`][.slice()] | columns 4, 5, 6, 7, and 8 of the first 3 rows
@@ -625,7 +625,7 @@
 //! [stack!]: ../../macro.stack.html
 //! [stack()]: ../../fn.stack.html
 //! [.strides()]: ../../struct.ArrayBase.html#method.strides
-//! [.subview()]: ../../struct.ArrayBase.html#method.subview
+//! [.index_axis()]: ../../struct.ArrayBase.html#method.index_axis
 //! [.sum_axis()]: ../../struct.ArrayBase.html#method.sum_axis
 //! [.t()]: ../../struct.ArrayBase.html#method.t
 //! [::uninitialized()]: ../../struct.ArrayBase.html#method.uninitialized

src/impl_2d.rs

@@ -19,7 +19,7 @@ impl<A, S> ArrayBase<S, Ix2>
     /// **Panics** if `index` is out of bounds.
     pub fn row(&self, index: Ix) -> ArrayView1<A>
     {
-        self.subview(Axis(0), index)
+        self.index_axis(Axis(0), index)
     }
 
     /// Return a mutable array view of row `index`.
@@ -41,7 +41,7 @@ impl<A, S> ArrayBase<S, Ix2>
     /// **Panics** if `index` is out of bounds.
     pub fn column(&self, index: Ix) -> ArrayView1<A>
     {
-        self.subview(Axis(1), index)
+        self.index_axis(Axis(1), index)
     }
 
     /// Return a mutable array view of column `index`.

src/impl_methods.rs

@@ -542,6 +542,34 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         }
     }
 
+    /// Along `axis`, select the subview `index` and return a
+    /// view with that axis removed.
+    ///
+    /// See [*Subviews*](#subviews) for full documentation.
+    ///
+    /// **Panics** if `axis` or `index` is out of bounds.
+    ///
+    /// ```
+    /// use ndarray::{arr2, ArrayView, Axis};
+    ///
+    /// let a = arr2(&[[1., 2. ],    // ... axis 0, row 0
+    ///                [3., 4. ],    // --- axis 0, row 1
+    ///                [5., 6. ]]);  // ... axis 0, row 2
+    /// //               .   \
+    /// //                .   axis 1, column 1
+    /// //                 axis 1, column 0
+    /// assert!(
+    ///     a.index_axis(Axis(0), 1) == ArrayView::from(&[3., 4.]) &&
+    ///     a.index_axis(Axis(1), 1) == ArrayView::from(&[2., 4., 6.])
+    /// );
+    /// ```
+    pub fn index_axis(&self, axis: Axis, index: usize) -> ArrayView<A, D::Smaller>
+    where
+        D: RemoveAxis,
+    {
+        self.view().index_axis_move(axis, index)
+    }
+
     /// Along `axis`, select the subview `index` and return a read-write view
     /// with the axis removed.
     ///
@@ -577,7 +605,7 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
     /// Along `axis`, select the subview `index` and return `self`
     /// with that axis removed.
     ///
-    /// See [`.subview()`](#method.subview) and [*Subviews*](#subviews) for full documentation.
+    /// See [`.index_axis()`](#method.index_axis) and [*Subviews*](#subviews) for full documentation.
     pub fn index_axis_move(mut self, axis: Axis, index: usize) -> ArrayBase<S, D::Smaller>
     where
         D: RemoveAxis,
@@ -603,28 +631,12 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
     /// Along `axis`, select the subview `index` and return a
     /// view with that axis removed.
     ///
-    /// See [*Subviews*](#subviews) for full documentation.
-    ///
     /// **Panics** if `axis` or `index` is out of bounds.
-    ///
-    /// ```
-    /// use ndarray::{arr2, ArrayView, Axis};
-    ///
-    /// let a = arr2(&[[1., 2. ],    // ... axis 0, row 0
-    ///                [3., 4. ],    // --- axis 0, row 1
-    ///                [5., 6. ]]);  // ... axis 0, row 2
-    /// //               .   \
-    /// //                .   axis 1, column 1
-    /// //                 axis 1, column 0
-    /// assert!(
-    ///     a.subview(Axis(0), 1) == ArrayView::from(&[3., 4.]) &&
-    ///     a.subview(Axis(1), 1) == ArrayView::from(&[2., 4., 6.])
-    /// );
-    /// ```
+    #[deprecated(note="renamed to `index_axis`", since="0.12.1")]
     pub fn subview(&self, axis: Axis, index: Ix) -> ArrayView<A, D::Smaller>
         where D: RemoveAxis,
     {
-        self.view().index_axis_move(axis, index)
+        self.index_axis(axis, index)
     }
 
     /// Along `axis`, select the subview `index` and return a read-write view
@@ -1894,7 +1906,7 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         let view_stride = self.strides.axis(axis);
         // use the 0th subview as a map to each 1d array view extended from
         // the 0th element.
-        self.subview(axis, 0).map(|first_elt| {
+        self.index_axis(axis, 0).map(|first_elt| {
             unsafe {
                 mapping(ArrayView::new_(first_elt, Ix1(view_len), Ix1(view_stride)))
             }

src/lib.rs

@@ -520,14 +520,14 @@ pub type Ixs = isize;
 /// ## Subviews
 ///
 /// Subview methods allow you to restrict the array view while removing one
-/// axis from the array. Subview methods include [`.subview()`],
+/// axis from the array. Subview methods include [`.index_axis()`],
 /// [`.index_axis_mut()`], [`.index_axis_move()`], and [`.collapse_axis()`]. You
 /// can also take a subview by using a single index instead of a range when
 /// slicing.
 ///
 /// Subview takes two arguments: `axis` and `index`.
 ///
-/// [`.subview()`]: #method.subview
+/// [`.index_axis()`]: #method.index_axis
 /// [`.index_axis_mut()`]: #method.index_axis_mut
 /// [`.index_axis_move()`]: #method.index_axis_move
 /// [`.collapse_axis()`]: #method.collapse_axis
@@ -553,8 +553,8 @@ pub type Ixs = isize;
 /// // Let’s take a subview along the greatest dimension (axis 0),
 /// // taking submatrix 0, then submatrix 1
 ///
-/// let sub_0 = a.subview(Axis(0), 0);
-/// let sub_1 = a.subview(Axis(0), 1);
+/// let sub_0 = a.index_axis(Axis(0), 0);
+/// let sub_1 = a.index_axis(Axis(0), 1);
 ///
 /// assert_eq!(sub_0, aview2(&[[ 1,  2,  3],
 ///                            [ 4,  5,  6]]));
@@ -563,7 +563,7 @@ pub type Ixs = isize;
 /// assert_eq!(sub_0.shape(), &[2, 3]);
 ///
 /// // This is the subview picking only axis 2, column 0
-/// let sub_col = a.subview(Axis(2), 0);
+/// let sub_col = a.index_axis(Axis(2), 0);
 ///
 /// assert_eq!(sub_col, aview2(&[[ 1,  4],
 ///                              [ 7, 10]]));
@@ -574,7 +574,7 @@ pub type Ixs = isize;
 /// # }
 /// ```
 ///
-/// [`.collapse_axis()`] modifies the view in the same way as [`.subview()`],
+/// [`.collapse_axis()`] modifies the view in the same way as [`.index_axis()`],
 /// but since it is *in place*, it cannot remove the collapsed axis. It becomes
 /// an axis of length 1.
 ///

src/numeric/impl_numeric.rs

@@ -107,11 +107,11 @@ impl<A, S, D> ArrayBase<S, D>
             // contiguous along the axis we are summing
             let ax = axis.index();
             for (i, elt) in enumerate(&mut res) {
-                *elt = self.subview(Axis(1 - ax), i).sum();
+                *elt = self.index_axis(Axis(1 - ax), i).sum();
             }
         } else {
             for i in 0..n {
-                let view = self.subview(axis, i);
+                let view = self.index_axis(axis, i);
                 res = res + &view;
             }
         }

tests/array.rs

@@ -253,7 +253,7 @@ fn test_slice_with_subview() {
     assert_eq!(vi.shape(), &[2, 2]);
     assert!(
         vi.iter()
-            .zip(arr.subview(Axis(1), 2).slice(s![1.., ..;2]).iter())
+            .zip(arr.index_axis(Axis(1), 2).slice(s![1.., ..;2]).iter())
             .all(|(a, b)| a == b)
     );
 
@@ -262,8 +262,8 @@ fn test_slice_with_subview() {
     assert!(
         vi.iter()
             .zip(
-                arr.subview(Axis(0), 1)
-                    .subview(Axis(0), 2)
+                arr.index_axis(Axis(0), 1)
+                    .index_axis(Axis(0), 2)
                     .slice(s![..;2])
                     .iter()
             )
@@ -515,21 +515,21 @@ fn test_cow_shrink()
 fn test_sub()
 {
     let mat = RcArray::linspace(0., 15., 16).reshape((2, 4, 2));
-    let s1 = mat.subview(Axis(0), 0);
-    let s2 = mat.subview(Axis(0), 1);
+    let s1 = mat.index_axis(Axis(0), 0);
+    let s2 = mat.index_axis(Axis(0), 1);
     assert_eq!(s1.shape(), &[4, 2]);
     assert_eq!(s2.shape(), &[4, 2]);
     let n = RcArray::linspace(8., 15., 8).reshape((4,2));
     assert_eq!(n, s2);
     let m = RcArray::from_vec(vec![2., 3., 10., 11.]).reshape((2, 2));
-    assert_eq!(m, mat.subview(Axis(1), 1));
+    assert_eq!(m, mat.index_axis(Axis(1), 1));
 }
 
 #[should_panic]
 #[test]
 fn test_sub_oob_1() {
     let mat = RcArray::linspace(0., 15., 16).reshape((2, 4, 2));
-    mat.subview(Axis(0), 2);
+    mat.index_axis(Axis(0), 2);
 }
 
 
@@ -652,9 +652,9 @@ fn standard_layout()
     assert!(!a.is_standard_layout());
     a.swap_axes(0, 1);
     assert!(a.is_standard_layout());
-    let x1 = a.subview(Axis(0), 0);
+    let x1 = a.index_axis(Axis(0), 0);
     assert!(x1.is_standard_layout());
-    let x2 = a.subview(Axis(1), 0);
+    let x2 = a.index_axis(Axis(1), 0);
     assert!(!x2.is_standard_layout());
 }
 
@@ -887,7 +887,7 @@ fn zero_axes()
     println!("{:?}\n{:?}", b.shape(), b);
 
     // we can even get a subarray of b
-    let bsub = b.subview(Axis(0), 2);
+    let bsub = b.index_axis(Axis(0), 2);
     assert_eq!(bsub.dim(), 0);
 }
 
@@ -1400,9 +1400,9 @@ fn insert_axis_f() {
 fn insert_axis_view() {
     let a = array![[[1, 2], [3, 4]], [[5, 6], [7, 8]], [[9, 10], [11, 12]]];
 
-    assert_eq!(a.subview(Axis(1), 0).insert_axis(Axis(0)), array![[[1, 2], [5, 6], [9, 10]]]);
-    assert_eq!(a.subview(Axis(1), 0).insert_axis(Axis(1)), array![[[1, 2]], [[5, 6]], [[9, 10]]]);
-    assert_eq!(a.subview(Axis(1), 0).insert_axis(Axis(2)), array![[[1], [2]], [[5], [6]], [[9], [10]]]);
+    assert_eq!(a.index_axis(Axis(1), 0).insert_axis(Axis(0)), array![[[1, 2], [5, 6], [9, 10]]]);
+    assert_eq!(a.index_axis(Axis(1), 0).insert_axis(Axis(1)), array![[[1, 2]], [[5, 6]], [[9, 10]]]);
+    assert_eq!(a.index_axis(Axis(1), 0).insert_axis(Axis(2)), array![[[1], [2]], [[5], [6]], [[9], [10]]]);
 }
 
 #[test]
@@ -1420,7 +1420,7 @@ fn char_array()
 {
     // test compilation & basics of non-numerical array
     let cc = RcArray::from_iter("alphabet".chars()).reshape((4, 2));
-    assert!(cc.subview(Axis(1), 0) == RcArray::from_iter("apae".chars()));
+    assert!(cc.index_axis(Axis(1), 0) == RcArray::from_iter("apae".chars()));
 }
 
 #[test]

tests/dimension.rs

@@ -53,7 +53,7 @@ fn remove_axis()
     assert_eq!(Dim(vec![4, 5, 6]).remove_axis(Axis(1)), Dim(vec![4, 6]));
 
     let a = RcArray::<f32, _>::zeros((4,5));
-    a.subview(Axis(1), 0);
+    a.index_axis(Axis(1), 0);
 
     let a = RcArray::<f32, _>::zeros(vec![4,5,6]);
     let _b = a.index_axis_move(Axis(1), 0).reshape((4, 6)).reshape(vec![2, 3, 4]);

tests/iterators.rs

@@ -92,12 +92,12 @@ fn as_slice() {
     let a = a.reshape((2, 4));
     assert_slice_correct(&a);
 
-    assert!(a.view().subview(Axis(1), 0).as_slice().is_none());
+    assert!(a.view().index_axis(Axis(1), 0).as_slice().is_none());
 
     let v = a.view();
     assert_slice_correct(&v);
-    assert_slice_correct(&v.subview(Axis(0), 0));
-    assert_slice_correct(&v.subview(Axis(0), 1));
+    assert_slice_correct(&v.index_axis(Axis(0), 0));
+    assert_slice_correct(&v.index_axis(Axis(0), 1));
 
     assert!(v.slice(s![.., ..1]).as_slice().is_none());
     println!("{:?}", v.slice(s![..1;2, ..]));
@@ -180,12 +180,12 @@ fn outer_iter() {
     //   [8, 9],
     //    ...
     assert_equal(a.outer_iter(),
-                 vec![a.subview(Axis(0), 0), a.subview(Axis(0), 1)]);
+                 vec![a.index_axis(Axis(0), 0), a.index_axis(Axis(0), 1)]);
     let mut b = RcArray::zeros((2, 3, 2));
     b.swap_axes(0, 2);
     b.assign(&a);
     assert_equal(b.outer_iter(),
-                 vec![a.subview(Axis(0), 0), a.subview(Axis(0), 1)]);
+                 vec![a.index_axis(Axis(0), 0), a.index_axis(Axis(0), 1)]);
 
     let mut found_rows = Vec::new();
     for sub in b.outer_iter() {
@@ -210,7 +210,7 @@ fn outer_iter() {
     cv.assign(&a);
     assert_eq!(&a, &cv);
     assert_equal(cv.outer_iter(),
-                 vec![a.subview(Axis(0), 0), a.subview(Axis(0), 1)]);
+                 vec![a.index_axis(Axis(0), 0), a.index_axis(Axis(0), 1)]);
 
     let mut found_rows = Vec::new();
     for sub in cv.outer_iter() {
@@ -233,9 +233,9 @@ fn axis_iter() {
     //   [8, 9],
     //    ...
     assert_equal(a.axis_iter(Axis(1)),
-                 vec![a.subview(Axis(1), 0),
-                      a.subview(Axis(1), 1),
-                      a.subview(Axis(1), 2)]);
+                 vec![a.index_axis(Axis(1), 0),
+                      a.index_axis(Axis(1), 1),
+                      a.index_axis(Axis(1), 2)]);
 }
 
 #[test]
@@ -264,7 +264,7 @@ fn outer_iter_mut() {
     b.swap_axes(0, 2);
     b.assign(&a);
     assert_equal(b.outer_iter_mut(),
-                 vec![a.subview(Axis(0), 0), a.subview(Axis(0), 1)]);
+                 vec![a.index_axis(Axis(0), 0), a.index_axis(Axis(0), 1)]);
 
     let mut found_rows = Vec::new();
     for sub in b.outer_iter_mut() {