Sane C++ Libraries
C++ Platform Abstraction Libraries
All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
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 Entryget () 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 fsIterator;
fsIterator.options.recursive = true;
SC_TEST_EXPECT(fsIterator.init(report.applicationRootDirectory, 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 fsIterator;
fsIterator.options.recursive = false; // As we manually call recurseSubdirectory
SC_TEST_EXPECT(fsIterator.init(report.applicationRootDirectory, 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.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
directoryDirectory to iterate
recursiveEntriesUser 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: