# FileRead

检索文件的内容.

    Text := FileRead(Filename , Options)

## 参数

Filename

  类型: 字符串

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

Options

  类型: 字符串

  以下字符串的零个或多个, 使用单个空格或制表符将每个选项与下一个选项分开. 例如: `"`n m5000 UTF-8"`

  Encoding: 如果文件缺少 UTF-8 或 UTF-16 字节顺序标记, 则指定 FileEncoding 接受的任何编码名称(不包括空字符串) 以使用该编码. 如果省略, 默认为 A_FileEncoding.

  RAW: 指定单词 RAW(不区分大小写) 以原始二进制数据读取文件内容, 并返回缓冲对象而不是字符串. 此选项覆盖以前指定的任何编码, 反之亦然.

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

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

  `n(换行符): 把所有的回车换行符(`r`n) 替换为换行符(`n). 不过, 这种转换会降低性能而且往往不必要. 例如, 包含 `r`n 的文本已经以正确的格式添加到 Gui Edit 控件中. 下面的解析循环将正确工作, 不管每一行的结尾是 `r`n 还是 `n: `Loop Parse, MyFileContents, "`n", "`r"`.

## 返回值

类型: 字符串或缓冲

函数返回指定文件的内容. 如果 RAW 选项有效且文件可以打开, 则返回值为缓冲对象; 否则, 返回字符串. 如果文件不存在或由于其他原因无法打开, 则返回一个空字符串.

## 错误处理

如果打开或读取文件有问题, 则抛出 OSError.

如果文件大小超过 4 Gb, 则会引发 MemoryError, 除非存在 *m 选项, 在这种情况下, 将加载文件前面的部分. 如果程序无法分配足够的内存来包含请求的数据量, 也会抛出 MemoryError.

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

## 读取二进制数据

使用 `RAW` 选项时, 返回值为缓冲对象, 其中包含文件的原始, 未修改的内容. 对象的 Size 属性返回读取的字节数. NumGet 或 StrGet 用于从缓冲中检索数据. 例如:

    buf := FileRead(A_AhkPath, "RAW")
    if StrGet(buf, 2, "cp0") == "MZ"  ; 看起来像一个可执行文件...
    {
        ; 从 COFF 文件头中读取机器类型.
        machine := NumGet(buf, NumGet(buf, 0x3C, "uint") + 4, "ushort")
        machine := machine=0x8664 ? "x64" : machine=0x014C ? "x86" : "unknown"
        ; 显示机器类型和文件大小.
        MsgBox "This " machine " executable is " buf.Size " bytes."
    }
    buf := ""

读取二进制数据通常需要这个选项, 因为默认情况下, 从文件中读取的任何字节都被解释为文本, 并且可以从源文件的编码(如选项中指定的或通过 A_FileEncoding) 转换为脚本的原生编码, UTF-16. 如果数据不是 UTF-16 文本, 这种转换通常会以不希望的方式更改数据.

有关 RAW 选项的另一个演示, 请参阅保存和恢复剪贴板.

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

## 备注

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

如果担心使用太多的内存, 可以预先用 FileGetSize 来检查文件的大小.

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

## 相关

FileEncoding, FileOpen/File Object, file-reading loop, FileGetSize, FileAppend, IniRead, Sort, Download

## 示例

读取文本文件到 MyText.

    MyText := FileRead("C:\My Documents\My File.txt")

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

    Contents := FileRead("C:\Address List.txt")
    if not ErrorLevel  ; 加载成功.
    {
        Contents := Sort(Contents)
        FileDelete "C:\Address List (alphabetical).txt"
        FileAppend Contents, "C:\Address List (alphabetical).txt"
        Contents := "" ; 是否内存.
    }

dftg