GVSDS/TransPyC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrote the comments in the libraries under 'includes' in English (excluding those inside folders)

Browse Source
This commit is contained in:
TermiNexus
2026-07-29 23:34:36 +08:00
parent 3633be1995
commit a2cc28a6ab
54 changed files with 7091 additions and 899 deletions
Download Patch File Download Diff File Expand all files Collapse all files

283
includes/linkedlist.py
View File

@@ -3,38 +3,39 @@ from stdint import *
# ============================================================
# LinkedNode: 非多态继承基类（@t.NoVTable）
# LinkedNode: Non-polymorphic base class (@t.NoVTable)
#
# 子类继承此类即"启用"标准链表/树形结构能力：
# - 双向兄弟链表（next/prev）→ O(1) 删除
# - 父子树结构（child/last_child/parent）→ O(1) 追加子节点
# - 子节点计数（child_count）
# Subclasses inheriting from this class gain standard linked list and tree capabilities:
# - Bidirectional sibling links (next/prev) → O(1) removal
# - Parent-child tree structure (child/last_child/parent) → O(1) child appending
# - Child counter (child_count)
#
# 字段展平嵌入子类，无 vtable 开销（对应 C++ 非多态继承）。
# OOP 方法通过 _generate_inherited_method_wrappers 自动生成子类包装
# （self bitcast 为父类指针后调用），子类可直接调用继承的方法。
# Fields are flattened and embedded into subclasses with no vtable overhead
# (equivalent to non-polymorphic inheritance in C++).
# OOP methods are automatically wrapped for subclasses via _generate_inherited_method_wrappers
# (self pointer cast to base type before invocation). Inherited methods can be called directly by subclasses.
#
# 用法：
# Usage:
# class MyNode(LinkedNode):
# value: t.CInt
# root: MyNode = MyNode()
# child: MyNode = MyNode()
# root.append(child) # OOP 调用，self = root
# child.detach() # 从兄弟链摘除（分离自己）
# root.append(child) # OOP invocation, self = root
# child.detach() # Remove self from sibling chain
# ============================================================
@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 # 子节点数
next: "LinkedNode" | t.CPtr # Next sibling node
prev: "LinkedNode" | t.CPtr # Previous sibling node (doubly linked list, O(1) removal)
child: "LinkedNode" | t.CPtr # First child node
last_child: "LinkedNode" | t.CPtr # Last child node (O(1) append)
parent: "LinkedNode" | t.CPtr # Parent node
child_count: t.CSizeT # Number of child nodes
def append(self, node: "LinkedNode" | t.CPtr):
"""将 node 追加为 self 的最后一个子节点（O(1)）。
"""Append node as the last child of self (O(1)).
若 node 已在某链表中，调用方应先 node.detach() 再 append。
If node is already attached to any list, the caller shall invoke node.detach() prior to append.
"""
if self is None or node is None: return
node.parent = self
@@ -48,7 +49,7 @@ class LinkedNode:
self.child_count += 1
def prepend(self, node: "LinkedNode" | t.CPtr):
"""将 node 插入为 self 的第一个子节点（O(1)）"""
"""Insert node as the first child of self (O(1))."""
if self is None or node is None: return
node.parent = self
node.prev = None
@@ -62,7 +63,7 @@ class LinkedNode:
def insert_before(self, node: "LinkedNode" | t.CPtr,
new_node: "LinkedNode" | t.CPtr):
"""在 node 之前插入 new_node（node 必须是 self 的子节点，O(1)）"""
"""Insert new_node before node (O(1)). node must be a direct child of self."""
if self is None or node is None or new_node is None: return
new_node.parent = self
new_node.prev = node.prev
@@ -76,7 +77,7 @@ class LinkedNode:
def insert_after(self, node: "LinkedNode" | t.CPtr,
new_node: "LinkedNode" | t.CPtr):
"""在 node 之后插入 new_node（node 必须是 self 的子节点，O(1)）"""
"""Insert new_node after node (O(1)). node must be a direct child of self."""
if self is None or node is None or new_node is None: return
new_node.parent = self
new_node.prev = node
@@ -89,19 +90,20 @@ class LinkedNode:
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
"""Remove node from self's child linked list (O(1)). The node must be a direct child of self."""
if self is None or node is None:
return
# Patch prev.next
if node.prev is not None:
node.prev.next = node.next
else:
self.child = node.next
# 修复 next.prev
# Patch next.prev
if node.next is not None:
node.next.prev = node.prev
else:
self.last_child = node.prev
# 清除 node 的兄弟/父链接
# Clear sibling and parent links of node
node.next = None
node.prev = None
node.parent = None
@@ -109,64 +111,70 @@ class LinkedNode:
self.child_count -= 1
def detach(self):
"""将 self 从其所在兄弟链表中摘除（O(1)）。
"""Detach self from its sibling linked list (O(1)).
调用后 self 的 next/prev/parent 被清空，child 链不受影响。
After invocation, self.next/self.prev/self.parent are cleared. The child chain remains untouched.
"""
if self is None: return
# 修复 prev.next
if self is None:
return
# Patch 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
# Patch 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
# 递减父节点计数
# Decrement parent child counter
if self.parent is not None:
if self.parent.child_count > 0:
self.parent.child_count -= 1
# 清除 self 链接
# Clear links of self
self.next = None
self.prev = None
self.parent = None
def unlink(self):
"""断开 self 的所有连接（兄弟 + 父子），不递归处理子节点。
"""Sever all links of self (siblings and parent). Child nodes are not processed recursively.
调用后 self 成为孤立节点，但其 child 链仍指向原子节点
（子节点的 parent 仍指向 self）。若需完全隔离，调用方应
先逐个 self.remove_child 子节点。
After invocation, self becomes an isolated node, while its child chain still references original children
(the parent field of child nodes still points to self). For full isolation, the caller shall
invoke self.remove_child on each child beforehand.
"""
if self is None: return
# 先从兄弟链摘除
if self is None:
return
# First detach from sibling list
self.detach()
# 再断开父子链接
# Then break parent-child links
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 1 if child nodes exist, otherwise return 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
"""Return the child node at specified zero-based index (O(n)). Return None if index out of bounds."""
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
if i == index:
return cur
i += 1
cur = cur.next
return None
def count_children(self) -> t.CSizeT:
"""遍历计算子节点数（O(n)），用于校验 child_count"""
"""Count children by traversal (O(n)), used to validate child_count."""
if self is None: return 0
n: t.CSizeT = 0
cur: "LinkedNode" | t.CPtr = self.child
@@ -176,7 +184,7 @@ class LinkedNode:
return n
def first_sibling(self) -> "LinkedNode" | t.CPtr:
"""返回兄弟链表的头节点（沿 prev 回溯）"""
"""Return the head node of sibling linked list (traverse backward via prev pointers)."""
if self is None: return None
cur: "LinkedNode" | t.CPtr = self
while cur.prev is not None:
@@ -184,7 +192,7 @@ class LinkedNode:
return cur
def last_sibling(self) -> "LinkedNode" | t.CPtr:
"""返回兄弟链表的尾节点（沿 next 前进）"""
"""Return the tail node of sibling linked list (traverse forward via next pointers)."""
if self is None: return None
cur: "LinkedNode" | t.CPtr = self
while cur.next is not None:
@@ -193,24 +201,27 @@ class LinkedNode:
# ============================================================
# SListNode: 单向链表节点（@t.NoVTable）
# SListNode: Singly linked list node (@t.NoVTable)
#
# 轻量级单向链表，仅 Next 指针，无 prev/parent/child。
# 适用于队列/栈/简单链场景（如 llvmlite 的 Param/BasicBlock/Function/Line/Value）。
# O(1) 追加需调用方维护 tail 指针（append_after）；
# O(n) 追加仅需 head（append）。
# Lightweight singly linked list with only Next pointer. No prev/parent/child.
# Suitable for queues, stacks and simple linked structures
# (such as Param/BasicBlock/Function/Line/Value in llvmlite).
# O(1) append requires caller to maintain tail pointer (append_after).
# O(n) append works with head pointer only (append).
# ============================================================
@t.NoVTable
class SListNode:
Next: "SListNode" | t.CPtr # 下一个节点
Next: "SListNode" | t.CPtr # Next node
def append(self, node: "SListNode" | t.CPtr) -> "SListNode" | t.CPtr:
"""将 node 追加到链表末尾（O(n)），返回 self（head）。
"""Append node to the end of the linked list (O(n)). Return self (head).
若 self 为 None，应直接使用 node 作为 head（调用方需自行处理）。
If self is None, the caller shall adopt node directly as the new head.
"""
if self is None: return node
if node is None: return self
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:
@@ -219,19 +230,21 @@ class SListNode:
return self
def append_after(self, node: "SListNode" | t.CPtr) -> "SListNode" | t.CPtr:
"""将 node 追加到 self 之后（O(1)），返回新的 tail（即 node）。
"""Insert node immediately after self (O(1)). Return new tail (node).
调用方需自行维护 head 指针。若 self 为 None，返回 node 作为首节点。
Caller must maintain the head pointer manually. Return node as head if self is None.
"""
if node is None: return self
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
"""Calculate list length via full traversal (O(n))."""
if self is None:
return 0
n: t.CSizeT = 0
cur: "SListNode" | t.CPtr = self
while cur is not None:
@@ -240,22 +253,25 @@ class SListNode:
return n
def at(self, index: t.CSizeT) -> "SListNode" | t.CPtr:
"""返回第 index 个节点（O(n)，从 0 开始），越界返回 None"""
if self is None: return None
"""Return node at zero-based index (O(n)). Return None if index out of bounds."""
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
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）。
"""Remove node from list (O(n)). Return updated head.
node 的 Next 被清空。若 node 是 head，返回 head.Next。
The Next pointer of node will be cleared. If node is the original head, return head.Next.
"""
if self is None or node is None: return self
if self is None or node is None:
return self
if self is node:
new_head: "SListNode" | t.CPtr = self.Next
self.Next = None
@@ -271,21 +287,22 @@ class SListNode:
# ============================================================
# GSListNode[T]: 泛型单向链表节点（@t.NoVTable + PEP 695 泛型）
# GSListNode[T]: Generic singly linked list node (@t.NoVTable + PEP 695 generics)
#
# 相比 SListNode（非泛型，Next: SListNode|CPtr），GSListNode[T] 的 Next
# 字段类型为 T|CPtr，特化后直接是具体节点类型，无需向下转型。
# Unlike SListNode (non-generic, Next: SListNode|t.CPtr), the Next field of GSListNode[T]
# is typed as T|t.CPtr. After specialization it becomes a concrete node type directly,
# eliminating downcasts.
#
# 递归泛型用法（子类继承自身特化版本）：
# Recursive generic usage pattern (subclass inherits from self-specialized variant):
# class GNode(GSListNode[GNode]):
# value: t.CInt
# # 此时 GNode.Next: GNode|CPtr（强类型，无转型）
# # At this point GNode.Next: GNode|t.CPtr (strongly typed, no casting required)
#
# 技术验证点：
# 1. 递归泛型 class GNode(GSListNode[GNode])
# 2. @t.NoVTable + 泛型组合
# 3. 泛型类作字段类型 list: GSList[GNode]
# 4. 泛型方法继承（GSList[T].append 在特化后可用）
# Technical validation targets:
# 1. Recursive generics: class GNode(GSListNode[GNode])
# 2. Combination of @t.NoVTable attribute with generics
# 3. Generic class used as field type: list: GSList[GNode]
# 4. Inheritance of generic methods (GSList[T].append available after specialization)
# ============================================================
@t.NoVTable
class GSListNode[T]:
@@ -293,14 +310,14 @@ class GSListNode[T]:
# ============================================================
# GSList[T]: 泛型单向链表容器（@t.NoVTable + PEP 695 泛型）
# GSList[T]: Generic singly linked list container (@t.NoVTable + PEP 695 generics)
#
# 持有 Head/Tail/Count，提供 O(1) append 和 O(n) at。
# 节点类型 T 必须继承 GSListNode[T]（以获得 Next 字段）。
# Holds Head, Tail and Count. Provides O(1) append and O(n) indexed access.
# Node type T must inherit from GSListNode[T] (to acquire the Next field).
#
# 用法：
# Usage:
# list: GSList[GNode] | t.CPtr = GSList[GNode]()
# list.append(node) # 方法调用，非全局函数
# list.append(node) # Method invocation, not free function
# ============================================================
@t.NoVTable
class GSList[T]:
@@ -314,8 +331,9 @@ class GSList[T]:
self.Count = 0
def append(self, node: T):
"""将 node 追加到链表末尾（O(1)）"""
if node is None: return
"""Append node to the end of the list (O(1))."""
if node is None:
return
node.Next = None
if self.Head is None:
self.Head = node
@@ -325,59 +343,63 @@ class GSList[T]:
self.Count += 1
def count(self) -> t.CSizeT:
"""返回节点数（O(1)）"""
"""Return node count (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
"""Return node at zero-based index (O(n)). Return None if index out of bounds."""
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
if i == index:
return cur
i += 1
cur = cur.Next
return None
# ============================================================
# GTreeNode[T]: 泛型树节点（@t.NoVTable + PEP 695 泛型）
# GTreeNode[T]: Generic tree node (@t.NoVTable + PEP 695 generics)
#
# 强类型版本的 LinkedNode，所有指针字段类型为 T|t.CPtr。
# 提供：
# - 双向兄弟链表（Next/Prev）→ O(1) 删除
# - 父子树结构（Child/LastChild/Parent）→ O(1) 追加子节点
# - 子节点计数（Count）
# Type-safe variant of LinkedNode. All pointer fields are typed T|t.CPtr.
# Capabilities provided:
# - Bidirectional sibling linked list (Next/Prev) → O(1) removal
# - Parent-child tree structure (Child/LastChild/Parent) → O(1) child appending
# - Child counter (Count)
#
# 递归泛型用法（子类继承自身特化版本）：
# Recursive generic usage pattern (subclass inherits self-specialized variant):
# @t.CVTable
# class AST(GTreeNode[AST]):
# def kind(self) -> t.CInt:
# return 0
# # 此时 AST.Next/Prev/Child/LastChild/Parent 均为 AST|t.CPtr（强类型）
# # At this point AST.Next/Prev/Child/LastChild/Parent are all AST|t.CPtr (strongly typed)
#
# 字段展平嵌入子类，无 vtable 开销（对应 C++ 非多态继承）。
# 子类若为 @t.CVTable，则获得自己的 vtable（offset 0），
# GTreeNode 字段展平在 vtable 之后。
# Fields are flattened and embedded into subclasses with no vtable overhead
# (equivalent to non-polymorphic inheritance in C++).
# If a subclass is marked @t.CVTable, it receives its own vtable (at offset 0),
# and GTreeNode fields are laid out after the vtable.
#
# OOP 方法通过 _generate_inherited_method_wrappers 自动生成子类包装
# （self bitcast 为父类指针后调用），子类可直接调用继承的方法。
# OOP methods are automatically wrapped for subclasses via _generate_inherited_method_wrappers
# (self pointer cast to base type before invocation). Inherited methods can be called directly by subclasses.
# ============================================================
@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 # 子节点数
Next: T | t.CPtr # Next sibling node
Prev: T | t.CPtr # Previous sibling node (doubly linked list, O(1) removal)
Child: T | t.CPtr # First child node
LastChild: T | t.CPtr # Last child node (O(1) append)
Parent: T | t.CPtr # Parent node
Count: t.CSizeT # Number of child nodes
def append(self, node: T | t.CPtr):
"""将 node 追加为 self 的最后一个子节点（O(1)）。
"""Append node as the last child of self (O(1)).
若 node 已在某链表中，调用方应先 node.detach() 再 append。
If node is already attached to any list, the caller shall invoke node.detach() prior to append.
"""
if self is None or node is None: return
if self is None or node is None:
return
node.Parent = self
node.Next = None
node.Prev = self.LastChild
@@ -389,8 +411,9 @@ class GTreeNode[T]:
self.Count += 1
def prepend(self, node: T | t.CPtr):
"""将 node 插入为 self 的第一个子节点（O(1)）"""
if self is None or node is None: return
"""Insert node as the first child of self (O(1))."""
if self is None or node is None:
return
node.Parent = self
node.Prev = None
node.Next = self.Child
@@ -402,11 +425,12 @@ class GTreeNode[T]:
self.Count += 1
def detach(self):
"""将 self 从其所在兄弟链表中摘除（O(1)）。
"""Detach self from its sibling linked list (O(1)).
调用后 self 的 Next/Prev/Parent 被清空，Child 链不受影响。
After invocation, self.Next/self.Prev/self.Parent are cleared. The child chain remains untouched.
"""
if self is None: return
if self is None:
return
if self.Prev is not None:
self.Prev.Next = self.Next
elif self.Parent is not None:
@@ -423,25 +447,30 @@ class GTreeNode[T]:
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 1 if child nodes exist, otherwise return 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
"""Return the child node at specified zero-based index (O(n)). Return None if index out of bounds."""
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
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
"""Count children by traversal (O(n)), used to validate Count field."""
if self is None:
return 0
n: t.CSizeT = 0
cur: T | t.CPtr = self.Child
while cur is not None: