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