# FileRead

读取文件的内容到变量.

    FileRead, OutputVar, Filename

## 参数

OutputVar

  用来存储获取的数据的变量名. 如果遇到问题, 例如文件 "在使用中" 或不存在, 则 OutputVar 被置空(此时 ErrorLevel 被设置为 1). 如果 Filename 是个空文件, 则输出变量也被置空(此时 ErrorLevel 被置为 0).

Filename

  要读取的文件名, 如果未指定绝对路径, 则假定在 %A_WorkingDir% 中.

  选项: 在文件名前面可以直接添加零个或多个下列字符串. 在选项间使用单个空格或 tab 分隔. 例如: `*t *m5000 C:\Log Files\200601.txt`.

  *c: 读取保存了 ClipboardAll 内容的文件或其他二进制数据. 使用了 *c 选项时其他所有选项会被忽略.

  *m1024: 如果省略此选项, 则读取整个文件, 不过如果内存不足, 则显示错误消息并退出线程(使用 Try 可以避免这种情况). 否则, 请把 1024 替换为十进制或十六进制表示的字节数. 如果文件大于此字节数, 那么只读取其前面部分.

  注意: 此选项可能导致最后一行以单独的回车符(`r) 而不是 `r`n 结束.

  *t: 把所有的回车换行符(`r`n) 替换为换行符(`n). 不过, 这种转换会降低性能而且往往不必要. 例如, 包含 `r`n 的文本已经是添加到 Gui 编辑控件的正确格式. 同样地, FileAppend 打开新文件时会检测是否含有 `r`n; 它知道按原样写入每对 `r`n 而不是把它转换成 `r`r`n. 最后, 不论每行的结束符是 `r`n 或只是 `n, 后面的解析循环都可以正确执行: `Loop, parse, MyFileContents, `n, `r`.

  *Pnnn: [AHK_L 42+]: 覆盖 FileEncoding 包含的默认编码设置, 其中 nnn 必须是数值的代码页标识符.

## 错误处理

[v1.1.04+]: 此命令失败时会抛出异常. 想了解更多信息, 请参阅运行时错误.

读取成功时 ErrorLevel 被置为 0. 如果遇到问题, 它被设置为 1, 例如: 1) 文件不存在; 2) 文件被锁定或无法访问; 3) 系统没有足够的内存加载文件.

A_LastError 被设置为操作系统 GetLastError() 函数返回的结果.

## 读取二进制数据

根据文件, 参数和默认设置, FileRead 可能把文件数据解释为文本并且把它转换成脚本使用的原生编码. 如果文件包含二进制数据, 那么这样的操作很可能引起问题, 不过在下列情况中则可以避免:

- 如果存在 *C 选项, 则无条件忽略所有代码页和行结束符的转换.
- 如果存在 *Pnnn 选项且 nnn 符合原生的字符串编码, 则不会进行代码页转换.
- 如果当前文件编码设置符合原生字符串编码, 则不会进行代码页转换.

注意一旦把数据读取到 OutputVar, 那么只有首个二进制零(如果存在) 才能被大多数 AutoHotkey 命令和函数 "看到". 然而, 所有的内容仍然存在并且可以使用高级的方法进行访问(例如 NumGet()).

最后, 使用 FileOpen() 和 File.RawRead() 或 File.ReadNum() 可以在无需首先读取整个文件到内存中的情况下读取二进制数据.

## 备注

当需要读取文件的全部或大部分内容到内存时, 使用 FileRead 比文件读取循环执行地更好.

大于 1 GB 的文件会导致 ErrorLevel 被设置为 1 并且 OutputVar 被置为空, 此时可以使用 *m 选项来避免并读取文件的前面部分.

FileRead 不遵循 #MaxMem 的设置. 如果担心使用太多的内存, 可以预先用 FileGetSize 检查文件的大小.

FileOpen() 比 FileRead 提供了更高级的功能, 例如在文件的指定位置读取或写入数据时无需把整个文件读取到内存中. 请参阅文件对象了解函数列表.

## 相关

FileEncoding, FileOpen() / 文件对象, 文件读取循环, FileReadLine, FileGetSize, FileAppend, IniRead, Sort, UrlDownloadToFile

## 示例

读取文本文件到 OutputVar.

    FileRead, OutputVar, C:\My Documents\My File.txt

快速对文件的内容进行排序.

    FileRead, Contents, C:\Address List.txt
    if not ErrorLevel  ; 加载成功
    {
        Sort, Contents
        FileDelete, C:\Address List (alphabetical).txt
        FileAppend, %Contents%, C:\Address List (alphabetical).txt
        Contents := "" ; 清空占用的内存.
    }

dftg