Ξ
Δ
◄
►
¬
Ѕ
Filter
Directives
Built-in Variables
Built-in Functions
Control Flow Statements
Operators
Declarations
Commands
Sub-commands
Built-in Methods/Properties
Ahk2Exe Compiler
Highlight keywords
</head> <body> <h1>File Object <span class="ver">[AHK_L 42+]</span></h1> <p>Provides an interface for file input/output. <a href="../commands/FileOpen.htm">FileOpen()</a> returns an object of this type.</p> <h2 id="toc">Table of Contents</h2> <ul class="indent"> <li><a href="#Methods">Methods</a>: <ul> <li><a href="#Read">Read</a>: Reads a string of characters from the file and advances the file pointer.</li> <li><a href="#Write">Write</a>: Writes a string of characters to the file and advances the file pointer.</li> <li><a href="#ReadLine">ReadLine</a>: Reads a line of text from the file and advances the file pointer.</li> <li><a href="#WriteLine">WriteLine</a>: Writes a string of characters followed by <code>`n</code> or <code>`r`n</code> depending on the flags used to open the file. Advances the file pointer.</li> <li><a href="#ReadNum">Read<em>NumType</em></a>: Reads a number from the file and advances the file pointer.</li> <li><a href="#WriteNum">Write<em>NumType</em></a>: Writes a number to the file and advances the file pointer.</li> <li><a href="#RawRead">RawRead</a>: Reads raw binary data from the file into memory and advances the file pointer.</li> <li><a href="#RawWrite">RawWrite</a>: Writes raw binary data to the file and advances the file pointer.</li> <li><a href="#Seek">Seek</a>: Moves the file pointer. If the second parameter is omitted, it is equivalent to <code>File.Pos := Distance</code>.</li> <li><a href="#Tell">Tell</a>: Returns the position of the file pointer. Equivalent to <code>Pos := File.Pos</code>.</li> <li><a href="#Close">Close</a>: Closes the file, flushes any data in the cache to disk and releases the share locks.</li> </ul> </li> <li><a href="#Properties">Properties</a>: <ul> <li><a href="#Seek">Position / Pos</a>: Retrieves or sets the position of the file pointer. Equivalent to <code>Pos := File.Tell()</code> or <code>File.Seek(Distance)</code>.</li> <li><a href="#Length">Length</a>: Retrieves or sets the size of the file.</li> <li><a href="#AtEOF">AtEOF</a>: Retrieves a non-zero value if the file pointer has reached the end of the file.</li> <li><a href="#Encoding">Encoding</a>: Retrieves or sets the text encoding used by this file object.</li> <li><a href="#Handle">Handle</a>: Alias of <a href="#__Handle">__Handle</a>.</li> <li><a href="#__Handle">__Handle</a>: Retrieves a system file handle, intended for use with DllCall().</li> </ul> </li> </ul> <h2 id="Methods">Methods</h2> <div class="methodShort" id="Read"><h3>Read</h3> <p>Reads a string of characters from the file and advances the file pointer.</p> <pre class="Syntax">String := File.<span class="func">Read</span>(<span class="optional">Characters</span>)</pre> <dl> <dt>Characters</dt> <dd>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.</dd> </dl> <p>Returns a string.</p> </div> <div class="methodShort" id="Write"><h3>Write</h3> <p>Writes a string of characters to the file and advances the file pointer.</p> <pre class="Syntax">File.<span class="func">Write</span>(String)</pre> <dl> <dt>String</dt> <dd>A string to write.</dd> </dl> <p>Returns the number of bytes (not characters) that were written.</p> </div> <div class="methodShort" id="ReadLine"><h3>ReadLine</h3> <p>Reads a line of text from the file and advances the file pointer.</p> <pre class="Syntax">TextLine := File.<span class="func">ReadLine</span>()</pre> <p>Returns a line of text. This may include <code>`n</code>, <code>`r`n</code> or <code>`r</code> depending on the file and EOL flags used to open the file.</p> <p>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.</p></div> <div class="methodShort" id="WriteLine"><h3>WriteLine</h3> <p>Writes a string of characters followed by <code>`n</code> or <code>`r`n</code> depending on the flags used to open the file. Advances the file pointer.</p> <pre class="Syntax">File.<span class="func">WriteLine</span>(<span class="optional">String</span>)</pre> <dl> <dt>String</dt> <dd>An optional string to write.</dd> </dl> <p>Returns the number of bytes (not characters) that were written.</p> </div> <div class="methodShort" id="ReadNum"><h3>Read<i>NumType</i></h3> <p>Reads a number from the file and advances the file pointer.</p> <pre class="Syntax">Num := File.Read<i>NumType</i>()</pre> <p><em>NumType</em> is either UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with <a href="../commands/DllCall.htm#types">DllCall()</a>.</p> <p>Returns a number if successful, otherwise an empty string.</p> <p>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 <i>NumType</i> is greater than the number of bytes read. Instead, the missing bytes are assumed to be zero.</p></div> <div class="methodShort" id="WriteNum"><h3>Write<i>NumType</i></h3> <p>Writes a number to the file and advances the file pointer.</p> <pre class="Syntax">File.Write<i>NumType</i>(Num)</pre> <dl> <dt>Num</dt> <dd>A number to write.</dd> </dl> <p><em>NumType</em> is either UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with <a href="../commands/DllCall.htm#types">DllCall()</a>.</p> <p>Returns the number of bytes that were written. For instance, WriteUInt returns 4 if successful.</p> </div> <div class="methodShort" id="RawRead"><h3>RawRead</h3> <p>Reads raw binary data from the file into memory and advances the file pointer.</p> <pre class="Syntax">File.<span class="func">RawRead</span>(VarOrAddress, Bytes)</pre> <dl> <dt>VarOrAddress</dt> <dd>A variable or memory address to which the data will be copied. Usage is similar to <a href="../commands/NumGet.htm">NumGet()</a>. If a variable is specified, it is expanded automatically when necessary.</dd> <dt>Bytes</dt> <dd>The maximum number of bytes to read.</dd> </dl> <p>Returns the number of bytes that were read.</p> <p>If a Try statement is active and <em>Bytes</em> is non-zero but no bytes were read, an exception is thrown. <a href="#AtEOF">AtEOF</a> can be used to avoid this, if needed.</p></div> <div class="methodShort" id="RawWrite"><h3>RawWrite</h3> <p>Writes raw binary data to the file and advances the file pointer.</p> <pre class="Syntax">File.<span class="func">RawWrite</span>(VarOrAddress, Bytes)</pre> <dl> <dt>VarOrAddress</dt> <dd>A variable containing the data or the address of the data in memory. Usage is similar to <a href="../commands/NumPut.htm">NumPut()</a>.</dd> <dt>Bytes</dt> <dd>The number of bytes to write.</dd> </dl> <p>Returns the number of bytes that were written.</p> </div> <div class="methodShort" id="Seek"><h3>Seek</h3> <p>Moves the file pointer.</p> <pre class="Syntax"> File.<span class="func">Seek</span>(Distance <span class="optional">, Origin := 0</span>) File.Position := Distance File.Pos := Distance </pre> <dl> <dt>Distance</dt> <dd>Distance to move, in bytes. Lower values are closer to the beginning of the file.</dd> <dt>Origin</dt> <dd><p>Starting point for the file pointer move. Must be one of the following:</p> <ul> <li>0 (SEEK_SET): Beginning of the file. <i>Distance</i> must be zero or greater.</li> <li>1 (SEEK_CUR): Current position of the file pointer.</li> <li>2 (SEEK_END): End of the file. <i>Distance</i> should usually be negative.</li> </ul> <p>If omitted, <i>Origin</i> defaults to SEEK_END when <em>Distance</em> is negative and SEEK_SET otherwise.</p></dd> </dl> <p>Returns a non-zero value if successful, otherwise zero.</p> </div> <div class="methodShort" id="Tell"><h3>Tell</h3> <p>Returns the current position of the file pointer, where 0 is the beginning of the file.</p> <pre class="Syntax"> Pos := File.<span class="func">Tell</span>() Pos := File.Position Pos := File.Pos </pre> </div> <div class="methodShort" id="Close"><h3>Close</h3> <p>Closes the file, flushes any data in the cache to disk and releases the share locks.</p> <pre class="Syntax">File.<span class="func">Close</span>()</pre> <p>Although the file is closed automatically when the object is freed, it is recommended to close the file as soon as possible.</p></div> <h2 id="Properties">Properties</h2> <div class="methodShort" id="Length"><h3>Length</h3> <p>Retrieves or sets the size of the file.</p> <pre class="Syntax">FileSize := File.Length</pre> <pre class="Syntax">File.Length := NewSize</pre> <p><em>FileSize</em> and <em>NewSize</em> is the size of the file, in bytes.</p> <p>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.</p></div> <div class="methodShort" id="AtEOF"><h3>AtEOF</h3> <p>Retrieves a non-zero value if the file pointer has reached the end of the file, otherwise zero.</p> <pre class="Syntax">IsAtEOF := File.AtEOF</pre> <p>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".</p></div> <div class="methodShort" id="Encoding"><h3>Encoding</h3> <p>Retrieves or sets the text encoding used by this file object.</p> <pre class="Syntax">RetrievedEncoding := File.Encoding</pre> <pre class="Syntax">File.Encoding := NewEncoding</pre> <p><em>RetrievedEncoding</em> and <em>NewEncoding</em> is a numeric code page identifier (see <a href="https://learn.microsoft.com/windows/desktop/Intl/code-page-identifiers">MSDN</a>) or one of the following strings:</p> <ul> <li><code>UTF-8</code>: Unicode UTF-8, equivalent to CP65001.</li> <li><code>UTF-16</code>: Unicode UTF-16 with little endian byte order, equivalent to CP1200.</li> <li><code>CP<i>nnn</i></code>: a code page with numeric identifier <i>nnn</i>.</li> </ul> <p><em>RetrievedEncoding</em> is never a value with the <code>-RAW</code> suffix, regardless of how the file was opened or whether it contains a byte order mark (BOM). Setting <em>NewEncoding</em> never causes a BOM to be added or removed, as the BOM is normally written to the file when it is first created.</p> <p><span class="ver">[v1.1.15.04+]</span>: Setting <em>NewEncoding</em> to <code>UTF-8-RAW</code> or <code>UTF-16-RAW</code> is valid, but the <code>-RAW</code> suffix is ignored. In earlier versions, <code>UTF-8-RAW</code> and <code>UTF-16-RAW</code> behaved like an invalid 8-bit encoding, causing all non-ASCII characters to be discarded. This only applies to <code>File.Encoding</code>, not <a href="../commands/FileOpen.htm">FileOpen()</a>.</p> </div> <div class="methodShort" id="Handle"><h3>Handle <span class="ver">[v1.1.35+]</span></h3> <p>Alias of <a href="#__Handle">__Handle</a>.</p> <pre class="Syntax">File.Handle</pre> </div> <div class="methodShort" id="__Handle"><h3>__Handle</h3> <p>Returns a system file handle, intended for use with DllCall(). See <a href="http://msdn.microsoft.com/en-us/library/aa363858.aspx">CreateFile</a>.</p> <pre class="Syntax">File.__Handle</pre> <p>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 <code>File.Pos</code>.</p></div> </body> </html>