set

启用与依赖

依赖关系：

设计契约

• 默认按完整元素字节使用稳定 xrtHash64 和精确比较。
• 桶数组负载上限为 75%，扩缩容只重建桶链，不移动元素。
• 删除后重新加入的元素位于插入顺序尾部。
• GetOrAdd、Add 和单元素扩容在分配失败时不改变集合。
• Merge 预先暂存全部缺失元素和新桶，成功后一次提交；失败时目标完全不变。
• Merge 不复制或移动目标已有元素，并保持这些元素的地址与相对顺序。
• 集合不内置锁；跨线程并发访问由调用方同步。
• 结构修改使迭代器失效；Reserve 和 Trim 不使迭代器失效。
• 键策略和生命周期回调不得调用同一集合的任何 API。
• 访问器可查询当前集合，但不得修改、结束或再次访问当前集合。

初始化与生命周期

Init 用于栈对象和嵌入对象，配对 Unit。Create 用于堆对象，配对 Destroy。Clear 释放元素但保留桶数组，Trim 可释放空闲桶。

键策略

哈希器和相等器必须成对设置，并且只可在集合为空时修改。相等关系必须满足自反、对称和传递，相等元素必须产生相同哈希。自定义策略适合忽略结构填充、按业务键去重、字符串内容比较或抗碰撞哈希。

键策略回调只借用输入元素，不得保留指针，也不得调用同一集合的任何 API。回调期间尝试重入同一集合会得到 XERR_STATE。不同集合之间不存在隐式同步；共享回调上下文时仍由调用方保证线程安全。

资源生命周期

复制器和释放器必须成对设置。目标槽在调用复制器前已经清零；复制器失败时不得留下需要释放的资源，并应设置能够说明失败原因的错误。复制成功后的目标必须与源元素拥有相同哈希且相等，否则集合会调用释放器回滚并报告 XERR_STATE。该契约使字符串、引用计数句柄和 xvalue 等拥有型元素可以安全参与克隆与集合运算。

没有生命周期回调时，集合按字节复制元素，也不会释放元素内部指针。

复制器和释放器不得调用同一集合的任何 API。释放器只处理元素内部拥有的资源，集合负责释放条目槽。

完整的拥有型结构示例见 examples/containers/set/owned/main.c。它按业务编号实现 xsethash、xsetequal，用 xsetcopy 深复制字符串，并用 xsetdrop 释放资源。

基础操作

GetOrAdd 和 Get 返回集合内部规范元素。加入等价元素不会替换第一次保存的元素。返回地址在该元素删除或集合销毁前保持稳定。

Remove 调用释放器。Take 把完整元素字节移交给输出后删除，不调用释放器。为避免删除后悬空、覆盖桶或破坏元数据，完整输出区间不得与集合结构、桶数组或任何元素条目重叠；该安全检查需要扫描条目，因此 Take 为 O(n)，普通查找和删除仍为平均 O(1)。

容量

Capacity 是再次扩容前可容纳的元素数，不是桶数。

xrtSetCount(&tSet) 返回当前元素数，xrtSetCapacity(&tSet) 返回已预留的元素容量。 空集合调用 Trim 会释放桶数组；非空集合只把桶数缩到当前元素数所需的最小值。

遍历

遍历顺序确定为首次插入顺序。迭代器只借用集合，调用方必须在集合有效期内结束使用。

Visit 调用访问器期间允许 Count、Capacity、Get 和 Has 等查询，但拒绝增删、容量或策略修改、Unit、Destroy 以及嵌套 Visit，并报告 XERR_STATE。外置迭代器不会锁定集合；任何结构修改都会让已有迭代器在下一次推进时报告 XERR_STATE。

集合运算

参与二元运算的集合必须具有相同元素大小、对齐、键策略和生命周期策略。结果集合沿用左集合策略。所有返回的集合由调用方使用 xrtSetDestroy 释放。

IsDisjoint 遍历元素较少的一侧，找到首个共同元素即停止；两个空集合互斥，同一个非空集合不互斥。关系判断不分配内存，false 可以表示正常的关系不成立；参数或集合状态错误通过线程错误记录区分。

克隆和集合运算是多步只读操作。实现会临时保护输入集合，阻止键策略或生命周期回调修改、结束输入集合；即使函数参数为 const，同一集合实例仍不得被其他线程并发访问。Merge 只暂存缺失元素，不复制或释放目标已有元素；仅合并重复元素不会改变结构版本，真正加入元素才会使外置迭代器失效。