FileRead

Retrieves the contents of a file.

Text := FileRead(Filename , Options)

Parameters

Filename

Type: String

The name of the file to read, which is assumed to be in A_WorkingDir if an absolute path isn't specified.

Options

Type: String

Zero or more of the following strings. Separate each option from the next with a single space or tab. For example: "`n m5000 UTF-8"

Encoding: Specify any of the encoding names accepted by FileEncoding (excluding the empty string) to use that encoding if the file lacks a UTF-8 or UTF-16 byte order mark. If omitted, it defaults to A_FileEncoding.

RAW: Specify the word RAW (case-insensitive) to read the file's content as raw binary data and return a Buffer object instead of a string. This option overrides any previously specified encoding and vice versa.

m1024: If this option is omitted, the entire file is loaded unless there is insufficient memory, in which case an error message is shown and the thread exits (but Try can be used to avoid this). Otherwise, replace 1024 with a decimal or hexadecimal number of bytes. If the file is larger than this, only its leading part is loaded.

Note: This might result in the last line ending in a naked carriage return (`r) rather than `r`n.

`n (a linefeed character): Replaces any/all occurrences of carriage return & linefeed (`r`n) with linefeed (`n). However, this translation reduces performance and is usually not necessary. For example, text containing `r`n is already in the right format to be added to a Gui Edit control. The following parsing loop will work correctly regardless of whether each line ends in `r`n or just `n: Loop Parse, MyFileContents, "`n", "`r".

Return Value

Type: String or Buffer

This function returns the contents of the specified file. The return value is a Buffer object if the RAW option is in effect and the file can be opened; otherwise, it is a string. If the file does not exist or cannot be opened for any other reason, an empty string is returned.

Error Handling

An exception is thrown on failure, such as if: 1) file does not exist; 2) file is locked or inaccessible; 3) the system lacks sufficient memory to load the file.

A_LastError is set to the result of the operating system's GetLastError() function.

Reading Binary Data

When the RAW option is used, the return value is a Buffer object containing the raw, unmodified contents of the file. The object's Size property returns the number of bytes read. NumGet or StrGet can be used to retrieve data from the buffer. For example:

buf := FileRead(A_AhkPath, "RAW")
if StrGet(buf, 2, "cp0") == "MZ"  ; Looks like an executable file...
{
    ; Read machine type from COFF file header.
    machine := NumGet(buf, NumGet(buf, 0x3C, "uint") + 4, "ushort")
    machine := machine=0x8664 ? "x64" : machine=0x014C ? "x86" : "unknown"
    ; Display machine type and file size.
    MsgBox "This " machine " executable is " buf.Size " bytes."
}
buf := ""

This option is generally required for reading binary data because by default, any bytes read from file are interpreted as text and may be converted from the source file's encoding (as specified in the options or by A_FileEncoding) to the script's native encoding, UTF-16. If the data is not UTF-16 text, this conversion generally changes the data in undesired ways.

For another demonstration of the RAW option, see ClipboardAll example #2.

Finally, FileOpen and File.RawRead or File.ReadNum may be used to read binary data without first reading the entire file into memory.

Remarks

When the goal is to load all or a large part of a file into memory, FileRead performs much better than using a file-reading loop.

A file greater than 4 GB in size will cause an exception to be thrown unless the *m option is present, in which case the leading part of the file is loaded. An exception will also be thrown if the program is unable to allocate enough memory to contain the requested amount of data.

If there is concern about using too much memory, check the file size beforehand with FileGetSize.

FileOpen provides more advanced functionality than FileRead, such as reading or writing data at a specific location in the file without reading the entire file into memory. See File Object for a list of functions.

Related

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

Examples

#1: Read a text file into MyText.

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

#2: Quickly sort the contents of a file.

Contents := FileRead("C:\Address List.txt")
Contents := Sort(Contents)
FileDelete "C:\Address List (alphabetical).txt"
FileAppend Contents, "C:\Address List (alphabetical).txt"
Contents := "" ; Free the memory.