# IniWrite

写入值或段到标准格式的 .ini 文件.

    IniWrite Value, Filename, Section, Key
    IniWrite Pairs, Filename, Section

## 参数

Value

  类型: 字符串

  将被写入到 Key 的等号(=) 右边的字符串或数字.

  如果文本较长, 可以通过延续片段的方法将其分解成较短的几行, 这样可以增加可读性和可维护性.

Pairs

  类型: 字符串

  要写入 .ini 文件的 Section 的完整内容, 不包括 [SectionName] 题头. Key 必须省略. Pairs 不能包含空行. 如果 section 已经存在, 最后一个键=值对之前的所有内容都被覆盖. Pairs 可以包含没有等号(=) 的行, 但这可能会产生不一致的结果. 注释可以写入文件中, 但被 IniRead 读回时将被抛弃.

Filename

  类型: 字符串

  .ini 文件的名称, 如果未指定绝对路径, 则假定在 A_WorkingDir 中.

Section

  类型: 字符串

  .ini 文件的段名, 它是包含在方括号中的标题短语(在此参数中不需要加方括号).

Key

  类型: 字符串

  .ini 文件中的键名.

## 错误处理

失败时抛出 OSError.

无论是否抛出异常, A_LastError 被设置为操作系统的 GetLastError() 函数的结果.

## 备注

超过 65,535 个字符的值可以写入文件, 但可能会产生不一致的结果, 因为 IniRead 或其他应用程序通常无法正确读取它们.

标准的 ini 文件看起来类似下面这样:

    [SectionName]
    Key=Value

新文件使用带有 UTF-16 字节顺序标记的方式来创建, 以确保可以使用全部的 Unicode 字符. 如果不希望这样, 那么请确保在调用 IniWrite 前目标文件已经存在. 例如:

    ; 创建一个 ANSI 编码的文件.
    FileAppend "", "NonUnicode.ini", "CP0"

    ; 创建一个没有字节顺序标记的 UTF-16 文件.
    FileAppend "[SectionName]`n", "Unicode.ini", "UTF-16-RAW"

Unicode: IniRead 和 IniWrite 依靠外部函数 GetPrivateProfileString 和 WritePrivateProfileString 来读取和写入值. 这些函数只支持 UTF-16 件中的 Unicode; 所有其他文件都假定使用系统的默认 ANSI 代码页.

    FileAppend "", "NonUnicode.ini", "CP0" ; 在大多数情况下最后一个参数是可选的.

## 相关

IniDelete, IniRead, RegWrite

## 示例

将一个值写入位于标准格式 .ini 文件中 section2 的一个键.

    IniWrite "this is a new value", "C:\Temp\myfile.ini", "section2", "key"

dftg