pythonstl 0.1.4__cp311-cp311-win_amd64.whl

pythonstl/implementations/heaps/__init__.py

@@ -0,0 +1,5 @@
+"""Heap-based data structure implementations."""
+
+from ._priority_queue_impl import _PriorityQueueImpl
+
+__all__ = ['_PriorityQueueImpl']

pythonstl/implementations/heaps/_priority_queue_impl.py

@@ -0,0 +1,118 @@
+"""
+Private implementation of Priority Queue data structure.
+
+This module contains the internal implementation of a priority queue
+following C++ STL semantics. Users should not access this directly.
+"""
+
+from typing import TypeVar, List
+import heapq
+from pythonstl.core.exceptions import EmptyContainerError
+
+T = TypeVar('T')
+
+
+class _PriorityQueueImpl:
+    """
+    Internal implementation of a priority queue using heapq.
+
+    This class should not be accessed directly by users.
+    Use the facade class `priority_queue` instead.
+
+    Note:
+        Python's heapq implements a min-heap. We support both min and max heaps
+        through the comparator parameter.
+    """
+
+    def __init__(self, comparator: str = "max") -> None:
+        """
+        Initialize an empty priority queue.
+
+        Args:
+            comparator: Either "max" for max-heap (default, matches C++ STL)
+                       or "min" for min-heap.
+
+        Time Complexity:
+            O(1)
+        """
+        self._data: List[T] = []
+        self._comparator = comparator
+        if comparator not in ["max", "min"]:
+            raise ValueError("comparator must be 'max' or 'min'")
+
+    def push(self, value: T) -> None:
+        """
+        Insert an element into the priority queue.
+
+        Args:
+            value: The element to insert.
+
+        Time Complexity:
+            O(log n) where n is the number of elements
+        """
+        if self._comparator == "max":
+            # Negate for max-heap behavior
+            heapq.heappush(self._data, -value if isinstance(value, (int, float)) else value)
+        else:
+            heapq.heappush(self._data, value)
+
+    def pop(self) -> None:
+        """
+        Remove the top element from the priority queue.
+
+        Raises:
+            EmptyContainerError: If the priority queue is empty.
+
+        Time Complexity:
+            O(log n) where n is the number of elements
+        """
+        if self.empty():
+            raise EmptyContainerError("priority_queue")
+        heapq.heappop(self._data)
+
+    def top(self) -> T:
+        """
+        Get the top element of the priority queue without removing it.
+
+        Returns:
+            The top element (highest priority).
+
+        Raises:
+            EmptyContainerError: If the priority queue is empty.
+
+        Time Complexity:
+            O(1)
+        """
+        if self.empty():
+            raise EmptyContainerError("priority_queue")
+        top_value = self._data[0]
+        if self._comparator == "max" and isinstance(top_value, (int, float)):
+            return -top_value
+        return top_value
+
+    def empty(self) -> bool:
+        """
+        Check if the priority queue is empty.
+
+        Returns:
+            True if the priority queue is empty, False otherwise.
+
+        Time Complexity:
+            O(1)
+        """
+        return len(self._data) == 0
+
+    def size(self) -> int:
+        """
+        Get the number of elements in the priority queue.
+
+        Returns:
+            The number of elements in the priority queue.
+
+        Time Complexity:
+            O(1)
+        """
+        return len(self._data)
+
+
+__all__ = ['_PriorityQueueImpl']

pythonstl/implementations/linear/__init__.py

@@ -0,0 +1,7 @@
+"""Linear data structure implementations."""
+
+from ._stack_impl import _StackImpl
+from ._queue_impl import _QueueImpl
+from ._vector_impl import _VectorImpl
+
+__all__ = ['_StackImpl', '_QueueImpl', '_VectorImpl']

pythonstl/implementations/linear/_queue_impl.py

@@ -0,0 +1,117 @@
+"""
+Private implementation of Queue data structure.
+
+This module contains the internal implementation of a queue
+following C++ STL semantics. Users should not access this directly.
+"""
+
+from typing import TypeVar
+from collections import deque
+from pythonstl.core.exceptions import EmptyContainerError
+
+T = TypeVar('T')
+
+
+class _QueueImpl:
+    """
+    Internal implementation of a queue using collections.deque.
+
+    This class should not be accessed directly by users.
+    Use the facade class `queue` instead.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize an empty queue.
+
+        Time Complexity:
+            O(1)
+        """
+        self._data: deque[T] = deque()
+
+    def push(self, value: T) -> None:
+        """
+        Add an element to the back of the queue.
+
+        Args:
+            value: The element to add to the queue.
+
+        Time Complexity:
+            O(1)
+        """
+        self._data.append(value)
+
+    def pop(self) -> None:
+        """
+        Remove the front element from the queue.
+
+        Raises:
+            EmptyContainerError: If the queue is empty.
+
+        Time Complexity:
+            O(1)
+        """
+        if self.empty():
+            raise EmptyContainerError("queue")
+        self._data.popleft()
+
+    def front(self) -> T:
+        """
+        Get the front element of the queue without removing it.
+
+        Returns:
+            The front element of the queue.
+
+        Raises:
+            EmptyContainerError: If the queue is empty.
+
+        Time Complexity:
+            O(1)
+        """
+        if self.empty():
+            raise EmptyContainerError("queue")
+        return self._data[0]
+
+    def back(self) -> T:
+        """
+        Get the back element of the queue without removing it.
+
+        Returns:
+            The back element of the queue.
+
+        Raises:
+            EmptyContainerError: If the queue is empty.
+
+        Time Complexity:
+            O(1)
+        """
+        if self.empty():
+            raise EmptyContainerError("queue")
+        return self._data[-1]
+
+    def empty(self) -> bool:
+        """
+        Check if the queue is empty.
+
+        Returns:
+            True if the queue is empty, False otherwise.
+
+        Time Complexity:
+            O(1)
+        """
+        return len(self._data) == 0
+
+    def size(self) -> int:
+        """
+        Get the number of elements in the queue.
+
+        Returns:
+            The number of elements in the queue.
+
+        Time Complexity:
+            O(1)
+        """
+        return len(self._data)
+
+
+__all__ = ['_QueueImpl']

pythonstl/implementations/linear/_stack_impl.py

@@ -0,0 +1,99 @@
+"""
+Private implementation of Stack data structure.
+
+This module contains the internal implementation of a stack
+following C++ STL semantics. Users should not access this directly.
+"""
+
+from typing import TypeVar, List
+from pythonstl.core.exceptions import EmptyContainerError
+
+T = TypeVar('T')
+
+
+class _StackImpl:
+    """
+    Internal implementation of a stack using Python list.
+
+    This class should not be accessed directly by users.
+    Use the facade class `stack` instead.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize an empty stack.
+
+        Time Complexity:
+            O(1)
+        """
+        self._data: List[T] = []
+
+    def push(self, value: T) -> None:
+        """
+        Push an element onto the stack.
+
+        Args:
+            value: The element to push onto the stack.
+
+        Time Complexity:
+            O(1) amortized
+        """
+        self._data.append(value)
+
+    def pop(self) -> None:
+        """
+        Remove the top element from the stack.
+
+        Raises:
+            EmptyContainerError: If the stack is empty.
+
+        Time Complexity:
+            O(1)
+        """
+        if self.empty():
+            raise EmptyContainerError("stack")
+        self._data.pop()
+
+    def top(self) -> T:
+        """
+        Get the top element of the stack without removing it.
+
+        Returns:
+            The top element of the stack.
+
+        Raises:
+            EmptyContainerError: If the stack is empty.
+
+        Time Complexity:
+            O(1)
+        """
+        if self.empty():
+            raise EmptyContainerError("stack")
+        return self._data[-1]
+
+    def empty(self) -> bool:
+        """
+        Check if the stack is empty.
+
+        Returns:
+            True if the stack is empty, False otherwise.
+
+        Time Complexity:
+            O(1)
+        """
+        return len(self._data) == 0
+
+    def size(self) -> int:
+        """
+        Get the number of elements in the stack.
+
+        Returns:
+            The number of elements in the stack.
+
+        Time Complexity:
+            O(1)
+        """
+        return len(self._data)
+
+
+__all__ = ['_StackImpl']

pythonstl/implementations/linear/_vector_impl.py

@@ -0,0 +1,251 @@
+"""
+Private implementation of Vector data structure.
+
+This module contains the internal implementation of a dynamic array (vector)
+following C++ STL semantics. Users should not access this directly.
+"""
+
+from typing import TypeVar, List
+from pythonstl.core.exceptions import EmptyContainerError, OutOfRangeError
+from pythonstl.core.iterator import VectorIterator, VectorReverseIterator
+
+T = TypeVar('T')
+
+
+class _VectorImpl:
+    """
+    Internal implementation of a vector using Python list with capacity management.
+
+    This class should not be accessed directly by users.
+    Use the facade class `vector` instead.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize an empty vector.
+
+        Time Complexity:
+            O(1)
+        """
+        self._data: List[T] = []
+        self._capacity: int = 0
+
+    def push_back(self, value: T) -> None:
+        """
+        Add an element to the end of the vector.
+
+        Args:
+            value: The element to add to the vector.
+
+        Time Complexity:
+            O(1) amortized
+        """
+        self._data.append(value)
+        if len(self._data) > self._capacity:
+            self._capacity = max(1, self._capacity * 2)
+
+    def pop_back(self) -> None:
+        """
+        Remove the last element from the vector.
+
+        Raises:
+            EmptyContainerError: If the vector is empty.
+
+        Time Complexity:
+            O(1)
+        """
+        if self.empty():
+            raise EmptyContainerError("vector")
+        self._data.pop()
+
+    def at(self, index: int) -> T:
+        """
+        Access element at specified index with bounds checking.
+
+        Args:
+            index: The index of the element to access.
+
+        Returns:
+            The element at the specified index.
+
+        Raises:
+            OutOfRangeError: If index is out of bounds.
+
+        Time Complexity:
+            O(1)
+        """
+        if index < 0 or index >= len(self._data):
+            raise OutOfRangeError(index, len(self._data))
+        return self._data[index]
+
+    def insert(self, position: int, value: T) -> None:
+        """
+        Insert an element at the specified position.
+
+        Args:
+            position: The position to insert the element.
+            value: The element to insert.
+
+        Raises:
+            OutOfRangeError: If position is out of bounds.
+
+        Time Complexity:
+            O(n) where n is the number of elements after position
+        """
+        if position < 0 or position > len(self._data):
+            raise OutOfRangeError(position, len(self._data))
+        self._data.insert(position, value)
+        if len(self._data) > self._capacity:
+            self._capacity = max(1, self._capacity * 2)
+
+    def erase(self, position: int) -> None:
+        """
+        Remove the element at the specified position.
+
+        Args:
+            position: The position of the element to remove.
+
+        Raises:
+            OutOfRangeError: If position is out of bounds.
+
+        Time Complexity:
+            O(n) where n is the number of elements after position
+        """
+        if position < 0 or position >= len(self._data):
+            raise OutOfRangeError(position, len(self._data))
+        self._data.pop(position)
+
+    def clear(self) -> None:
+        """
+        Remove all elements from the vector.
+
+        Time Complexity:
+            O(n) where n is the number of elements
+        """
+        self._data.clear()
+
+    def reserve(self, new_capacity: int) -> None:
+        """
+        Reserve capacity for the vector.
+
+        Pre-allocates memory to avoid reallocation during growth.
+        Does not change the size of the vector.
+
+        Args:
+            new_capacity: The new capacity to reserve.
+
+        Time Complexity:
+            O(1) - only updates capacity tracking
+        """
+        if new_capacity > self._capacity:
+            self._capacity = new_capacity
+
+    def shrink_to_fit(self) -> None:
+        """
+        Reduce capacity to match the current size.
+
+        Frees unused capacity to save memory.
+
+        Time Complexity:
+            O(1) - only updates capacity tracking
+        """
+        self._capacity = len(self._data)
+
+    def begin(self) -> VectorIterator:
+        """
+        Get iterator to the beginning of the vector.
+
+        Returns:
+            Iterator pointing to the first element.
+
+        Time Complexity:
+            O(1)
+        """
+        return VectorIterator(self._data, 0)
+
+    def end(self) -> VectorIterator:
+        """
+        Get iterator to the end of the vector.
+
+        Returns:
+            Iterator pointing past the last element.
+
+        Time Complexity:
+            O(1)
+        """
+        return VectorIterator(self._data, len(self._data))
+
+    def rbegin(self) -> VectorReverseIterator:
+        """
+        Get reverse iterator to the end of the vector.
+
+        Returns:
+            Reverse iterator pointing to the last element.
+
+        Time Complexity:
+            O(1)
+        """
+        return VectorReverseIterator(self._data)
+
+    def rend(self) -> VectorReverseIterator:
+        """
+        Get reverse iterator to the beginning of the vector.
+
+        Returns:
+            Reverse iterator pointing before the first element.
+
+        Time Complexity:
+            O(1)
+        """
+        return VectorReverseIterator(self._data, -1)
+
+    def get_data(self) -> List[T]:
+        """
+        Get a copy of the internal data for iteration.
+
+        Returns:
+            Copy of the internal data list.
+
+        Time Complexity:
+            O(n) where n is the number of elements
+        """
+        return self._data.copy()
+
+    def size(self) -> int:
+        """
+        Get the number of elements in the vector.
+
+        Returns:
+            The number of elements in the vector.
+
+        Time Complexity:
+            O(1)
+        """
+        return len(self._data)
+
+    def capacity(self) -> int:
+        """
+        Get the current capacity of the vector.
+
+        Returns:
+            The current capacity of the vector.
+
+        Time Complexity:
+            O(1)
+        """
+        return self._capacity
+
+    def empty(self) -> bool:
+        """
+        Check if the vector is empty.
+
+        Returns:
+            True if the vector is empty, False otherwise.
+
+        Time Complexity:
+            O(1)
+        """
+        return len(self._data) == 0
+
+
+__all__ = ['_VectorImpl']