algonest 0.1.0__py3-none-any.whl

algonest/__init__.py

@@ -0,0 +1,223 @@
+"""Public API for algonest Phase 5."""
+
+from algonest.arrays import (
+    container_with_water,
+    longest_unique_substring,
+    max_subarray_sum,
+    max_sum_subarray_k,
+    partition_by_pivot,
+    prefix_sum,
+    range_sum,
+    remove_duplicates,
+    sort_three_values,
+    subarray_sum_equals_k,
+    two_sum_sorted,
+)
+from algonest.search import (
+    binary_search,
+    jump_search,
+    linear_search,
+    lower_bound,
+    ternary_search,
+    upper_bound,
+)
+from algonest.heap import MaxHeap, MinHeap, PriorityQueue
+from algonest.linked_list import (
+    CircularLinkedList,
+    DoublyLinkedList,
+    DoublyListNode,
+    ListNode,
+    SinglyLinkedList,
+)
+from algonest.sort import (
+    bubble_sort,
+    counting_sort,
+    heap_sort,
+    insertion_sort,
+    merge_sort,
+    quick_sort,
+    radix_sort,
+    selection_sort,
+)
+from algonest.stack_queue import (
+    DequeDS,
+    Queue,
+    Stack,
+    largest_rectangle_in_histogram,
+    next_greater_element,
+)
+from algonest.dynamic_programming import (
+    coin_change_ways,
+    edit_distance,
+    knapsack_01,
+    lcs_length,
+    lis_length,
+    matrix_chain_order,
+    min_coins,
+    unbounded_knapsack,
+)
+from algonest.graphs import (
+    DSU,
+    bellman_ford,
+    bfs_traversal,
+    connected_components,
+    dfs_topological_sort,
+    dfs_traversal,
+    dijkstra_shortest_paths,
+    floyd_warshall,
+    has_cycle_undirected,
+    kahn_topological_sort,
+    kruskal_mst,
+    prim_mst,
+    shortest_path_unweighted,
+)
+from algonest.trees import (
+    AVLTree,
+    BST,
+    BinaryTree,
+    FenwickTree,
+    SegmentTree,
+    TreeNode,
+    inorder,
+    level_order,
+    postorder,
+    preorder,
+)
+from algonest.strings import (
+    Trie,
+    find_all_anagrams,
+    group_anagrams,
+    is_anagram,
+    kmp_search,
+    rabin_karp_search,
+    z_array,
+    z_search,
+)
+from algonest.math import (
+    chinese_remainder_theorem,
+    clear_bit,
+    count_bits,
+    extended_gcd,
+    fast_power,
+    gcd,
+    is_power_of_two,
+    is_prime,
+    lcm,
+    mod_exp,
+    mod_inverse,
+    prime_factors,
+    set_bit,
+    sieve_of_eratosthenes,
+    xor_trick,
+)
+from algonest.utils import (
+    assert_sorted,
+    build_pytest_command,
+    read_ints_from_text,
+    run_tests,
+    time_function,
+    validate_iterable,
+    write_lines,
+)
+
+__all__ = [
+    "lower_bound",
+    "upper_bound",
+    "binary_search",
+    "linear_search",
+    "ternary_search",
+    "jump_search",
+    "max_sum_subarray_k",
+    "longest_unique_substring",
+    "two_sum_sorted",
+    "remove_duplicates",
+    "container_with_water",
+    "prefix_sum",
+    "range_sum",
+    "subarray_sum_equals_k",
+    "max_subarray_sum",
+    "sort_three_values",
+    "partition_by_pivot",
+    "bubble_sort",
+    "selection_sort",
+    "insertion_sort",
+    "merge_sort",
+    "quick_sort",
+    "heap_sort",
+    "counting_sort",
+    "radix_sort",
+    "ListNode",
+    "DoublyListNode",
+    "SinglyLinkedList",
+    "DoublyLinkedList",
+    "CircularLinkedList",
+    "Stack",
+    "Queue",
+    "DequeDS",
+    "next_greater_element",
+    "largest_rectangle_in_histogram",
+    "MinHeap",
+    "MaxHeap",
+    "PriorityQueue",
+    "TreeNode",
+    "BinaryTree",
+    "BST",
+    "inorder",
+    "preorder",
+    "postorder",
+    "level_order",
+    "AVLTree",
+    "SegmentTree",
+    "FenwickTree",
+    "bfs_traversal",
+    "shortest_path_unweighted",
+    "dfs_traversal",
+    "connected_components",
+    "has_cycle_undirected",
+    "dijkstra_shortest_paths",
+    "bellman_ford",
+    "floyd_warshall",
+    "kahn_topological_sort",
+    "dfs_topological_sort",
+    "kruskal_mst",
+    "prim_mst",
+    "DSU",
+    "knapsack_01",
+    "unbounded_knapsack",
+    "lcs_length",
+    "lis_length",
+    "min_coins",
+    "coin_change_ways",
+    "matrix_chain_order",
+    "edit_distance",
+    "kmp_search",
+    "rabin_karp_search",
+    "z_array",
+    "z_search",
+    "Trie",
+    "group_anagrams",
+    "is_anagram",
+    "find_all_anagrams",
+    "gcd",
+    "lcm",
+    "extended_gcd",
+    "sieve_of_eratosthenes",
+    "is_prime",
+    "prime_factors",
+    "mod_exp",
+    "mod_inverse",
+    "chinese_remainder_theorem",
+    "fast_power",
+    "count_bits",
+    "is_power_of_two",
+    "set_bit",
+    "clear_bit",
+    "xor_trick",
+    "validate_iterable",
+    "read_ints_from_text",
+    "write_lines",
+    "time_function",
+    "assert_sorted",
+    "build_pytest_command",
+    "run_tests",
+]

algonest/arrays/__init__.py

@@ -0,0 +1,21 @@
+"""Array algorithms package."""
+
+from algonest.arrays.dutch_flag import partition_by_pivot, sort_three_values
+from algonest.arrays.kadane import max_subarray_sum
+from algonest.arrays.prefix_sum import prefix_sum, range_sum, subarray_sum_equals_k
+from algonest.arrays.sliding_window import longest_unique_substring, max_sum_subarray_k
+from algonest.arrays.two_pointers import container_with_water, remove_duplicates, two_sum_sorted
+
+__all__ = [
+	"max_sum_subarray_k",
+	"longest_unique_substring",
+	"two_sum_sorted",
+	"remove_duplicates",
+	"container_with_water",
+	"prefix_sum",
+	"range_sum",
+	"subarray_sum_equals_k",
+	"max_subarray_sum",
+	"sort_three_values",
+	"partition_by_pivot",
+]

algonest/arrays/dutch_flag.py

@@ -0,0 +1,92 @@
+"""Dutch flag partitioning algorithms."""
+
+from typing import Any, Iterable, List
+
+from algonest.utils import _validate_iterable
+
+
+def sort_three_values(
+    arr: Iterable[Any],
+    low_value: Any,
+    mid_value: Any,
+    high_value: Any,
+) -> List[Any]:
+    """Return values sorted by low/mid/high categories in one pass.
+
+    Args:
+        arr (Iterable[Any]): Iterable containing only three category values.
+        low_value (Any): Category that should appear first.
+        mid_value (Any): Category that should appear second.
+        high_value (Any): Category that should appear third.
+
+    Returns:
+        List[Any]: Newly sorted list by category order.
+
+    Raises:
+        TypeError: If arr is not iterable.
+        ValueError: If arr contains values outside the three categories.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n)
+
+    Example:
+        >>> sort_three_values([2, 0, 1, 2, 1, 0], 0, 1, 2)
+        [0, 0, 1, 1, 2, 2]
+    """
+    values = _validate_iterable(arr)
+    allowed = {low_value, mid_value, high_value}
+    for value in values:
+        if value not in allowed:
+            raise ValueError("arr must contain only the three provided values")
+
+    out = values[:]
+    low = 0
+    mid = 0
+    high = len(out) - 1
+    while mid <= high:
+        if out[mid] == low_value:
+            out[low], out[mid] = out[mid], out[low]
+            low += 1
+            mid += 1
+        elif out[mid] == mid_value:
+            mid += 1
+        else:
+            out[mid], out[high] = out[high], out[mid]
+            high -= 1
+    return out
+
+
+def partition_by_pivot(arr: Iterable[Any], pivot: Any) -> List[Any]:
+    """Return values partitioned into < pivot, == pivot, > pivot.
+
+    Args:
+        arr (Iterable[Any]): Iterable input values.
+        pivot (Any): Pivot for partitioning.
+
+    Returns:
+        List[Any]: Partitioned list.
+
+    Raises:
+        TypeError: If arr is not iterable.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n)
+
+    Example:
+        >>> partition_by_pivot([3, 5, 2, 5, 1], 3)
+        [2, 1, 3, 5, 5]
+    """
+    values = _validate_iterable(arr)
+    lower: List[Any] = []
+    equal: List[Any] = []
+    higher: List[Any] = []
+
+    for value in values:
+        if value < pivot:
+            lower.append(value)
+        elif value == pivot:
+            equal.append(value)
+        else:
+            higher.append(value)
+
+    return lower + equal + higher

algonest/arrays/kadane.py

@@ -0,0 +1,42 @@
+"""Kadane algorithm for maximum subarray sum."""
+
+from numbers import Real
+from typing import Iterable
+
+from algonest.utils import _validate_iterable
+
+
+def max_subarray_sum(arr: Iterable[Real]) -> Real:
+    """Return the maximum sum among all contiguous subarrays.
+
+    Args:
+        arr (Iterable[Real]): Iterable of numeric values.
+
+    Returns:
+        Real: Maximum contiguous subarray sum.
+
+    Raises:
+        TypeError: If arr is not iterable or contains non-numeric values.
+        ValueError: If input is empty.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n)
+
+    Example:
+        >>> max_subarray_sum([-2, 1, -3, 4, -1, 2, 1, -5, 4])
+        6
+    """
+    values = _validate_iterable(arr)
+    if not values:
+        raise ValueError("arr cannot be empty")
+
+    for value in values:
+        if not isinstance(value, Real) or isinstance(value, bool):
+            raise TypeError("All elements in arr must be numeric")
+
+    current = values[0]
+    best = values[0]
+    for value in values[1:]:
+        current = max(value, current + value)
+        best = max(best, current)
+    return best

algonest/arrays/prefix_sum.py

@@ -0,0 +1,115 @@
+"""Prefix-sum based array algorithms."""
+
+from numbers import Real
+from typing import Any, Iterable, List
+
+from algonest.utils import _validate_iterable
+
+
+def prefix_sum(arr: Iterable[Real]) -> List[Real]:
+    """Return prefix sums for numeric iterable input.
+
+    Args:
+        arr (Iterable[Real]): Iterable of numeric values.
+
+    Returns:
+        List[Real]: Prefix sums where out[i] = sum(arr[0:i+1]).
+
+    Raises:
+        TypeError: If arr is not iterable or contains non-numeric values.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n)
+
+    Example:
+        >>> prefix_sum([3, 5, 2, 7])
+        [3, 8, 10, 17]
+    """
+    values = _validate_iterable(arr)
+    out: List[Real] = []
+    running: Real = 0
+
+    for value in values:
+        if not isinstance(value, Real) or isinstance(value, bool):
+            raise TypeError("All elements in arr must be numeric")
+        running += value
+        out.append(running)
+    return out
+
+
+def range_sum(prefix: Iterable[Real], left: int, right: int) -> Real:
+    """Return inclusive sum from left to right using prefix sums.
+
+    Args:
+        prefix (Iterable[Real]): Prefix-sum iterable.
+        left (int): Left index, inclusive.
+        right (int): Right index, inclusive.
+
+    Returns:
+        Real: Sum over [left, right].
+
+    Raises:
+        TypeError: If prefix is not iterable or bounds are not integers.
+        ValueError: If prefix is empty or left > right.
+        IndexError: If bounds are out of range.
+
+    Time Complexity: O(1)
+    Space Complexity: O(n)
+
+    Example:
+        >>> p = prefix_sum([3, 5, 2, 7])
+        >>> range_sum(p, 1, 3)
+        14
+    """
+    values = _validate_iterable(prefix)
+    if not values:
+        raise ValueError("prefix cannot be empty")
+    if not isinstance(left, int) or isinstance(left, bool):
+        raise TypeError("left must be an integer")
+    if not isinstance(right, int) or isinstance(right, bool):
+        raise TypeError("right must be an integer")
+    if left > right:
+        raise ValueError("left cannot be greater than right")
+    if left < 0 or right < 0 or left >= len(values) or right >= len(values):
+        raise IndexError("left and right must be valid indices")
+
+    return values[right] if left == 0 else values[right] - values[left - 1]
+
+
+def subarray_sum_equals_k(arr: Iterable[Real], k: Real) -> int:
+    """Return count of contiguous subarrays with sum exactly equal to k.
+
+    Args:
+        arr (Iterable[Real]): Iterable of numeric values.
+        k (Real): Target sum.
+
+    Returns:
+        int: Number of matching subarrays.
+
+    Raises:
+        TypeError: If arr is not iterable or contains non-numeric values.
+        TypeError: If k is not numeric.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n)
+
+    Example:
+        >>> subarray_sum_equals_k([1, 1, 1], 2)
+        2
+    """
+    values = _validate_iterable(arr)
+    if not isinstance(k, Real) or isinstance(k, bool):
+        raise TypeError("k must be numeric")
+
+    for value in values:
+        if not isinstance(value, Real) or isinstance(value, bool):
+            raise TypeError("All elements in arr must be numeric")
+
+    count = 0
+    running: Real = 0
+    seen = {0: 1}
+    for value in values:
+        running += value
+        count += seen.get(running - k, 0)
+        seen[running] = seen.get(running, 0) + 1
+    return count

algonest/arrays/sliding_window.py

@@ -0,0 +1,90 @@
+"""Sliding window algorithms."""
+
+from numbers import Real
+from typing import Iterable
+
+from algonest.utils import _validate_iterable
+
+
+def max_sum_subarray_k(arr: Iterable[Real], k: int) -> Real:
+    """Return maximum sum over all contiguous subarrays of size k.
+
+    Args:
+        arr (Iterable[Real]): Iterable numeric input.
+        k (int): Window size.
+
+    Returns:
+        Real: Maximum subarray sum of length k.
+
+    Raises:
+        TypeError: If arr is not an iterable.
+        TypeError: If array values are not numeric.
+        ValueError: If k is not a valid positive integer in bounds.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n) due to list conversion
+
+    Example:
+        >>> max_sum_subarray_k([2, 1, 5, 1, 3, 2], 3)
+        9
+    """
+    values = _validate_iterable(arr)
+
+    if not isinstance(k, int) or isinstance(k, bool):
+        raise ValueError("k must be an integer")
+    if k <= 0:
+        raise ValueError("k must be a positive integer")
+    if k > len(values):
+        raise ValueError("k cannot be greater than the length of input")
+
+    for element in values:
+        if not isinstance(element, Real) or isinstance(element, bool):
+            raise TypeError("All elements in arr must be numeric")
+
+    window_sum = sum(values[:k])
+    best_sum = window_sum
+
+    for right in range(k, len(values)):
+        window_sum += values[right]
+        window_sum -= values[right - k]
+        if window_sum > best_sum:
+            best_sum = window_sum
+
+    return best_sum
+
+
+def longest_unique_substring(s: str) -> int:
+    """Return length of the longest substring without repeated characters.
+
+    Args:
+        s (str): Input string.
+
+    Returns:
+        int: Longest unique substring length.
+
+    Raises:
+        TypeError: If s is not a string.
+
+    Time Complexity: O(n)
+    Space Complexity: O(min(n, alphabet_size))
+
+    Example:
+        >>> longest_unique_substring("abcabcbb")
+        3
+    """
+    if not isinstance(s, str):
+        raise TypeError("longest_unique_substring expects 's' to be a string")
+
+    last_seen = {}
+    left = 0
+    max_length = 0
+
+    for right, char in enumerate(s):
+        if char in last_seen and last_seen[char] >= left:
+            left = last_seen[char] + 1
+        last_seen[char] = right
+        current_length = right - left + 1
+        if current_length > max_length:
+            max_length = current_length
+
+    return max_length

algonest/arrays/two_pointers.py

@@ -0,0 +1,119 @@
+"""Two-pointer algorithms for array problems."""
+
+from numbers import Real
+from typing import Any, Iterable, Tuple
+
+from algonest.utils import _validate_iterable
+
+
+def two_sum_sorted(arr: Iterable[Real], target: Real) -> Tuple[int, int]:
+    """Return indices of two values in sorted input whose sum equals target.
+
+    Args:
+        arr (Iterable[Real]): Sorted iterable of numeric values.
+        target (Real): Desired sum.
+
+    Returns:
+        Tuple[int, int]: Pair of indices or (-1, -1) if not found.
+
+    Raises:
+        TypeError: If arr is not iterable or contains non-numeric values.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n)
+
+    Example:
+        >>> two_sum_sorted([1, 2, 4, 7, 11], 9)
+        (1, 3)
+    """
+    values = _validate_iterable(arr)
+    if not isinstance(target, Real) or isinstance(target, bool):
+        raise TypeError("target must be numeric")
+
+    for value in values:
+        if not isinstance(value, Real) or isinstance(value, bool):
+            raise TypeError("All elements in arr must be numeric")
+
+    left = 0
+    right = len(values) - 1
+    while left < right:
+        current = values[left] + values[right]
+        if current == target:
+            return left, right
+        if current < target:
+            left += 1
+        else:
+            right -= 1
+    return -1, -1
+
+
+def remove_duplicates(arr: Iterable[Any]) -> int:
+    """Return number of unique values in sorted iterable input.
+
+    Args:
+        arr (Iterable[Any]): Sorted iterable input values.
+
+    Returns:
+        int: Count of unique values.
+
+    Raises:
+        TypeError: If arr is not iterable.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n)
+
+    Example:
+        >>> remove_duplicates([1, 1, 2, 2, 3])
+        3
+    """
+    values = _validate_iterable(arr)
+    if not values:
+        return 0
+
+    unique = 1
+    for i in range(1, len(values)):
+        if values[i] != values[i - 1]:
+            unique += 1
+    return unique
+
+
+def container_with_water(arr: Iterable[Any]) -> int:
+    """Return the maximum area formed by two lines and the x-axis.
+
+    Args:
+        arr (Iterable[Any]): Iterable of non-negative integer heights.
+
+    Returns:
+        int: Maximum container area.
+
+    Raises:
+        TypeError: If arr is not iterable or contains non-integer heights.
+        ValueError: If any height is negative.
+
+    Time Complexity: O(n)
+    Space Complexity: O(n)
+
+    Example:
+        >>> container_with_water([1, 8, 6, 2, 5, 4, 8, 3, 7])
+        49
+    """
+    values = _validate_iterable(arr)
+    for value in values:
+        if not isinstance(value, int) or isinstance(value, bool):
+            raise TypeError("All heights must be integers")
+        if value < 0:
+            raise ValueError("Heights must be non-negative")
+
+    left = 0
+    right = len(values) - 1
+    best = 0
+    while left < right:
+        width = right - left
+        area = width * min(values[left], values[right])
+        if area > best:
+            best = area
+        if values[left] < values[right]:
+            left += 1
+        else:
+            right -= 1
+    return best