diff --git a/data_structures/arrays/dutch_national_flag_sort.py b/data_structures/arrays/dutch_national_flag_sort.py new file mode 100644 index 000000000000..4b6d1d091316 --- /dev/null +++ b/data_structures/arrays/dutch_national_flag_sort.py @@ -0,0 +1,108 @@ +""" +Implements the Dutch National Flag algorithm to sort an array of 0s, 1s, and 2s +in-place. Includes error handling for invalid values and examples in the docstring. + +This algorithm runs in O(n) time and O(1) space using three pointers. +See: https://en.wikipedia.org/wiki/Dutch_national_flag_problem +""" + +from __future__ import annotations + + +def dutch_flag_sort(arr: list[int]) -> None: + """ + Sorts an array of 0s, 1s, and 2s in-place. + + Args: + arr: List containing only 0, 1, or 2. + + Returns: + None + + Raises: + ValueError: If array contains values other than 0, 1, or 2. + + Examples: + >>> arr = [2, 0, 2, 1, 1, 0] + >>> dutch_flag_sort(arr) + >>> arr + [0, 0, 1, 1, 2, 2] + + >>> arr = [2, 0, 1] + >>> dutch_flag_sort(arr) + >>> arr + [0, 1, 2] + + >>> arr = [] + >>> dutch_flag_sort(arr) + >>> arr + [] + + >>> arr = [1] + >>> dutch_flag_sort(arr) + >>> arr + [1] + + >>> arr = [0, 0, 0] + >>> dutch_flag_sort(arr) + >>> arr + [0, 0, 0] + + >>> arr = [3] + >>> dutch_flag_sort(arr) + Traceback (most recent call last): + ... + ValueError: Array contains invalid value: 3 + + >>> arr = [-1, 0, 1] + >>> dutch_flag_sort(arr) + Traceback (most recent call last): + ... + ValueError: Array contains invalid value: -1 + + >>> arr = [2, 0, '1'] + >>> dutch_flag_sort(arr) + Traceback (most recent call last): + ... + ValueError: Array contains invalid value: 1 + """ + if not arr: + return + + low = mid = 0 + high = len(arr) - 1 + + while mid <= high: + value = arr[mid] + if value == 0: + arr[low], arr[mid] = arr[mid], arr[low] + low += 1 + mid += 1 + elif value == 1: + mid += 1 + elif value == 2: + arr[mid], arr[high] = arr[high], arr[mid] + high -= 1 + else: + msg = f"Array contains invalid value: {value}" + raise ValueError(msg) + + +if __name__ == "__main__": + examples = [ + [2, 0, 2, 1, 1, 0], + [2, 0, 1], + [], + [1], + [0, 0, 0], + [2, 2, 2], + [1, 1, 1], + [0, 1, 2, 0, 1, 2], + [2, 1, 0, 2, 1, 0], + ] + + for test_arr in examples: + arr = test_arr.copy() + print(f"Before: {arr}") + dutch_flag_sort(arr) + print(f"After : {arr}\n")