refactor(searches): Improve readability of Floyd's Cycle-Finding Algorithm

Signed-off-by: Aditya Kumar <aditya.kumar60@infosys.com>

Author: AdityaK60

searches/floyds_cycle_finding.py

@@ -7,67 +7,64 @@
 
 Wikipedia: https://en.wikipedia.org/wiki/Cycle_detection#Floyd's_tortoise_and_hare
 """
+from collections.abc import Callable
+from typing import Any
 
-from typing import Any, Callable, Optional, Tuple
 
-
-def floyds_cycle_finding(f: Callable[[Any], Any], x0: Any) -> Optional[Tuple[int, int]]:
+def floyds_cycle_finding(
+    successor_function: Callable[[Any], Any], start_value: Any
+) -> tuple[int, int] | None:
     """
-    Finds a cycle in the sequence of values generated by the function f.
+    Finds a cycle in the sequence of values generated by the successor function.
 
     Args:
-        f: A function that takes a value and returns the next value in the sequence.
-        x0: The starting value of the sequence.
+        successor_function: A function that takes a value and returns the next value.
+        start_value: The starting value of the sequence.
 
     Returns:
         A tuple containing the index of the first element of the cycle (mu)
         and the length of the cycle (lam), or None if no cycle is found.
 
     Doctest examples:
-    >>> # Example with a cycle
-    >>> f = lambda x: (2 * x + 3) % 17
-    >>> floyds_cycle_finding(f, 0)
+    >>> # Example with a mathematical sequence
+    >>> sequence_func = lambda x: (2 * x + 3) % 17
+    >>> floyds_cycle_finding(sequence_func, 0)
     (0, 8)
 
-    >>> # Example with a different starting point and cycle
-    >>> f = lambda x: [1, 2, 3, 4, 5, 3][x]
-    >>> floyds_cycle_finding(f, 0)
+    >>> # Example with a list acting as a sequence
+    >>> get_next_item = lambda x: [1, 2, 3, 4, 5, 3][x]
+    >>> floyds_cycle_finding(get_next_item, 0)
     (2, 3)
 
-    >>> # Example with no cycle (sequence terminates)
-    >>> nodes = {0: 1, 1: 2, 2: 3, 3: None}
-    >>> f = lambda x: nodes.get(x)
-    >>> floyds_cycle_finding(f, 0)
+    >>> # Example with a graph-like structure (no cycle)
+    >>> get_next_node = lambda x: {0: 1, 1: 2, 2: 3, 3: None}.get(x)
+    >>> floyds_cycle_finding(get_next_node, 0)
 
     """
-    # Main phase of the algorithm: finding a repetition x_i = x_2i.
+    # Main phase: finding a repetition x_i = x_2i.
     # The hare moves twice as fast as the tortoise.
-    tortoise = f(x0)
-    hare = f(f(x0))
+    tortoise = successor_function(start_value)
+    hare = successor_function(successor_function(start_value))
     while tortoise != hare:
         # If the hare reaches the end of the sequence, there is no cycle.
-        if hare is None or f(hare) is None:
+        if hare is None or successor_function(hare) is None:
             return None
-        tortoise = f(tortoise)
-        hare = f(f(hare))
+        tortoise = successor_function(tortoise)
+        hare = successor_function(successor_function(hare))
 
-    # At this point, the tortoise and hare have met.
-    # Now, find the position of the first repetition.
-    # The distance from the start to the cycle's beginning is mu.
+    # Phase 2: find the position of the first repetition (mu).
     mu = 0
-    tortoise = x0
+    tortoise = start_value
     while tortoise != hare:
-        tortoise = f(tortoise)
-        hare = f(hare)
+        tortoise = successor_function(tortoise)
+        hare = successor_function(hare)
         mu += 1
 
-    # Finally, find the length of the cycle.
-    # The hare moves one step at a time while the tortoise stays put.
-    # The number of steps until they meet again is the cycle length (lam).
+    # Phase 3: find the length of the cycle (lam).
     lam = 1
-    hare = f(tortoise)
+    hare = successor_function(tortoise)
     while tortoise != hare:
-        hare = f(hare)
+        hare = successor_function(hare)
         lam += 1
 
     return mu, lam