File System Iterator

Table of Contents

• Dependencies
• Features
• Status
• Blog
• Description
• Roadmap
• Statistics

🟩 Enumerates files and directories inside a given path

SaneCppFileSystemIterator.h is a library that enumerates files and directories at a given path.

Dependencies

• Dependencies: (none)
• All dependencies: (none)

Features

• Iterate files in directory
• Handle recursive iteration

Status

🟩 Usable
The library is simple but gets the job done.

• On Windows it expects paths in UTF8 or UTF16 and outputs paths as UTF16.
• On Posix it expects and outputs paths in UTF8.

Blog

Some relevant blog posts are:

• June 2025 Update
• July 2025 Update

Description

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());

Roadmap

🟦 Complete Features:

• Not sure what else could be useful here

💡 Unplanned Features:

• No hypothesis has been made so far

Statistics

LOC counts exclude comments. Library counts files physically under Libraries/FileSystemIterator. Single File counts SaneCppFileSystemIterator.h. Standalone counts SaneCppFileSystemIteratorStandalone.h and intentionally includes dependency payloads.

Metric	Header	Source	Sum
Library	92	402	494
Single File	1121	977	2098
Standalone	1121	977	2098