SC::FileSystemIterator Struct Reference

Iterates files and directories inside a given path without allocating any memory. More...

#include <FileSystemIterator.h>

Classes
struct	Entry
	Contains information on a file or directory. More...
struct	FolderState
	Holds state of a folder when recursing into it to list its files. More...
struct	Options
	Options when iterating (recursive and other options) More...

Public Types
enum class	Type {   Directory ,   File }
	Entry type (File or Directory) More...

Public Member Functions
	~FileSystemIterator ()
	Destroys the FileSystemIterator object.
const Entry &	get () const
	Get current Entry being iterated.
Result	checkErrors ()
	Check if any error happened during iteration.
Result	init (StringSpan directory, Span< FolderState > recursiveEntries)
	Initializes the iterator on a given directory.
Result	enumerateNext ()
	Returned string is only valid until next enumerateNext call and/or another init call.
Result	recurseSubdirectory ()
	Recurse into current item (assuming Entry::isDirectory == true)

Public Attributes
Options	options
	Options to control recursive behaviour and other options.

Detailed Description

Iterates files and directories inside a given path without allocating any memory.

FileSystemIterator uses an iterator pattern to enumerate files instead of a callback. This allows avoiding blocking on enumeration of very large directories and also the allocation of a huge number of strings to hold all filenames. When configuring an iteration, the caller can ask for a fully recursive enumeration or manually call SC::FileSystemIterator::recurseSubdirectory when the current SC::FileSystemIterator::Entry item (obtained with SC::FileSystemIterator::get) matches a directory of interest. The maximum number of nested recursion levels that will be allowed depends on the size of the FileSystemIterator::FolderState span (can be a static array) passed in during init by the caller.

Note

This class doesn't allocate any dynamic memory.

Example of recursive iteration of a directory:

    FileSystemIterator::FolderState entries[16];
 
    FileSystemIterator fsIterator;
    fsIterator.options.recursive = true;
    SC_TEST_EXPECT(fsIterator.init(report.applicationRootDirectory.view(), entries));
    while (fsIterator.enumerateNext())
    {
        report.console.printLine(fsIterator.get().path);
    }
    SC_TEST_EXPECT(fsIterator.checkErrors());

If only some directories should be recursed, manual recursion can help speeding up directory iteration:

    FileSystemIterator::FolderState entries[16];
 
    FileSystemIterator fsIterator;
    fsIterator.options.recursive = false; // As we manually call recurseSubdirectory
    SC_TEST_EXPECT(fsIterator.init(report.applicationRootDirectory.view(), entries));
    while (fsIterator.enumerateNext())
    {
        const FileSystemIterator::Entry& entry = fsIterator.get();
        report.console.printLine(entry.path);
        // Only recurse directories not ending with "someExcludePattern"
        if (entry.isDirectory() and not StringView(entry.name).endsWith("someExcludePattern"))
        {
            SC_TEST_EXPECT(fsIterator.recurseSubdirectory());
        }
    }
    SC_TEST_EXPECT(fsIterator.checkErrors());

Member Enumeration Documentation

Type

enum class SC::FileSystemIterator::Type

strong

Entry type (File or Directory)

Constructor & Destructor Documentation

~FileSystemIterator()

SC::FileSystemIterator::~FileSystemIterator

(

)

Destroys the FileSystemIterator object.

Member Function Documentation

checkErrors()

Result SC::FileSystemIterator::checkErrors ( )

inline

Check if any error happened during iteration.

Returns

A valid Result if no errors have happened during file system iteration

enumerateNext()

Result SC::FileSystemIterator::enumerateNext

(

)

Returned string is only valid until next enumerateNext call and/or another init call.

Moves iterator to next file

Returns

Valid result if there are more files to iterate

get()

const Entry & SC::FileSystemIterator::get ( ) const

inline

Get current Entry being iterated.

Returns

Current entry

init()

Result SC::FileSystemIterator::init	(	StringSpan	directory,
		Span< FolderState >	recursiveEntries )

Initializes the iterator on a given directory.

Parameters

directory	Directory to iterate
recursiveEntries	User supplied buffer for the stack used during folder recursion (must be >= 1 elements)

Returns

Valid result if directory exists and is accessible

recurseSubdirectory()

Result SC::FileSystemIterator::recurseSubdirectory

(

)

Recurse into current item (assuming Entry::isDirectory == true)

Returns

Valid result if current item is a directory and it can be accessed successfully

Member Data Documentation

options

Options SC::FileSystemIterator::options

Options to control recursive behaviour and other options.

---

The documentation for this struct was generated from the following file:

• FileSystemIterator.h