Function Reference


_FileListToArrayRec

Lists files and\or folders in specified path with optional recursion to defined level and result sorting

#include <File.au3>
_FileListToArrayRec ( $sFilePath [, $sMask = "*" [, $iReturn = $FLTAR_FILESFOLDERS [, $iRecur = $FLTAR_NORECUR [, $iSort = $FLTAR_NOSORT [, $iReturnPath = $FLTAR_RELPATH]]]]] )

Parameters

$sFilePath Initial path used to generate filelist.
If path ends in \ then folders will be returned with an ending \
If path lengths > 260 chars, prefix path with "\\?\" - return paths are not affected
$sMask [optional] Filter for result. Multiple filters must be separated by ";"
Use "|" to separate 3 possible sets of filters: "Include|Exclude|Exclude_Folders"
    Include = Files/Folders to include (default = "*" [all])
    Exclude = Files/Folders to exclude (default = "" [none])
    Exclude_Folders = only used if $iRecur = 1 AND $iReturn <> 2 to exclude defined folders (default = "" [none])
$iReturn [optional] Specifies whether to return files, folders or both and omit those with certain attributes
    $FLTAR_FILESFOLDERS (0) - (Default) Return both files and folders
    $FLTAR_FILES (1) - Return files only
    $FLTAR_FOLDERS (2) - Return Folders only
Add one or more of the following to $iReturn to omit files/folders with that attribute
    + $FLTAR_NOHIDDEN (4) - Hidden files and folders
    + $FLTAR_NOSYSTEM (8) - System files and folders
    + $FLTAR_NOLINK (16) - Link/junction folders
$iRecur [optional] Specifies whether to search recursively in subfolders and to what level
    $FLTAR_NORECUR (0) - Do not search in subfolders (Default)
    $FLTAR_RECUR (1) - Search in all subfolders (unlimited recursion)
Negative integer - Search in subfolders to specified depth
$iSort [optional] Sort results in alphabetical and depth order
    $FLTAR_NOSORT (0) - Not sorted (Default)
    $FLTAR_SORT (1) - Sorted
    $FLTAR_FASTSORT (2) - Sorted with faster algorithm (assumes files in folder returned sorted - requires NTFS and not guaranteed)
$iReturnPath [optional] Specifies displayed path of results
    $FLTAR_NOPATH (0) - File/folder name only
    $FLTAR_RELPATH (1) - Relative to initial path (Default)
    $FLTAR_FULLPATH (2) - Full path included

Return Value

Success: a one-dimensional array made up as follows:
    [0] = Number of Files/Folders returned
    [1] = 1st File/Folder
    [2] = 2nd File/Folder
    ...
    [n] = nth File\Folder
Failure: an empty string and sets the @error flag to 1 with @extended set as follows:
    1 - Path not found or invalid
    2 - Invalid Include parameter
    3 - Invalid Exclude parameter
    4 - Invalid Exclude_Folders parameter
    5 - Invalid $iReturn parameter
    6 - Invalid $iRecur parameter
    7 - Invalid $iSort parameter
    8 - Invalid $iReturnPath parameter
    9 - No files/folders found

Remarks

If the files and/or folders to be returned are all within the same folder and can be specified with a single simple filter the _FileListToArray() function might be better suited as it is considerably faster.

Include/Exclude/Exclude_Folders logic:
    Non-recursive:
        Include/Exclude: Files and/or folders
        Exclude_Folders: Ignored
    Recursive:
        Include/Exclude:
            $iReturn = $FLTAR_FILESFOLDERS/$FLTAR_FILES - Files only
            $iReturn = $FLTAR_FOLDERS - Folders only
        Exclude_Folders:
            $iReturn = $FLTAR_FILESFOLDERS/$FLTAR_FILES - Folders only
            $iReturn = $FLTAR_FOLDERS - Ignored

Sorting the results will significantly increase the time required for the UDF to return the array

Despite the name, this UDF is iterative, not recursive. Constants are defined in FileConstants.au3

Related

_FileListToArray

Example

#include <Array.au3> ; Only required to display the arrays
#include <File.au3>
#include <MsgBoxConstants.au3>

Example()

Func Example()
    Local $sAutoItDir = StringLeft(@AutoItExe, StringInStr(@AutoItExe, "\", Default, -1))
    If StringRight($sAutoItDir, 5) = "beta\" Then
        $sAutoItDir = StringTrimRight($sAutoItDir, 5)
    EndIf
    ConsoleWrite($sAutoItDir & @CRLF)

    ; A sorted list of all files and folders in the AutoIt installation
    Local $aArray = _FileListToArrayRec($sAutoItDir, "*", $FLTAR_FILESFOLDERS, $FLTAR_RECUR, $FLTAR_SORT)
    _ArrayDisplay($aArray, "Sorted tree")

    ; And now ignoring the "Include" folder
    $aArray = _FileListToArrayRec($sAutoItDir, "*||include", $FLTAR_FILESFOLDERS, $FLTAR_RECUR, $FLTAR_SORT)
    _ArrayDisplay($aArray, "No 'Include' folder")

    ; A sorted list of all but the .exe files in the \AutoIt3 folder
    $aArray = _FileListToArrayRec($sAutoItDir, "*|*.exe", $FLTAR_FILES, $FLTAR_NORECUR, $FLTAR_SORT)
    _ArrayDisplay($aArray, "Non .EXE files")

    ; And here are the .exe files we left out last time
    $aArray = _FileListToArrayRec($sAutoItDir, "*.exe", $FLTAR_FILES)
    _ArrayDisplay($aArray, ".EXE Files")

    ; A test for all folders and .exe files only throughout the folder tree, omitting folders beginning with I (Icons and Include)
    $aArray = _FileListToArrayRec($sAutoItDir, "*.exe||i*", $FLTAR_FILESFOLDERS, $FLTAR_RECUR, $FLTAR_SORT)
    _ArrayDisplay($aArray, "Recur with filter")

    ; Look for icon files - but exlude the "Icons" folder
    $aArray = _FileListToArrayRec($sAutoItDir, "*.ico||ic*", $FLTAR_FILES, $FLTAR_RECUR, $FLTAR_SORT)
    If @error Then
        MsgBox($MB_SYSTEMMODAL, "Ooops!", "No ico files found")
    Else
        _ArrayDisplay($aArray, "Icon files not in 'Icons' folder")
    EndIf

    ; And to show that the filter applies to files AND folders when not recursive
    $aArray = _FileListToArrayRec($sAutoItDir, "*.exe", $FLTAR_FILESFOLDERS, $FLTAR_NORECUR, $FLTAR_SORT)
    _ArrayDisplay($aArray, "Non-recur with filter")

    ; The filter also applies to folders when recursively searching for folders
    $aArray = _FileListToArrayRec($sAutoItDir, "Icons", $FLTAR_FOLDERS, $FLTAR_RECUR, $FLTAR_SORT)
    _ArrayDisplay($aArray, "Folder recur with filter")

    ; Note the exlude_folder parameter is ignored when looking for folders - "Icons" will be excluded but "Include" will still be there
    $aArray = _FileListToArrayRec($sAutoItDir, "*|ic*|i*", $FLTAR_FOLDERS, $FLTAR_RECUR, $FLTAR_SORT)
    _ArrayDisplay($aArray, "'Icons' out - 'Include' in")

    ; The root of C:\Windows showing hidden/system folders
    $aArray = _FileListToArrayRec("C:\Windows\", "*", $FLTAR_FOLDERS)
    _ArrayDisplay($aArray, "Show hidden folders")

    ; The root of C:\Windows omitting hidden/system folders
    $aArray = _FileListToArrayRec("C:\Windows\", "*", $FLTAR_FOLDERS + $FLTAR_NOHIDDEN + $FLTAR_NOSYSTEM)
    _ArrayDisplay($aArray, "Hide hidden folders")
EndFunc   ;==>Example