File Object
Provides an interface for file input/output. FileOpen returns an object of this type.
Read
Reads a string of characters from the file and advances the file pointer.
String := File.Read(Characters)
| Characters | The maximum number of characters to read. If omitted, the rest of the file is read and returned as one string. If the File object was created from a handle to a non-seeking device such as a console buffer or pipe, omitting this parameter may cause the method to fail or return only what data is currently available. |
| Returns | A string. |
Write
Writes a string of characters to the file and advances the file pointer.
File.Write(String)
| String | A string. |
| Returns | The number of bytes (not characters) that were written. |
ReadLine
Reads a line of text from the file and advances the file pointer.
Line := File.ReadLine()
| Returns | A line of text, excluding the line ending. |
Lines up to 65,534 characters long can be read. If the length of a line exceeds this, the remainder of the line is returned by subsequent calls to this method.
WriteLine
Writes a string of characters followed by `n or `r`n depending on the flags used to open the file. Advances the file pointer.
File.WriteLine(String)
| String | An optional string. |
| Returns | The number of bytes (not characters) that were written. |
ReadNum
Reads a number from the file and advances the file pointer.
Num := File.ReadNumType()
| NumType | One of the following specified directly as part of the function name: UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with DllCall. |
| Returns | A number if successful, otherwise an empty string. |
If a Try statement is active and no bytes were read, an exception is thrown. However, no exception is thrown if at least one byte was read, even if the size of the given NumType is greater than the number of bytes read. Instead, the missing bytes are assumed to be zero.
WriteNum
Writes a number to the file and advances the file pointer.
File.WriteNumType(Num)
| NumType | One of the following specified directly as part of the function name: UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with DllCall. |
| Num | A number. |
| Returns | The number of bytes that were written. For instance, WriteUInt returns 4 if successful. |
RawRead
Read raw binary data from the file into memory.
File.RawRead(Buffer, Bytes)
| Buffer | The variable or memory address which will receive the data. |
| Bytes | The maximum number of bytes to read. |
| Returns | The number of bytes that were read. |
To read to a memory address, pass a pure integer such as &variable + offset or a variable containing a pure integer.
To read into a variable, pass a variable which is empty or contains a string. If Bytes is omitted, it defaults to the capacity of the variable. If Bytes is greater than the capacity of the variable, the variable is expanded. After the data is read, the variable's length is set to the string length of the data (rounded up to a whole number).
RawWrite
Write raw binary data to the file.
File.RawWrite(Data, Bytes)
| Data | A memory address or string containing binary data. |
| Bytes | The number of bytes to write. |
| Returns | The number of bytes that were written. |
To write data from a given memory address, pass a pure integer such as &variable + offset or a variable containing a pure integer.
To write data from a string containing binary data, pass a string or a variable containing a string. If Bytes is omitted, it defaults to the string length times 2 (so is always an even number).
For an example, see Saving and Restoring the Clipboard.
Seek
Moves the file pointer.
File.Seek(Distance , Origin := 0) File.Position := Distance File.Pos := Distance
| Distance | Distance to move, in bytes. Lower values are closer to the beginning of the file. |
| Origin | Starting point for the file pointer move. Must be one of the following:
|
| Returns | A non-zero value if successful, otherwise zero. |
Tell
Pos := File.Tell()
Pos := File.Position
| Returns | The current position of the file pointer, where 0 is the beginning of the file. |
Length
Retrieves or sets the size of the file.
FileSize := File.Length File.Length := NewSize
| NewSize | The new size of the file, in bytes. |
| Returns | The size of the file, in bytes. |
This property should be used only with an actual file. If the File object was created from a handle to a pipe, it may return the amount of data currently available in the pipe's internal buffer, but this behaviour is not guaranteed.
AtEOF
IsAtEOF := File.AtEOF
| Returns | A non-zero value if the file pointer has reached the end of the file, otherwise zero. |
This property should be used only with an actual file. If the File object was created from a handle to a non-seeking device such as a console buffer or pipe, the returned value may not be meaningful, as such devices do not logically have an "end of file".
Close
Closes the file, flushes any data in the cache to disk and releases the share locks. Although the file is closed automatically when the object is freed, it is recommended to close the file as soon as possible.
File.Close()
No parameters or return value.
Encoding
Retrieves or sets the text encoding used by this file object.
Encoding := File.Encoding File.Encoding := Encoding
| Encoding | A numeric code page identifier (see MSDN) or one of the following strings:
Encoding never returns a value with the Setting Encoding to |
__Handle
File.__Handle
| Returns | A system file handle, intended for use with DllCall. See CreateFile. |
File objects internally buffer reads or writes. If data has been written into the object's internal buffer, it is committed to disk before the handle is returned. If the buffer contains data read from file, it is discarded and the actual file pointer is reset to the logical position indicated by File.Pos.