change feature name to par-iter and add doc example to par_column_iter_mut

Cargo.toml

@@ -33,7 +33,7 @@ libm    = [ "simba/libm" ]
 libm-force = [ "simba/libm_force" ]
 macros = [ "nalgebra-macros" ]
 cuda   = [ "cust_core", "simba/cuda" ]
-rayon  = [ "std", "dep:rayon" ]
+par-iter  = [ "std", "rayon" ]
 
 # Conversion
 convert-mint = [ "mint" ]

src/base/iter.rs

@@ -440,7 +440,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim, S: 'a + RawStorageMut<T, R, C>> DoubleEndedI
 }
 
 /// implementations for parallel iteration with rayon
-#[cfg(feature = "rayon")]
+#[cfg(feature = "par-iter")]
 mod parallel {
     use super::*;
     use rayon::iter::plumbing::Producer;

src/base/matrix.rs

@@ -100,7 +100,7 @@ pub type MatrixCross<T, R1, C1, R2, C2> =
 /// - [Find the min and max components (vector-specific methods) <span style="float:right;">`argmin`, `argmax`, `icamin`, `icamax`…</span>](#find-the-min-and-max-components-vector-specific-methods)
 ///
 /// #### Iteration, map, and fold
-/// - [Iteration on components, rows, and columns <span style="float:right;">`iter`, `column_iter`…</span>](#iteration-on-components-rows-and-columns)
+/// - [Iteration on components, rows, and columns <span style="float:right;">`iter`, `column_iter`, `par_column_iter`…</span>](#iteration-on-components-rows-and-columns)
 /// - [Elementwise mapping and folding <span style="float:right;">`map`, `fold`, `zip_map`…</span>](#elementwise-mapping-and-folding)
 /// - [Folding or columns and rows <span style="float:right;">`compress_rows`, `compress_columns`…</span>](#folding-on-columns-and-rows)
 ///

src/base/mod.rs

@@ -42,7 +42,8 @@ mod min_max;
 /// Mechanisms for working with values that may not be initialized.
 pub mod uninit;
 
-#[cfg(feature = "rayon")]
+
+#[cfg(feature = "par-iter")]
 pub mod par_iter;
 
 #[cfg(feature = "rkyv-serialize-no-std")]

src/base/par_iter.rs

@@ -15,7 +15,7 @@ use rayon::{iter::plumbing::bridge, prelude::*};
 ///
 /// [`par_column_iter`]: crate::Matrix::par_column_iter
 /// [`Matrix`]: crate::Matrix
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 pub struct ParColumnIter<'a, T, R: Dim, Cols: Dim, S: RawStorage<T, R, Cols>> {
     mat: &'a Matrix<T, R, Cols, S>,
 }
@@ -27,7 +27,7 @@ impl<'a, T, R: Dim, Cols: Dim, S: RawStorage<T, R, Cols>> ParColumnIter<'a, T, R
     }
 }
 
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 impl<'a, T, R: Dim, Cols: Dim, S: RawStorage<T, R, Cols>> ParallelIterator
     for ParColumnIter<'a, T, R, Cols, S>
 where
@@ -48,7 +48,7 @@ where
     }
 }
 
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 impl<'a, T, R: Dim, Cols: Dim, S: RawStorage<T, R, Cols>> IndexedParallelIterator
     for ParColumnIter<'a, T, R, Cols, S>
 where
@@ -72,7 +72,7 @@ where
     }
 }
 
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 impl<T, R: Dim, Cols: Dim, S: RawStorage<T, R, Cols>> Matrix<T, R, Cols, S>
 where
     T: Send + Sync + Scalar,
@@ -83,7 +83,7 @@ where
     /// if *mutable* access to the columns is required, use [`par_column_iter_mut`]
     /// instead.
     /// 
-    /// **Example**
+    /// # Example
     /// Using parallel column iterators to calculate the sum of the maximum
     /// elements in each column:
     /// ```
@@ -110,7 +110,7 @@ where
     }
 }
 
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 /// A rayon parallel iterator through the mutable columns of a matrix
 pub struct ParColumnIterMut<
     'a,
@@ -122,7 +122,7 @@ pub struct ParColumnIterMut<
     mat: &'a mut Matrix<T, R, Cols, S>,
 }
 
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 impl<'a, T, R, Cols, S> ParColumnIterMut<'a, T, R, Cols, S>
 where
     R: Dim,
@@ -135,7 +135,7 @@ where
     }
 }
 
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 impl<'a, T, R, Cols, S> ParallelIterator for ParColumnIterMut<'a, T, R, Cols, S>
 where
     R: Dim,
@@ -157,7 +157,7 @@ where
     }
 }
 
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 impl<'a, T, R, Cols, S> IndexedParallelIterator for ParColumnIterMut<'a, T, R, Cols, S>
 where
     R: Dim,
@@ -183,14 +183,36 @@ where
     }
 }
 
-#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))]
 impl<T, R: Dim, Cols: Dim, S: RawStorage<T, R, Cols> + RawStorageMut<T, R, Cols>>
     Matrix<T, R, Cols, S>
 where
     T: Send + Sync + Scalar,
     S: Sync,
 {
-    /// Mutably iterate through the columns of this matrix in parallel using rayon
+    /// Mutably iterate through the columns of this matrix in parallel using rayon.
+    /// Allows mutable access to the columns in parallel using mutable references.
+    /// If mutable access to the columns is not required rather use [`par_column_iter`]
+    /// instead.
+    /// 
+    /// # Example 
+    /// Normalize each column of a matrix with respect to its own maximum value.
+    /// 
+    /// ```
+    /// use nalgebra::{dmatrix,DMatrix};
+    /// use rayon::prelude::*;
+    ///
+    /// let mut matrix : DMatrix<f64> =
+    ///                     dmatrix![2.,4.,6.;
+    ///                             1.,2.,3.];
+    /// matrix.par_column_iter_mut().for_each(|mut col| col /= col.max());
+    ///
+    /// assert_eq!(matrix,
+    ///             dmatrix![1. ,1. , 1.;
+    ///                      0.5,0.5,0.5]);
+    /// ```
+    ///
+    /// [`par_column_iter`]: crate::Matrix::par_column_iter
     pub fn par_column_iter_mut(&mut self) -> ParColumnIterMut<'_, T, R, Cols, S> {
         ParColumnIterMut::new(self)
     }

tests/core/matrix.rs

@@ -1200,7 +1200,7 @@ fn column_iteration_double_ended() {
 }
 
 #[test]
-#[cfg(feature = "rayon")]
+#[cfg(feature = "par-iter")]
 fn parallel_column_iteration() {
     use nalgebra::dmatrix;
     use rayon::prelude::*;
@@ -1222,7 +1222,7 @@ fn parallel_column_iteration() {
 }
 
 #[test]
-#[cfg(feature = "rayon")]
+#[cfg(feature = "par-iter")]
 fn column_iteration_mut_double_ended() {
     let dmat = nalgebra::dmatrix![
     13,14,15,16,17;
@@ -1241,7 +1241,7 @@ fn column_iteration_mut_double_ended() {
 }
 
 #[test]
-#[cfg(feature = "rayon")]
+#[cfg(feature = "par-iter")]
 fn parallel_column_iteration_mut() {
     use rayon::prelude::*;
     let mut first = DMatrix::<f32>::zeros(400, 300);

tests/lib.rs

@@ -10,8 +10,8 @@ compile_error!(
 );
 
 // make sure to test the parallel iterators for all builds that do not require no_std
-#[cfg(all(feature = "std", not(feature = "rayon")))]
-compile_error!("Please additionally enable the `rayon` feature to compile and run the tests");
+#[cfg(all(feature = "std", not(feature = "par-iter")))]
+compile_error!("Please additionally enable the `par-iter` feature to compile and run the tests");
 
 #[cfg(all(feature = "debug", feature = "compare", feature = "rand"))]
 #[macro_use]