File Object

Provides an interface for file input/output. FileOpen returns an object of this type.

Object Members

Properties:

Methods:

Read

Reads a string of characters from the file and advances the file pointer.

String := File.Read(Characters)
Characters

Type: Integer

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

Type: String

A string to write.

Returns the number of bytes (not characters) that were written.

ReadLine

Reads a line of text from the file and advances the file pointer.

TextLine := 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

Type: String

An optional string to write.

Returns the number of bytes (not characters) that were written.

ReadNumType

Reads a number from the file and advances the file pointer.

Num := File.ReadNumType()

NumType is either UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with DllCall.

Returns a number if the read was successful, otherwise an empty string. If the number of bytes read is non-zero but less than the size of NumType, the missing bytes are assumed to be zero.

WriteNumType

Writes a number to the file and advances the file pointer.

File.WriteNumType(Num)
Num

Type: Integer or Float

A number to write.

NumType is either UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with DllCall.

Returns the number of bytes that were written. For instance, WriteUInt returns 4 if successful.

RawRead

Reads raw binary data from the file into memory and advances the file pointer.

File.RawRead(Buffer , Bytes)
Buffer

Type: Object or Integer

The Buffer-like object or memory address which will receive the data.

Reading into a Buffer created by BufferAlloc is recommended. If Bytes is omitted, it defaults to the size of the buffer. An exception is thrown if Bytes exceeds the size of the buffer.

If a memory address is passed, Bytes must also be specified.

Bytes

Type: Integer

The maximum number of bytes to read. This is optional when Buffer is an object; otherwise, it is required.

Returns the number of bytes that were read.

RawWrite

Writes raw binary data to the file and advances the file pointer.

File.RawWrite(Data , Bytes)
Data

Type: Object, String or Integer

A Buffer-like object or string containing binary data, or a memory address. If an object or string is specified, Bytes is optional and defaults to the size of the buffer or string. Otherwise, Bytes must also be specified.

Bytes

Type: Integer

The number of bytes to write. This is optional when Data is an object or string; otherwise, it is required.

Returns the number of bytes that were written.

Seek

Moves the file pointer.

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

Type: Integer

Distance to move, in bytes. Lower values are closer to the beginning of the file.

Origin

Type: Integer

Starting point for the file pointer move. Must be one of the following:

  • 0 (SEEK_SET): Beginning of the file. Distance must be zero or greater.
  • 1 (SEEK_CUR): Current position of the file pointer.
  • 2 (SEEK_END): End of the file. Distance should usually be negative.

If omitted, Origin defaults to SEEK_END when Distance is negative and SEEK_SET otherwise.

Returns a non-zero value if successful, otherwise zero.

Pos

Retrieves or sets the current position of the file pointer.

Pos := File.Pos
File.Pos := NewPos

Equivalent to File.Seek(NewPos).

The position is a byte offset from the beginning of the file, where 0 is the first byte. When data is written to or read from the file, the file pointer automatically moves to the next byte after that data.

Length

Retrieves or sets the size of the file.

FileSize := File.Length
File.Length := NewSize

FileSize and NewSize is 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

Retrieves a non-zero value if the file pointer has reached the end of the file, otherwise zero.

IsAtEOF := File.AtEOF

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.

File.Close()

 Although the file is closed automatically when the object is freed, it is recommended to close the file as soon as possible.

Encoding

Retrieves or sets the text encoding used by this file object.

RetrievedEncoding := File.Encoding
File.Encoding := NewEncoding

RetrievedEncoding and NewEncoding is a numeric code page identifier (see MSDN) or one of the following strings:

RetrievedEncoding is never a value with the -RAW suffix, regardless of how the file was opened or whether it contains a byte order mark (BOM). Setting NewEncoding never causes a BOM to be added or removed, as the BOM is normally written to the file when it is first created.

Setting NewEncoding to UTF-8-RAW or UTF-16-RAW is valid, but the -RAW suffix is ignored. This only applies to File.Encoding, not FileOpen.

Handle

Returns a system file handle, intended for use with DllCall. See CreateFile.

File.Handle

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.