From 539050a73bfbd9f78a3be4fd23795e1946df170e Mon Sep 17 00:00:00 2001
From: Martin Geisler <martin@geisler.net>
Date: Sun, 17 Sep 2023 20:52:31 +0200
Subject: [PATCH 1/2] Link to SMAWK algorithm

---
 src/lib.rs | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 075ecc1..8856bee 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -155,21 +155,22 @@ impl<T: Copy> Matrix<T> for ndarray::Array2<T> {
 
 /// Compute row minima in O(*m* + *n*) time.
 ///
-/// This implements the SMAWK algorithm for finding row minima in a
-/// totally monotone matrix.
+/// This implements the [SMAWK algorithm] for efficiently finding row
+/// minima in a totally monotone matrix.
 ///
 /// The SMAWK algorithm is from Agarwal, Klawe, Moran, Shor, and
 /// Wilbur, *Geometric applications of a matrix searching algorithm*,
 /// Algorithmica 2, pp. 195-208 (1987) and the code here is a
 /// translation [David Eppstein's Python code][pads].
 ///
-/// [pads]: https://github.com/jfinkels/PADS/blob/master/pads/smawk.py
-///
 /// Running time on an *m* ✕ *n* matrix: O(*m* + *n*).
 ///
 /// # Panics
 ///
 /// It is an error to call this on a matrix with zero columns.
+///
+/// [pads]: https://github.com/jfinkels/PADS/blob/master/pads/smawk.py
+/// [SMAWK algorithm]: https://en.wikipedia.org/wiki/SMAWK_algorithm
 pub fn smawk_row_minima<T: PartialOrd + Copy, M: Matrix<T>>(matrix: &M) -> Vec<usize> {
     // Benchmarking shows that SMAWK performs roughly the same on row-
     // and column-major matrices.
@@ -185,21 +186,22 @@ pub fn smawk_row_minima<T: PartialOrd + Copy, M: Matrix<T>>(matrix: &M) -> Vec<u
 
 /// Compute column minima in O(*m* + *n*) time.
 ///
-/// This implements the SMAWK algorithm for finding column minima in a
-/// totally monotone matrix.
+/// This implements the [SMAWK algorithm] for efficiently finding
+/// column minima in a totally monotone matrix.
 ///
 /// The SMAWK algorithm is from Agarwal, Klawe, Moran, Shor, and
 /// Wilbur, *Geometric applications of a matrix searching algorithm*,
 /// Algorithmica 2, pp. 195-208 (1987) and the code here is a
 /// translation [David Eppstein's Python code][pads].
 ///
-/// [pads]: https://github.com/jfinkels/PADS/blob/master/pads/smawk.py
-///
 /// Running time on an *m* ✕ *n* matrix: O(*m* + *n*).
 ///
 /// # Panics
 ///
 /// It is an error to call this on a matrix with zero rows.
+///
+/// [SMAWK algorithm]: https://en.wikipedia.org/wiki/SMAWK_algorithm
+/// [pads]: https://github.com/jfinkels/PADS/blob/master/pads/smawk.py
 pub fn smawk_column_minima<T: PartialOrd + Copy, M: Matrix<T>>(matrix: &M) -> Vec<usize> {
     let mut minima = vec![0; matrix.ncols()];
     smawk_inner(

From ce5ec7c0e29479d737ff6e89816520cb2abe6f0e Mon Sep 17 00:00:00 2001
From: Martin Geisler <martin@geisler.net>
Date: Sun, 17 Sep 2023 20:53:41 +0200
Subject: [PATCH 2/2] Add examples to all functions

---
 src/brute_force.rs | 28 ++++++++++++++++++++++++++++
 src/lib.rs         | 22 ++++++++++++++++++++++
 src/recursive.rs   | 30 ++++++++++++++++++++++++++++++
 3 files changed, 80 insertions(+)

diff --git a/src/brute_force.rs b/src/brute_force.rs
index 1ea239c..1ec0ca3 100644
--- a/src/brute_force.rs
+++ b/src/brute_force.rs
@@ -22,6 +22,20 @@ pub fn lane_minimum<T: Ord>(lane: ArrayView1<'_, T>) -> usize {
 
 /// Compute row minima by brute force in O(*mn*) time.
 ///
+/// This function implements a simple brute-force approach where each
+/// matrix row is scanned completely. This means that the function
+/// works on all matrices, not just Monge matrices.
+///
+/// # Examples
+///
+/// ```
+/// let matrix = ndarray::arr2(&[[4, 2, 4, 3],
+///                              [5, 3, 5, 3],
+///                              [5, 3, 3, 1]]);
+/// assert_eq!(smawk::brute_force::row_minima(&matrix),
+///            vec![1, 1, 3]);
+/// ```
+///
 /// # Panics
 ///
 /// It is an error to call this on a matrix with zero columns.
@@ -31,6 +45,20 @@ pub fn row_minima<T: Ord>(matrix: &Array2<T>) -> Vec<usize> {
 
 /// Compute column minima by brute force in O(*mn*) time.
 ///
+/// This function implements a simple brute-force approach where each
+/// matrix column is scanned completely. This means that the function
+/// works on all matrices, not just Monge matrices.
+///
+/// # Examples
+///
+/// ```
+/// let matrix = ndarray::arr2(&[[4, 2, 4, 3],
+///                              [5, 3, 5, 3],
+///                              [5, 3, 3, 1]]);
+/// assert_eq!(smawk::brute_force::column_minima(&matrix),
+///            vec![0, 0, 2, 2]);
+/// ```
+///
 /// # Panics
 ///
 /// It is an error to call this on a matrix with zero rows.
diff --git a/src/lib.rs b/src/lib.rs
index 8856bee..aa43a28 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -165,6 +165,17 @@ impl<T: Copy> Matrix<T> for ndarray::Array2<T> {
 ///
 /// Running time on an *m* ✕ *n* matrix: O(*m* + *n*).
 ///
+/// # Examples
+///
+/// ```
+/// use smawk::{Matrix, smawk_row_minima};
+/// let matrix = vec![vec![4, 2, 4, 3],
+///                   vec![5, 3, 5, 3],
+///                   vec![5, 3, 3, 1]];
+/// assert_eq!(smawk_row_minima(&matrix),
+///            vec![1, 1, 3]);
+/// ```
+///
 /// # Panics
 ///
 /// It is an error to call this on a matrix with zero columns.
@@ -196,6 +207,17 @@ pub fn smawk_row_minima<T: PartialOrd + Copy, M: Matrix<T>>(matrix: &M) -> Vec<u
 ///
 /// Running time on an *m* ✕ *n* matrix: O(*m* + *n*).
 ///
+/// # Examples
+///
+/// ```
+/// use smawk::{Matrix, smawk_column_minima};
+/// let matrix = vec![vec![4, 2, 4, 3],
+///                   vec![5, 3, 5, 3],
+///                   vec![5, 3, 3, 1]];
+/// assert_eq!(smawk_column_minima(&matrix),
+///            vec![0, 0, 2, 2]);
+/// ```
+///
 /// # Panics
 ///
 /// It is an error to call this on a matrix with zero rows.
diff --git a/src/recursive.rs b/src/recursive.rs
index e7f769b..9df8b9c 100644
--- a/src/recursive.rs
+++ b/src/recursive.rs
@@ -10,6 +10,21 @@ use ndarray::{s, Array2, ArrayView2, Axis};
 
 /// Compute row minima in O(*m* + *n* log *m*) time.
 ///
+/// This function computes row minima in a totally monotone matrix
+/// using a recursive algorithm.
+///
+/// Running time on an *m* ✕ *n* matrix: O(*m* + *n* log *m*).
+///
+/// # Examples
+///
+/// ```
+/// let matrix = ndarray::arr2(&[[4, 2, 4, 3],
+///                              [5, 3, 5, 3],
+///                              [5, 3, 3, 1]]);
+/// assert_eq!(smawk::recursive::row_minima(&matrix),
+///            vec![1, 1, 3]);
+/// ```
+///
 /// # Panics
 ///
 /// It is an error to call this on a matrix with zero columns.
@@ -21,6 +36,21 @@ pub fn row_minima<T: Ord>(matrix: &Array2<T>) -> Vec<usize> {
 
 /// Compute column minima in O(*n* + *m* log *n*) time.
 ///
+/// This function computes column minima in a totally monotone matrix
+/// using a recursive algorithm.
+///
+/// Running time on an *m* ✕ *n* matrix: O(*n* + *m* log *n*).
+///
+/// # Examples
+///
+/// ```
+/// let matrix = ndarray::arr2(&[[4, 2, 4, 3],
+///                              [5, 3, 5, 3],
+///                              [5, 3, 3, 1]]);
+/// assert_eq!(smawk::recursive::column_minima(&matrix),
+///            vec![0, 0, 2, 2]);
+/// ```
+///
 /// # Panics
 ///
 /// It is an error to call this on a matrix with zero rows.