Implement pythonstl.algorithm module

[AnshMNSoni]

Problem

The library is missing an algorithm module entirely. In C++ STL, <algorithm> is one of the most used headers. Without it, the library feels incomplete for any real-world use case.

---

Proposed Module: pythonstl.algorithm

Sorting

Function	Description
sort(arr)	Sorts in ascending order — O(n log n)
stable_sort(arr)	Stable sort preserving relative order
partial_sort(arr, k)	Sorts only first k elements
is_sorted(arr)	Returns True if array is sorted
nth_element(arr, n)	Rearranges so nth element is in correct position

Searching

Function	Description
binary_search(arr, val)	Returns True if val exists — O(log n)
lower_bound(arr, val)	Index of first element >= val
upper_bound(arr, val)	Index of first element > val
find(arr, val)	Returns index of first occurrence
find_if(arr, pred)	Returns index of first match for predicate

Transforms

Function	Description
transform(arr, func)	Applies func to each element
for_each(arr, func)	Calls func on each element
fill(arr, val)	Fills all elements with val
replace(arr, old, new)	Replaces all occurrences
remove(arr, val)	Removes all occurrences
remove_if(arr, pred)	Removes elements matching predicate

Min / Max / Count

Function	Description
min_element(arr)	Returns min value
max_element(arr)	Returns max value
minmax_element(arr)	Returns (min, max) tuple
clamp(val, lo, hi)	Clamps val between lo and hi
count(arr, val)	Count occurrences of val
count_if(arr, pred)	Count elements matching predicate
all_of(arr, pred)	True if all match predicate
any_of(arr, pred)	True if any matches predicate
none_of(arr, pred)	True if none matches predicate

Permutations & Heap

Function	Description
next_permutation(arr)	Transforms to next lexicographic permutation
prev_permutation(arr)	Transforms to previous permutation
make_heap(arr)	Builds a max-heap
push_heap(arr, val)	Pushes val into heap
pop_heap(arr)	Pops max element from heap
is_heap(arr)	Returns True if array satisfies heap property

Set Operations (on sorted arrays)

Function	Description
set_union(a, b)	Union of two sorted arrays
set_intersection(a, b)	Intersection of two sorted arrays
set_difference(a, b)	Difference of two sorted arrays
set_symmetric_difference(a, b)	Symmetric difference

---

Expected API

from pythonstl.algorithm import sort, binary_search, lower_bound, count_if

arr = [5, 3, 1, 4, 2]
sort(arr)
print(arr)                          # [1, 2, 3, 4, 5]
print(binary_search(arr, 3))        # True
print(lower_bound(arr, 3))          # 2
print(count_if(arr, lambda x: x > 2))  # 3

---

Checklist

• Sorting functions
• Searching functions
• Transform functions
• Min/Max/Count functions
• Permutation functions
• Heap operations
• Set operations
• Unit tests
• Docstrings with O() complexity