Merge branch 'master' into fix/binary-insertion-comparable

Author: cclauss

.github/pull_request_template.md

@@ -17,4 +17,4 @@
 * [ ] All function parameters and return values are annotated with Python [type hints](https://docs.python.org/3/library/typing.html).
 * [ ] All functions have [doctests](https://docs.python.org/3/library/doctest.html) that pass the automated testing.
 * [ ] All new algorithms include at least one URL that points to Wikipedia or another similar explanation.
-* [ ] If this pull request resolves one or more open issues then the description above includes the issue number(s) with a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue): "Fixes #ISSUE-NUMBER".
+* [ ] If this pull request resolves one or more open issues, then the description above includes the issue number(s) with a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue): "Fixes #ISSUE-NUMBER".

.github/skills/new-pull-request/SKILL.md

@@ -19,7 +19,13 @@ hand. A hand-modified `uv.lock` makes the `algorithms-keeper` bot close the pull
 request as invalid, and even a repo maintainer cannot undo that.
 
 Always check at least one Markdown checkbox in the pull request description (the "Describe your change" section), or the
-`algorithms-keeper` bot will close the pull request as invalid. Any repo maintainer can undo this if you @mention them on the closed pull request.
+`algorithms-keeper` bot will close the pull request as invalid — and it does
+this *before* a human reads the PR, so a genuinely good change gets closed for a
+formatting reason. This applies to **every** pull request, including CI, docs,
+and tooling changes that are not algorithms: tick the boxes that genuinely apply
+so the body is never submitted with all boxes empty. Any repo maintainer can
+undo this if you @mention them on the closed pull request, but re-opening is
+often unreliable, so it is far better to get it right the first time.
 
 ### 1. Before contributing / Is this an algorithm?
 
@@ -55,3 +61,15 @@ Always check at least one Markdown checkbox in the pull request description (the
 - [ ] At least one **Wikipedia (or equivalent) URL** documenting the algorithm.
 - [ ] Docstring explains what the function does and its parameters/returns.
 - [ ] No unnecessary third-party dependencies.
+
+## Before you click "Create pull request"
+
+This is the final gate. Do not open the pull request until every item here is true:
+
+- [ ] At least one Markdown checkbox in the PR description is checked. **Verify
+      this by re-reading the rendered body** — if every box is still `- [ ]`, the
+      `algorithms-keeper` bot will auto-close the PR before any human sees it.
+      Check the boxes that genuinely apply to this change; never submit an
+      all-empty checklist, even for a CI, docs, or tooling PR.
+- [ ] The branch is not `master`, and `master` is synced with `upstream/master`.
+- [ ] `uv.lock` was not hand-edited.

.github/zizmor.yml

@@ -2,7 +2,6 @@ rules:
   excessive-permissions:
     disable: true
   unpinned-uses:
-    disable: true
-    # config:
-    #   policies:
-    #     actions/*: ref-pin
+    config:
+      policies:
+        "*": ref-pin

DIRECTORY.md

@@ -1370,6 +1370,7 @@
   * [Dutch National Flag Sort](sorts/dutch_national_flag_sort.py)
   * [Exchange Sort](sorts/exchange_sort.py)
   * [External Sort](sorts/external_sort.py)
+  * [Flash Sort](sorts/flash_sort.py)
   * [Gnome Sort](sorts/gnome_sort.py)
   * [Heap Sort](sorts/heap_sort.py)
   * [Insertion Sort](sorts/insertion_sort.py)

sorts/adaptive_merge_sort.py

@@ -0,0 +1,57 @@
+def adaptive_merge_sort(sequence: list) -> list:
+    if len(sequence) < 2:
+        return sequence
+
+    aux = sequence[:]
+    print(f"Initial sequence: {sequence}")
+    adaptive_merge_sort_helper(sequence, aux, 0, len(sequence) - 1)
+    print(f"Sorted sequence: {sequence}")
+    return sequence
+
+
+def adaptive_merge_sort_helper(array: list, aux: list, low: int, high: int) -> None:
+    if high <= low:
+        return
+
+    mid = (low + high) // 2
+    print(f"Sorting: array[{low}:{mid + 1}] and array[{mid + 1}:{high + 1}]")
+
+    adaptive_merge_sort_helper(aux, array, low, mid)
+    adaptive_merge_sort_helper(aux, array, mid + 1, high)
+
+    if array[mid] <= array[mid + 1]:
+        print(f"Skipping merge as array[{mid}] <= array[{mid + 1}]")
+        array[low : high + 1] = aux[low : high + 1]
+        return
+
+    merge(array, aux, low, mid, high)
+
+
+def merge(array: list, aux: list, low: int, mid: int, high: int) -> None:
+    print(f"Merging: array[{low}:{mid + 1}] and array[{mid + 1}:{high + 1}]")
+
+    i, j = low, mid + 1
+    for k in range(low, high + 1):
+        if i > mid or j > high:
+            if i > mid:
+                aux[k] = array[j]
+                j += 1
+            else:
+                aux[k] = array[i]
+                i += 1
+        elif array[i] <= array[j]:
+            aux[k] = array[i]
+            i += 1
+        else:
+            aux[k] = array[j]
+            j += 1
+
+    for k in range(low, high + 1):
+        array[k] = aux[k]
+
+    print(f"After merge: {array[low:high + 1]}")
+
+
+# Example usage
+if __name__ == "__main__":
+    print(adaptive_merge_sort([4, 3, 1, 2]))

sorts/bubble_sort_recursive.py

@@ -0,0 +1,35 @@
+def bubble_sort_recursive(arr: list[int]) -> list[int]:
+    """
+    Sorts a list of integers using the recursive Bubble Sort algorithm.
+
+    >>> bubble_sort_recursive([5, 1, 4, 2, 8])
+    [1, 2, 4, 5, 8]
+    >>> bubble_sort_recursive([])
+    []
+    >>> bubble_sort_recursive([1])
+    [1]
+    >>> bubble_sort_recursive([3, 3, 2, 1])
+    [1, 2, 3, 3]
+    >>> bubble_sort_recursive([-1, 5, 0, -2])
+    [-2, -1, 0, 5]
+    """
+    n = len(arr)
+    if n <= 1:
+        return arr
+
+    swapped = False
+    for i in range(n - 1):
+        if arr[i] > arr[i + 1]:
+            arr[i], arr[i + 1] = arr[i + 1], arr[i]
+            swapped = True
+
+    if not swapped:
+        return arr
+
+    return [*bubble_sort_recursive(arr[:-1]), arr[-1]]
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

sorts/comb_sort.py

@@ -30,15 +30,19 @@ def comb_sort(data: list) -> list:
     []
     >>> comb_sort([99, 45, -7, 8, 2, 0, -15, 3])
     [-15, -7, 0, 2, 3, 8, 45, 99]
+    >>> comb_sort([2, 0, 3, 4, 5, 6, 1])
+    [0, 1, 2, 3, 4, 5, 6]
     """
     shrink_factor = 1.3
     gap = len(data)
     completed = False
 
     while not completed:
-        # Update the gap value for a next comb
-        gap = int(gap / shrink_factor)
-        if gap <= 1:
+        # Update the gap value for a next comb.  The gap is never allowed to drop
+        # below 1: a gap of 0 compares each element with itself, so no swap can
+        # ever happen and the loop would exit while the data is still unsorted.
+        gap = max(int(gap / shrink_factor), 1)
+        if gap == 1:
             completed = True
 
         index = 0

sorts/cyclic_sort.py

@@ -5,6 +5,7 @@
 python -m doctest -v cyclic_sort.py
 or
 python3 -m doctest -v cyclic_sort.py
+
 For manual testing run:
 python cyclic_sort.py
 or
@@ -27,20 +28,42 @@ def cyclic_sort(nums: list[int]) -> list[int]:
     []
     >>> cyclic_sort([3, 5, 2, 1, 4])
     [1, 2, 3, 4, 5]
+
+    >>> cyclic_sort([1, 2, 2])
+    Traceback (most recent call last):
+    ...
+    ValueError: All numbers must be unique, got 2
+
+    >>> cyclic_sort([1, 5])
+    Traceback (most recent call last):
+    ...
+    ValueError: All numbers must be in range 1 to 2, got 5
     """
 
+    # Input validation
+    seen = set()
+    n = len(nums)
+
+    for num in nums:
+        if num in seen:
+            message = f"All numbers must be unique, got {num}"
+            raise ValueError(message)
+
+        if num < 1 or num > n:
+            message = f"All numbers must be in range 1 to {n}, got {num}"
+            raise ValueError(message)
+
+        seen.add(num)
+
     # Perform cyclic sort
     index = 0
     while index < len(nums):
-        # Calculate the correct index for the current element
         correct_index = nums[index] - 1
-        # If the current element is not at its correct position,
-        # swap it with the element at its correct index
+
         if index != correct_index:
             nums[index], nums[correct_index] = nums[correct_index], nums[index]
+
         else:
-            # If the current element is already in its correct position,
-            # move to the next element
             index += 1
 
     return nums
@@ -50,6 +73,7 @@ def cyclic_sort(nums: list[int]) -> list[int]:
     import doctest
 
     doctest.testmod()
+
     user_input = input("Enter numbers separated by a comma:\n").strip()
     unsorted = [int(item) for item in user_input.split(",")]
     print(*cyclic_sort(unsorted), sep=",")

sorts/flash_sort.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""
+Flash Sort Algorithm Implementation
+
+Flash sort is a distribution sorting algorithm showing linear computational
+complexity O(n) for uniformly distributed datasets and relatively little
+additional memory requirement. The basic idea is to use the distribution
+of the values to be sorted to determine their approximate final positions
+directly, without comparing and moving each element through many intermediate
+positions as done by other algorithms.
+
+The algorithm was developed by Karl-Dietrich Neubert in 1998 and builds upon
+the idea of bucket sort. It works by classifying elements into classes and
+then sorting each class.
+
+Time Complexity:
+- Best Case: O(n) when data is uniformly distributed
+- Average Case: O(n + k) where k is the number of classes
+- Worst Case: O(n²) when data is not uniformly distributed
+
+Space Complexity: O(k) where k is the number of classes
+
+Source: https://en.wikipedia.org/wiki/Flashsort
+"""
+
+from __future__ import annotations
+
+
+def flash_sort(arr: list[int | float]) -> list[int | float]:
+    """
+    Sorts a list using the Flash Sort algorithm.
+
+    Flash sort is particularly efficient for uniformly distributed data.
+    It uses the distribution of values to determine approximate positions.
+
+    Args:
+        arr: List of integers or floats to be sorted
+
+    Returns:
+        Sorted list in ascending order
+
+    Examples:
+    >>> flash_sort([4, 2, 7, 1, 9, 3])
+    [1, 2, 3, 4, 7, 9]
+    >>> flash_sort([])
+    []
+    >>> flash_sort([5])
+    [5]
+    >>> flash_sort([3, 3, 3, 3])
+    [3, 3, 3, 3]
+    >>> flash_sort([-1, -5, 0, 3, 2])
+    [-5, -1, 0, 2, 3]
+    >>> flash_sort([1.5, 2.3, 0.1, 3.7, 1.2])
+    [0.1, 1.2, 1.5, 2.3, 3.7]
+    >>> flash_sort([10, 9, 8, 7, 6, 5, 4, 3, 2, 1])
+    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+    >>> import random
+    >>> data = random.sample(range(100), 20)
+    >>> flash_sort(data) == sorted(data)
+    True
+    >>> flash_sort([42])
+    [42]
+    >>> flash_sort([2.5, 1.1, 3.3, 2.5, 1.1])
+    [1.1, 1.1, 2.5, 2.5, 3.3]
+    """
+    if len(arr) <= 1:
+        return arr.copy()
+
+    # Create a copy to avoid modifying the original array
+    result = arr.copy()
+    n = len(result)
+
+    # Find min and max values
+    min_val = min(result)
+    max_val = max(result)
+
+    # If all elements are the same, return the array
+    if min_val == max_val:
+        return result
+
+    # Number of classes (buckets) - typically n/10 to n/5 works well
+    m = max(1, int(0.45 * n))
+
+    # Initialize class sizes array
+    class_sizes = [0] * m
+
+    # Calculate class sizes
+    c1 = (m - 1) / (max_val - min_val)
+
+    for value in result:
+        class_index = int(c1 * (value - min_val))
+        if class_index >= m:
+            class_index = m - 1
+        class_sizes[class_index] += 1
+
+    # Calculate cumulative class sizes (positions)
+    for i in range(1, m):
+        class_sizes[i] += class_sizes[i - 1]
+
+    # Permutation phase
+    hold = result[0]
+    j = 0
+    k = m - 1
+
+    while j < n - 1:
+        while j >= class_sizes[k]:
+            k -= 1
+
+        flash = int(c1 * (hold - min_val))
+        if flash >= m:
+            flash = m - 1
+
+        while j < class_sizes[flash]:
+            k = flash
+            class_sizes[k] -= 1
+            result[j], result[class_sizes[k]] = result[class_sizes[k]], result[j]
+            hold = result[j]
+            j += 1
+            flash = int(c1 * (hold - min_val))
+            if flash >= m:
+                flash = m - 1
+
+        j += 1
+        if j < n:
+            hold = result[j]
+
+    # Insertion sort for final sorting within classes
+    for i in range(1, n):
+        key = result[i]
+        j = i - 1
+        while j >= 0 and result[j] > key:
+            result[j + 1] = result[j]
+            j -= 1
+        result[j + 1] = key
+
+    return result
+
+
+if __name__ == "__main__":
+    from doctest import testmod
+
+    testmod()
+
+    # Additional test cases
+    test_cases: list[list[int | float]] = [
+        [64, 34, 25, 12, 22, 11, 90],
+        [5, 2, 4, 6, 1, 3],
+        [1],
+        [],
+        [3, 3, 3, 3],
+        [-1, -3, 2, 0, -5],
+        [1.1, 2.2, 0.5, 3.3, 1.5],
+    ]
+
+    for test_case in test_cases:
+        sorted_result = flash_sort(test_case)
+        expected = sorted(test_case)
+        assert sorted_result == expected, f"Failed for {test_case}"
+        print(f"✓ {test_case} -> {sorted_result}")
+
+    print("All tests passed!")