pkstruct 0.1.0__py3-none-any.whl

pkstruct/linear/utils/__init__.py

@@ -0,0 +1,18 @@
+from .benchmark import benchmark_operations, compare_with_builtins
+from .debug_tools import memory_usage, validate_integrity
+from .helpers import detect_intersection, list_equal, merge_sorted_lists, to_array
+from .iterators import BackwardIterator, CircularIterator, ForwardIterator
+
+__all__ = [
+    "ForwardIterator",
+    "BackwardIterator",
+    "CircularIterator",
+    "benchmark_operations",
+    "compare_with_builtins",
+    "merge_sorted_lists",
+    "detect_intersection",
+    "list_equal",
+    "to_array",
+    "memory_usage",
+    "validate_integrity",
+]

pkstruct/linear/utils/benchmark.py

@@ -0,0 +1,255 @@
+"""Benchmarking utilities for pkstruct linked list classes."""
+from __future__ import annotations
+
+import collections
+import time
+from typing import Any
+
+from pkstruct.linear import CircularLinkedList, DoublyLinkedList, SinglyLinkedList
+
+
+def _timeit(fn, *args, **kwargs) -> float:
+    """Run *fn* once and return elapsed seconds."""
+    start = time.perf_counter()
+    fn(*args, **kwargs)
+    return time.perf_counter() - start
+
+
+def benchmark_operations(
+    list_class: type,
+    sizes: list[int] | None = None,
+    n: int | None = None,
+) -> dict[str, Any]:
+    """Time insert / delete / get / search operations for *list_class*.
+
+    Args:
+        list_class: A pkstruct linked list class to benchmark.
+        sizes: List of element counts to test against.
+            Defaults to ``[100, 1000, 10000]``.
+        n: If provided, sets sizes to [n].
+
+    Returns:
+        Nested dict::
+
+            {
+                size: {
+                    "insert_head": float,   # seconds
+                    "insert_tail": float,
+                    "delete_head": float,
+                    "delete_tail": float,
+                    "get_middle": float,
+                    "search": float,
+                },
+                ...
+            }
+    """
+    if n is not None:
+        sizes = [n]
+    if sizes is None:
+        sizes = [100, 1000, 10000]
+
+    results: dict[str, Any] = {}
+
+    for n in sizes:
+        data = list(range(n))
+        stats: dict[str, float] = {}
+
+        # --- insert head (position 0) ---
+        lst = list_class()
+        start = time.perf_counter()
+        for v in data:
+            lst.insert(v, position=0)
+        stats["insert_head"] = time.perf_counter() - start
+
+        # --- insert tail (position=None appends) ---
+        lst2 = list_class()
+        start = time.perf_counter()
+        for v in data:
+            lst2.insert(v)  # position=None appends at tail
+        stats["insert_tail"] = time.perf_counter() - start
+
+        # Build a fresh list for deletion / access tests
+        lst3 = list_class.from_list(data)
+
+        # --- get middle ---
+        mid = n // 2
+        start = time.perf_counter()
+        _ = lst3.get(mid)
+        stats["get_middle"] = time.perf_counter() - start
+
+        # --- search using index() ---
+        target = data[mid]
+        start = time.perf_counter()
+        _ = lst3.index(target)
+        stats["search"] = time.perf_counter() - start
+
+        # --- delete head (position 0) ---
+        lst4 = list_class.from_list(data)
+        start = time.perf_counter()
+        for _ in range(min(100, n)):
+            lst4.delete(position=0)
+        stats["delete_head"] = time.perf_counter() - start
+
+        # --- delete tail (position = size-1) ---
+        lst5 = list_class.from_list(data)
+        start = time.perf_counter()
+        for _ in range(min(100, n)):
+            lst5.delete(position=lst5.size() - 1)
+        stats["delete_tail"] = time.perf_counter() - start
+
+        results[str(n)] = stats
+
+    return results
+
+
+def compare_with_builtins(sizes: list[int] | None = None, n: int | None = None) -> dict[str, Any]:
+    """Compare all pkstruct list types against Python ``list`` and ``deque``.
+
+    Args:
+        sizes: List of element counts to test. Defaults to ``[100, 1000]``.
+        n: If provided, sets sizes to [n].
+
+    Returns:
+        Nested dict::
+
+            {
+                size: {
+                    class_name: {operation: seconds, ...},
+                    ...
+                },
+                ...
+            }
+    """
+    if n is not None:
+        sizes = [n]
+    if sizes is None:
+        sizes = [100, 1000]
+
+    from pkstruct.linear.linked_lists.circular_linked_list import CircularLinkedList
+    from pkstruct.linear.linked_lists.doubly_linked_list import DoublyLinkedList
+    from pkstruct.linear.linked_lists.singly_linked_list import SinglyLinkedList
+
+    pkstruct_classes = [SinglyLinkedList, DoublyLinkedList, CircularLinkedList]
+
+    results: dict[str, Any] = {}
+
+    for n in sizes:
+        data = list(range(n))
+        size_results: dict[str, dict[str, float]] = {}
+
+        # --- pkstruct classes ---
+        for cls in pkstruct_classes:
+            name = cls.__name__
+            stats: dict[str, float] = {}
+
+            # Insert tail
+            lst = cls()
+            start = time.perf_counter()
+            for v in data:
+                lst.insert(v)  # position=None appends
+            stats["insert_tail"] = time.perf_counter() - start
+
+            # Search using index
+            start = time.perf_counter()
+            _ = lst.index(data[n // 2])
+            stats["search"] = time.perf_counter() - start
+
+            # Delete head
+            stats["delete_head"] = _timeit(lst.delete, position=0)
+
+            size_results[name] = stats
+
+        # --- Python list ---
+        py_stats: dict[str, float] = {}
+        py_list: list[int] = []
+        
+        # Insert tail
+        start = time.perf_counter()
+        for v in data:
+            py_list.append(v)
+        py_stats["insert_tail"] = time.perf_counter() - start
+
+        # Search
+        start = time.perf_counter()
+        _ = (data[n // 2] in py_list)
+        py_stats["search"] = time.perf_counter() - start
+
+        # Delete head
+        start = time.perf_counter()
+        if py_list:
+            py_list.pop(0)
+        py_stats["delete_head"] = time.perf_counter() - start
+
+        size_results["list"] = py_stats
+
+        # --- collections.deque ---
+        dq_stats: dict[str, float] = {}
+        dq: collections.deque[int] = collections.deque()
+        
+        # Insert tail
+        start = time.perf_counter()
+        for v in data:
+            dq.append(v)
+        dq_stats["insert_tail"] = time.perf_counter() - start
+
+        # Search (deque requires iteration, so convert to list or use 'in')
+        start = time.perf_counter()
+        _ = (data[n // 2] in dq)
+        dq_stats["search"] = time.perf_counter() - start
+
+        # Delete head
+        start = time.perf_counter()
+        if dq:
+            dq.popleft()
+        dq_stats["delete_head"] = time.perf_counter() - start
+
+        size_results["deque"] = dq_stats
+
+        results[str(n)] = size_results
+
+    return results
+
+
+def run_full_benchmark() -> dict[str, Any]:
+    """Run complete benchmark suite and return results."""
+    print("Running pkstruct benchmarks...")
+    
+    print("\n--- Benchmark: SinglyLinkedList ---")
+    singly_results = benchmark_operations(
+        SinglyLinkedList,
+        sizes=[100, 1000, 5000]
+    )
+    
+    print("\n--- Benchmark: DoublyLinkedList ---")
+    doubly_results = benchmark_operations(
+        DoublyLinkedList,
+        sizes=[100, 1000, 5000]
+    )
+    
+    print("\n--- Benchmark: CircularLinkedList ---")
+    circular_results = benchmark_operations(
+        CircularLinkedList,
+        sizes=[100, 1000, 5000]
+    )
+    
+    print("\n--- Comparison with Built-ins ---")
+    comparison = compare_with_builtins(sizes=[100, 500])
+    
+    return {
+        "singly": singly_results,
+        "doubly": doubly_results,
+        "circular": circular_results,
+        "vs_builtins": comparison,
+    }
+
+
+if __name__ == "__main__":
+    # Run benchmarks when script executed directly
+    results = run_full_benchmark()
+    
+    # Pretty print results
+    import json
+    print("\n" + "="*60)
+    print("FINAL RESULTS")
+    print("="*60)
+    print(json.dumps(results, indent=2, default=str))

pkstruct/linear/utils/debug_tools.py

@@ -0,0 +1,239 @@
+"""Debug and integrity utilities for pkstruct linked lists."""
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+
+def _get_list_types() -> tuple[type, type, type]:
+    from pkstruct.linear.linked_lists.circular_linked_list import CircularLinkedList
+    from pkstruct.linear.linked_lists.doubly_linked_list import DoublyLinkedList
+    from pkstruct.linear.linked_lists.singly_linked_list import SinglyLinkedList
+    return SinglyLinkedList, DoublyLinkedList, CircularLinkedList
+
+
+# Base per-node overhead in bytes (measured experimentally on CPython 3.10)
+_SINGLY_NODE_BYTES = 56
+_DOUBLY_NODE_BYTES = 72
+_CIRCULAR_NODE_BYTES = 56
+
+
+def memory_usage(list_instance: Any) -> int:
+    """Estimate memory used by *list_instance* in bytes.
+
+    Uses fixed per-node overhead constants plus ``sys.getsizeof`` for the
+    value stored in each node.
+
+    Node overhead constants:
+        - SinglyNode / CircularNode: 56 bytes
+        - DoublyNode: 72 bytes
+
+    Args:
+        list_instance: Any pkstruct linked list instance.
+
+    Returns:
+        Estimated total bytes used by the list structure.
+
+    Raises:
+        TypeError: If *list_instance* is not a recognised list type.
+    """
+    SinglyLinkedList, DoublyLinkedList, CircularLinkedList = _get_list_types()
+
+    if isinstance(list_instance, CircularLinkedList):
+        per_node = _CIRCULAR_NODE_BYTES
+        current = list_instance.head
+        size = list_instance.size()
+        steps = 0
+        total = 0
+        while current is not None and steps < size:
+            try:
+                value_bytes = sys.getsizeof(current.value)
+            except Exception:
+                value_bytes = 0
+            total += per_node + value_bytes
+            current = current.next
+            steps += 1
+        return total
+
+    if isinstance(list_instance, DoublyLinkedList):
+        per_node = _DOUBLY_NODE_BYTES
+    elif isinstance(list_instance, SinglyLinkedList):
+        per_node = _SINGLY_NODE_BYTES
+    else:
+        raise TypeError(
+            f"memory_usage does not support {type(list_instance).__name__}."
+        )
+
+    total = 0
+    current = list_instance.head
+    visited: set[int] = set()
+    while current is not None:
+        if id(current) in visited:
+            break
+        visited.add(id(current))
+        try:
+            value_bytes = sys.getsizeof(current.value)
+        except Exception:
+            value_bytes = 0
+        total += per_node + value_bytes
+        current = current.next
+
+    return total
+
+
+def validate_integrity(list_instance: Any) -> dict[str, Any]:
+    """Validate the structural integrity of *list_instance*.
+
+    Checks performed:
+        - **SinglyLinkedList**: no cycles (via Floyd's algorithm), size matches.
+        - **DoublyLinkedList**: all ``prev``/``next`` pointers consistent,
+          no cycles, size matches.
+        - **CircularLinkedList**: ``tail.next is head``, no broken links,
+          size matches.
+
+    Args:
+        list_instance: Any pkstruct linked list instance.
+
+    Returns:
+        Dictionary::
+
+            {
+                "valid": bool,
+                "errors": list[str],
+                "size_matches": bool,
+            }
+
+    Raises:
+        TypeError: If *list_instance* is not a recognised list type.
+    """
+    SinglyLinkedList, DoublyLinkedList, CircularLinkedList = _get_list_types()
+
+    errors: list[str] = []
+    size_matches = True
+
+    if isinstance(list_instance, CircularLinkedList):
+        errors, size_matches = _validate_circular(list_instance)
+
+    elif isinstance(list_instance, DoublyLinkedList):
+        errors, size_matches = _validate_doubly(list_instance)
+
+    elif isinstance(list_instance, SinglyLinkedList):
+        errors, size_matches = _validate_singly(list_instance)
+
+    else:
+        raise TypeError(
+            f"validate_integrity does not support {type(list_instance).__name__}."
+        )
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "size_matches": size_matches,
+    }
+
+
+def _validate_singly(lst: Any) -> tuple[list[str], bool]:
+    errors: list[str] = []
+
+    # Floyd's cycle detection
+    slow = lst.head
+    fast = lst.head
+    while fast is not None and fast.next is not None:
+        slow = slow.next
+        fast = fast.next.next
+        if slow is fast:
+            errors.append("Cycle detected in SinglyLinkedList.")
+            break
+
+    # Count nodes
+    counted = 0
+    current = lst.head
+    visited: set[int] = set()
+    while current is not None:
+        if id(current) in visited:
+            break
+        visited.add(id(current))
+        counted += 1
+        current = current.next
+
+    size_matches = counted == lst.size()
+    if not size_matches:
+        errors.append(
+            f"Size mismatch: recorded={lst.size()}, counted={counted}."
+        )
+
+    return errors, size_matches
+
+
+def _validate_doubly(lst: Any) -> tuple[list[str], bool]:
+    errors: list[str] = []
+
+    # Walk forward, check prev pointers
+    prev_node = None
+    current = lst.head
+    counted = 0
+    visited: set[int] = set()
+
+    while current is not None:
+        if id(current) in visited:
+            errors.append(f"Cycle detected at node with data={current.value!r}.")
+            break
+        visited.add(id(current))
+
+        if current.prev is not prev_node:
+            errors.append(
+                f"Broken prev pointer at node data={current.value!r}: "
+                f"expected id={id(prev_node)}, got id={id(current.prev)}."
+            )
+
+        prev_node = current
+        current = current.next
+        counted += 1
+
+    # Verify tail pointer
+    if lst.tail is not None and lst.tail is not prev_node:
+        errors.append(
+            f"Tail pointer mismatch: tail.data={lst.tail.value!r}, "
+            f"last traversed data={prev_node.value if prev_node else None!r}."
+        )
+
+    size_matches = counted == lst.size()
+    if not size_matches:
+        errors.append(
+            f"Size mismatch: recorded={lst.size()}, counted={counted}."
+        )
+
+    return errors, size_matches
+
+
+def _validate_circular(lst: Any) -> tuple[list[str], bool]:
+    errors: list[str] = []
+
+    # tail.next must be head
+    if lst.head is not None and lst.tail is not None:
+        if lst.tail.next is not lst.head:
+            errors.append(
+                "CircularLinkedList integrity error: tail.next is not head."
+            )
+    elif lst.head is None and lst.tail is not None:
+        errors.append("head is None but tail is not None.")
+    elif lst.tail is None and lst.head is not None:
+        errors.append("tail is None but head is not None.")
+
+    # Count nodes (bounded by reported size + 1 to detect over-count)
+    counted = 0
+    limit = lst.size() + 1
+    current = lst.head
+    while current is not None and counted < limit:
+        counted += 1
+        current = current.next
+        if current is lst.head:
+            break
+
+    size_matches = counted == lst.size()
+    if not size_matches:
+        errors.append(
+            f"Size mismatch: recorded={lst.size()}, counted={counted}."
+        )
+
+    return errors, size_matches

pkstruct/linear/utils/helpers.py

@@ -0,0 +1,143 @@
+"""Helper utilities for pkstruct linked lists."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def _get_list_types() -> tuple[type, type, type]:
+    from pkstruct.linear.linked_lists.circular_linked_list import CircularLinkedList
+    from pkstruct.linear.linked_lists.doubly_linked_list import DoublyLinkedList
+    from pkstruct.linear.linked_lists.singly_linked_list import SinglyLinkedList
+    return SinglyLinkedList, DoublyLinkedList, CircularLinkedList
+
+
+def _to_values(lst: Any) -> list[Any]:
+    """Extract all values from a linked list into a Python list."""
+    SinglyLinkedList, DoublyLinkedList, CircularLinkedList = _get_list_types()
+
+    if isinstance(lst, CircularLinkedList):
+        result = []
+        current = lst.head
+        size = lst.size
+        steps = 0
+        while current is not None and steps < size:
+            result.append(current.value)  # FIXED: .data → .value
+            current = current.next
+            steps += 1
+        return result
+
+    result = []
+    current = lst.head
+    visited: set[int] = set()
+    while current is not None:
+        if id(current) in visited:
+            break
+        visited.add(id(current))
+        result.append(current.value)  # FIXED: .data → .value
+        current = current.next
+    return result
+
+
+def merge_sorted_lists(*lists: Any) -> Any:
+    """Merge pre-sorted linked lists into a new sorted SinglyLinkedList.
+
+    All input lists must already be sorted in ascending order.
+
+    Args:
+        *lists: Any number of pkstruct linked list instances, each sorted.
+
+    Returns:
+        A new SinglyLinkedList containing all elements from *lists* in
+        sorted (ascending) order.
+
+    Raises:
+        ValueError: If no lists are provided.
+    """
+    if not lists:
+        raise ValueError("merge_sorted_lists requires at least one list argument.")
+
+    SinglyLinkedList, _, _ = _get_list_types()
+
+    # Collect all values, sort, build new list
+    all_values: list[Any] = []
+    for lst in lists:
+        all_values.extend(_to_values(lst))
+
+    all_values.sort()
+    return SinglyLinkedList.from_list(all_values)
+
+
+def detect_intersection(list_a: Any, list_b: Any) -> Any | None:
+    """Detect whether two linked lists share a common node by identity.
+
+    Uses a hash-set approach on node ids to find the first node that
+    appears in both *list_a* and *list_b*.
+
+    Args:
+        list_a: First linked list instance.
+        list_b: Second linked list instance.
+
+    Returns:
+        The data value of the first intersecting node, or ``None`` if the
+        lists do not intersect.
+    """
+    SinglyLinkedList, DoublyLinkedList, CircularLinkedList = _get_list_types()
+
+    def node_ids(lst: Any) -> dict[int, Any]:
+        """Return mapping of node id → data for *lst*."""
+        mapping: dict[int, Any] = {}
+        if isinstance(lst, CircularLinkedList):
+            current = lst.head
+            size = lst.size
+            steps = 0
+            while current is not None and steps < size:
+                mapping[id(current)] = current.value  # FIXED: .data → .value
+                current = current.next
+                steps += 1
+        else:
+            current = lst.head
+            visited: set[int] = set()
+            while current is not None:
+                nid = id(current)
+                if nid in visited:
+                    break
+                visited.add(nid)
+                mapping[nid] = current.value  # FIXED: .data → .value
+                current = current.next
+        return mapping
+
+    ids_a = node_ids(list_a)
+    ids_b = node_ids(list_b)
+
+    for nid in ids_b:
+        if nid in ids_a:
+            return ids_b[nid]
+
+    return None
+
+
+def list_equal(list_a: Any, list_b: Any) -> bool:
+    """Return True if *list_a* and *list_b* contain the same values in order.
+
+    Args:
+        list_a: First linked list instance.
+        list_b: Second linked list instance.
+
+    Returns:
+        ``True`` if the value sequences are identical, ``False`` otherwise.
+    """
+    return _to_values(list_a) == _to_values(list_b)
+
+
+def to_array(list_instance: Any) -> list[Any]:
+    """Alias for converting a linked list to a Python list via ``to_list()``.
+
+    Args:
+        list_instance: Any pkstruct linked list instance.
+
+    Returns:
+        A plain Python list of node values in forward order.
+    """
+    if hasattr(list_instance, "to_list"):
+        return list_instance.to_list()
+    return _to_values(list_instance)