cKit/Foundation/c_LinkStack.h

#ifndef INCLUDED_C_LINKSTACK_H
#define INCLUDED_C_LINKSTACK_H

#ifndef INCLUDED_C_TYPES_H
#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 {
    struct c_LinkStackNode_t* next; // 指向下一个更早入栈的节点
    // 后面紧跟一整块大小为 item_size 的物理连续内存，直接存放真实数据值
} c_LinkStackNode_t;

// 终极闭环泛型链式栈控制头（无哨兵极致架构）
typedef struct {
    c_LinkStackNode_t* top;   // 指向当前的栈顶节点（即单链表真实的第一个有效元素）
    c_size_t item_size;       // 单个元素的字节大小
    c_size_t size;            // 当前栈内持有的有效元素个数（O(1) 实时读取）
    c_Allocator_t allocator;  // 内部绑定的自主内存管理器
} c_LinkStack_t;

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

C_STATIC_FORCE_INLINE
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
bool c_LinkStack_IsEmpty(const c_LinkStack_t* self) {
    return c_LinkStack_Size(self) == 0;
}

#endif /*INCLUDED_C_LINKSTACK_H*/