Reads the specified file into a 1D or 2D array
#include <File.au3>
_FileReadToArray ( $sFilePath, ByRef $vReturn [, $iFlags = $FRTA_COUNT [, $sDelimiter = ""]] )
| $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 |
| 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) |
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.
#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
#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