TransPyC/includes/linkedlist.py

import t, c
from stdint import *


# ============================================================
# LinkedNode: 非多态继承基类（@t.NoVTable）
#
# 子类继承此类即"启用"标准链表/树形结构能力：
#   - 双向兄弟链表（next/prev）→ O(1) 删除
#   - 父子树结构（child/last_child/parent）→ O(1) 追加子节点
#   - 子节点计数（child_count）
#
# 字段展平嵌入子类，无 vtable 开销（对应 C++ 非多态继承）。
# OOP 方法通过 _generate_inherited_method_wrappers 自动生成子类包装
# （self bitcast 为父类指针后调用），子类可直接调用继承的方法。
#
# 用法：
#   class MyNode(LinkedNode):
#       value: t.CInt
#   root: MyNode = MyNode()
#   child: MyNode = MyNode()
#   root.append(child)             # OOP 调用，self = root
#   child.detach()                 # 从兄弟链摘除（分离自己）
# ============================================================
@t.NoVTable
class LinkedNode:
    next: "LinkedNode" | t.CPtr        # 下一个兄弟节点
    prev: "LinkedNode" | t.CPtr        # 上一个兄弟节点（双向链表，O(1) 删除）
    child: "LinkedNode" | t.CPtr       # 第一个子节点
    last_child: "LinkedNode" | t.CPtr  # 最后一个子节点（O(1) 追加）
    parent: "LinkedNode" | t.CPtr      # 父节点
    child_count: t.CSizeT              # 子节点数

    def append(self, node: "LinkedNode" | t.CPtr):
        """将 node 追加为 self 的最后一个子节点（O(1)）。

        若 node 已在某链表中，调用方应先 node.detach() 再 append。
        """
        if self is None or node is None: return
        node.parent = self
        node.next = None
        node.prev = self.last_child
        if self.child is None:
            self.child = node
        else:
            self.last_child.next = node
        self.last_child = node
        self.child_count += 1

    def prepend(self, node: "LinkedNode" | t.CPtr):
        """将 node 插入为 self 的第一个子节点（O(1)）"""
        if self is None or node is None: return
        node.parent = self
        node.prev = None
        node.next = self.child
        if self.child is not None:
            self.child.prev = node
        else:
            self.last_child = node
        self.child = node
        self.child_count += 1

    def insert_before(self, node: "LinkedNode" | t.CPtr,
                      new_node: "LinkedNode" | t.CPtr):
        """在 node 之前插入 new_node（node 必须是 self 的子节点，O(1)）"""
        if self is None or node is None or new_node is None: return
        new_node.parent = self
        new_node.prev = node.prev
        new_node.next = node
        if node.prev is not None:
            node.prev.next = new_node
        else:
            self.child = new_node
        node.prev = new_node
        self.child_count += 1

    def insert_after(self, node: "LinkedNode" | t.CPtr,
                     new_node: "LinkedNode" | t.CPtr):
        """在 node 之后插入 new_node（node 必须是 self 的子节点，O(1)）"""
        if self is None or node is None or new_node is None: return
        new_node.parent = self
        new_node.prev = node
        new_node.next = node.next
        if node.next is not None:
            node.next.prev = new_node
        else:
            self.last_child = new_node
        node.next = new_node
        self.child_count += 1

    def remove_child(self, node: "LinkedNode" | t.CPtr):
        """从 self 的子链表中摘除 node（O(1)）。node 必须是 self 的直接子节点。"""
        if self is None or node is None: return
        # 修复 prev.next
        if node.prev is not None:
            node.prev.next = node.next
        else:
            self.child = node.next
        # 修复 next.prev
        if node.next is not None:
            node.next.prev = node.prev
        else:
            self.last_child = node.prev
        # 清除 node 的兄弟/父链接
        node.next = None
        node.prev = None
        node.parent = None
        if self.child_count > 0:
            self.child_count -= 1

    def detach(self):
        """将 self 从其所在兄弟链表中摘除（O(1)）。

        调用后 self 的 next/prev/parent 被清空，child 链不受影响。
        """
        if self is None: return
        # 修复 prev.next
        if self.prev is not None:
            self.prev.next = self.next
        elif self.parent is not None:
            self.parent.child = self.next
        # 修复 next.prev
        if self.next is not None:
            self.next.prev = self.prev
        elif self.parent is not None:
            self.parent.last_child = self.prev
        # 递减父节点计数
        if self.parent is not None:
            if self.parent.child_count > 0:
                self.parent.child_count -= 1
        # 清除 self 链接
        self.next = None
        self.prev = None
        self.parent = None

    def unlink(self):
        """断开 self 的所有连接（兄弟 + 父子），不递归处理子节点。

        调用后 self 成为孤立节点，但其 child 链仍指向原子节点
        （子节点的 parent 仍指向 self）。若需完全隔离，调用方应
        先逐个 self.remove_child 子节点。
        """
        if self is None: return
        # 先从兄弟链摘除
        self.detach()
        # 再断开父子链接
        self.child = None
        self.last_child = None
        self.child_count = 0

    def has_children(self) -> t.CInt:
        """返回 1 若有子节点，否则 0"""
        if self is None: return 0
        if self.child is not None: return 1
        return 0

    def child_at(self, index: t.CSizeT) -> "LinkedNode" | t.CPtr:
        """返回第 index 个子节点（O(n)，从 0 开始），越界返回 None"""
        if self is None: return None
        cur: "LinkedNode" | t.CPtr = self.child
        i: t.CSizeT = 0
        while cur is not None:
            if i == index: return cur
            i += 1
            cur = cur.next
        return None

    def count_children(self) -> t.CSizeT:
        """遍历计算子节点数（O(n)），用于校验 child_count"""
        if self is None: return 0
        n: t.CSizeT = 0
        cur: "LinkedNode" | t.CPtr = self.child
        while cur is not None:
            n += 1
            cur = cur.next
        return n

    def first_sibling(self) -> "LinkedNode" | t.CPtr:
        """返回兄弟链表的头节点（沿 prev 回溯）"""
        if self is None: return None
        cur: "LinkedNode" | t.CPtr = self
        while cur.prev is not None:
            cur = cur.prev
        return cur

    def last_sibling(self) -> "LinkedNode" | t.CPtr:
        """返回兄弟链表的尾节点（沿 next 前进）"""
        if self is None: return None
        cur: "LinkedNode" | t.CPtr = self
        while cur.next is not None:
            cur = cur.next
        return cur


# ============================================================
# SListNode: 单向链表节点（@t.NoVTable）
#
# 轻量级单向链表，仅 Next 指针，无 prev/parent/child。
# 适用于队列/栈/简单链场景（如 llvmlite 的 Param/BasicBlock/Function/Line/Value）。
# O(1) 追加需调用方维护 tail 指针（append_after）；
# O(n) 追加仅需 head（append）。
# ============================================================
@t.NoVTable
class SListNode:
    Next: "SListNode" | t.CPtr      # 下一个节点

    def append(self, node: "SListNode" | t.CPtr) -> "SListNode" | t.CPtr:
        """将 node 追加到链表末尾（O(n)），返回 self（head）。

        若 self 为 None，应直接使用 node 作为 head（调用方需自行处理）。
        """
        if self is None: return node
        if node is None: return self
        node.Next = None
        cur: "SListNode" | t.CPtr = self
        while cur.Next is not None:
            cur = cur.Next
        cur.Next = node
        return self

    def append_after(self, node: "SListNode" | t.CPtr) -> "SListNode" | t.CPtr:
        """将 node 追加到 self 之后（O(1)），返回新的 tail（即 node）。

        调用方需自行维护 head 指针。若 self 为 None，返回 node 作为首节点。
        """
        if node is None: return self
        node.Next = None
        if self is not None:
            self.Next = node
        return node

    def count(self) -> t.CSizeT:
        """遍历计算链表长度（O(n)）"""
        if self is None: return 0
        n: t.CSizeT = 0
        cur: "SListNode" | t.CPtr = self
        while cur is not None:
            n += 1
            cur = cur.Next
        return n

    def at(self, index: t.CSizeT) -> "SListNode" | t.CPtr:
        """返回第 index 个节点（O(n)，从 0 开始），越界返回 None"""
        if self is None: return None
        cur: "SListNode" | t.CPtr = self
        i: t.CSizeT = 0
        while cur is not None:
            if i == index: return cur
            i += 1
            cur = cur.Next
        return None

    def remove(self, node: "SListNode" | t.CPtr) -> "SListNode" | t.CPtr:
        """从链表中移除 node（O(n)），返回新的 head（self）。

        node 的 Next 被清空。若 node 是 head，返回 head.Next。
        """
        if self is None or node is None: return self
        if self is node:
            new_head: "SListNode" | t.CPtr = self.Next
            self.Next = None
            return new_head
        cur: "SListNode" | t.CPtr = self
        while cur.Next is not None:
            if cur.Next is node:
                cur.Next = node.Next
                node.Next = None
                break
            cur = cur.Next
        return self


# ============================================================
# GSListNode[T]: 泛型单向链表节点（@t.NoVTable + PEP 695 泛型）
#
# 相比 SListNode（非泛型，Next: SListNode|CPtr），GSListNode[T] 的 Next
# 字段类型为 T|CPtr，特化后直接是具体节点类型，无需向下转型。
#
# 递归泛型用法（子类继承自身特化版本）：
#   class GNode(GSListNode[GNode]):
#       value: t.CInt
#   # 此时 GNode.Next: GNode|CPtr（强类型，无转型）
#
# 技术验证点：
#   1. 递归泛型 class GNode(GSListNode[GNode])
#   2. @t.NoVTable + 泛型组合
#   3. 泛型类作字段类型 list: GSList[GNode]
#   4. 泛型方法继承（GSList[T].append 在特化后可用）
# ============================================================
@t.NoVTable
class GSListNode[T]:
    Next: T | t.CPtr


# ============================================================
# GSList[T]: 泛型单向链表容器（@t.NoVTable + PEP 695 泛型）
#
# 持有 Head/Tail/Count，提供 O(1) append 和 O(n) at。
# 节点类型 T 必须继承 GSListNode[T]（以获得 Next 字段）。
#
# 用法：
#   list: GSList[GNode] | t.CPtr = GSList[GNode]()
#   list.append(node)   # 方法调用，非全局函数
# ============================================================
@t.NoVTable
class GSList[T]:
    Head: T | t.CPtr
    Tail: T | t.CPtr
    Count: t.CSizeT

    def __init__(self):
        self.Head = None
        self.Tail = None
        self.Count = 0

    def append(self, node: T):
        """将 node 追加到链表末尾（O(1)）"""
        if node is None: return
        node.Next = None
        if self.Head is None:
            self.Head = node
        else:
            self.Tail.Next = node
        self.Tail = node
        self.Count += 1

    def count(self) -> t.CSizeT:
        """返回节点数（O(1)）"""
        return self.Count

    def at(self, index: t.CSizeT) -> T | t.CPtr:
        """返回第 index 个节点（O(n)，从 0 开始），越界返回 None"""
        if self.Head is None: return None
        cur: T | t.CPtr = self.Head
        i: t.CSizeT = 0
        while cur is not None:
            if i == index: return cur
            i += 1
            cur = cur.Next
        return None


# ============================================================
# GTreeNode[T]: 泛型树节点（@t.NoVTable + PEP 695 泛型）
#
# 强类型版本的 LinkedNode，所有指针字段类型为 T|t.CPtr。
# 提供：
#   - 双向兄弟链表（Next/Prev）→ O(1) 删除
#   - 父子树结构（Child/LastChild/Parent）→ O(1) 追加子节点
#   - 子节点计数（Count）
#
# 递归泛型用法（子类继承自身特化版本）：
#   @t.CVTable
#   class AST(GTreeNode[AST]):
#       def kind(self) -> t.CInt:
#           return 0
#   # 此时 AST.Next/Prev/Child/LastChild/Parent 均为 AST|t.CPtr（强类型）
#
# 字段展平嵌入子类，无 vtable 开销（对应 C++ 非多态继承）。
# 子类若为 @t.CVTable，则获得自己的 vtable（offset 0），
# GTreeNode 字段展平在 vtable 之后。
#
# OOP 方法通过 _generate_inherited_method_wrappers 自动生成子类包装
# （self bitcast 为父类指针后调用），子类可直接调用继承的方法。
# ============================================================
@t.NoVTable
class GTreeNode[T]:
    Next:       T | t.CPtr        # 下一个兄弟节点
    Prev:       T | t.CPtr        # 上一个兄弟节点（双向链表，O(1) 删除）
    Child:      T | t.CPtr        # 第一个子节点
    LastChild:  T | t.CPtr        # 最后一个子节点（O(1) 追加）
    Parent:     T | t.CPtr        # 父节点
    Count:      t.CSizeT          # 子节点数

    def append(self, node: T | t.CPtr):
        """将 node 追加为 self 的最后一个子节点（O(1)）。

        若 node 已在某链表中，调用方应先 node.detach() 再 append。
        """
        if self is None or node is None: return
        node.Parent = self
        node.Next = None
        node.Prev = self.LastChild
        if self.Child is None:
            self.Child = node
        else:
            self.LastChild.Next = node
        self.LastChild = node
        self.Count += 1

    def prepend(self, node: T | t.CPtr):
        """将 node 插入为 self 的第一个子节点（O(1)）"""
        if self is None or node is None: return
        node.Parent = self
        node.Prev = None
        node.Next = self.Child
        if self.Child is not None:
            self.Child.Prev = node
        else:
            self.LastChild = node
        self.Child = node
        self.Count += 1

    def detach(self):
        """将 self 从其所在兄弟链表中摘除（O(1)）。

        调用后 self 的 Next/Prev/Parent 被清空，Child 链不受影响。
        """
        if self is None: return
        if self.Prev is not None:
            self.Prev.Next = self.Next
        elif self.Parent is not None:
            self.Parent.Child = self.Next
        if self.Next is not None:
            self.Next.Prev = self.Prev
        elif self.Parent is not None:
            self.Parent.LastChild = self.Prev
        if self.Parent is not None:
            if self.Parent.Count > 0:
                self.Parent.Count -= 1
        self.Next = None
        self.Prev = None
        self.Parent = None

    def has_children(self) -> t.CInt:
        """返回 1 若有子节点，否则 0"""
        if self is None: return 0
        if self.Child is not None: return 1
        return 0

    def child_at(self, index: t.CSizeT) -> T | t.CPtr:
        """返回第 index 个子节点（O(n)，从 0 开始），越界返回 None"""
        if self is None: return None
        cur: T | t.CPtr = self.Child
        i: t.CSizeT = 0
        while cur is not None:
            if i == index: return cur
            i += 1
            cur = cur.Next
        return None

    def count_children(self) -> t.CSizeT:
        """遍历计算子节点数（O(n)），用于校验 Count"""
        if self is None: return 0
        n: t.CSizeT = 0
        cur: T | t.CPtr = self.Child
        while cur is not None:
            n += 1
            cur = cur.Next
        return n