# 文件对象

    class File extends Object

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

下面使用 "FileObj" 作为任何文件对象的占位符, 因为 "File" 就是类本身.

除了从 Object 继承的方法和属性外, File 对象还具有以下预定义的方法和属性.

## 目录

- 方法:
  - Read: 从文件中读取字符串, 并向后移动文件指针.
  - Write: 写入字符串到文件, 并向后移动文件指针.
  - ReadLine: 从文件中读取一行文本, 并向后移动文件指针.
  - WriteLine: 根据打开文件时使用的标志(flags), 写入后面跟着 ``n` 或 ``r`n` 的字符串. 向后移动文件指针.
  - ReadNumType: 从文件中读取指定类型的数据, 并向后移动文件指针.
  - WriteNumType: 写入指定类型的数据到文件, 并向后移动文件指针.
  - RawRead: 从文件读取原始的二进制数据到内存, 并向后移动文件指针.
  - RawWrite: 写入原始的二进制数据到文件, 并向后移动文件指针.
  - Seek: 移动文件指针. 如果第二个参数被省略, 等同于 `FileObj.Pos := Distance`.
  - Close: 关闭文件, 将缓存中的所有数据写入磁盘并释放共享锁定.
- 属性:
  - Pos: 获取或设置文件指针的位置.
  - Length: 获取或设置文件的大小.
  - AtEOF: 获取一个非零值当文件指针到达文件的末尾时.
  - Encoding: 获取或设置此文件对象使用的编码.
  - __Handle: 获取用于 DllCall() 的系统文件句柄.

## 方法

### Read

从文件读取字符串并向前移动文件指针.

    String := FileObj.Read(Characters)

Characters

  类型: 整数

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

返回 字符串.

### Write

写入字符串到文件并向前移动文件指针.

    FileObj.Write(String)

String

  类型: 字符串

  要写入的字符串.

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

### ReadLine

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

    TextLine := FileObj.ReadLine()

返回 一行文本, 不包括行结束符.

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

### WriteLine

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

    File.WriteLine(String)

String

  类型: 字符串

  可选的字符串.

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

### ReadNumType

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

    Num := FileObj.ReadNumType()

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

返回 一个数字, 如果读取成功, 否则为空字符串. 如果读出的字节数为非零, 但小于 NumType 的大小, 那么缺失的字节数被假定为零.

### WriteNumType

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

    FileObj.WriteNumType(Num)

Num

  类型: 整数或浮点数

  写入的数字.

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

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

### RawRead

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

    FileObj.RawRead(Buffer , Bytes)

Buffer

  类型: 对象或整数

  将接收数据的类缓冲对象或内存地址.

  建议读入缓冲. 如果省略 Bytes, 它默认为缓冲的大小. 如果 Bytes 超过缓冲的大小, 则抛出异常.

  如果传递一个内存地址, 则 Bytes 也必须指定.

Bytes

  类型: 整数

  要读取的最大字节数. 这是可选的, 当 Buffer 是一个对象或字符串变量(不推荐); 否则, 它是必需的.

返回 读取的字节数.

### RawWrite

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

    FileObj.RawWrite(Data , Bytes)

Data

  类型: 对象, 字符串或整数

  类缓冲对象或包含二进制数据的字符串, 或内存地址. 如果指定了一个对象或字符串, Bytes 是可选的, 默认为缓冲或字符串的大小. 否则, 必须指定 Bytes.

Bytes

  类型: 整数

  要写入的字节数. 当 Data 是一个对象或字符串时, 这是可选的; 否则, 它是必需的.

返回 写入的字节数.

### Seek

移动文件指针.

    FileObj.Seek(Distance , Origin)

Distance

  类型: 整数

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

Origin

  类型: 整数

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

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

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

返回 非零值, 如果成功, 否则为 0.

### Close

关闭文件, 将缓存中的任何数据写入磁盘, 并释放共享锁.

    FileObj.Close()

虽然在释放对象时文件会自动关闭, 但建议尽快关闭文件.

## 属性

### Pos

检索或设置文件指针的当前位置.

    Pos := FileObj.Pos

    FileObj.Pos := NewPos

等同于 `FileObj.Seek(NewPos)`.

位置是从文件开始的字节偏移, 其中 0 是第一个字节. 当数据被写入或从文件中读取时, 文件指针会自动移动到该数据之后的下一个字节.

### Length

获取或设置文件的大小.

    FileSize := FileObj.Length

    FileObj.Length := NewSize

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

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

### AtEOF

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

    IsAtEOF := FileObj.AtEOF

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

### Encoding

检索或设置此文件对象使用的文本编码.

    RetrievedEncoding := FileObj.Encoding

    FileObj.Encoding := NewEncoding

NewEncoding 可以是一个数字代码页标识符(请参阅 Microsoft Docs) 或以下字符串之一.

RetrievedEncoding 为以下字符串之一:

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

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

设置 NewEncoding 为 `UTF-8-RAW` 或 `UTF-16-RAW` 合法, 但 `-RAW` 后缀将被忽略. 这仅适用于 `FileObj.Encoding`, 而不会影响 FileOpen.

### Handle

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

    FileObj.Handle

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

dftg