textkit.utf16 库模块帮助文档

只操作文件

定位

四个入口均接收包含 path 的参数表，仅操作文件，不提供内存文本 API。磁盘固定 UTF-16LE（codepage=1200）；参数、返回数据、补丁和编辑引擎中的文本均为 UTF-8。内存文本直接使用 textkit / textkit.patch / textkit.editor。本库不依赖或修改 Autos 工具及 textkit.ansi。

编码与文件边界

接受带 FF FE BOM 或无 BOM 的 UTF-16LE；新文件默认带 BOM，已有文件保留有/无 BOM 状态。BOM 不进入正文或行号；bom 返回该状态但不是可设置参数。
不猜测编码、不支持 UTF-16BE/UTF-32。不自动修复奇数字节、不配对代理、U+0000 等无效文本；支持非 BMP 字符与正常 UTF-16 零字节。
无 BOM 文件拒绝以 U+FEFF/U+FFFE 开头的新正文，避免与文件 BOM 混淆；有 BOM 文件允许正文以这些字符开头。
不统一换行、不编译执行。持续写入的日志可能不完整或发生竞争，建议停止写入/创建稳定副本后编辑。
patch/edit 默认 backup=true；save 覆盖也默认备份。备份为原始字节，见 backupPath；使用 io.copy 原样恢复，不要交给 UTF-8 文本工具。
dryRun 无备份/暂存；无字节变化不写入。父目录须已存在，不自动建目录。
同目录独占暂存、校验、提交前复查、ReplaceFileW 替换。复查不是跨进程锁，不承诺跨文件事务或断电持久性。
originalBytes/resultBytes 是含 BOM 的磁盘 UTF-16 字节数；预览、诊断和 read 的 maxBytes 均按 UTF-8 计。
read 是分页展示视图（默认行号、LF 展示、可能截断），不是可用于 save 的无损全文；内部仍读取完整文件，不是流式日志尾随器。

» UTF-16LE 文件编辑

textkit.utf16 成员列表 #

UTF-16LE 文件接口，适用于 Windows 工具的 Unicode 日志等文本文件。
仅操作文件，固定 codepage=1200；参数和返回文本均为 UTF-8，内存文本直接使用 textkit。接口与 textkit.ansi 一致，不修改 Autos 工具。
新建带 FF FE BOM，已有文件保留有/无 BOM；不猜编码、不支持 UTF-16BE。拒绝不完整编码与 U+0000，不修复乱码。
均返回结果表，先检查 ok；失败看 code/error/hint。默认原始字节备份；dryRun 不写入。

textkit.utf16.edit(args) #

对 UTF-16LE 文件执行结构化字面编辑，与 edit_text_file 字段对齐但没有 compile。
公共path/operation/backup=true/dryRun=false/previewMaxBytes=1024。replace: oldText,newText；insertBefore/insertAfter: anchor,newText；replaceLines: startLine,endLine?,expectedOldText?,newText；replaceBetween: beginAnchor,endAnchor,newText；deleteBetween: beginAnchor,endAnchor。
默认唯一；expectedCount=N要求恰好N处，不是替换上限；replaceAll=true替换全部非重叠命中，0命中失败。newText显式传入，空串删除，deleteBetween不传newText；插入不自动加换行。
区间默认留锚点，includeAnchors=true含锚点；嵌套/缺尾拒绝。行区间两端含，空串删整行；保留原末行EOL。preserveEol默认true仅容忍换行差异，新文本适配局部EOL，false禁用等价。
只传适用字段，保留BOM；返回结果表同patch，原始字节备份用于io.copy恢复，勿用UTF-8工具。

textkit.utf16.patch(args) #

对 UTF-16LE 文件应用 Aider SEARCH/REPLACE 补丁。
{path;patches;backup=true;dryRun=false;previewMaxBytes=1024}，预览0..4096按UTF-8计。全部块匹配同一修改前正文，SEARCH非空、唯一、区间不重叠；任一失败整单不写。
标记独占行 <<<<<<< SEARCH / ======= / >>>>>>> REPLACE；只传块、不传路径行。大小写/空白严格，仅CRLF/LF/CR等价；旧片段原样复制，不trim/dedent，标记冲突改用edit。
保留原BOM状态与未编辑处换行；返回ok/written/changed/path/bom/backupPath/count/changedCount/preview等，原始字节大小包含BOM。诊断不授权模糊修改。

textkit.utf16.read(args) #

读取 UTF-16LE 文件的有界 UTF-8 展示视图。
{path;startLine=1;lineCount=120;maxBytes=20000;lineNumbers=true}。BOM不进入正文；data默认带行号，复制SEARCH时去行号。lineNumbers=false仍是LF展示视图，可能截断，不能当全文save。
返回ok/path/data/bom/startLine/endLine/totalLines/truncated/clipped/textBytes/originalBytes；预算包含行号与展示换行，0可仅取元数据；空文本1行，末尾换行后有空逻辑行。内部读取完整文件，不是流式读取。

textkit.utf16.save(args) #

新建或明确全文覆盖 UTF-16LE 文件，不追加、不自动建父目录。
{path;content;backup=true;dryRun=false}；content为UTF-8字符串，内部转codepage=1200。新建带FF FE BOM，覆盖保留原BOM状态，不改变换行。空串表示空文本，新文件为2字节BOM。
覆盖前验证原文件是有效UTF-16LE；不作为编码转换/修复工具。无变化不写入，已有文件默认原始字节备份；局部修改优先patch/edit。返回ok/written/changed/path/bom/originalBytes/resultBytes/backupPath。

Markdown 格式