Reads all of a file's text into a variable.
| FileRead, OutputVar, Filename |
Parameters
| OutputVar | The name of the variable in which to store the retrieved text. OutputVar will be made blank if a problem occurs such as the file being "in use" or not existing. It will also be made blank if Filename is an empty file. To distinguish between these two conditions, use ErrorLevel. |
| Filename | The name of the file to read, which is assumed to be in %A_WorkingDir% if an absolute path isn't specified. When loading a ClipboardAll file, precede the path name with *c. |
ErrorLevel
ErrorLevel is set to 0 if the load was successful. It is set to 1 if a problem occurred such as: 1) file does not exist; 2) file is locked or inaccessible; 3) the system lacks sufficient memory to load the file.
Remarks
When the goal is to load an entire file into memory, FileRead performs much better than using a file-reading loop.
By default, the file is loaded exactly as-is. For example, a carriage return and linefeed (`r`n) will exist at the end of each line loaded from a standard Windows text file. To automatically translate each `r`n to `n, include *t in front of the filename, followed by a single space or tab. For example: FileRead, OutputVar, *t C:\My Text File.txt. However, this translation will reduce 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. Similarly, FileAppend detects the presence of `r`n when it opens a new file; it knows to write each `r`n as-is rather than translating it to `r`r`n. Finally, the following parsing loop will work correctly regardless of whether each line ends in `r`n or just `n: Loop, parse, MyFileContents, `n, `r
A file greater than 1 GB in size will cause ErrorLevel to be set to 1 and OutputVar to be made blank.
The file is loaded completely even if it is larger than #MaxMem. If there is concern about using too much memory, check the file size beforehand with FileGetSize.
If the specified file contains any binary zeros (which never occur in proper text files), only the text before the first binary zero will be available in OutputVar.
FileRead can be used to quickly sort the contents of a file as in the following example:
FileRead, Contents, C:\Address List.txt
if ErrorLevel = 0 ; Successfully loaded.
{
Sort, Contents
FileDelete, C:\Address List (alphabetical).txt
FileAppend, %Contents%, C:\Address List (alphabetical).txt
Contents = ; Free the memory.
}
Related
file-reading loop, FileReadLine, FileGetSize, FileAppend, IniRead, Sort
Example
FileRead, OutputVar, C:\My Documents\My File.txt