Merge branch 'master' into feature/recursive-quick-sort-comparable-typing

Author: cclauss

DIRECTORY.md

@@ -269,13 +269,16 @@
     * [Index 2D Array In 1D](data_structures/arrays/index_2d_array_in_1d.py)
     * [Kth Largest Element](data_structures/arrays/kth_largest_element.py)
     * [Median Two Array](data_structures/arrays/median_two_array.py)
+    * [Merge Sorted](data_structures/arrays/merge_sorted.py)
     * [Monotonic Array](data_structures/arrays/monotonic_array.py)
     * [Pairs With Given Sum](data_structures/arrays/pairs_with_given_sum.py)
     * [Pairwise Iteration](data_structures/arrays/pairwise_iteration.py)
     * [Permutations](data_structures/arrays/permutations.py)
     * [Prefix Sum](data_structures/arrays/prefix_sum.py)
     * [Product Sum](data_structures/arrays/product_sum.py)
+    * [Reverse Array](data_structures/arrays/reverse_array.py)
     * [Rotate Array](data_structures/arrays/rotate_array.py)
+    * [Set Matrix Zeroes](data_structures/arrays/set_matrix_zeroes.py)
     * [Sparse Table](data_structures/arrays/sparse_table.py)
     * [Sudoku Solver](data_structures/arrays/sudoku_solver.py)
   * Binary Tree

data_structures/arrays/merge_sorted.py

@@ -0,0 +1,76 @@
+def merge_sorted_arrays(nums1: list[int], nums2: list[int]) -> list[int]:
+    """
+    Merge two sorted arrays into one sorted array.
+
+    Args:
+        nums1: The first sorted array.
+        nums2: The second sorted array.
+
+    Returns:
+        A single merged and sorted array.
+
+    Examples:
+        >>> merge_sorted_arrays([1, 3, 5], [2, 4, 6])
+        [1, 2, 3, 4, 5, 6]
+
+        >>> merge_sorted_arrays([1, 2], [])
+        [1, 2]
+
+        >>> merge_sorted_arrays([], [3, 4])
+        [3, 4]
+
+        >>> merge_sorted_arrays([], [])
+        []
+
+        >>> merge_sorted_arrays([0, 0], [0, 0])
+        [0, 0, 0, 0]
+
+        >>> merge_sorted_arrays([-5, -3, -1], [-2, -2])
+        [-5, -3, -2, -2, -1]
+
+        >>> merge_sorted_arrays(range(5), range(5))
+        [0, 0, 1, 1, 2, 2, 3, 3, 4, 4]
+
+        >>> merge_sorted_arrays([1, -1], [])
+        Traceback (most recent call last):
+            ...
+        ValueError: nums = [1, -1] is not sorted
+
+        >>> merge_sorted_arrays([], [1, -1])
+        Traceback (most recent call last):
+            ...
+        ValueError: nums = [1, -1] is not sorted
+    """
+    for nums in (nums1, nums2):
+        if list(nums) != sorted(nums):
+            msg = f"{nums = } is not sorted"
+            raise ValueError(msg)
+    # If one array is empty, simply return the other.
+    if not nums1:
+        return nums2
+    if not nums2:
+        return nums1
+
+    # Two-pointer approach to merge both sorted arrays.
+    i, j = 0, 0
+    merged = []
+
+    while i < len(nums1) and j < len(nums2):
+        if nums1[i] <= nums2[j]:
+            merged.append(nums1[i])
+            i += 1
+        else:
+            merged.append(nums2[j])
+            j += 1
+
+    # Append remaining elements if any.
+    merged.extend(nums1[i:])
+    merged.extend(nums2[j:])
+
+    return merged
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

data_structures/arrays/reverse_array.py

@@ -0,0 +1,72 @@
+"""
+In-place array reversal that also returns the reversed list to the caller.
+This algorithm reverses the elements of a list without using extra space.
+"""
+
+from typing import Any
+
+
+def reverse_array(arr: list[Any]) -> list[Any]:
+    """
+    Reverses a list in-place.
+
+    This function takes a list and reverses its elements using a two-pointer
+    approach. The left pointer starts at the beginning of the list, and the
+    right pointer starts at the end. The elements at these two pointers are
+    swapped, and the pointers move towards the center until they meet or cross.
+
+    Args:
+        arr: The list to be reversed.
+
+    Returns:
+        The same list, now reversed. This allows for method chaining.
+
+    Doctests:
+    >>> reverse_array([1, 2, 3, 4, 5])
+    [5, 4, 3, 2, 1]
+    >>> reverse_array(['a', 'b', 'c', 'd'])
+    ['d', 'c', 'b', 'a']
+    >>> reverse_array([10.5, 20.2, 30.8])
+    [30.8, 20.2, 10.5]
+    >>> reverse_array(["apple", "banana", "cherry"])
+    ['cherry', 'banana', 'apple']
+    >>> reverse_array([1])
+    [1]
+    >>> reverse_array([])
+    []
+    >>> reverse_array(list(range(5)))
+    [4, 3, 2, 1, 0]
+    >>> reverse_array(tuple(range(5)))
+    Traceback (most recent call last):
+        ...
+    TypeError: 'tuple' object does not support item assignment
+    >>> reverse_array(range(5))
+    Traceback (most recent call last):
+        ...
+    TypeError: 'range' object does not support item assignment
+    """
+    left = 0
+    right = len(arr) - 1
+
+    while left < right:
+        # Swap the elements at the left and right pointers
+        arr[left], arr[right] = arr[right], arr[left]
+        # Move the pointers towards the center
+        left += 1
+        right -= 1
+    return arr
+
+
+if __name__ == "__main__":
+    # The doctest module runs the tests embedded in the function's docstring.
+    # To run the tests, execute this script from the command line:
+    # python -m doctest -v reverse_array.py
+    import doctest
+
+    doctest.testmod()
+
+    # Example usage:
+    print("\n--- Example Usage ---")
+    sample_array = [10, 20, 30, 40, 50, 60]
+    print(f"{sample_array = }")
+    print(f"{reverse_array(sample_array) = }")

data_structures/arrays/set_matrix_zeroes.py

@@ -0,0 +1,67 @@
+"""
+Set Matrix Zeroes Algorithm
+---------------------------
+If an element in an m x n matrix is 0, set its entire row and column to 0.
+
+Explanation:
+We use the first row and first column as markers to track which rows and
+columns should be zeroed, avoiding extra space usage (O(1) space complexity).
+
+References:
+https://leetcode.com/problems/set-matrix-zeroes/
+
+Doctest:
+>>> matrix = [
+...     [1, 1, 1],
+...     [1, 0, 1],
+...     [1, 1, 1]
+... ]
+>>> set_matrix_zeroes(matrix)
+>>> matrix
+[[1, 0, 1], [0, 0, 0], [1, 0, 1]]
+>>> matrix = [[0, 1, 2, 0], [3, 4, 5, 2], [1, 3, 1, 5]]
+>>> set_matrix_zeroes(matrix)
+>>> matrix
+[[0, 0, 0, 0], [0, 4, 5, 0], [0, 3, 1, 0]]
+"""
+
+
+def set_matrix_zeroes(matrix: list[list[int]]) -> None:
+    """
+    Modify the matrix in-place such that if an element is 0,
+    its entire row and column are set to 0.
+
+    :param matrix: 2D list of integers
+    :return: None (modifies matrix in-place)
+
+    Time Complexity: O(m * n)
+    Space Complexity: O(1)
+    """
+    rows = len(matrix)
+    cols = len(matrix[0])
+    col0 = 1
+
+    # Step 1: Mark rows and columns that need to be zeroed
+    for i in range(rows):
+        if matrix[i][0] == 0:
+            col0 = 0
+        for j in range(1, cols):
+            if matrix[i][j] == 0:
+                matrix[i][0] = 0
+                matrix[0][j] = 0
+
+    # Step 2: Update the inner matrix cells
+    for i in range(1, rows):
+        for j in range(1, cols):
+            if matrix[i][0] == 0 or matrix[0][j] == 0:
+                matrix[i][j] = 0
+
+    # Step 3: Handle the first row
+    if matrix[0][0] == 0:
+        for j in range(cols):
+            matrix[0][j] = 0
+
+    # Step 4: Handle the first column
+    if col0 == 0:
+        for i in range(rows):
+            matrix[i][0] = 0

sorts/quick_sort_3_partition.py

@@ -1,7 +1,14 @@
 from random import randrange
+from typing import Any, Protocol
 
 
-def quick_sort_3partition(sorting: list, left: int, right: int) -> None:
+class Comparable(Protocol):
+    def __lt__(self, other: Any, /) -> bool: ...
+
+
+def quick_sort_3partition[T: Comparable](
+    sorting: list[T], left: int, right: int
+) -> None:
     """ "
     Python implementation of the quicksort algorithm with 3-way partition.
     The idea of 3-way quicksort is based on "Dutch National Flag algorithm".
@@ -44,7 +51,9 @@ def quick_sort_3partition(sorting: list, left: int, right: int) -> None:
     quick_sort_3partition(sorting, b + 1, right)
 
 
-def quick_sort_lomuto_partition(sorting: list, left: int, right: int) -> None:
+def quick_sort_lomuto_partition[T: Comparable](
+    sorting: list[T], left: int, right: int
+) -> None:
     """
     A pure Python implementation of the quicksort algorithm(in-place)
     with Lomuto partition scheme:
@@ -75,7 +84,7 @@ def quick_sort_lomuto_partition(sorting: list, left: int, right: int) -> None:
         quick_sort_lomuto_partition(sorting, pivot_index + 1, right)
 
 
-def lomuto_partition(sorting: list, left: int, right: int) -> int:
+def lomuto_partition[T: Comparable](sorting: list[T], left: int, right: int) -> int:
     """
     Example:
     >>> lomuto_partition([1,5,7,6], 0, 3)
@@ -91,8 +100,8 @@ def lomuto_partition(sorting: list, left: int, right: int) -> int:
     return store_index
 
 
-def hoare_partition_by_value(
-    array: list, pivot_value: int, start: int = 0, end: int | None = None
+def hoare_partition_by_value[T: Comparable](
+    array: list[T], pivot_value: T, start: int = 0, end: int | None = None
 ) -> int:
     """
     Returns the starting index of the right subarray, which contains the
@@ -172,8 +181,8 @@ def hoare_partition_by_value(
     return right + 1
 
 
-def hoare_partition_by_pivot(
-    array: list, pivot_index: int, start=0, end: int | None = None
+def hoare_partition_by_pivot[T: Comparable](
+    array: list[T], pivot_index: int, start=0, end: int | None = None
 ) -> int:
     """
     Returns the new pivot index after partitioning
@@ -201,7 +210,9 @@ def swap(i1, i2):
     return greater_or_equal
 
 
-def quicksort_hoare(array: list, start: int = 0, end: int | None = None):
+def quicksort_hoare[T: Comparable](
+    array: list[T], start: int = 0, end: int | None = None
+) -> None:
     """
     Quicksort using the Hoare partition scheme:
     - https://en.wikipedia.org/wiki/Quicksort#Hoare_partition_scheme
@@ -225,7 +236,7 @@ def quicksort_hoare(array: list, start: int = 0, end: int | None = None):
     quicksort_hoare(array, pivot_index_final + 1, end)
 
 
-def three_way_radix_quicksort(sorting: list) -> list:
+def three_way_radix_quicksort[T: Comparable](sorting: list[T]) -> list[T]:
     """
     Three-way radix quicksort:
     https://en.wikipedia.org/wiki/Quicksort#Three-way_radix_quicksort

sorts/reverse_selection.py

@@ -4,14 +4,20 @@
 This algorithm progressively sorts the array by reversing subarrays
 
 For doctests run following command:
-python3 -m doctest -v reverse_selection_sort.py
+python3 -m doctest -v reverse_selection.py
 
 For manual testing run:
-python3 reverse_selection_sort.py
+python3 reverse_selection.py
 """
 
+from typing import Any, Protocol
 
-def reverse_subarray(arr: list, start: int, end: int) -> None:
+
+class Comparable(Protocol):
+    def __lt__(self, other: Any, /) -> bool: ...
+
+
+def reverse_subarray[T](arr: list[T], start: int, end: int) -> None:
     """
     Reverse a subarray in-place.
 
@@ -41,7 +47,7 @@ def reverse_subarray(arr: list, start: int, end: int) -> None:
         end -= 1
 
 
-def reverse_selection_sort(collection: list) -> list:
+def reverse_selection_sort[T: Comparable](collection: list[T]) -> list[T]:
     """
     A pure implementation of reverse selection sort algorithm in Python
 
@@ -64,6 +70,17 @@ def reverse_selection_sort(collection: list) -> list:
 
     >>> reverse_selection_sort([5, 4, 3, 2, 1])
     [1, 2, 3, 4, 5]
+
+    >>> reverse_selection_sort(["banana", "apple", "cherry"])
+    ['apple', 'banana', 'cherry']
+
+    >>> reverse_selection_sort([3.14, 1.5, 2.7])
+    [1.5, 2.7, 3.14]
+
+    >>> reverse_selection_sort([1, "a"])  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    TypeError: ...
     """
     n = len(collection)
     for i in range(n - 1):