言容：容器与集合

言容 1.0 的有界容器、稳定优先队列、LRU 缓存与受限集合算法。

言容（yanxu-collections）是纯言序实现的通用容器与集合算法库。稳定版 1.0.0 为容器、批量算法和回调建立了明确的顺序契约、无异常结果与资源预算。

版本与安装

项目	稳定值
包名	`言容`
版本 / 公开标签	`1.0.0` / `v1.0.0`
最低言序	`1.1.6`
依赖	无
构建目标	字节码

yanbao add 言容 \
  --git https://github.com/yanxulang/yanxu-collections.git \
  --rev v1.0.0 \
  --version '^1.0'

[依赖]
言容 = { git = "https://github.com/yanxulang/yanxu-collections.git", 修订 = "v1.0.0", 版 = "^1.0" }

提交生成的 言序.lock，以固定标签解析出的修订与内容校验。

核心能力：选择容器

容器	主要入口	顺序与用途
`栈()`	`压入`、`弹出`、`尝试弹出`、`查看`	后进先出
`队列()`	`入队`、`出队`、`尝试出队`、`队首`	先进先出
`双端队列()`	`加首`、`加尾`、`移首`、`移尾`	两端操作，快照按首到尾
`有序集合()`	`加入`、`删除`、`含有`、`转列`	去重并保留首次加入顺序
`优先队列()`	`加入`、`取出项`、`转项列`	数值越小越优先，同级保持加入顺序
`最近最少使用缓存(容量)`	`写入`、`读取`、`查看`、`尝试读取`	固定容量，读取触碰、查看不触碰

稳定优先队列

引「包:言容」为 言容；

定 待办 为 言容.优先队列（）；
待办.限制为（100）；
待办.加入（「常规任务」，10）
    .加入（「紧急任务甲」，1）
    .加入（「紧急任务乙」，1）；

定 下一项：典 为 待办.取出项（）；
言 下一项【「值」】；
言 下一项【「优先级」】；

输出的第一项是“紧急任务甲”。取出项返回值和优先级，取出只返回值。

LRU 缓存

定 缓存 为 言容.最近最少使用缓存（2）；
缓存.写入（「甲」，1）.写入（「乙」，2）；
缓存.读取（「甲」）；          # 命中并触碰甲
缓存.写入（「丙」，3）；       # 淘汰乙

言 缓存.含有（「乙」）；       # 假
言 缓存.键列（）；             # 从最少使用到最近使用

旧式 读取在缺失时返回空。若缓存允许保存真实空值，应使用 尝试读取或不触碰顺序的 尝试查看，并读取结果中的成功字段。

容量和无异常操作

栈、队列、双端队列、有序集合和优先队列默认最多保存 100000 项，可以按实例收紧：

定 事件队 为 言容.队列（）；
事件队.限制为（256）；

定 结果：典 为 事件队.尝试出队（）；
若 结果【「成功」】 则
    言 结果【「值」】；
否则
    言 结果【「错误」】【「代码」】；
终

上限必须为正整数，不能超过库硬上限，也不能低于当前项目数。超限加入会在修改容器前以 YANRONG_LIMIT失败。

集合与列算法

法 数值先于（甲：数，乙：数）：理 则
    归 （甲 小于 乙）；
终

定 来源：列<数> 为 【5，2，3，2，1】；

言 言容.去重（来源）；
言 言容.并集（来源，【8，2】）；
言 言容.对称差（【1，2】，【2，3】）；
言 言容.窗口（来源，3）；
言 言容.频次（来源）；
言 言容.稳定排序（来源，数值先于）；

还提供 交集、差集、分块、压平一级、拉链、拉链全部、划分、分组和旋转。所有算法返回新的外层列，不改写输入；分组和频次按键或值首次出现顺序输出。

每个批量算法都有同名的“受限”入口，最后一个参数为限制典：

定 限制：典 为 {
    「最大输入项」：200，
    「最大输出项」：1000，
    「最大比较次数」：4000
}；

言 言容.窗口受限（来源，3，限制）；

默认预算为 1024 个输入项、100000 个输出项目和 8192 次通用相等比较。窗口、分块、拉链和分组生成的子列或记录也计入输出预算。

错误、权限与安全边界

稳定错误前缀为 YANRONG_。常见代码包括：

代码	含义
`YANRONG_EMPTY`	从空容器读取或移出
`YANRONG_NOT_FOUND`	缓存键不存在
`YANRONG_LIMIT`	容量、输入、输出或比较预算耗尽
`YANRONG_LIMIT_CONFIG`	限制配置不合法
`YANRONG_CAPACITY`	LRU 容量不合法
`YANRONG_PRIORITY`	优先级超出安全数值范围
`YANRONG_CALLBACK` / `YANRONG_ORDER`	回调返回类型或排序关系不合法

捕获错误后用 错误详情取代码，不要比较中文消息。言容无第三方依赖，不申请文件、网络、监听、环境、进程或原生扩展权限。

已知限制

通用相等使用言序值相等语义，不依赖哈希；有序集合、LRU、去重、分组和频次在大量互异值下最坏为二次时间。
快照和算法结果只复制外层列，复合项目仍是浅引用；需要隔离可变敏感对象时由调用方先复制或冻结。
通用比较的可配置硬上限为 16384 次；大型可信数据也应优先分批，而不是盲目提高预算。
排序比较器必须返回逻辑值、不可令值先于自身，也不可同时令甲先于乙且乙先于甲；库不能证明任意回调的传递性或纯度。
单实例容器是内存对象，不提供持久化、跨进程同步或并发协调。