Add pair, tuple, optional, variant, bitset & iterator utilities

[AnshMNSoni]

Problem

The library is missing fundamental utility types and iterator infrastructure that C++ STL developers rely on daily. Without pair, tuple, and iterator utilities, many common patterns cannot be expressed cleanly in PythonSTL style.

---

Missing Utility Types (<utility> / <optional> / <variant>)

Class	C++ Equivalent	Description
pair	std::pair<T1,T2>	Two-element typed pair with .first and .second
tuple	std::tuple<T...>	N-element typed tuple with get<N>(), make_tuple(), tie()
optional	std::optional<T>	A value that may or may not exist
variant	std::variant<T...>	Type-safe tagged union
bitset	std::bitset<N>	Fixed-size bit array with AND, OR, XOR ops
string_stl	std::string wrapper	STL-style string: find, substr, erase, replace, compare

---

Missing Iterator Utilities

Function/Class	C++ Equivalent	Description
advance(it, n)	std::advance	Moves iterator forward by n steps
distance(a, b)	std::distance	Number of steps between two iterators
next(it, n)	std::next	Returns iterator advanced by n
prev(it, n)	std::prev	Returns iterator moved back by n
reverse_iterator	std::reverse_iterator	Wraps any iterator to iterate in reverse
Iterator base classes	—	Forward, Bidirectional, RandomAccess base classes

---

Expected API

from pythonstl.utility import pair, optional, bitset
from pythonstl.iterator import advance, distance, reverse_iterator

# pair
p = pair(10, "hello")
print(p.first, p.second)       # 10 hello

# optional
val = optional(42)
print(val.has_value())          # True
print(val.value())              # 42
empty = optional()
print(empty.has_value())        # False

# bitset
b = bitset(8)                   # 8-bit bitset
b.set(3)
b.set(5)
print(b.to_string())            # 00101000
print(b.count())                # 2

# iterator
arr = [1, 2, 3, 4, 5]
it = iter(arr)
advance(it, 2)
print(distance(iter(arr), it))  # 2

---

Checklist

Utility Types

• pair
• tuple
• optional
• variant
• bitset
• string_stl wrapper

Iterator Utilities

• advance, distance, next, prev
• reverse_iterator wrapper
• Iterator base classes (forward, bidirectional, random-access)

General

• Unit tests for all
• Docstrings with O() complexity

---

Notes

• pair and tuple are the highest priority as they are returned by many STL functions (e.g., equal_range returns a pair).
• bitset has no direct Python built-in equivalent, making it a strong differentiator for this library.
• Iterator utilities are needed to properly support future range-based algorithms.