QDirListing Class

The QDirListing class provides an STL-style iterator for directory entries. More...

Header: #include <QDirListing>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Since: Qt 6.8

Public Types

enum class IteratorFlag { NoFlag, FollowSymlinks, Recursive }
flags IteratorFlags

Public Functions

QDirListing(const QDir &dir, QDirListing::IteratorFlags flags = IteratorFlag::NoFlag)
QDirListing(const QString &path, QDirListing::IteratorFlags flags = IteratorFlag::NoFlag)
QDirListing(const QString &path, QDir::Filters filters, QDirListing::IteratorFlags flags = IteratorFlag::NoFlag)
QDirListing(const QString &path, const QStringList &nameFilters, QDir::Filters filters = QDir::NoFilter, QDirListing::IteratorFlags flags = IteratorFlag::NoFlag)
~QDirListing()
QDirListing::const_iterator begin() const
QDirListing::const_iterator cbegin() const
QDirListing::const_iterator cend() const
QDirListing::const_iterator end() const
QString iteratorPath() const

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 QDir or a directory path 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 files filtered by name, recursively:

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

Iterators constructed by QDirListing (QDirListing::const_iterator) are forward-only (you cannot iterate directories in reverse order) and don't allow random access. They can be used in ranged-for loops (or with STL alogrithms that don't require random access iterators). Dereferencing a valid iterator returns a QDirListing::DirEntry object. The (c)end() iterator marks the end of the iteration. Dereferencing the end iterator is undefiend 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 implemnetation) 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 */) { /* ... */ }
}

See also QDir and QDir::entryList().

Member Type Documentation

enum class QDirListing::IteratorFlag
flags QDirListing::IteratorFlags

This enum class describes flags can be used to configure the behavior of QDirListing. These flags can be bitwise OR'ed together.

ConstantValueDescription
QDirListing::IteratorFlag::NoFlag0x0The default value, representing no flags. The iterator will return entries for the assigned path.
QDirListing::IteratorFlag::FollowSymlinks0x1When combined with Recursive, this flag enables iterating through all subdirectories of the assigned path, following all symbolic links. Symbolic link loops (e.g., link => . or link => ..) are automatically detected and ignored.
QDirListing::IteratorFlag::Recursive0x2List entries inside all subdirectories as well.

The IteratorFlags type is a typedef for QFlags<IteratorFlag>. It stores an OR combination of IteratorFlag values.

Member Function Documentation

QDirListing::const_iterator QDirListing::begin() const

QDirListing::const_iterator QDirListing::cbegin() const

QDirListing::const_iterator QDirListing::cend() const

QDirListing::const_iterator QDirListing::end() const

begin()/cbegin() returns a QDirListing::const_iterator that enables iterating over directory entries using a ranged-for loop; dereferencing this iterator returns a const QFileInfo &.

end()/cend() return a sentinel const_iterator that signals the end of the iteration. Dereferencing this iterator is undefined behavior.

For example:

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 files filtered by name, recursively:

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

Note: As this is a unidirectional (forward-only) iterator, calling begin()/cbegin() more than once on the same QDirListing object could result in unexpected behavior (for example, some entries being skipped).

See also fileInfo(), fileName(), and filePath().

QDirListing::QDirListing(const QDir &dir, QDirListing::IteratorFlags flags = IteratorFlag::NoFlag)

Constructs a QDirListing that can iterate over dir's entries, using dir's name filters and the QDir::Filters set in dir. You can pass options via flags to decide how the directory should be iterated.

By default, flags is NoIteratorFlags, which provides the same behavior as in QDir::entryList().

The sorting in dir is ignored.

Note: To list symlinks that point to non existing files, QDir::System must be set in dir's QDir::Filters.

See also hasNext(), next(), and IteratorFlags.

QDirListing::QDirListing(const QString &path, QDirListing::IteratorFlags flags = IteratorFlag::NoFlag)

Constructs a QDirListing that can iterate over path. You can pass options via flags to decide how the directory should be iterated.

By default, flags is NoIteratorFlags, which provides the same behavior as in QDir::entryList().

See also hasNext(), next(), and IteratorFlags.

QDirListing::QDirListing(const QString &path, QDir::Filters filters, QDirListing::IteratorFlags flags = IteratorFlag::NoFlag)

Constructs a QDirListing that can iterate over path. Entries are filtered according to filters. You can pass options via flags to decide how the directory should be iterated.

By default, filters is QDir::NoFilter, and flags is NoIteratorFlags, which provides the same behavior as in QDir::entryList().

Note: To list symlinks that point to non existing files, QDir::System must be set in filters.

See also hasNext(), next(), and IteratorFlags.

QDirListing::QDirListing(const QString &path, const QStringList &nameFilters, QDir::Filters filters = QDir::NoFilter, QDirListing::IteratorFlags flags = IteratorFlag::NoFlag)

Constructs a QDirListing that can iterate over path, using nameFilters and filters. You can pass options via flags to decide how the directory should be iterated.

By default, flags is NoIteratorFlags, which provides the same behavior as QDir::entryList().

For example, the following iterator could be used to iterate over audio files:

QDirListing audioFileIt(u"/home/johndoe/"_s, {"*.mp3", "*.wav"}, QDir::Files);

Note: To list symlinks that point to non existing files, QDir::System must be set in flags.

See also hasNext(), next(), IteratorFlags, and QDir::setNameFilters().

[noexcept] QDirListing::~QDirListing()

Destroys the QDirListing.

QString QDirListing::iteratorPath() const

Returns the directory path used to construct this QDirListing.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.