重构

Foundation/c_LinkStack.h

@@ -5,60 +5,59 @@
 #include <c_Types.h>
 #endif /*INCLUDED_C_TYPES_H*/
 
+#ifndef INCLUDED_C_ALLOCATOR_H
+#include <c_Allocator.h>
+#endif /*INCLUDED_C_ALLOCATOR_H*/
+
+
 /* ------------------------------------------------------------------------------------------------------------------ */
 /*  */
 
 
 typedef struct c_LinkStackNode_t {
-    void* data;
-    struct c_LinkStackNode_t* next;
+    struct c_LinkStackNode_t* next; // 指向下一个更早入栈的节点
+    // 后面紧跟一整块大小为 item_size 的物理连续内存，直接存放真实数据值
 } c_LinkStackNode_t;
 
+// 终极闭环泛型链式栈控制头（无哨兵极致架构）
 typedef struct {
-    c_LinkStackNode_t* head;
-    int obj_size;
-    c_size_t size;
+    c_LinkStackNode_t* top;   // 指向当前的栈顶节点（即单链表真实的第一个有效元素）
+    c_size_t item_size;       // 单个元素的字节大小
+    c_size_t size;            // 当前栈内持有的有效元素个数（O(1) 实时读取）
+    c_Allocator_t allocator;  // 内部绑定的自主内存管理器
 } c_LinkStack_t;
 
-typedef struct {
-    c_LinkStack_t* stack;
-    c_LinkStackNode_t** node;
-} c_LinkStackIter_t;
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
 
-c_err_t c_LinkStack_Init(c_LinkStack_t* self, int obj_size);
-void c_LinkStack_Destroy(c_LinkStack_t* self);
-c_err_t c_LinkStack_Push(c_LinkStack_t* self, void* obj);
-c_err_t c_LinkStack_Pop(c_LinkStack_t* self, void* obj);
-void* c_LinkStack_Peek(c_LinkStack_t* self);
-
-// 迭代器內聯函數實作
 C_STATIC_FORCE_INLINE
-void c_LinkStackIter_Init(c_LinkStackIter_t* self, c_LinkStack_t* stack) {
-    if (!self || !stack) return;
-    self->stack = stack;
-    self->node = &stack->head;
+void* c_LinkStackNode_Get(const c_LinkStackNode_t* self) {
+    if (!self) return NULL;
+    return ((void*)((char*)(self) + sizeof(c_LinkStackNode_t)));
+}
+
+/* ------------------------------------------------------------------------------------------------------------------ */
+/*  */
+
+c_err_t c_LinkStack_Init(c_LinkStack_t* self, c_size_t item_size, c_Allocator_t* allocator);
+void    c_LinkStack_Destroy(c_LinkStack_t* self);
+
+// 核心链式栈操作 API (安全值复制模式)
+c_err_t c_LinkStack_Push(c_LinkStack_t* self, const void* item);
+c_err_t c_LinkStack_Pop(c_LinkStack_t* self, void* out_item);
+void*   c_LinkStack_Peek(const c_LinkStack_t* self);
+void    c_LinkStack_Clear(c_LinkStack_t* self);
+
+// 内联高频辅助接口
+C_STATIC_FORCE_INLINE
+c_size_t c_LinkStack_Size(const c_LinkStack_t* self) {
+    if (!self) return 0;
+    return self->size; // O(1) 实时读取
 }
 
 C_STATIC_FORCE_INLINE
-c_bool_t c_LinkStackIter_HasNext(c_LinkStackIter_t* self) {
-    if (!self) return C_FALSE;
-    return (self->node != NULL) && (*(self->node) != NULL);
+bool c_LinkStack_IsEmpty(const c_LinkStack_t* self) {
+    return c_LinkStack_Size(self) == 0;
 }
 
-C_STATIC_FORCE_INLINE
-void* c_LinkStackIter_Next(c_LinkStackIter_t* self) {
-    if (!self || !self->node || !*(self->node)) return NULL;
-    void* data = (*(self->node))->data;
-    self->node = &(*(self->node))->next;
-    return data;
-}
-
-C_STATIC_FORCE_INLINE
-void* c_LinkStackIter_Get(c_LinkStackIter_t* self) {
-    if (!self || !self->node || !*(self->node)) return NULL;
-    return (*(self->node))->data;
-}
-
-void c_LinkStackIter_Remove(c_LinkStackIter_t* self);
-
 #endif /*INCLUDED_C_LINKSTACK_H*/