cKit/Foundation/c_LinkStack.c

#include <c_LinkStack.h>


#define STACK_NODE_DATA(node) ((void*)((char*)(node) + sizeof(c_LinkStackNode_t)))

// 原地初始化：无哨兵模式，初始化栈顶 top 为 0 (NULL)
c_err_t c_LinkStack_Init(c_LinkStack_t* self, c_size_t item_size, c_Allocator_t* allocator) {
    if (!self || item_size == 0) return C_ERR_PARAM;

    self->allocator = (allocator != NULL) ? *allocator : c_DefaultAllocator;
    self->item_size = item_size;
    self->size = 0;
    self->top = NULL;

    return C_ERR_OK;
}

// 入栈操作 (完美的真正 O(1) 极致无跳转头插)
c_err_t c_LinkStack_Push(c_LinkStack_t* self, const void* item) {
    if (!self || !item) return C_ERR_PARAM;

    // 1. 动态分配变长节点空间 (控制壳 + 业务数据一体化)
    c_size_t total_bytes = sizeof(c_LinkStackNode_t) + self->item_size;
    c_LinkStackNode_t* new_node = (c_LinkStackNode_t*)c_Allocator_Alloc(&self->allocator, total_bytes);
    if (!new_node) return C_ERR_NOMEM;

    // 2. 泛型值深度复制
    memcpy(STACK_NODE_DATA(new_node), item, self->item_size);

    // 3. 无边界头插拓扑串联：新节点咬住当前的 top，再让 top 沦为新节点
    new_node->next = self->top;
    self->top = new_node;

    self->size++;
    return C_ERR_OK;
}

// 出栈操作 (O(1) 性能，深度拷贝至外部缓冲区，完美防御下溢)
c_err_t c_LinkStack_Pop(c_LinkStack_t* self, void* out_item) {
    if (!self || self->size == 0 || !self->top) return C_ERR_OUTOFBOUND;

    // 锁定即将被弹出解体的栈顶节点
    c_LinkStackNode_t* node_to_free = self->top;

    // 如果外部需要拷出数据快照，执行 memcpy
    if (out_item) {
        memcpy(out_item, STACK_NODE_DATA(node_to_free), self->item_size);
    }

    // 栈顶指针顺理成章移向下一个更早入栈的项
    self->top = node_to_free->next;

    // 闭环通过内置分配器归还物理块资源
    c_Allocator_Free(&self->allocator, node_to_free);
    self->size--;

    return C_ERR_OK;
}

// 查看栈顶元素 (只读原位原位窥探，零拷贝损耗)
void* c_LinkStack_Peek(const c_LinkStack_t* self) {
    if (!self || self->size == 0 || !self->top) return NULL;
    return STACK_NODE_DATA(self->top);
}

// 高效清空栈内全部节点
void c_LinkStack_Clear(c_LinkStack_t* self) {
    if (!self) return;

    c_LinkStackNode_t* curr = self->top;
    while (curr) {
        c_LinkStackNode_t* next_to_free = curr->next;
        c_Allocator_Free(&self->allocator, curr);
        curr = next_to_free;
    }

    self->top = NULL; // 还原到你 Init 指定的 0 纯净空空空状态
    self->size = 0;
}

// 彻底销毁
void c_LinkStack_Destroy(c_LinkStack_t* self) {
    if (!self) return;
    c_LinkStack_Clear(self);
}