# textkit.utf16 库模块帮助文档

<details>  <summary>只操作文件</summary>  <p>
## 定位

四个入口均接收包含 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 的无损全文；内部仍读取完整文件，不是流式日志尾随器。
</p></details>

[» UTF-16LE 文件编辑](https://www.aardio.com/zh-cn/docs/library/textkit/utf16/index.html)

## textkit.utf16 成员列表 <a id="textkit.utf16" href="#textkit.utf16">&#x23;</a>

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) <a id="textkit.utf16.edit" href="#textkit.utf16.edit">&#x23;</a>
对 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) <a id="textkit.utf16.patch" href="#textkit.utf16.patch">&#x23;</a>
对 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) <a id="textkit.utf16.read" href="#textkit.utf16.read">&#x23;</a>
读取 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) <a id="textkit.utf16.save" href="#textkit.utf16.save">&#x23;</a>
新建或明确全文覆盖 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。