QDirListing Class

Member Function Documentation

(c)begin() returns a QDirListing::const_iterator that can be used to iterate over directory entries.

• This is a forward-only, single-pass iterator (you cannot iterate directory entries in reverse order)
• Can't be copied, only std::move()d.
• The return value of post-increment on objects that model std::input_iterator is partially-formed (a copy of an iterator that has since been advanced), the only valid operations on such an object are destruction and assignment of a new iterator. Therefore the post-increment operator advances the iterator and returns void.
• Doesn't allow random access
• Can be used in ranged-for loops; or with C++20 std::ranges algorithms that don't require random access iterators
• Dereferencing a valid iterator returns a const DirEntry &
• (c)end() returns a QDirListing::sentinel that signals the end of the iteration. Dereferencing an iterator that compares equal to end() is undefined behavior

(Some of the above restrictions are dictated by the underlying system library functions' implementation).

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 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";
}

See also QDirListing::DirEntry.

[explicit] QDirListing::QDirListing(const QString &path, QDirListing::IteratorFlags flags = IteratorFlag::Default)

Constructs a QDirListing that can iterate over path.

You can pass options via flags to control how the directory should be iterated.

By default, flags is IteratorFlag::Default.

See also IteratorFlags.

[explicit] QDirListing::QDirListing(const QString &path, const QStringList &nameFilters, QDirListing::IteratorFlags flags = IteratorFlag::Default)

Constructs a QDirListing that can iterate over path.

You can pass options via flags to control how the directory should be iterated. By default, flags is IteratorFlag::Default.

The listed entries will be filtered according to the file glob patterns in nameFilters (see QDir::setNameFilters() for more details).

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

QDirListing audioFileIt(u"/home/johndoe/"_s, QStringList{u"*.mp3"_s, u"*.wav"_s},
                        QDirListing::IteratorFlag::FilesOnly);

See also IteratorFlags and QDir::setNameFilters().

[noexcept] QDirListing::QDirListing(QDirListing &&other)

Move constructor. Moves other into this QDirListing.

[noexcept] QDirListing::~QDirListing()

Destroys the QDirListing.

QDirListing::IteratorFlags QDirListing::iteratorFlags() const

Returns the set of IteratorFlags used to construct this QDirListing.

QString QDirListing::iteratorPath() const

Returns the directory path used to construct this QDirListing.

QStringList QDirListing::nameFilters() const

Returns the list of file name glob filters used to construct this QDirListing.

[noexcept] QDirListing &QDirListing::operator=(QDirListing &&other)

Move-assigns other to this QDirListing.