# Function Reference

# FileReadLine

Read in a line of text from a previously opened text file.

FileReadLine ( "filehandle/filename" [, line = 1] )

## Parameters

filehandle/filename | The handle of a file, as returned by a previous call to FileOpen(). Alternatively you may use a string filename as the first parameter.
line | [optional] The line number to read. The first line of a text file is line 1 (not zero); the last line is -1.

## Return Value

Success: | a line of text.
Failure: | sets the @error flag to non-zero.
@error: | 1 = if file not opened in read mode or other error -1 = if end-of-file is reached

## Remarks

Returns the text of the line read, any newline characters (@CR or @LF) at the end of the line are automatically stripped.
If a filehandle is passed to the function and no line number is specified, the "next" line will be read - for a newly opened file this will be the first line. If lines are read in a loop, it is recommended to let the count increase automatically and not to use the "line" parameter, as doing so will force AutoIt to re-read the file from the beginning each time, significantly slowing execution time for large files.
If a filename is passed to the function, the file will be opened and closed during the call which slows execution considerably, particularly when reading multiple lines. Furthermore, because the file is closed after each call, there is no automatic "next" line increase and the "line" parameter must be used when reading lines in a loop. Note that this will further slow execution as AutoIt re-reads the file each time.
Do not mix filehandles and filenames, i.e. do not FileOpen() a file and then use a filename in this function. Use either filehandles (recommended) or filenames in your routines, not both!
Both ANSI and UTF16/UTF8 text formats can be read - See FileOpen() for details.

## Related

FileGetPos, FileOpen, FileRead, FileSetPos, FileWrite, FileWriteLine, IniRead

## Example

    #include <FileConstants.au3>
    #include <MsgBoxConstants.au3>
    #include <WinAPIFiles.au3>

    Example()

    Func Example()
        ; Create a constant variable in Local scope of the filepath that will be read/written to.
        Local Const $sFilePath = _WinAPI_GetTempFileName(@TempDir)

        ; Create a temporary file to read data from.
        If Not FileWrite($sFilePath, "This is an example of using FileReadLine.") Then
            MsgBox($MB_SYSTEMMODAL, "", "An error occurred whilst writing the temporary file.")
            Return False
        EndIf

        ; Open the file for reading and store the handle to a variable.
        Local $hFileOpen = FileOpen($sFilePath, $FO_READ)
        If $hFileOpen = -1 Then
            MsgBox($MB_SYSTEMMODAL, "", "An error occurred when reading the file.")
            Return False
        EndIf

        ; Read the fist line of the file using the handle returned by FileOpen.
        Local $sFileRead = FileReadLine($hFileOpen, 1)

        ; Close the handle returned by FileOpen.
        FileClose($hFileOpen)

        ; Display the first line of the file.
        MsgBox($MB_SYSTEMMODAL, "", "First line of the file:" & @CRLF & $sFileRead)

        ; Delete the temporary file.
        FileDelete($sFilePath)
    EndFunc   ;==>Example