stack

裁剪与依赖

固定栈不依赖动态数组。只需要本地有界工作栈时，不会带入任何扩容代码。 BlockStack 与连续 Stack 可分别裁剪；两者都只复用 Array 的块索引或连续存储底座。 启用 ptr_stack 必须同时启用 stack 和 array，公共头会拒绝所有不完整依赖。

共同契约

• 栈顶是最后压入的元素，Push、Top、Pop 均为 O(1) 摊销操作；固定栈始终为 O(1)。
• Push 浅复制一个完整元素；Add 返回未初始化新槽，调用方必须立即写满。
• Get(index) 使用统一的 0 基栈底索引；Peek(depth) 从栈顶计数，depth == 0 等价于 Top。
• Top、Get 和 Peek 返回栈内借用地址。FixedStack 地址在生命周期内稳定；连续 Stack 扩容可能移动全部元素；BlockStack 的活动元素在 Push、Pop 和 Reserve 后仍保持地址稳定。
• Pop 把值复制到外部缓冲后再删除，不返回失活槽地址。输出可以为 NULL，表示只删除栈顶；输出不得与同一栈的存储区重叠。FixedStack 和连续 Stack 会主动检查这一条件；BlockStack 的低成本前置条件见其专节。
• 容器只管理元素字节。结构体中的指针、句柄和其他资源仍由调用方管理。
• 空栈 Top 或 Pop 返回失败并设置 XERR_RANGE。固定栈已满时 Add 或 Push 设置 XERR_AGAIN，且原栈不变。
• 容器不隐式加锁。一个栈同时只能由一个执行流修改；跨线程共享时使用外部同步。

PtrFixedStack

Init 直接借用调用方的 ptr[]，容量参数使用元素数量而不是字节数。指针数组不得与栈结构本身重叠。整个生命周期可以完全不分配内存，适合固定上限的资源回滚、清理动作和句柄栈。Create 则复用 FixedStack 的拥有型固定缓冲。

PtrFixedStack 只保存指针值，不拥有目标。它允许保存合法 NULL； 此时 Get、Peek 或 Top 返回 NULL 且不设置新错误，空栈或越界则设置 XERR_RANGE。 需要区分合法空值与失败时，应在读取前清除旧错误，再检查本次调用后的错误状态； 已知索引小于公开 Count 时，返回的 NULL 就是合法值。 所有入口都会拒绝元素宽度不是 sizeof(ptr) 的 FixedStack， 避免旧版“在更宽结构体前几个字节写入指针”的隐式布局。

PtrStack

指针栈允许保存合法 NULL。此时 Top 返回 NULL 但不会设置新错误； 空栈也返回 NULL，同时设置 XERR_RANGE。 需要无歧义处理时，在调用前清除错误并检查 xrtGetError()，或直接使用 Count。

Pop 返回布尔结果，因此能无歧义弹出空指针。输出参数可以为空，表示丢弃栈顶。清空、弹出和销毁都不会释放指针目标。 类型化入口会检查底层连续栈确实使用 sizeof(ptr) 元素，并直接复用已验证的 Array 增长原语；因此 Push 不需要通用字节复制和来源别名分析。分配失败保持 地址、深度、容量和已有指针值不变。Pop 继续复用通用栈的输出别名检查， 若输出指向自身存储区则设置 XERR_ARGUMENT 且不删除栈顶。