# Function Reference

# _FileReadToArray

Reads the specified file into a 1D or 2D array

#include <File.au3>
_FileReadToArray ( $sFilePath, ByRef $vReturn [, $iFlags = $FRTA_COUNT [, $sDelimiter = ""]] )

## Parameters

$sFilePath | Path and filename of the file to be read.
$vReturn | Variable to hold returned data - does not need to be an array.
$iFlags | [optional] Add multiple values together as required $FRTA_NOCOUNT (0) - array is 0-based use UBound() to get size $FRTA_COUNT (1) - array count in the first element. (default) $FRTA_INTARRAYS (2) - Create "array of arrays" - see remarks $FRTA_ENTIRESPLIT (4) - Use entire delimiter string as split point (default each character defines a split point)
$sDelimiter | [optional] Used to further split each line of the file - e.g. reading CSV files into a 2D array

## Return Value

Success: | 1 and $vReturn holds an array.
Failure: | 0, @error flag set to non-zero and $vReturn is set to 0.
@error: | 1 - Error opening specified file 2 - Unable to split the file 3 - File lines have different numbers of fields (only if $FRTA_INTARRAYS flag not set) 4 - No delimiters found (only if $FRTA_INTARRAYS flag not set)

## Remarks

If a delimiter is not specified the function returns a 1D array with each element holding a line of the file - line endings can be any mix of @CR, @LF and @CRLF.
When a delimiter is specified the function tries to further split each line of the file - how this is done depends on the setting of the $FRTA_INTARRAYS flag. If the flag is not set and each line has the same number of fields split by the delimiter then a 2D array is created, but if this is not the case then @error is set to 3 and no array is returned. If the $FRTA_INTARRAYS flag is set the function creates a 1D array where each element is a further array holding the fields of the line split on the delimiter - the lines do not need to have the same number of fields. See example below.
If the delimiter is more than a single character then the $FRTA_ENTIRESPLIT flag setting determines the split method.

## Related

_FileWriteFromArray

## Example

### Example 1

    #include <Array.au3>
    #include <File.au3>
    #include <MsgBoxConstants.au3>

    Example()

    Func Example()
        Local $aRetArray, $sFilePath = @TempDir & "\Test.txt"

        ; Create 1D array
        Local $aArray[] = ["0", "1", "2", "3", "4"]
        ; Write it to file
        _FileWriteFromArray($sFilePath, $aArray, Default, Default, @CRLF)
        Sleep(1000)

        ; Re-read it - with count
        _FileReadToArray($sFilePath, $aRetArray)
        _ArrayDisplay($aRetArray, "1D array - count", Default, 8)

        ; Re-read it - without count
        _FileReadToArray($sFilePath, $aRetArray, $FRTA_NOCOUNT)
        _ArrayDisplay($aRetArray, "1D array - no count", Default, 8)

        ; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        ; Create "square" 2D array
        Local $aArray[][] = [ _
                ["00", "01", "02", "03"], _
                ["10", "11", "12", "13"], _
                ["20", "21", "22", "23"], _
                ["30", "31", "32", "33"]]
        _ArrayDisplay($aArray, "Original", Default, 8)
        ; Write it to file
        _FileWriteFromArray($sFilePath, $aArray, Default, Default, ",")
        Sleep(1000)

        ; Re-read it - with count
        _FileReadToArray($sFilePath, $aRetArray, Default, ",")
        _ArrayDisplay($aRetArray, "2D array - count", Default, 8)

        ; Re-read it - without count
        _FileReadToArray($sFilePath, $aRetArray, $FRTA_NOCOUNT, ",")
        _ArrayDisplay($aRetArray, "2D array - no count", Default, 8)

        ; Read into "array of arrays" with count
        _FileReadToArray($sFilePath, $aRetArray, $FRTA_COUNT + $FRTA_INTARRAYS, ",")
        _ArrayDisplay($aRetArray, "Array of arrays - count", Default, 8)
        ; Now look inside the arrays inside the returned array
        _ArrayDisplay($aRetArray[1], "Array 1 inside RetArray - count", Default, 8)

        ; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        ; Rewrite 2D array with multiple delimiters
        _FileWriteFromArray($sFilePath, $aArray, Default, Default, ":|")
        Sleep(1000)

        ; Re-read with each delimiter acting as a split point
        _FileReadToArray($sFilePath, $aRetArray, $FRTA_NOCOUNT, ":|")
        _ArrayDisplay($aRetArray, "Split on each character", Default, 8)

        ; Re-read with whole delimiter acting as a split point
        _FileReadToArray($sFilePath, $aRetArray, $FRTA_NOCOUNT + $FRTA_ENTIRESPLIT, ":|")
        _ArrayDisplay($aRetArray, "Split on full delimiter", Default, 8)

        FileDelete($sFilePath)
    EndFunc   ;==>Example

### Example 2

    #include <Array.au3>
    #include <File.au3>
    #include <MsgBoxConstants.au3>

    Example()

    Func Example()
        ; Define a variable to pass to _FileReadToArray.
        Local $aArray = 0

        ; Read the current script file into an array using the variable defined previously.
        ; $iFlag is specified as 0 in which the array count will not be defined. Use UBound() to find the size of the array.
        If Not _FileReadToArray(@ScriptFullPath, $aArray, 0) Then
            MsgBox($MB_SYSTEMMODAL, "", "There was an error reading the file. @error: " & @error) ; An error occurred reading the current script file.
        EndIf

        ; Display the array in _ArrayDisplay.
        _ArrayDisplay($aArray)
    EndFunc   ;==>Example