# 文件对象 [AHK_L 42+]

提供文件输入/输出的接口. FileOpen() 返回文件类型的对象.

## 对象成员

属性:

- Position / Pos: 获取或设置文件指针的位置. 等同于 `Pos := File.Tell()` 或 `File.Seek(Distance)`.
- Length: 获取或设置文件的大小.
- AtEOF: 获取一个非零值当文件指针到达文件的末尾时.
- Encoding: 获取或设置此文件对象使用的编码.
- __Handle: 获取用于 DllCall() 的系统文件句柄.

方法:

译者注: 关于方向的问题, 文件的开头为前, 文件的结束为后, 向后移动文件指针表示往文件的结束方向移动(针对文件), 以前翻译为向前移动文件指针, 针对的是文件指针.

- Read: 从文件中读取字符串, 并向后移动文件指针.
- Write: 写入字符串到文件, 并向后移动文件指针.
- ReadLine: 从文件中读取一行文本, 并向后移动文件指针.
- WriteLine: 根据打开文件时使用的标志(flags), 写入后面跟着 ``n` 或 ``r`n` 的字符串. 向后移动文件指针.
- ReadNumType: 从文件中读取指定类型的数据, 并向后移动文件指针.
- WriteNumType: 写入指定类型的数据到文件, 并向后移动文件指针.
- RawRead: 从文件读取原始的二进制数据到内存, 并向后移动文件指针.
- RawWrite: 写入原始的二进制数据到文件, 并向后移动文件指针.
- Seek: 移动文件指针. 如果第二个参数被省略, 等同于 `File.Pos := Distance`.
- Tell: 返回文件指针的当前位置. 等同于 `Pos := File.Pos`.
- Close: 关闭文件, 将缓存中的所有数据写入磁盘并释放共享锁定.

## Read

从文件读取字符串, 并使文件指针向后移动.

    String := File.Read(Characters)

Characters
  需读取的最大字符数. 如果省略, 则读取文件的剩余部分并作为单个字符串返回. 如果 File 对象创建于非搜寻设备(例如控制台缓冲区或管道) 的句柄, 省略此参数可能引起执行方法失败或仅返回当前可用的数据.

返回 字符串.

## Write

写入字符串到文件, 并使文件指针向后移动.

    File.Write(String)

String
  要写入的字符串.

返回 写入的字节数(不是字符数).

## ReadLine

从文件中读取一行文本, 并使文件指针向后移动.

    TextLine := File.ReadLine()

返回 一行文本. 其中可能包括 ``n`, ``r`n` 或 ``r` 取决于文件和打开文件时使用的 EOL 标志.

可以读取长达 65,534 个字符的行. 如果一个行的长度超过这个长度, 则该行的其余部分将通过对此方法的后续调用返回.

## WriteLine

根据打开文件时使用的标志(flags), 写入后面跟着 ``n` 或 ``r`n` 的字符串. 向后移动文件指针.

    File.WriteLine(String)

String
  可选的字符串.

返回 写入的字节数(不是字符数).

## ReadNumType

从文件中读取指定类型的数据, 并使文件指针向后移动.

    Num := File.ReadNumType()

NumType 可以是 UInt, Int, Int64, Short, UShort, Char, UChar, Double 或 Float. 这些类型名称与 DllCall() 具有相同的含义.

返回 数字, 如果失败则返回空字符串.

如果使用 Try 语句且没有读取任何字节时将抛出异常. 但是, 如果读取到任何字节则不会抛出异常, 即使 NumType 的设定值大于读取的字节数. 不足位用 0 填充.

## WriteNumType

写入指定类型的数据到文件, 并使文件指针向后移动.

    File.WriteNumType(Num)

Num
  写入的数字.

NumType 可以是 UInt, Int, Int64, Short, UShort, Char, UChar, Double 或 Float. 这些类型名称与 DllCall() 具有相同的含义.

返回 写入的字节数. 例如, 写入成功时 WriteUInt 返回 4.

## RawRead

从文件读取原始的二进制数据到内存, 并使文件指针向后移动.

    File.RawRead(VarOrAddress, Bytes)

VarOrAddress
  用来保存复制出来的数据的变量或内存地址. 用法类似于 NumGet.
Bytes
  需读取的最大字节数.

返回 读取的字节数.

如果使用 Try 语句, 且 Bytes 不为零, 但是没有读取到字节, 则抛出异常. 如果有需要, 可使用 AtEOF 来避免这种情况.

## RawWrite

写入原始的二进制数据到文件, 并使文件指针向后移动.

    File.RawWrite(VarOrAddress, Bytes)

VarOrAddress
  包含数据的变量或内存中的数据地址. 用法类似于 NumPut(). 如果指定了变量, 则必要时会自动扩展.
Bytes
  需写入的字节数.

返回 写入的字节数.

## Seek

移动文件指针.

    File.Seek(Distance , Origin := 0)
    File.Position := Distance
    File.Pos := Distance

Distance
  需移动的距离, 单位为字节. 较小的值更接近文件的开始处.
Origin

  文件指针开始移动的起点. 必须为下列值的其中一个:

  - 0(SEEK_SET): 文件的开始处. Distance 必须为零或更大.
  - 1(SEEK_CUR): 文件指针的当前位置.
  - 2(SEEK_END): 文件的末尾. Distance 通常应该为负数.

  如果省略, 当 Distance 为负数时 Origin 为 SEEK_END, 而其他情况时为 SEEK_SET.

返回 非零值在成功时, 否则为零.

## Tell

返回文件指针的当前位置, 其中 0 是文件的开始.

    Pos := File.Tell()
    Pos := File.Position
    Pos := File.Pos

## Length

获取或设置文件的大小.

    FileSize := File.Length

    File.Length := NewSize

FileSize 和 NewSize 是文件的大小, 单位为字节.

此属性应该仅用于真实的文件. 如果 File 对象创建于管道的句柄, 那么它可能返回管道内部缓冲区中当前可能数据的数目, 但不能保证一定如此.

## AtEOF

当文件指针到达文件末尾时, 返回非零值, 否则为零.

    IsAtEOF := File.AtEOF

此属性应该仅用于真实的文件. 如果 File 对象创建于非搜寻设备(例如控制台缓冲区或管道) 的句柄, 那么返回的值可能没有意义, 因为这些设备逻辑上没有 "文件末尾".

## Close

关闭文件, 把缓冲区的数据写入磁盘并释放共享锁定.

    File.Close()

尽管当对象释放时文件会自动关闭, 不过建议尽快关闭文件.

## Encoding

获取或设置此文件对象使用的编码.

    RetrievedEncoding := File.Encoding

    File.Encoding := NewEncoding

RetrievedEncoding 和 NewEncoding 是一个代表代码页标识符的数字(请参阅 MSDN) 或以下字符串之一:

- `UTF-8`: Unicode UTF-8, 相当于 CP65001.
- 带小端字节顺序标识的 Unicode UTF-16 等效于 CP1200.
- `CPnnn`: 带数字的标识符 nnn 的代码页.

RetrievedEncoding 不会返回带 `-RAW` 后缀的值, 不论文件如何被打开或是否包含字节顺序标识(BOM). 设置 NewEncoding 不会增加或移除 BOM, 因为 BOM 通常在文件建立时就被写入其中.

[v1.1.15.04+]: 设置 NewEncoding 为 `UTF-8-RAW` 或 `UTF-16-RAW` 合法, 但 `-RAW` 后缀将被忽略. 而之前的版本中, `UTF-8-RAW` 及 `UTF-16-RAW` 如同非法的 8 位编码, 导致所有非 ASCII 字符被丢弃, 不过这只会影响 `File.Encoding`, 而不会影响 FileOpen().

## __Handle

返回用于 DllCall() 的系统文件句柄. 请参阅 CreateFile.

    File.__Handle

文件对象使用内部缓冲区读取或写入. 如果数据已经被写入对象的内部缓冲区, 则在返回句柄前会确保把数据写入磁盘. 如果缓冲区中包含从文件读取的数据, 则会把数据丢弃且文件指针的实际位置被重设为由 `File.Pos` 表示的逻辑位置.

dftg