Repository: rust-ndarray/ndarray (rust)

Issue:
Rename genrows()?
`.genrows()` has an unfortunate name. It's supposedly the *generalized rows* of an array. The reason for the tricky name, was that `.rows()` was taken - by the row count.

We could rename `rows` →`row_count` and `genrows` → `rows` to solve this, ideally with deprecations, so in a two version cycle.

`rows()` is a more natural name for the ndproducer and iterable for rows, for example because the user doesn't have to care that it's “generalized” rows if they only use 2D arrays — they don't need to know and it doesn't matter.

The main problem with the `genrows` name is that it is non-intuitive to guess to type and guess what it means.

Note that we chose the `.rows()` name for the row count to match the sprs crate, but I think we can choose to go our own way here, if we have a good reason.

An alternative to the `row_count` name is `nrows()` — anyone have a survey of what other crates prefer apart from sprs?

NOTE: The same story applies to `gencolumns`.

Pull request:
Rename genrows/gencolumns to rows/columns
Remove these functions which were deprecated:

- rows, cols (for row and column count; the new names are `nrows` and `ncols`)

Renames these without behaviour change:

- genrows/_mut -> rows/_mut
- gencolumns/_mut -> columns/_mut

The old names are deprecated. New names should be easier to understand. Note that the rows/columns names make most sense with two-dim arrays, with others it has a "generalized" meaning (see docs) - using `lanes` instead might be better for clarity sometimes.

Fixes #698

Patch:
diff --git a/benches/bench1.rs b/benches/bench1.rs
index 8cd04c45..35a1d6e7 100644
--- a/benches/bench1.rs
+++ b/benches/bench1.rs
@@ -61,7 +61,7 @@ fn iter_sum_2d_by_row(bench: &mut test::Bencher) {
     let a = black_box(a);
     bench.iter(|| {
         let mut sum = 0;
-        for row in a.genrows() {
+        for row in a.rows() {
             for &elt in row {
                 sum += elt;
             }
@@ -121,7 +121,7 @@ fn iter_sum_2d_cutout_outer_iter(bench: &mut test::Bencher) {
     let a = black_box(av);
     bench.iter(|| {
         let mut sum = 0;
-        for row in a.genrows() {
+        for row in a.rows() {
             for &elt in row {
                 sum += elt;
             }
diff --git a/examples/life.rs b/examples/life.rs
index 1c278938..748f1605 100644
--- a/examples/life.rs
+++ b/examples/life.rs
@@ -67,7 +67,7 @@ fn turn_on_corners(z: &mut Board) {
 }
 
 fn render(a: &Board) {
-    for row in a.genrows() {
+    for row in a.rows() {
         for &x in row {
             if x > 0 {
                 print!("#");
diff --git a/src/impl_2d.rs b/src/impl_2d.rs
index 7b919eb3..64d4860c 100644
--- a/src/impl_2d.rs
+++ b/src/impl_2d.rs
@@ -58,12 +58,6 @@ where
         self.len_of(Axis(0))
     }
 
-    /// Return the number of rows (length of `Axis(0)`) in the two-dimensional array.
-    #[deprecated(note = "Renamed to .nrows(), please use the new name")]
-    pub fn rows(&self) -> usize {
-        self.nrows()
-    }
-
     /// Return an array view of column `index`.
     ///
     /// **Panics** if `index` is out of bounds.
@@ -108,12 +102,6 @@ where
         self.len_of(Axis(1))
     }
 
-    /// Return the number of columns (length of `Axis(1)`) in the two-dimensional array.
-    #[deprecated(note = "Renamed to .ncols(), please use the new name")]
-    pub fn cols(&self) -> usize {
-        self.ncols()
-    }
-
     /// Return true if the array is square, false otherwise.
     ///
     /// # Examples
diff --git a/src/impl_methods.rs b/src/impl_methods.rs
index dd0034b2..09edbb15 100644
--- a/src/impl_methods.rs
+++ b/src/impl_methods.rs
@@ -811,12 +811,12 @@ where
     ///                [[ 6,  7,  8],    // -- row 1, 0
     ///                 [ 9, 10, 11]]]); // -- row 1, 1
     ///
-    /// // `genrows` will yield the four generalized rows of the array.
-    /// for row in a.genrows() {
+    /// // `rows` will yield the four generalized rows of the array.
+    /// for row in a.rows() {
     ///     /* loop body */
     /// }
     /// ```
-    pub fn genrows(&self) -> Lanes<'_, A, D::Smaller>
+    pub fn rows(&self) -> Lanes<'_, A, D::Smaller>
     where
         S: Data,
     {
@@ -827,11 +827,19 @@ where
         Lanes::new(self.view(), Axis(n - 1))
     }
 
+    #[deprecated(note="Renamed to .rows()", since="0.15.0")]
+    pub fn genrows(&self) -> Lanes<'_, A, D::Smaller>
+    where
+        S: Data,
+    {
+        self.rows()
+    }
+
     /// Return a producer and iterable that traverses over the *generalized*
     /// rows of the array and yields mutable array views.
     ///
     /// Iterator element is `ArrayView1<A>` (1D read-write array view).
-    pub fn genrows_mut(&mut self) -> LanesMut<'_, A, D::Smaller>
+    pub fn rows_mut(&mut self) -> LanesMut<'_, A, D::Smaller>
     where
         S: DataMut,
     {
@@ -842,6 +850,14 @@ where
         LanesMut::new(self.view_mut(), Axis(n - 1))
     }
 
+    #[deprecated(note="Renamed to .rows_mut()", since="0.15.0")]
+    pub fn genrows_mut(&mut self) -> LanesMut<'_, A, D::Smaller>
+    where
+        S: DataMut,
+    {
+        self.rows_mut()
+    }
+
     /// Return a producer and iterable that traverses over the *generalized*
     /// columns of the array. For a 2D array these are the regular columns.
     ///
@@ -863,29 +879,53 @@ where
     /// let a = arr3(&[[[ 0,  1,  2], [ 3,  4,  5]],
     ///                [[ 6,  7,  8], [ 9, 10, 11]]]);
     ///
-    /// // Here `gencolumns` will yield the six generalized columns of the array.
-    /// for row in a.gencolumns() {
+    /// // Here `columns` will yield the six generalized columns of the array.
+    /// for row in a.columns() {
     ///     /* loop body */
     /// }
     /// ```
-    pub fn gencolumns(&self) -> Lanes<'_, A, D::Smaller>
+    pub fn columns(&self) -> Lanes<'_, A, D::Smaller>
     where
         S: Data,
     {
         Lanes::new(self.view(), Axis(0))
     }
 
+    /// Return a producer and iterable that traverses over the *generalized*
+    /// columns of the array. For a 2D array these are the regular columns.
+    ///
+    /// Renamed to `.columns()`
+    #[deprecated(note="Renamed to .columns()", since="0.15.0")]
+    pub fn gencolumns(&self) -> Lanes<'_, A, D::Smaller>
+    where
+        S: Data,
+    {
+        self.columns()
+    }
+
     /// Return a producer and iterable that traverses over the *generalized*
     /// columns of the array and yields mutable array views.
     ///
     /// Iterator element is `ArrayView1<A>` (1D read-write array view).
-    pub fn gencolumns_mut(&mut self) -> LanesMut<'_, A, D::Smaller>
+    pub fn columns_mut(&mut self) -> LanesMut<'_, A, D::Smaller>
     where
         S: DataMut,
     {
         LanesMut::new(self.view_mut(), Axis(0))
     }
 
+    /// Return a producer and iterable that traverses over the *generalized*
+    /// columns of the array and yields mutable array views.
+    ///
+    /// Renamed to `.columns_mut()`
+    #[deprecated(note="Renamed to .columns_mut()", since="0.15.0")]
+    pub fn gencolumns_mut(&mut self) -> LanesMut<'_, A, D::Smaller>
+    where
+        S: DataMut,
+    {
+        self.columns_mut()
+    }
+
     /// Return a producer and iterable that traverses over all 1D lanes
     /// pointing in the direction of `axis`.
     ///
diff --git a/src/lib.rs b/src/lib.rs
index a99d6d52..b94eee22 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -413,16 +413,16 @@ pub type Ixs = isize;
 ///
 /// The `outer_iter` and `axis_iter` are one dimensional producers.
 ///
-/// ## `.genrows()`, `.gencolumns()` and `.lanes()`
+/// ## `.rows()`, `.columns()` and `.lanes()`
 ///
-/// [`.genrows()`][gr] is a producer (and iterable) of all rows in an array.
+/// [`.rows()`][gr] is a producer (and iterable) of all rows in an array.
 ///
 /// ```
 /// use ndarray::Array;
 ///
 /// // 1. Loop over the rows of a 2D array
 /// let mut a = Array::zeros((10, 10));
-/// for mut row in a.genrows_mut() {
+/// for mut row in a.rows_mut() {
 ///     row.fill(1.);
 /// }
 ///
@@ -430,7 +430,7 @@ pub type Ixs = isize;
 /// use ndarray::Zip;
 /// let mut b = Array::zeros(a.nrows());
 ///
-/// Zip::from(a.genrows())
+/// Zip::from(a.rows())
 ///     .and(&mut b)
 ///     .apply(|a_row, b_elt| {
 ///         *b_elt = a_row[a.ncols() - 1] - a_row[0];
@@ -448,21 +448,21 @@ pub type Ixs = isize;
 /// has *a m* rows. It's composed of *a* times the previous array, so it
 /// has *a* times as many rows.
 ///
-/// All methods: [`.genrows()`][gr], [`.genrows_mut()`][grm],
-/// [`.gencolumns()`][gc], [`.gencolumns_mut()`][gcm],
+/// All methods: [`.rows()`][gr], [`.rows_mut()`][grm],
+/// [`.columns()`][gc], [`.columns_mut()`][gcm],
 /// [`.lanes(axis)`][l], [`.lanes_mut(axis)`][lm].
 ///
-/// [gr]: #method.genrows
-/// [grm]: #method.genrows_mut
-/// [gc]: #method.gencolumns
-/// [gcm]: #method.gencolumns_mut
+/// [gr]: #method.rows
+/// [grm]: #method.rows_mut
+/// [gc]: #method.columns
+/// [gcm]: #method.columns_mut
 /// [l]: #method.lanes
 /// [lm]: #method.lanes_mut
 ///
-/// Yes, for 2D arrays `.genrows()` and `.outer_iter()` have about the same
+/// Yes, for 2D arrays `.rows()` and `.outer_iter()` have about the same
 /// effect:
 ///
-///  + `genrows()` is a producer with *n* - 1 dimensions of 1 dimensional items
+///  + `rows()` is a producer with *n* - 1 dimensions of 1 dimensional items
 ///  + `outer_iter()` is a producer with 1 dimension of *n* - 1 dimensional items
 ///
 /// ## Slicing
diff --git a/src/zip/mod.rs b/src/zip/mod.rs
index ed92e250..835ae5d3 100644
--- a/src/zip/mod.rs
+++ b/src/zip/mod.rs
@@ -561,7 +561,7 @@ impl<A, D: Dimension> NdProducer for RawArrayViewMut<A, D> {
 /// let mut totals = Array1::zeros(a.nrows());
 ///
 /// Zip::from(&mut totals)
-///     .and(a.genrows())
+///     .and(a.rows())
 ///     .apply(|totals, row| *totals = row.sum());
 ///
 /// // Check the result against the built in `.sum_axis()` along axis 1.
@@ -570,7 +570,7 @@ impl<A, D: Dimension> NdProducer for RawArrayViewMut<A, D> {
 ///
 /// // Example 3: Recreate Example 2 using apply_collect to make a new array
 ///
-/// let mut totals2 = Zip::from(a.genrows()).apply_collect(|row| row.sum());
+/// let mut totals2 = Zip::from(a.rows()).apply_collect(|row| row.sum());
 ///
 /// // Check the result against the previous example.
 /// assert_eq!(totals, totals2);
diff --git a/src/zip/zipmacro.rs b/src/zip/zipmacro.rs
index ba2b3da2..5353a637 100644
--- a/src/zip/zipmacro.rs
+++ b/src/zip/zipmacro.rs
@@ -89,8 +89,8 @@
 ///     // entry in `totals` with the sum across each row.
 ///     //
 ///     // The row is an array view; it doesn't need to be dereferenced.
-///     let mut totals = Array1::zeros(a.rows());
-///     azip!((totals in &mut totals, row in a.genrows()) *totals = row.sum());
+///     let mut totals = Array1::zeros(a.nrows());
+///     azip!((totals in &mut totals, row in a.rows()) *totals = row.sum());
 ///
 ///     // Check the result against the built in `.sum_axis()` along axis 1.
 ///     assert_eq!(totals, a.sum_axis(Axis(1)));


Test patch:
diff --git a/tests/array.rs b/tests/array.rs
index db54b7e5..7a0e2d51 100644
--- a/tests/array.rs
+++ b/tests/array.rs
@@ -1701,7 +1701,7 @@ fn test_f_order() {
     assert_eq!(c.strides(), &[3, 1]);
     assert_eq!(f.strides(), &[1, 2]);
     itertools::assert_equal(f.iter(), c.iter());
-    itertools::assert_equal(f.genrows(), c.genrows());
+    itertools::assert_equal(f.rows(), c.rows());
     itertools::assert_equal(f.outer_iter(), c.outer_iter());
     itertools::assert_equal(f.axis_iter(Axis(0)), c.axis_iter(Axis(0)));
     itertools::assert_equal(f.axis_iter(Axis(1)), c.axis_iter(Axis(1)));
diff --git a/tests/iterators.rs b/tests/iterators.rs
index 371339b9..7a30003c 100644
--- a/tests/iterators.rs
+++ b/tests/iterators.rs
@@ -142,7 +142,7 @@ fn inner_iter() {
     //   [8, 9],
     //    ...
     assert_equal(
-        a.genrows(),
+        a.rows(),
         vec![
             aview1(&[0, 1]),
             aview1(&[2, 3]),
@@ -156,7 +156,7 @@ fn inner_iter() {
     b.swap_axes(0, 2);
     b.assign(&a);
     assert_equal(
-        b.genrows(),
+        b.rows(),
         vec![
             aview1(&[0, 1]),
             aview1(&[2, 3]),
@@ -171,13 +171,13 @@ fn inner_iter() {
 #[test]
 fn inner_iter_corner_cases() {
     let a0 = ArcArray::<i32, _>::zeros(());
-    assert_equal(a0.genrows(), vec![aview1(&[0])]);
+    assert_equal(a0.rows(), vec![aview1(&[0])]);
 
     let a2 = ArcArray::<i32, _>::zeros((0, 3));
-    assert_equal(a2.genrows(), vec![aview1(&[]); 0]);
+    assert_equal(a2.rows(), vec![aview1(&[]); 0]);
 
     let a2 = ArcArray::<i32, _>::zeros((3, 0));
-    assert_equal(a2.genrows(), vec![aview1(&[]); 3]);
+    assert_equal(a2.rows(), vec![aview1(&[]); 3]);
 }
 
 #[test]
@@ -185,7 +185,7 @@ fn inner_iter_size_hint() {
     // Check that the size hint is correctly computed
     let a = ArcArray::from_iter(0..24).reshape((2, 3, 4));
     let mut len = 6;
-    let mut it = a.genrows().into_iter();
+    let mut it = a.rows().into_iter();
     assert_eq!(it.len(), len);
     while len > 0 {
         it.next();
@@ -223,7 +223,7 @@ fn outer_iter() {
             found_rows.push(row);
         }
     }
-    assert_equal(a.genrows(), found_rows.clone());
+    assert_equal(a.rows(), found_rows.clone());
 
     let mut found_rows_rev = Vec::new();
     for sub in b.outer_iter().rev() {
@@ -251,7 +251,7 @@ fn outer_iter() {
         }
     }
     println!("{:#?}", found_rows);
-    assert_equal(a.genrows(), found_rows);
+    assert_equal(a.rows(), found_rows);
 }
 
 #[test]
@@ -370,7 +370,7 @@ fn outer_iter_mut() {
             found_rows.push(row);
         }
     }
-    assert_equal(a.genrows(), found_rows);
+    assert_equal(a.rows(), found_rows);
 }
 
 #[test]
@@ -747,8 +747,8 @@ fn iterators_are_send_sync() {
     _send_sync(&a.iter_mut());
     _send_sync(&a.indexed_iter());
     _send_sync(&a.indexed_iter_mut());
-    _send_sync(&a.genrows());
-    _send_sync(&a.genrows_mut());
+    _send_sync(&a.rows());
+    _send_sync(&a.rows_mut());
     _send_sync(&a.outer_iter());
     _send_sync(&a.outer_iter_mut());
     _send_sync(&a.axis_iter(Axis(1)));