QDirListing Class

Detailed Description

You can use QDirListing to navigate entries of a directory one at a time. It is similar to QDir::entryList() and QDir::entryInfoList(), but because it lists entries one at a time instead of all at once, it scales better and is more suitable for large directories. It also supports listing directory contents recursively, and following symbolic links. Unlike QDir::entryList(), QDirListing does not support sorting.

The QDirListing constructor takes a directory path string as argument. Here's how to iterate over all entries recursively:

 using ItFlag = QDirListing::IteratorFlag;
 for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) {
     qDebug() << dirEntry.filePath();
     // /etc/.
     // /etc/..
     // /etc/X11
     // /etc/X11/fs
     // ...
 }

Here's how to find and read all regular files filtered by name, recursively:

 using F = QDirListing::IteratorFlag;
 QDirListing dirList(u"/sys"_s, QStringList{u"scaling_cur_freq"_s}, F::FilesOnly | F::Recursive);
 for (const auto &dirEntry : dirList) {
     QFile f(dirEntry.filePath());
     if (f.open(QIODevice::ReadOnly))
         qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
 }

Here's how to list only regular files, recursively:

 using F = QDirListing::IteratorFlag;
 const auto flags = F::FilesOnly | F::Recursive;
 for (const auto &dirEntry : QDirListing(u"/etc"_s, flags)) {
     // ...
 }

Here's how to list only regular files and symbolic links to regular files, recursively:

 using F = QDirListing::IteratorFlag;
 const auto flags = F::FilesOnly | F::Recursive | F::ResolveSymlinks;
 for (const auto &dirEntry : QDirListing(u"/etc"_s, flags)) {
     // ...
 }

QDirListing::const_iterator models C++20 std::input_iterator, that is, it is a move-only, forward-only, single-pass iterator, that doesn't allow random access. It can be used in ranged-for loops (or with C++20 range algorithms that don't require random access iterators). Dereferencing a valid iterator returns a QDirListing::DirEntry object. The (c)end() sentinel marks the end of the iteration. Dereferencing an iterator that is equal to sentinel is undefined behavior.

QDirListing::DirEntry offers a subset of QFileInfo's API (for example, fileName(), filePath(), exists()). Internally, DirEntry only constructs a QFileInfo object if needed, that is, if the info hasn't been already fetched by other system functions. You can use DirEntry::fileInfo() to get a QFileInfo. For example:

 using ItFlag = QDirListing::IteratorFlag;
 for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) {
     // Faster
     if (dirEntry.fileName().endsWith(u".conf")) { /* ... */ }

     // This works, but might be potentially slower, since it has to construct a
     // QFileInfo, whereas (depending on the implementation) the fileName could
     // be known already
     if (dirEntry.fileInfo().fileName().endsWith(u".conf")) { /* ... */ }
 }
 using ItFlag = QDirListing::IteratorFlag;
 for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) {
     // Both approaches are the same, because DirEntry will have to construct
     // a QFileInfo to get this info (for example, by calling system stat())

     if (dirEntry.size() >= 4'000 /* 4KB */) { /* ...*/ }
     if (dirEntry.fileInfo().size() >= 4'000 /* 4KB */) { /* ... */ }
 }