color

颜色工具

RGB/RGBA、HSV/HSL、命名色与对比度。C 输出由调用者持有，xlang 字符串独立拥有。

2026-10-29 补齐八个文本出口的缓冲、部分重叠与空结果 OOM 合同，新增 C/XLang 主题 CSS 生成范例。Windows 55 阶段与 Linux sanitizer、线程、26552 项独立 oracle、JIT/AOT 门禁通过；未修改算法、API 或返回所有权。

#3366CC #808080 #FFFFFF

规范化与混色

import color
string accent = color.normalize("#36c")
println(accent)
println(color.mix("#000", "#fff", 0.5))

依次输出 #3366CC、#808080。十六进制输入支持 3/4/6/8 位，# 可省略，不接受空白。四位和八位写法的 alpha 在末尾；名称先用 fromName 转换，valid("red") 为 false。

全部函数

下列颜色/名称参数为 string，RGB/alpha 分量为 int，h/s/v/l/t 为 float；所有参数均必填。

调用	返回与含义
`valid(text)`	bool，是否为合法十六进制 RGB/RGBA。
`red(text), green(text), blue(text), alpha(text)`	int，0..255；无 alpha 默认 255；非法为 -1。
`hex(r,g,b), hexA(r,g,b,a)`	string，大写 #RRGGBB / #RRGGBBAA；分量越界为空串。
`normalize(text)`	string，展开短写、舍弃 alpha；非法为空串。
`hue(text)`	float，色相 [0,360)，灰色为 0。
`saturation(text), value(text)`	float，HSV 的 S/V，范围 [0,1]。
`lightness(text)`	float，HSL 的 L，范围 [0,1]；不是相对亮度。
`fromHsv(h,s,v), fromHsl(h,s,l)`	string，转换为 RGB；有限 hue 环绕，其他有限分量截至 [0,1]。
`luminance(text), contrast(a,b)`	float，相对亮度 [0,1] / 对比度 [1,21]。
`isDark(text), isLight(text)`	bool，合法颜色按相对亮度 0.5 分界；非法均 false。
`mix(a,b,t)`	string，编码后的 RGB 分量插值；有限 t 截至 [0,1]，舍弃 alpha。
`fromName(name)`	string，148 个 CSS 命名色，ASCII 大小写不敏感。
`toName(text)`	string，仅匹配不透明颜色；同值别名返回按字母顺序排列的第一个。

数值查询遇到非法颜色返回 -1，文本查询返回空串。NaN/无穷浮点参数返回空串；分配失败属于错误，不能当作正常空结果。saturation 返回 HSV 饱和度，不是 HSL 饱和度。

使用边界

normalize/mix 不保留 alpha，luminance/contrast 不进行背景合成。透明颜色应先确定实际背景。 isDark/isLight 是方便判断，不是可访问性结论。工具不解析 rgb()/hsl() 文本、系统颜色或其他色域。

fromName 不接受 transparent/currentColor 或前后空白；toName 不模糊寻找近似色。 cyan/aqua 等别名可能得到同一个规范名称，不承诺恢复原输入。

颜色值参考 W3C 命名色表，亮度参考 W3C sRGB 定义。

C 接口与所有权

include/color.h 的数值接口返回 bool/int64_t/double，八个文本接口接收 char *output 与 size_t capacity。 XCOLOR_HEX_SIZE=10，XCOLOR_NAME_SIZE=24，容量包含结尾 NUL。足够大的输出可与输入共用缓冲。

C 核心结果不用释放，各线程使用自己的缓冲；没有共享可变缓存，正常路径不分配。 NULL/零容量输出设置 XERR_ARGUMENT，容量不足设置 XERR_RANGE；非法颜色正常返回 false 和空串。每次公开调用清除旧 XRT 错误。输入是借用的 NUL 结尾文本，不保留指针。

仅 color_native.h 的 *_text 桥返回需 xrtFree 的独立 char*，NULL 表示分配失败； xlang 以 @owned string 直接接管。普通 C 用户只链接 color_core.c 和所需 XRT，不需要语言编译器。

双语范例

发行目录运行 xl run examples/extlibs/color_basic.xl；C 对照为 extlibs/color/examples/basic.c。范例覆盖 21 个 API，实现同一组转换与黑/白前景选择，按固定黄金输出核对。在仓库根目录也可直接运行 xl run release/extlibs/color/examples/basic.c；该 C 范例只内嵌纯 C 核心。开发仓库仍可用 tools/run_extlib_c.ps1 -Package color -Source release/extlibs/color/examples/basic.c。

AA/AAA 标签只表示普通文字的对比度阈值，不是整页可访问性认证。

新增 extlibs/color/examples/theme.xl 与 extlibs/color/examples/theme_c.c：接收十六进制或命名色，选择对比度更高的黑/白文字，再生成背景、文字、悬停色 CSS 变量。发行目录用 xl run 分别执行即可；共用 theme.expected.txt，两平台的严格 C、直跑与独立程序均核对同一输出。范例不处理透明度合成。

验收范围

2026-10-29 新合同覆盖 432 组容量/NULL/非法输入/陈旧错误、75 组部分重叠（包括混色同时覆盖两个输入），并验证八个拥有型空结果的分配失败、恢复及独立寿命。Windows 默认门禁 55 阶段全部通过、输入未变；Linux 原生快照通过 ASan/UBSan/float-cast、21 个实际生成原型、八条直接接管路径和双语输出；两平台各八条独立程序路径均通过。Linux 失败现场现在默认保留，并在失败时也检查输入指纹；旧记录中的无条件清理不再适用。

门禁检查 C 缓冲边界、输入输出重叠、非有限数、零分配核心、拥有结果的故障恢复，四线程结果/错误隔离，独立数值和 148 个命名色参照，实际生成 C 原型、JIT/AOT、DLL 上下文及双语输出。独立参照现另核对 4101 组对比度和 4131 组 RGB 插值；先前 Windows 根目录的 VFS 头路径阻断只属旧发布物。

2026-10-24 使用更新后的 Windows 发布版复验，默认专项门禁完整通过：实际生成原型、语言边界与分配故障 AOT、双语范例 AOT、DLL 上下文复用及文档代码块。旧共享文本快照缺符号已解除。脚本将结果标为包级限定验证，并非正式产品全量重建；此页不宣称全部发布形态已经准入。

xlang 字符串入口已拒绝内嵌 NUL，不把有效前缀误判为完整颜色。Linux 门禁现同次覆盖 C sanitizer/oracle、XLang 边界及分配故障、双语范例逐字节对照；32 位/ARM、TSan 和长期性能仍待验收。 Windows 使用 tools/check_extlib_color.ps1 默认入口验证完整 AOT；-SkipAot 仅用于开发时缩短反馈。 Linux 执行入口：tools/check_extlib_color.sh。

2026-10-26 完整重建 Windows xl.exe/xl.dll/xlc.dll 与 Linux xl/libxl.so/libxlc.so 后复验：Windows 默认门禁报告 passed-scoped，43 项检查通过、输入哈希未变。Linux 门禁通过 C ASan/UBSan/float-cast、四线程 8000 轮、26552 项独立 oracle、中央与包内边界及分配故障的语言 AOT，以及 C 单文件范例 AOT；C/GCC、C/TCC、C/AOT 与 XLang 基础范例输出一致。两平台默认测试目录互不覆盖；Linux 默认临时目录退出清理，显式 COLOR_WORK_DIR 可保留证据。当时拥有型 C 文本由 takeCstr 接管。本包在上述 Windows/Linux x64 范围签收。脚本仍标记 releaseReady=false，因为它不运行全产品回归，不代表产品发布准入；此页也不外推 32 位/ARM、TSan 或长时性能。

2026-10-27：八个文本入口改为 char* 与 @owned string 直接接管；现有 Windows 完整专项门禁、Linux C ASan/UBSan 与语言 JIT/AOT 门禁再次通过。生成 C 直接保存原指针、扫描一次长度并按原合同处理失败，不再经过包内 point 转发；这不等于整个调用链零成本。