feat: add binary search algorithm and iterable array constructors

Implement binary_search, lower_bound, and upper_bound for any indexable
collection (list, StaticArray, DynamicArray). Add iterable constructors
to both array types for convenient initialization. Add algorithms
package to coverage config.

Author: AzizAlievDevelopment

algorithms/__init__.py

@@ -0,0 +1 @@
+

algorithms/searching/__init__.py

@@ -0,0 +1 @@
+

algorithms/searching/binary_search.py

@@ -0,0 +1,65 @@
+from typing import Any
+
+
+def binary_search(arr: Any, target: Any) -> int:
+    """Return the index of *target* in a sorted sequence, or -1 if not found.
+
+    Time: O(log n). Space: O(1).
+
+    Accepts any indexable collection with ``__getitem__`` and ``__len__``
+    (``list``, ``StaticArray``, ``DynamicArray``, etc.).
+    The input must be sorted in ascending order.
+    """
+    low = 0
+    high = len(arr) - 1
+
+    while low <= high:
+        mid = low + (high - low) // 2
+        if arr[mid] == target:
+            return mid
+        if arr[mid] < target:
+            low = mid + 1
+        else:
+            high = mid - 1
+
+    return -1
+
+
+def lower_bound(arr: Any, target: Any) -> int:
+    """Return the index of the first element >= *target*.
+
+    Time: O(log n). Space: O(1).
+
+    Returns ``len(arr)`` if all elements are less than *target*.
+    """
+    low = 0
+    high = len(arr)
+
+    while low < high:
+        mid = low + (high - low) // 2
+        if arr[mid] < target:
+            low = mid + 1
+        else:
+            high = mid
+
+    return low
+
+
+def upper_bound(arr: Any, target: Any) -> int:
+    """Return the index of the first element > *target*.
+
+    Time: O(log n). Space: O(1).
+
+    Returns ``len(arr)`` if no element is greater than *target*.
+    """
+    low = 0
+    high = len(arr)
+
+    while low < high:
+        mid = low + (high - low) // 2
+        if arr[mid] <= target:
+            low = mid + 1
+        else:
+            high = mid
+
+    return low

data_structures/array/dynamic_array.py

@@ -1,3 +1,4 @@
+from collections.abc import Iterable
 from typing import Iterator
 
 from .base import IArray
@@ -17,11 +18,23 @@ class DynamicArray[T](IArray[T]):
     elements between shrink thresholds.
     """
 
-    def __init__(self) -> None:
-        """Create an empty dynamic array."""
-        self._capacity: int = _DEFAULT_CAPACITY
-        self._size: int = 0
-        self._data: list[T | None] = [None] * self._capacity
+    def __init__(self, values: Iterable[T] | None = None) -> None:
+        """Create a dynamic array, optionally pre-filled from *values*.
+
+        >>> DynamicArray()            # empty
+        DynamicArray([])
+        >>> DynamicArray([1, 2, 3])   # pre-filled
+        DynamicArray([1, 2, 3])
+        """
+        if values is None:
+            self._capacity: int = _DEFAULT_CAPACITY
+            self._size: int = 0
+            self._data: list[T | None] = [None] * self._capacity
+        else:
+            items = list(values)
+            self._size = len(items)
+            self._capacity = max(_DEFAULT_CAPACITY, self._size)
+            self._data = items + [None] * (self._capacity - self._size)
 
     def append(self, value: T) -> None:
         """Append *value* after the last element. O(1) amortised."""
@@ -99,7 +112,7 @@ def __len__(self) -> int:
     def __iter__(self) -> Iterator[T]:
         """Iterate over all elements from first to last."""
         for i in range(self._size):
-            yield self._data[i]  # type: ignore[misc]
+            yield self._data[i]
 
     def __contains__(self, item: object) -> bool:
         """Return ``True`` if *item* is in the array. O(n)."""

data_structures/array/static_array.py

@@ -1,3 +1,4 @@
+from collections.abc import Iterable
 from typing import Iterator
 
 from .base import IArray
@@ -8,15 +9,32 @@ class StaticArray[T](IArray[T]):
 
     Capacity is set at construction time and cannot grow.
     Raises ``OverflowError`` when appending to a full array.
+
+    >>> StaticArray(3)             # empty with capacity 3
+    StaticArray([])
+    >>> StaticArray([1, 2, 3])    # pre-filled, capacity == len
+    StaticArray([1, 2, 3])
     """
 
-    def __init__(self, capacity: int) -> None:
-        """Create an empty array that can hold at most *capacity* elements."""
-        if capacity <= 0:
-            raise ValueError("Capacity must be positive")
-        self._capacity: int = capacity
-        self._size: int = 0
-        self._data: list[T | None] = [None] * capacity
+    def __init__(self, capacity_or_values: int | Iterable[T]) -> None:
+        """Create a static array.
+
+        Pass an ``int`` for an empty array with that capacity, or an
+        iterable to pre-fill (capacity equals the number of elements).
+        """
+        if isinstance(capacity_or_values, int):
+            if capacity_or_values <= 0:
+                raise ValueError("Capacity must be positive")
+            self._capacity: int = capacity_or_values
+            self._size: int = 0
+            self._data: list[T | None] = [None] * self._capacity
+        else:
+            values = list(capacity_or_values)
+            if not values:
+                raise ValueError("Capacity must be positive")
+            self._capacity = len(values)
+            self._size = len(values)
+            self._data = list(values)
 
     def append(self, value: T) -> None:
         """Append *value* after the last element. O(1).
@@ -96,7 +114,7 @@ def __len__(self) -> int:
     def __iter__(self) -> Iterator[T]:
         """Iterate over all elements from first to last."""
         for i in range(self._size):
-            yield self._data[i]  # type: ignore[misc]
+            yield self._data[i]
 
     def __contains__(self, item: object) -> bool:
         """Return ``True`` if *item* is in the array. O(n)."""

pyproject.toml

@@ -23,4 +23,4 @@ select = ["E", "F", "W", "I"]
 
 [tool.pytest.ini_options]
 pythonpath = ["."]
-addopts = "--cov=data_structures --cov-report=term-missing"
+addopts = "--cov=data_structures --cov=algorithms --cov-report=term-missing"

tests/test_arrays.py

@@ -201,6 +201,24 @@ def test_static_repr_empty():
     assert repr(StaticArray(5)) == "StaticArray([])"
 
 
+def test_static_init_from_list():
+    arr = StaticArray([10, 20, 30])
+    assert list(arr) == [10, 20, 30]
+    assert arr.capacity == 3
+    assert len(arr) == 3
+
+
+def test_static_init_from_iterable():
+    arr = StaticArray(range(4))
+    assert list(arr) == [0, 1, 2, 3]
+    assert arr.capacity == 4
+
+
+def test_static_init_empty_iterable_raises():
+    with pytest.raises(ValueError):
+        StaticArray([])
+
+
 # ── DynamicArray-specific tests ──────────────────────────────────────
 
 
@@ -269,3 +287,26 @@ def test_dynamic_repr():
 
 def test_dynamic_repr_empty():
     assert repr(DynamicArray()) == "DynamicArray([])"
+
+
+def test_dynamic_init_from_list():
+    arr = DynamicArray([10, 20, 30])
+    assert list(arr) == [10, 20, 30]
+    assert len(arr) == 3
+
+
+def test_dynamic_init_from_iterable():
+    arr = DynamicArray(range(4))
+    assert list(arr) == [0, 1, 2, 3]
+
+
+def test_dynamic_init_empty_iterable():
+    arr = DynamicArray([])
+    assert arr.is_empty()
+    assert arr.capacity == 4
+
+
+def test_dynamic_init_large_sets_capacity():
+    arr = DynamicArray(range(10))
+    assert arr.capacity >= 10
+    assert len(arr) == 10

tests/test_binary_search.py

@@ -0,0 +1,142 @@
+from algorithms.searching.binary_search import (
+    binary_search,
+    lower_bound,
+    upper_bound,
+)
+from data_structures.array.dynamic_array import DynamicArray
+from data_structures.array.static_array import StaticArray
+
+# ── binary_search ────────────────────────────────────────────────────
+
+
+def test_found_in_odd_length():
+    assert binary_search([1, 3, 5, 7, 9], 5) == 2
+
+
+def test_found_in_even_length():
+    assert binary_search([2, 4, 6, 8], 6) == 2
+
+
+def test_found_first_element():
+    assert binary_search([1, 2, 3], 1) == 0
+
+
+def test_found_last_element():
+    assert binary_search([1, 2, 3], 3) == 2
+
+
+def test_not_found():
+    assert binary_search([1, 2, 3, 4, 5], 42) == -1
+
+
+def test_empty_list():
+    assert binary_search([], 1) == -1
+
+
+def test_single_element_found():
+    assert binary_search([7], 7) == 0
+
+
+def test_single_element_not_found():
+    assert binary_search([7], 3) == -1
+
+
+def test_duplicates_returns_one_of_them():
+    result = binary_search([1, 3, 3, 3, 5], 3)
+    assert result in (1, 2, 3)
+
+
+def test_strings():
+    assert binary_search(["a", "b", "c", "d"], "c") == 2
+
+
+def test_large_list():
+    arr = list(range(0, 10000, 2))  # [0, 2, 4, ..., 9998]
+    assert binary_search(arr, 4444) == 2222
+    assert binary_search(arr, 4445) == -1
+
+
+# ── lower_bound ──────────────────────────────────────────────────────
+
+
+def test_lower_bound_exact():
+    assert lower_bound([1, 3, 5, 7], 3) == 1
+
+
+def test_lower_bound_between():
+    assert lower_bound([1, 3, 5, 7], 4) == 2
+
+
+def test_lower_bound_less_than_all():
+    assert lower_bound([2, 4, 6], 0) == 0
+
+
+def test_lower_bound_greater_than_all():
+    assert lower_bound([2, 4, 6], 10) == 3
+
+
+def test_lower_bound_duplicates():
+    assert lower_bound([1, 3, 3, 3, 5], 3) == 1
+
+
+def test_lower_bound_empty():
+    assert lower_bound([], 1) == 0
+
+
+# ── upper_bound ──────────────────────────────────────────────────────
+
+
+def test_upper_bound_exact():
+    assert upper_bound([1, 3, 5, 7], 3) == 2
+
+
+def test_upper_bound_between():
+    assert upper_bound([1, 3, 5, 7], 4) == 2
+
+
+def test_upper_bound_less_than_all():
+    assert upper_bound([2, 4, 6], 0) == 0
+
+
+def test_upper_bound_greater_than_all():
+    assert upper_bound([2, 4, 6], 10) == 3
+
+
+def test_upper_bound_duplicates():
+    assert upper_bound([1, 3, 3, 3, 5], 3) == 4
+
+
+def test_upper_bound_empty():
+    assert upper_bound([], 1) == 0
+
+
+# ── StaticArray ──────────────────────────────────────────────────────
+
+
+def test_binary_search_static_array():
+    assert binary_search(StaticArray([1, 3, 5, 7, 9]), 5) == 2
+    assert binary_search(StaticArray([1, 3, 5, 7, 9]), 42) == -1
+
+
+def test_lower_bound_static_array():
+    assert lower_bound(StaticArray([1, 3, 5, 7]), 4) == 2
+
+
+def test_upper_bound_static_array():
+    assert upper_bound(StaticArray([1, 3, 3, 3, 5]), 3) == 4
+
+
+# ── DynamicArray ─────────────────────────────────────────────────────
+
+
+def test_binary_search_dynamic_array():
+    assert binary_search(DynamicArray([1, 3, 5, 7, 9]), 5) == 2
+    assert binary_search(DynamicArray([1, 3, 5, 7, 9]), 42) == -1
+
+
+def test_lower_bound_dynamic_array():
+    assert lower_bound(DynamicArray([1, 3, 5, 7]), 4) == 2
+
+
+def test_upper_bound_dynamic_array():
+    assert upper_bound(DynamicArray([1, 3, 3, 3, 5]), 3) == 4