Add comprehensive tests and doc examples for partial cycle-finding

Co-authored-by: samueltardieu <44656+samueltardieu@users.noreply.github.com>

Author: Copilot

src/directed/cycle_detection.rs

@@ -9,6 +9,18 @@
 /// μ̃ satisfies μ ≤ μ̃ < μ + λ, where μ is the minimal index.
 ///
 /// This is faster than [`floyd`] as it skips the computation of the minimal μ.
+/// The upper bound μ̃ is sufficient for many applications, such as computing f^n(x) for
+/// large n, where knowing the exact starting point of the cycle is not necessary.
+///
+/// # Example
+///
+/// ```
+/// use pathfinding::prelude::floyd_partial;
+///
+/// let (lam, _elem, mu_tilde) = floyd_partial(1, |x| (x * 2) % 7);
+/// assert_eq!(lam, 3); // Cycle length
+/// assert!(mu_tilde >= 1); // Upper bound on mu
+/// ```
 ///
 /// # Warning
 ///
@@ -74,6 +86,18 @@ where
 /// μ̃ satisfies μ ≤ μ̃ < μ + λ, where μ is the minimal index.
 ///
 /// This is faster than [`brent`] as it skips the computation of the minimal μ.
+/// The upper bound μ̃ is sufficient for many applications, such as computing f^n(x) for
+/// large n, where knowing the exact starting point of the cycle is not necessary.
+///
+/// # Example
+///
+/// ```
+/// use pathfinding::prelude::brent_partial;
+///
+/// let (lam, _elem, mu_tilde) = brent_partial(1, |x| (x * 2) % 7);
+/// assert_eq!(lam, 3); // Cycle length
+/// assert!(mu_tilde >= 1); // Upper bound on mu
+/// ```
 ///
 /// # Warning
 ///

tests/cycle_detection.rs

@@ -35,3 +35,35 @@ fn brent_partial_works() {
     assert!(2 <= mu_tilde);
     assert!(mu_tilde < 2 + 3);
 }
+
+#[test]
+fn partial_functions_match_full_functions() {
+    // Test that partial functions return the same lambda as full functions
+    let f = |x| (x + 5) % 6 + 3;
+    
+    let (lam_floyd, elem_floyd, mu_floyd) = floyd(-10, f);
+    let (lam_floyd_partial, elem_floyd_partial, mu_tilde_floyd) = floyd_partial(-10, f);
+    
+    let (lam_brent, elem_brent, mu_brent) = brent(-10, f);
+    let (lam_brent_partial, elem_brent_partial, mu_tilde_brent) = brent_partial(-10, f);
+    
+    // Lambda should be the same
+    assert_eq!(lam_floyd, lam_floyd_partial);
+    assert_eq!(lam_brent, lam_brent_partial);
+    assert_eq!(lam_floyd, lam_brent);
+    
+    // Elements should be in the cycle
+    assert!([4, 6, 8].contains(&elem_floyd));
+    assert!([4, 6, 8].contains(&elem_floyd_partial));
+    assert!([4, 6, 8].contains(&elem_brent));
+    assert!([4, 6, 8].contains(&elem_brent_partial));
+    
+    // Mu values from full algorithms should be the same
+    assert_eq!(mu_floyd, mu_brent);
+    
+    // Mu_tilde should be valid upper bounds
+    assert!(mu_floyd <= mu_tilde_floyd);
+    assert!(mu_tilde_floyd < mu_floyd + lam_floyd);
+    assert!(mu_brent <= mu_tilde_brent);
+    assert!(mu_tilde_brent < mu_brent + lam_brent);
+}