pkstruct 0.1.0__py3-none-any.whl

pkstruct/linear/linked_lists/circular_linked_list.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, cast
+
+from pkstruct.linear.exceptions import (
+    EmptyStructureError,
+    ValidationError,
+)
+from pkstruct.linear.linked_lists._base import _LinkedListBase
+from pkstruct.linear.linked_lists.nodes import CircularNode
+from pkstruct.shared.validators import validate_index
+
+T = TypeVar("T")
+
+
+class CircularLinkedList(_LinkedListBase[T]):
+    __slots__ = ()
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def _append(self, value: T) -> None:
+        new_node: CircularNode[T] = CircularNode(value)
+        if self._tail is None:
+            new_node.next = new_node
+            self._head = new_node
+            self._tail = new_node
+        else:
+            new_node.next = self._head
+            self._tail.next = new_node
+            self._tail = new_node
+        self._size += 1
+
+    def _prepend(self, value: T) -> None:
+        new_node: CircularNode[T] = CircularNode(value)
+        if self._tail is None:
+            new_node.next = new_node
+            self._head = new_node
+            self._tail = new_node
+        else:
+            new_node.next = self._head
+            self._tail.next = new_node
+            self._head = new_node
+        self._size += 1
+
+    def _node_at(self, index: int) -> CircularNode[T]:
+        validate_index(index, self._size)
+        node: CircularNode[T] | None = self._head
+        for _ in range(index):
+            if node is None:
+                raise RuntimeError("internal invariant violated: unexpected None in linked list chain")
+            node = node.next
+        if node is None:
+            raise RuntimeError("internal invariant violated: unexpected None in linked list chain")
+        return node
+
+    def _node_before(self, target: CircularNode[T]) -> CircularNode[T]:
+        node: CircularNode[T] | None = self._tail
+        while node is not None and node.next is not target:
+            node = node.next
+        if node is None:
+            raise RuntimeError("internal invariant violated: unexpected None in linked list chain")
+        return node
+
+    def _find_node(self, value: object) -> CircularNode[T] | None:
+        if self._head is None:
+            return None
+        node: CircularNode[T] | None = self._head
+        for _ in range(self._size):
+            if node is None:
+                return None
+            if node.value == value:
+                return node
+            node = node.next
+        return None
+
+    def _remove_node(self, node: CircularNode[T]) -> T:
+        if self._size == 1:
+            self._head = None
+            self._tail = None
+            node.next = None
+            self._size -= 1
+            return node.value
+        prev = self._node_before(node)
+        prev.next = node.next
+        if node is self._head:
+            self._head = node.next
+        if node is self._tail:
+            self._tail = prev
+        node.next = None
+        self._size -= 1
+        return node.value
+
+    def _insert_before_node(self, node: CircularNode[T], value: T) -> None:
+        if node is self._head:
+            self._prepend(value)
+        else:
+            prev = self._node_before(node)
+            new_node: CircularNode[T] = CircularNode(value)
+            new_node.next = node
+            prev.next = new_node
+            self._size += 1
+
+    def _insert_after_node(self, node: CircularNode[T], value: T) -> None:
+        new_node: CircularNode[T] = CircularNode(value)
+        new_node.next = node.next
+        node.next = new_node
+        if node is self._tail:
+            self._tail = new_node
+        self._size += 1
+
+    def _to_list_unsafe(self) -> list[T]:
+        if self._head is None:
+            return []
+        result: list[T] = []
+        node = self._head
+        for _ in range(self._size):
+            result.append(node.value)
+            node = node.next
+        return result
+
+    # ------------------------------------------------------------------ #
+    #  Rotation overrides (pointer-based for full list)                     #
+    # ------------------------------------------------------------------ #
+
+    def _rotate_full_list(self, shift: int) -> None:
+        if shift == 0 or self._size <= 1:
+            return
+        steps = (self._size - shift) % self._size
+        for _ in range(steps):
+            self._head = self._head.next
+            self._tail = self._tail.next
+
+    def rotate_head(self, steps: int = 1, direction: bool = True) -> None:
+        with self._lock:
+            if self._size == 0:
+                raise EmptyStructureError("rotate_head on an empty list")
+            self._tracer.record("rotate_head", steps=steps, direction=direction)
+            steps = steps % self._size
+            if steps == 0:
+                return
+            if not direction:
+                steps = self._size - steps
+            for _ in range(steps):
+                self._tail = self._head
+                self._head = self._head.next
+
+    # ------------------------------------------------------------------ #
+    #  Josephus problem (circular-unique)                                   #
+    # ------------------------------------------------------------------ #
+
+    def josephus(self, step: int) -> T:
+        with self._lock:
+            if self._size == 0:
+                raise EmptyStructureError("josephus on an empty list")
+            if step < 1:
+                raise ValidationError("'step' must be >= 1.")
+            self._tracer.record("josephus", step=step)
+            current = self._head
+            while self._size > 1:
+                for _ in range(step - 1):
+                    current = current.next
+                next_node = current.next
+                self._remove_node(current)
+                current = next_node
+            survivor = cast(T, self._head.value)
+            self.clear()
+            return survivor
+
+    # ------------------------------------------------------------------ #
+    #  Visualization & Debug                                                #
+    # ------------------------------------------------------------------ #
+
+    def visualize(self, style: str = "ascii") -> str:
+        with self._lock:
+            if self._size == 0:
+                return "(empty circular list)"
+            values = self._to_list_unsafe()
+            if style == "simple":
+                return ", ".join(str(v) for v in values)
+            if style == "ring":
+                nodes_str = " -> ".join(f"[{v}]" for v in values)
+                return f"{nodes_str} -> \u21ba"
+            inner = " -> ".join(str(v) for v in values)
+            return f"{inner} -> (back to head)"
+
+    def debug(self) -> dict[str, Any]:
+        with self._lock:
+            invariant = (
+                (self._tail is not None and self._tail.next is self._head)
+                if self._size > 0
+                else True
+            )
+            return {
+                "type": "CircularLinkedList",
+                "length": self._size,
+                "size": self._size,
+                "head": self._head.value if self._head else None,
+                "tail": self._tail.value if self._tail else None,
+                "tail_next": (self._tail.next.value if self._tail and self._tail.next else None),
+                "invariant_ok": invariant,
+                "values": self._to_list_unsafe(),
+                "events": self._tracer.get_events(),
+            }
+
+    def detect_cycle(self, return_start: bool = False) -> bool | tuple[bool, Any]:
+        with self._lock:
+            if self._head is None:
+                return (False, None) if return_start else False
+            slow = self._head
+            fast = self._head
+            has_cycle = False
+            max_steps = self._size * 2
+            for _ in range(max_steps):
+                if fast.next is None or fast.next.next is None:
+                    break
+                slow = slow.next
+                fast = fast.next.next
+                if slow is fast:
+                    has_cycle = True
+                    break
+            if not return_start:
+                return has_cycle
+            if not has_cycle:
+                return False, None
+            slow = self._head
+            while slow is not fast:
+                slow = slow.next
+                fast = fast.next
+            return True, slow.value

pkstruct/linear/linked_lists/doubly_linked_list.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, cast
+
+from pkstruct.linear.exceptions import EmptyStructureError
+from pkstruct.linear.linked_lists._base import _LinkedListBase
+from pkstruct.linear.linked_lists.nodes import DoublyNode
+from pkstruct.shared.validators import validate_range
+
+T = TypeVar("T")
+
+
+class DoublyLinkedList(_LinkedListBase[T]):
+    __slots__ = ()
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def _append(self, value: T) -> None:
+        new_node: DoublyNode[T] = DoublyNode(value)
+        if self._tail is None:
+            self._head = new_node
+            self._tail = new_node
+        else:
+            new_node.prev = self._tail
+            self._tail.next = new_node
+            self._tail = new_node
+        self._size += 1
+
+    def _prepend(self, value: T) -> None:
+        new_node: DoublyNode[T] = DoublyNode(value)
+        if self._head is None:
+            self._head = new_node
+            self._tail = new_node
+        else:
+            new_node.next = self._head
+            self._head.prev = new_node
+            self._head = new_node
+        self._size += 1
+
+    def _node_at(self, index: int) -> DoublyNode[T]:
+        if index <= self._size // 2:
+            node: DoublyNode[T] | None = self._head
+            for _ in range(index):
+                if node is None:
+                    raise RuntimeError("internal invariant violated: unexpected None in linked list chain")
+                node = node.next
+        else:
+            node = self._tail
+            for _ in range(self._size - 1 - index):
+                if node is None:
+                    raise RuntimeError("internal invariant violated: unexpected None in linked list chain")
+                node = node.prev
+        if node is None:
+            raise RuntimeError("internal invariant violated: unexpected None in linked list chain")
+        return node
+
+    def _find_node(self, value: object) -> DoublyNode[T] | None:
+        node: DoublyNode[T] | None = self._head
+        while node is not None:
+            if node.value == value:
+                return node
+            node = node.next
+        return None
+
+    def _remove_node(self, node: DoublyNode[T]) -> T:
+        prev_node = node.prev
+        next_node = node.next
+        if prev_node is not None:
+            prev_node.next = next_node
+        else:
+            self._head = next_node
+        if next_node is not None:
+            next_node.prev = prev_node
+        else:
+            self._tail = prev_node
+        node.next = None
+        node.prev = None
+        self._size -= 1
+        return node.value
+
+    def _insert_before_node(self, node: DoublyNode[T], value: T) -> None:
+        new_node: DoublyNode[T] = DoublyNode(value)
+        prev_node = node.prev
+        new_node.next = node
+        new_node.prev = prev_node
+        node.prev = new_node
+        if prev_node is None:
+            self._head = new_node
+        else:
+            prev_node.next = new_node
+        self._size += 1
+
+    def _insert_after_node(self, node: DoublyNode[T], value: T) -> None:
+        new_node: DoublyNode[T] = DoublyNode(value)
+        next_node = node.next
+        new_node.prev = node
+        new_node.next = next_node
+        node.next = new_node
+        if next_node is None:
+            self._tail = new_node
+        else:
+            next_node.prev = new_node
+        self._size += 1
+
+    def _to_list_unsafe(self) -> list[T]:
+        result: list[T] = []
+        node = self._head
+        while node is not None:
+            result.append(node.value)
+            node = node.next
+        return result
+
+    def reverse(self, start: int | None = None, end: int | None = None) -> None:
+        with self._lock:
+            if self._size == 0:
+                raise EmptyStructureError("reverse an empty list")
+            lo = 0 if start is None else start
+            hi = self._size - 1 if end is None else end
+            if lo >= hi:
+                return
+            validate_range(lo, hi, self._size)
+            self._tracer.record("reverse", start=lo, end=hi)
+            left = self._node_at(lo)
+            right = self._node_at(hi)
+            while left is not right and left is not cast(DoublyNode[T], right.next):
+                left.value, right.value = right.value, left.value
+                left = cast(DoublyNode[T], left.next)
+                right = cast(DoublyNode[T], right.prev)
+
+    def visualize(self, style: str = "ascii") -> str:
+        with self._lock:
+            if self._size == 0:
+                return "None <- (empty) -> None"
+            values = self._to_list_unsafe()
+            if style == "simple":
+                return ", ".join(str(v) for v in values)
+            inner = " <-> ".join(str(v) for v in values)
+            return f"None <- {inner} -> None"
+
+    def debug(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "type": "DoublyLinkedList",
+                "length": self._size,
+                "size": self._size,
+                "head": self._head.value if self._head else None,
+                "tail": self._tail.value if self._tail else None,
+                "values": self._to_list_unsafe(),
+                "events": self._tracer.get_events(),
+            }

pkstruct/linear/linked_lists/nodes.py

@@ -0,0 +1,68 @@
+"""
+pkstruct.linear.linked_lists.nodes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Node definitions for all linked-list variants.
+
+All nodes use ``__slots__`` to minimise per-object memory overhead.
+"""
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class SinglyNode(Generic[T]):
+    """A node in a singly-linked list.
+
+    Attributes:
+        value: The stored element.
+        next:  Reference to the next node, or ``None`` if tail.
+    """
+
+    __slots__ = ("value", "next")
+
+    def __init__(self, value: T) -> None:
+        self.value: T = value
+        self.next: SinglyNode[T] | None = None
+
+    def __repr__(self) -> str:
+        return f"SinglyNode({self.value!r})"
+
+
+class DoublyNode(Generic[T]):
+    """A node in a doubly-linked list.
+
+    Attributes:
+        value: The stored element.
+        next:  Reference to the next node, or ``None`` if tail.
+        prev:  Reference to the previous node, or ``None`` if head.
+    """
+
+    __slots__ = ("value", "next", "prev")
+
+    def __init__(self, value: T) -> None:
+        self.value: T = value
+        self.next: DoublyNode[T] | None = None
+        self.prev: DoublyNode[T] | None = None
+
+    def __repr__(self) -> str:
+        return f"DoublyNode({self.value!r})"
+
+
+class CircularNode(Generic[T]):
+    """A node in a circular singly-linked list.
+
+    Attributes:
+        value: The stored element.
+        next:  Always points to a valid node (wraps to head at tail).
+    """
+
+    __slots__ = ("value", "next")
+
+    def __init__(self, value: T) -> None:
+        self.value: T = value
+        self.next: CircularNode[T] | None = None  # set to self or next during build
+
+    def __repr__(self) -> str:
+        return f"CircularNode({self.value!r})"

pkstruct/linear/linked_lists/singly_linked_list.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pkstruct.linear.linked_lists._base import _LinkedListBase
+from pkstruct.linear.linked_lists.nodes import SinglyNode
+
+T = TypeVar("T")
+
+
+class SinglyLinkedList(_LinkedListBase[T]):
+    def __init__(self) -> None:
+        super().__init__()
+
+    def _append(self, value: T) -> None:
+        node: SinglyNode[T] = SinglyNode(value)
+        if self._head is None:
+            self._head = node
+            self._tail = node
+        else:
+            self._tail.next = node
+            self._tail = node
+        self._size += 1
+
+    def _prepend(self, value: T) -> None:
+        node: SinglyNode[T] = SinglyNode(value)
+        node.next = self._head
+        self._head = node
+        if self._tail is None:
+            self._tail = node
+        self._size += 1
+
+    def _node_at(self, index: int) -> SinglyNode[T]:
+        cur: SinglyNode[T] | None = self._head
+        for _ in range(index):
+            if cur is None:
+                raise RuntimeError("internal invariant violated: unexpected None in linked list chain")
+            cur = cur.next
+        if cur is None:
+            raise RuntimeError("internal invariant violated: unexpected None in linked list chain")
+        return cur
+
+    def _find_node(self, value: object) -> SinglyNode[T] | None:
+        cur: SinglyNode[T] | None = self._head
+        while cur is not None:
+            if cur.value == value:
+                return cur
+            cur = cur.next
+        return None
+
+    def _remove_node(self, node: SinglyNode[T]) -> T:
+        if node is self._head:
+            self._head = node.next
+            if self._head is None:
+                self._tail = None
+        else:
+            prev = self._head
+            while prev is not None and prev.next is not node:
+                prev = prev.next
+            if prev is not None:
+                prev.next = node.next
+                if prev.next is None:
+                    self._tail = prev
+        node.next = None
+        self._size -= 1
+        return node.value
+
+    def _insert_before_node(self, node: SinglyNode[T], value: T) -> None:
+        new_node: SinglyNode[T] = SinglyNode(value)
+        if node is self._head:
+            new_node.next = self._head
+            self._head = new_node
+        else:
+            prev = self._head
+            while prev is not None and prev.next is not node:
+                prev = prev.next
+            if prev is not None:
+                new_node.next = node
+                prev.next = new_node
+        self._size += 1
+
+    def _insert_after_node(self, node: SinglyNode[T], value: T) -> None:
+        new_node: SinglyNode[T] = SinglyNode(value)
+        new_node.next = node.next
+        node.next = new_node
+        if node is self._tail:
+            self._tail = new_node
+        self._size += 1
+
+    def _to_list_unsafe(self) -> list[T]:
+        result: list[T] = []
+        cur = self._head
+        while cur is not None:
+            result.append(cur.value)
+            cur = cur.next
+        return result
+
+    def intersection_node(self, other: SinglyLinkedList[T]) -> T | None:
+        with self._lock:
+            len_a = self._size
+            len_b = other._size
+            cur_a: SinglyNode[T] | None = self._head
+            cur_b: SinglyNode[T] | None = other._head
+            while len_a > len_b:
+                cur_a = cur_a.next if cur_a else None
+                len_a -= 1
+            while len_b > len_a:
+                cur_b = cur_b.next if cur_b else None
+                len_b -= 1
+            while cur_a is not cur_b:
+                cur_a = cur_a.next if cur_a else None
+                cur_b = cur_b.next if cur_b else None
+            return cur_a.value if cur_a is not None else None
+
+    def visualize(self, style: str = "ascii") -> str:
+        with self._lock:
+            items = self._to_list_unsafe()
+        if style != "ascii":
+            from pkstruct.linear.exceptions import ValidationError
+            raise ValidationError(f"Unknown style {style!r}. Only 'ascii' is supported.")
+        if not items:
+            return "NULL (empty)"
+        parts = [f"[{v!r}]" for v in items]
+        return " -> ".join(parts) + " -> NULL"
+
+    def debug(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "type": "SinglyLinkedList",
+                "length": self._size,
+                "size": self._size,
+                "head": repr(self._head),
+                "tail": repr(self._node_at(self._size - 1)) if self._size > 0 else None,
+                "values": self._to_list_unsafe(),
+                "tracer": self._tracer.summary(),
+            }

pkstruct/linear/queues/__init__.py

@@ -0,0 +1,44 @@
+"""
+pkstruct.linear.queues
+======================
+
+FIFO (first-in, first-out) queue data structures for the pkstruct ecosystem.
+
+Provides multiple concrete queue implementations and a shared abstract base.
+
+Classes
+-------
+Queue
+    Abstract base class defining the queue interface.
+LinkedQueue
+    Queue backed by ``SinglyLinkedList`` (node-based, thread-safe).
+CircularQueue
+    Fixed-capacity queue backed by a ring buffer.
+PriorityQueue
+    Min-heap priority queue backed by ``heapq``.
+
+Example
+-------
+>>> from pkstruct.linear.queues import LinkedQueue
+>>> q = LinkedQueue([1, 2, 3])
+>>> q.enqueue(4)
+>>> q.dequeue()
+1
+>>> list(q)
+[2, 3, 4]
+"""
+
+from pkstruct.linear.queues.circular_queue import CircularQueue, QueueFullError
+from pkstruct.linear.queues.linked_queue import LinkedQueue
+from pkstruct.linear.queues.priority_queue import PriorityQueue
+from pkstruct.linear.queues.queue import Queue
+
+__all__ = [
+    # Queue classes
+    "CircularQueue",
+    "LinkedQueue",
+    "PriorityQueue",
+    "Queue",
+    # Exceptions
+    "QueueFullError",
+]