Rewrote the comments in the libraries under 'includes' in English (excluding those inside folders)
This commit is contained in:
@@ -4,8 +4,8 @@ import string
|
||||
import json
|
||||
from stdint import *
|
||||
|
||||
# Variant 类型标签 (与 _variant.py 保持一致)
|
||||
VARIANT_NONE: t.CDefine = 0 # 无类型/空值
|
||||
# Variant type tags (consistent with _variant.py)
|
||||
VARIANT_NONE: t.CDefine = 0 # Untyped / null value
|
||||
VARIANT_INT: t.CDefine = 1 # int (i64)
|
||||
VARIANT_FLOAT: t.CDefine = 2 # float (f32)
|
||||
VARIANT_DOUBLE: t.CDefine = 3 # double (f64)
|
||||
@@ -13,25 +13,25 @@ VARIANT_STR: t.CDefine = 4 # str (i8*)
|
||||
VARIANT_DICT: t.CDefine = 5 # dict*
|
||||
VARIANT_LIST: t.CDefine = 6 # list*
|
||||
VARIANT_BOOL: t.CDefine = 7 # bool (i1/i32)
|
||||
VARIANT_PTR: t.CDefine = 8 # 自定义指针类型
|
||||
VARIANT_PTR: t.CDefine = 8 # Custom pointer type
|
||||
|
||||
# Variant 结构体大小: vtype(i32, 4 bytes) + padding(4 bytes) + ptr(i8*, 8 bytes) = 16 bytes
|
||||
# Variant structure size: vtype(i32, 4 bytes) + padding(4 bytes) + ptr(i8*, 8 bytes) = 16 bytes
|
||||
_VARIANT_SIZE: t.CDefine = 16
|
||||
|
||||
|
||||
class dict:
|
||||
"""堆上动态字典容器，基于 mbuddy 分配器。
|
||||
键类型固定为 str (i8*)，值使用 Variant 存储 (类型标签 + 无类型指针)。
|
||||
支持嵌套 dict/list 和 JSON 序列化。
|
||||
"""Heap-allocated dynamic dictionary container based on mbuddy allocator.
|
||||
Key type is fixed to str (i8*), values are stored as Variant (type tag + untyped pointer).
|
||||
Supports nested dict/list structures and JSON serialization.
|
||||
|
||||
用法:
|
||||
Usage:
|
||||
mb: memhub.MemBuddy = memhub.MemBuddy(arena, arena_size)
|
||||
d: dict = dict(mb)
|
||||
d.set_int("x", 42)
|
||||
p: t.CPtr = d["x"]
|
||||
v: int = c.Deref(p)
|
||||
|
||||
# 嵌套 dict
|
||||
# Nested dict
|
||||
inner: dict = dict(mb)
|
||||
inner.set_int("a", 1)
|
||||
d.set_dict("sub", inner)
|
||||
@@ -46,7 +46,7 @@ class dict:
|
||||
__iter_index__: t.CSizeT = 0
|
||||
|
||||
def __new__(self, mb: memhub.MemBuddy | t.CPtr) -> t.CPtr:
|
||||
# 堆分配 dict 对象
|
||||
# Heap allocation for dict object
|
||||
return mb.alloc(dict.__sizeof__())
|
||||
|
||||
def __init__(self, mb: memhub.MemBuddy | t.CPtr):
|
||||
@@ -58,32 +58,32 @@ class dict:
|
||||
return self.__count__
|
||||
|
||||
def _find(self, key: str) -> t.CSizeT:
|
||||
"""查找 key 的索引，找不到返回 __count__"""
|
||||
"""Find index of target key; returns __count__ if not found"""
|
||||
for i in range(self.__count__):
|
||||
key_ptr: str | t.CPtr = t.CPtr(t.CUInt64T(self.__keys__) + i * 8)
|
||||
if key_ptr[0] == key: return i
|
||||
return self.__count__
|
||||
|
||||
def __getitem__(self, key: str) -> t.CPtr:
|
||||
"""返回值的无类型指针。用户用 c.Deref 解引用获取实际值。
|
||||
例: p: t.CPtr = d["x"]; v: int = c.Deref(p)"""
|
||||
"""Return untyped pointer to value. Use c.Deref to resolve the actual value.
|
||||
Example: p: t.CPtr = d["x"]; v: int = c.Deref(p)"""
|
||||
idx: t.CSizeT = self._find(key)
|
||||
if idx >= self.__count__: return None
|
||||
# Variant.ptr 在 Variant 结构体偏移 8 处
|
||||
# Variant.ptr is located at offset 8 within Variant structure
|
||||
val_ptr: str | t.CPtr = t.CPtr(t.CUInt64T(self.__values__) + idx * _VARIANT_SIZE + 8)
|
||||
return val_ptr[0]
|
||||
|
||||
def __setitem__(self, key: str, val: t.CNeedPtr):
|
||||
"""存储值为 VARIANT_PTR。val 自动取地址 (t.CNeedPtr)。
|
||||
注意: val 指向的值生命周期由调用者管理。
|
||||
如需持久存储，请使用 set_int / set_str 等类型化方法。"""
|
||||
"""Store value as VARIANT_PTR. Address is automatically resolved via t.CNeedPtr.
|
||||
Note: Lifecycle of the data pointed to by val is managed by caller.
|
||||
Use typed methods such as set_int / set_str for persistent storage."""
|
||||
self._set_variant_raw(key, VARIANT_PTR, val)
|
||||
|
||||
def _set_variant_raw(self, key: str, vtype: t.CInt, ptr: t.CPtr):
|
||||
"""内部方法: 存储 Variant (vtype + ptr)。不自动取地址。"""
|
||||
"""Internal method: store Variant entry (vtype + ptr). No automatic address resolution."""
|
||||
idx: t.CSizeT = self._find(key)
|
||||
if idx < self.__count__:
|
||||
# 更新已有键
|
||||
# Update existing key
|
||||
vtype_ptr: t.CInt | t.CPtr = t.CPtr(t.CUInt64T(self.__values__) + idx * _VARIANT_SIZE)
|
||||
vtype_ptr[0] = vtype
|
||||
val_ptr: str | t.CPtr = t.CPtr(t.CUInt64T(self.__values__) + idx * _VARIANT_SIZE + 8)
|
||||
@@ -108,55 +108,55 @@ class dict:
|
||||
self.__count__ += 1
|
||||
|
||||
# ============================================================
|
||||
# 类型化 setter — 在 __mbuddy__ 中分配持久存储
|
||||
# Typed setters — allocate persistent storage inside __mbuddy__
|
||||
# ============================================================
|
||||
|
||||
def set_int(self, key: str, val: int):
|
||||
"""存储 int 值 (VARIANT_INT)。值复制到 __mbuddy__ 持久存储。"""
|
||||
"""Store integer value (VARIANT_INT). Value is copied to persistent storage within __mbuddy__."""
|
||||
storage: t.CPtr = self.__mbuddy__.alloc(8)
|
||||
int_ptr: int | t.CPtr = t.CVoid(t.CUInt64T(storage), t.CPtr)
|
||||
int_ptr[0] = val
|
||||
self._set_variant_raw(key, VARIANT_INT, storage)
|
||||
|
||||
def set_str(self, key: str, val: str):
|
||||
"""存储 str 值 (VARIANT_STR)。直接存储字符串指针。"""
|
||||
"""Store string value (VARIANT_STR). Raw string pointer is stored directly."""
|
||||
self._set_variant_raw(key, VARIANT_STR, val)
|
||||
|
||||
def set_float(self, key: str, val: float):
|
||||
"""存储 float 值 (VARIANT_FLOAT)。值复制到 __mbuddy__ 持久存储。"""
|
||||
"""Store float value (VARIANT_FLOAT). Value is copied to persistent storage within __mbuddy__."""
|
||||
storage: t.CPtr = self.__mbuddy__.alloc(8)
|
||||
float_ptr: float | t.CPtr = t.CVoid(t.CUInt64T(storage), t.CPtr)
|
||||
float_ptr[0] = val
|
||||
self._set_variant_raw(key, VARIANT_FLOAT, storage)
|
||||
|
||||
def set_double(self, key: str, val: t.CDouble):
|
||||
"""存储 double 值 (VARIANT_DOUBLE)。值复制到 __mbuddy__ 持久存储。"""
|
||||
"""Store double value (VARIANT_DOUBLE). Value is copied to persistent storage within __mbuddy__."""
|
||||
storage: t.CPtr = self.__mbuddy__.alloc(8)
|
||||
dbl_ptr: t.CDouble | t.CPtr = t.CVoid(t.CUInt64T(storage), t.CPtr)
|
||||
dbl_ptr[0] = val
|
||||
self._set_variant_raw(key, VARIANT_DOUBLE, storage)
|
||||
|
||||
def set_dict(self, key: str, val: dict | t.CPtr):
|
||||
"""存储嵌套 dict 指针 (VARIANT_DICT)。"""
|
||||
"""Store nested dictionary pointer (VARIANT_DICT)."""
|
||||
self._set_variant_raw(key, VARIANT_DICT, val)
|
||||
|
||||
def set_list(self, key: str, val: t.CPtr):
|
||||
"""存储嵌套 list 指针 (VARIANT_LIST)。"""
|
||||
"""Store nested list pointer (VARIANT_LIST)."""
|
||||
self._set_variant_raw(key, VARIANT_LIST, val)
|
||||
|
||||
def set_bool(self, key: str, val: t.CInt):
|
||||
"""存储 bool 值 (VARIANT_BOOL)。值复制到 __mbuddy__ 持久存储。"""
|
||||
"""Store boolean value (VARIANT_BOOL). Value is copied to persistent storage within __mbuddy__."""
|
||||
storage: t.CPtr = self.__mbuddy__.alloc(8)
|
||||
bool_ptr: t.CInt | t.CPtr = t.CVoid(t.CUInt64T(storage), t.CPtr)
|
||||
bool_ptr[0] = val
|
||||
self._set_variant_raw(key, VARIANT_BOOL, storage)
|
||||
|
||||
# ============================================================
|
||||
# 查询方法
|
||||
# Query methods
|
||||
# ============================================================
|
||||
|
||||
def get_vtype(self, key: str) -> t.CInt:
|
||||
"""返回 key 对应值的 Variant 类型标签。"""
|
||||
"""Return Variant type tag associated with specified key."""
|
||||
idx: t.CSizeT = self._find(key)
|
||||
if idx >= self.__count__:
|
||||
return VARIANT_NONE
|
||||
@@ -164,7 +164,7 @@ class dict:
|
||||
return vtype_ptr[0]
|
||||
|
||||
def get(self, key: str, default: t.CPtr) -> t.CPtr:
|
||||
"""返回值指针，不存在则返回 default。"""
|
||||
"""Return value pointer; return default pointer if key does not exist."""
|
||||
idx: t.CSizeT = self._find(key)
|
||||
if idx >= self.__count__:
|
||||
return default
|
||||
@@ -172,7 +172,7 @@ class dict:
|
||||
return val_ptr[0]
|
||||
|
||||
def contains(self, key: str) -> t.CInt:
|
||||
"""检查 key 是否存在。"""
|
||||
"""Check whether target key exists."""
|
||||
idx: t.CSizeT = self._find(key)
|
||||
if idx < self.__count__:
|
||||
return 1
|
||||
@@ -191,12 +191,12 @@ class dict:
|
||||
return key_ptr[0]
|
||||
|
||||
# ============================================================
|
||||
# JSON 处理：利用 includes/json 库实现序列化/反序列化
|
||||
# JSON utilities: serialization / deserialization via includes/json library
|
||||
# ============================================================
|
||||
|
||||
def to_json(self, pool: memhub.MemManager | t.CPtr) -> json.JsonValue | t.CPtr:
|
||||
"""将 dict 转换为 JsonValue 对象 (JSON_OBJECT)。
|
||||
根据 Variant 类型标签自动选择合适的 JSON 值类型。"""
|
||||
"""Convert dict instance to JsonValue object (JSON_OBJECT).
|
||||
Automatically select corresponding JSON value type according to Variant tag."""
|
||||
obj: json.JsonValue | t.CPtr = json.object(pool)
|
||||
i: t.CSizeT = 0
|
||||
while i < self.__count__:
|
||||
@@ -223,7 +223,7 @@ class dict:
|
||||
fp: float | t.CPtr = t.CVoid(t.CUInt64T(vp), t.CPtr)
|
||||
jv.float_val = fp[0]
|
||||
elif vt == VARIANT_PTR:
|
||||
# 默认: 将 PTR 作为整数处理
|
||||
# Fallback: treat raw pointer as integer
|
||||
jv.vtype = 2 # JSON_INT
|
||||
ip: int | t.CPtr = t.CVoid(t.CUInt64T(vp), t.CPtr)
|
||||
jv.int_val = ip[0]
|
||||
@@ -232,8 +232,8 @@ class dict:
|
||||
return obj
|
||||
|
||||
def from_json(self, pool: memhub.MemManager | t.CPtr, root: json.JsonValue | t.CPtr):
|
||||
"""从 JsonValue 对象填充 dict。
|
||||
根据 JSON 值类型自动提取并存储为对应 Variant 类型。"""
|
||||
"""Populate dict from JsonValue object.
|
||||
Extract values and store them as matching Variant types based on JSON type tag."""
|
||||
if root == None:
|
||||
return
|
||||
if root.vtype != 6: # JSON_OBJECT
|
||||
@@ -261,11 +261,11 @@ class dict:
|
||||
cur = cur.next
|
||||
|
||||
def dumps(self, pool: memhub.MemManager | t.CPtr) -> str:
|
||||
"""将 dict 序列化为 JSON 字符串。"""
|
||||
"""Serialize dict to JSON string."""
|
||||
obj: json.JsonValue | t.CPtr = self.to_json(pool)
|
||||
return json.write(pool, obj, False)
|
||||
|
||||
def loads(self, pool: memhub.MemManager | t.CPtr, json_str: str):
|
||||
"""从 JSON 字符串解析并填充 dict。"""
|
||||
"""Parse JSON string and populate dict instance."""
|
||||
root: json.JsonValue | t.CPtr = json.parse(pool, json_str)
|
||||
self.from_json(pool, root)
|
||||
|
||||
Reference in New Issue
Block a user