# fs.atomic_write

## 功能

先把新内容写入目标同目录的临时文件并刷新到磁盘，再原子替换目标文件；可使用旧内容 SHA-256 检测外部修改，避免静默覆盖。

## 语法

```bt
fs(path).atomic_write(content, expected_sha256)
```

## 参数

| 参数 | 类型 | 必填 | 默认值 | 有效范围 | 说明 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| content | Any | 否 | '' | 可转换为文件内容的 BT 值 | 要写入的新内容；数组和对象会写入 JSON 字符串。 |
| expected_sha256 | String | 否 | 无 | 64 位十六进制文本 | 目标现有内容的 SHA-256；传入后会在创建临时文件前和最终替换前各校验一次。 |

## 返回值

返回 Object。

| 字段 | 类型 | 是否总是存在 | 默认值 | 有效范围 | 含义 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| bytes | Int | 是 | 无 | 0 及以上 | 新内容的字节数。 |
| sha256 | String | 是 | 无 | 64 位小写十六进制文本 | 新内容的 SHA-256。 |
| previous_sha256 | String/empty | 是 | empty | 64 位小写十六进制文本或 empty | 替换前旧内容的 SHA-256；目标原先不存在时为 empty。 |

## 示例

```bt
file = fs('config.bt')
old_hash = crypto(file.read()).sha256()
result = file.atomic_write("name = 'BT 2'\n", old_hash)

// 输出：true
print result.bytes > 0
```

## 注意事项

- 目标父目录必须存在，目标不能是目录。
- 临时文件和目标位于同一目录；只有临时内容完整写入并刷新后才替换目标。
- 传入 `expected_sha256` 时，目标不存在、摘要不匹配或写入期间被外部修改都会报冲突，原内容不会被新内容静默覆盖。
- Windows 使用带写穿透的原子替换；其它平台使用同文件系统重命名。