Merge branch 'master' of github.com:a3ro-dev/Python

Author: a3ro-dev

sorts/power_sort.py

@@ -37,18 +37,22 @@ def _find_run(
     """
     Detect a run (ascending or descending sequence) starting at 'start'.
 
+
     If the run is descending, reverse it in-place to make it ascending.
     Returns the end index (exclusive) of the detected run.
 
+
     Args:
         arr: The list to search in
         start: Starting index of the run
         end: End index (exclusive) of the search range
         key: Optional key function for comparisons
 
+
     Returns:
         End index (exclusive) of the detected run
 
+
     >>> arr = [3, 2, 1, 4, 5, 6]
     >>> _find_run(arr, 0, 6)
     3
@@ -63,9 +67,11 @@ def _find_run(
     if start >= end - 1:
         return start + 1
 
+
     key_func = key if key else lambda x: x
     run_end = start + 1
 
+
     # Check if run is ascending or descending
     if key_func(arr[run_end]) < key_func(arr[start]):
         # Descending run
@@ -78,28 +84,33 @@ def _find_run(
         while run_end < end and key_func(arr[run_end]) >= key_func(arr[run_end - 1]):
             run_end += 1
 
+
     return run_end
 
 
 def _node_power(n: int, b1: int, n1: int, b2: int, n2: int) -> int:
     """
     Calculate the node power for two adjacent runs.
 
+
     This determines the merge priority in the stack. The power is the smallest
     integer p such that floor(a * 2^p) != floor(b * 2^p), where:
     - a = (b1 + n1/2) / n
     - b = (b2 + n2/2) / n
 
+
     Args:
         n: Total length of the array
         b1: Start index of first run
         n1: Length of first run
         b2: Start index of second run
         n2: Length of second run
 
+
     Returns:
         The calculated node power
 
+
     >>> _node_power(100, 0, 25, 25, 25)
     2
     >>> _node_power(100, 0, 50, 50, 50)
@@ -122,6 +133,7 @@ def _node_power(n: int, b1: int, n1: int, b2: int, n2: int) -> int:
     while (a * (1 << power)) // two_n == (b * (1 << power)) // two_n:
         power += 1
 
+
     return power
 
 
@@ -135,15 +147,18 @@ def _merge(
     """
     Merge two adjacent sorted runs in-place using auxiliary space.
 
+
     Merges arr[start1:end1] with arr[end1:end2].
 
+
     Args:
         arr: The list containing the runs
         start1: Start index of first run
         end1: End index of first run (start of second run)
         end2: End index of second run
         key: Optional key function for comparisons
 
+
     >>> arr = [1, 3, 5, 2, 4, 6]
     >>> _merge(arr, 0, 3, 6)
     >>> arr
@@ -155,13 +170,16 @@ def _merge(
     """
     key_func = key if key else lambda x: x
 
+
     # Copy the runs to temporary storage
     left = arr[start1:end1]
     right = arr[end1:end2]
 
+
     i = j = 0
     k = start1
 
+
     # Merge the two runs
     while i < len(left) and j < len(right):
         if key_func(left[i]) <= key_func(right[j]):
@@ -172,12 +190,14 @@ def _merge(
             j += 1
         k += 1
 
+
     # Copy remaining elements
     while i < len(left):
         arr[k] = left[i]
         i += 1
         k += 1
 
+
     while j < len(right):
         arr[k] = right[j]
         j += 1
@@ -193,20 +213,25 @@ def power_sort(
     """
     Sort a list using the PowerSort algorithm.
 
+
     PowerSort is an adaptive merge sort that detects existing runs in the data
     and uses a power-based merging strategy for optimal performance.
 
+
     Args:
         collection: A mutable ordered collection with comparable items
         key: Optional function to extract comparison key from each element
         reverse: If True, sort in descending order
 
+
     Returns:
         The same collection ordered according to the parameters
 
+
     Time Complexity: O(n log n) worst case, O(n) for nearly sorted data
     Space Complexity: O(n)
 
+
     Examples:
     >>> power_sort([0, 5, 3, 2, 2])
     [0, 2, 2, 3, 5]
@@ -244,10 +269,12 @@ def power_sort(
     if len(collection) <= 1:
         return collection
 
+
     # Make a copy to avoid modifying the original if it's immutable
     arr = list(collection)
     n = len(arr)
 
+
     # Adjust key function for reverse sorting
     needs_final_reverse = False
     if reverse:
@@ -260,6 +287,7 @@ def reverse_key(x):
                     return -val
                 return val
 
+
             key = reverse_key
             needs_final_reverse = True
         else:
@@ -275,29 +303,34 @@ def reverse_cmp(x):
     # Stack to hold runs: each entry is (start_index, length, power)
     stack: list[tuple[int, int, int]] = []
 
+
     start = 0
     while start < n:
         # Find the next run
         run_end = _find_run(arr, start, n, key)
         run_length = run_end - start
 
+
         # Calculate power for this run
         if len(stack) == 0:
             power = 0
         else:
             prev_start, prev_length, _ = stack[-1]
             power = _node_power(n, prev_start, prev_length, start, run_length)
 
+
         # Merge runs from stack based on power comparison
         while len(stack) > 0 and stack[-1][2] >= power:
             # Merge the top run with the current run
             prev_start, prev_length, _ = stack.pop()
             _merge(arr, prev_start, prev_start + prev_length, run_end, key)
 
+
             # Update current run to include the merged run
             start = prev_start
             run_length = run_end - start
 
+
             # Recalculate power
             if len(stack) == 0:
                 power = 0
@@ -307,16 +340,19 @@ def reverse_cmp(x):
                     n, prev_prev_start, prev_prev_length, start, run_length
                 )
 
+
         # Push current run onto stack
         stack.append((start, run_length, power))
         start = run_end
 
+
     # Merge all remaining runs on the stack
     while len(stack) > 1:
         start2, length2, _ = stack.pop()
         start1, length1, _ = stack.pop()
         _merge(arr, start1, start1 + length1, start2 + length2, key)
 
+
         # Recalculate power for merged run
         if len(stack) == 0:
             power = 0
@@ -327,6 +363,7 @@ def reverse_cmp(x):
 
         stack.append((start1, start2 + length2 - start1, power))
 
+
     # Handle reverse sorting for non-numeric types
     if (
         reverse
@@ -345,27 +382,34 @@ def reverse_cmp(x):
 if __name__ == "__main__":
     import doctest
 
+
     doctest.testmod()
 
+
     print("\nPowerSort Interactive Testing")
     print("=" * 40)
 
+
     try:
         user_input = input("Enter numbers separated by a comma:\n").strip()
         if user_input == "":
             unsorted = []
         else:
             unsorted = [int(item.strip()) for item in user_input.split(",")]
 
+
         print(f"\nOriginal: {unsorted}")
         sorted_list = power_sort(unsorted)
         print(f"Sorted:   {sorted_list}")
 
+
         # Test reverse
         sorted_reverse = power_sort(unsorted, reverse=True)
         print(f"Reverse:  {sorted_reverse}")
 
+
     except ValueError:
         print("Invalid input. Please enter valid integers separated by commas.")
     except KeyboardInterrupt:
         print("\n\nGoodbye!")
+