Add Merge Sorted Arrays Algorithm with Type Hints and Doctests

DIRECTORY.md

@@ -267,6 +267,7 @@
     * [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)

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()