qdirlisting.cpp

Go to the documentation of this file.

// Copyright (C) 2016 The Qt Company Ltd.
// Copyright (C) 2024 Ahmad Samir <a.samirh78@gmail.com>
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
 
/*!
    \since 6.8
    \class QDirListing
    \inmodule QtCore
    \ingroup  io
    \brief The QDirListing class provides an STL-style iterator for directory entries.
 
    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:
 
    \snippet code/src_corelib_io_qdirlisting.cpp 0
 
    Here's how to find and read all regular files filtered by name, recursively:
 
    \snippet code/src_corelib_io_qdirlisting.cpp 1
 
    Here's how to list only regular files, recursively:
    \snippet code/src_corelib_io_qdirlisting.cpp 5
 
    Here's how to list only regular files and symbolic links to regular
    files, recursively:
    \snippet code/src_corelib_io_qdirlisting.cpp 6
 
//! [std-input-iterator-tag]
    QDirListing::const_iterator models C++20
    \l{https://en.cppreference.com/w/cpp/iterator/input_iterator}{std::input_iterator},
    that is, it is a move-only, forward-only, single-pass iterator, that
    doesn't allow random access.
//! [std-input-iterator-tag]
    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 \l{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:
 
    \snippet code/src_corelib_io_qdirlisting.cpp 3
    \snippet code/src_corelib_io_qdirlisting.cpp 4
 
    \sa QDir, QDir::entryList()
*/
 
/*! \enum QDirListing::IteratorFlag
 
    This enum class describes flags that can be used to configure the behavior
    of QDirListing. Values from this enumerator can be bitwise OR'ed together.
 
    \value Default
        List all entries, that is, files, directories, symbolic links including broken
        symbolic links (where the target doesn't exist) and special (\e other) system
        files, see ExcludeOther for details.
        Hidden files and directories and the special entries \c{.} and \c{..}
        aren't listed by default.
 
    \value ExcludeFiles
        Don't list regular files. When combined with ResolveSymlinks, symbolic
        links to regular files will be excluded too.
 
    \value ExcludeDirs
        Don't list directories. When combined with ResolveSymlinks, symbolic
        links to directories will be excluded too.
 
    \omitvalue ExcludeSpecial
    \value [since 6.10] ExcludeOther
        Don't list file system entries that are \e not directories, regular files,
        or symbolic links.
        \list
            \li On Unix, a special (other) file system entry is a FIFO, socket,
                character device, or block device. For more details see the
                \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/mknod.html}{\c mknod}
                manual page.
            \li On Windows (for historical reasons) \c .lnk files are considered
                special (other) file system entries.
        \endlist
 
    \value ResolveSymlinks
        Filter symbolic links based on the type of the target of the link,
        rather than the symbolic link itself. Broken symbolic links (where
        the target doesn't exist) are excluded, set IncludeBrokenSymlinks
        to include them.
        This flag is ignored on operating systems that don't support symbolic links.
 
    \value [since 6.11] IncludeBrokenSymlinks
        Lists broken symbolic links, where the target doesn't exist, regardless
        of the status of the ResolveSymlinks flag.
        This flag is ignored on operating systems that don't support symbolic links.
 
    \value FilesOnly
        Only regular files will be listed. When combined with ResolveSymlinks,
        symbolic links to files will also be listed.
 
    \value DirsOnly
        Only directories will be listed. When combined with ResolveSymlinks,
        symbolic links to directories will also be listed.
 
    \value IncludeHidden
        List hidden entries. When combined with Recursive, the iteration will
        recurse into hidden sub-directories as well.
 
    \value IncludeDotAndDotDot
        List the \c {.} and \c{..} special entries.
 
    \value CaseSensitive
        The file glob patterns in the name filters passed to the QDirListing
        constructor, will be matched case sensitively (for details, see
        QDir::setNameFilters()).
 
    \value Recursive
        List entries inside all sub-directories as well. When combined with
        FollowDirSymlinks, symbolic links to directories will be iterated too.
 
    \value FollowDirSymlinks
        When combined with Recursive, symbolic links to directories will be
        iterated too. Symbolic link loops (e.g., link => . or link => ..) are
        automatically detected and ignored.
 
    \omitvalue NoNameFiltersForDirs
*/
 
#include "qdirlisting.h"
#include "qdirentryinfo_p.h"
 
#include "qdir_p.h"
#include "qdiriterator.h"
#include "qabstractfileengine_p.h"
 
#if QT_CONFIG(regularexpression)
#include <QtCore/qregularexpression.h>
#endif
 
#include <QtCore/private/qfilesystemiterator_p.h>
#include <QtCore/private/qfilesystementry_p.h>
#include <QtCore/private/qfilesystemmetadata_p.h>
#include <QtCore/private/qfilesystemengine_p.h>
#include <QtCore/private/qfileinfo_p.h>
#include <QtCore/private/qduplicatetracker_p.h>
 
#include <memory>
#include <stack>
#include <variant>
#include <vector>
 
QT_BEGIN_NAMESPACE
 
using namespace Qt::StringLiterals;
 
class QDirListingPrivate
{
    Q_DISABLE_COPY_MOVE(QDirListingPrivate)
public:
    QDirListingPrivate() = default;
 
    // the default for std::stack is std::deque, but std::vector is more apt:
    template <typename T>
    struct vector_stack : std::stack<T, std::vector<T>>
    {
        using Base = std::stack<T, std::vector<T>>;
        using Base::Base;
        void clear() { this->c.clear(); } // std::stack is also missing clear()
    };
 
    void init();
    void advance();
    void beginIterating();
 
    bool entryMatches(QDirEntryInfo &info);
    void pushDirectory(QDirEntryInfo &info);
    void pushInitialDirectory();
 
    void checkAndPushDirectory(QDirEntryInfo &info);
    bool matchesFilters(QDirEntryInfo &data) const;
    bool hasIterators() const;
 
    QDirEntryInfo initialEntryInfo;
    QStringList nameFilters;
    QDirListing::IteratorFlags iteratorFlags;
    QDirEntryInfo currentEntryInfo;
 
#if QT_CONFIG(regularexpression)
    std::vector<QRegularExpression> nameRegExps;
    bool regexMatchesName(const QString &fileName) const
    {
        if (nameRegExps.empty())
            return true;
        auto hasMatch = [&fileName](const auto &re) { return re.match(fileName).hasMatch(); };
        return std::any_of(nameRegExps.cbegin(), nameRegExps.cend(), hasMatch);
    }
#endif
 
    // QDirListing scans either through a QAbstractFileEngine (resources, custom
    // engines) or natively (QFileSystemEngine + QFileSystemIterator). The mode
    // is selected by beginIterating().
    struct EngineData {
        using FEngineIteratorPtr = std::unique_ptr<QAbstractFileEngineIterator>;
        EngineData(std::unique_ptr<QAbstractFileEngine> engine) noexcept : engine(std::move(engine)) {}
        std::unique_ptr<QAbstractFileEngine> engine;
        vector_stack<FEngineIteratorPtr> iterators;
        QDuplicateTracker<QString> visitedLinks;
    };
    struct NativeData {
#ifndef QT_NO_FILESYSTEMITERATOR
        using FsIteratorPtr = std::unique_ptr<QFileSystemIterator>;
        vector_stack<FsIteratorPtr> iterators;
        QDuplicateTracker<QFileSystemNativeId> visitedLinks;
#else
        NativeData() noexcept
        { qWarning("Qt was built with -no-feature-filesystemiterator: no files/plugins will be found!"); }
#endif
    };
    std::variant<std::monostate, EngineData, NativeData> data;
 
private:
    bool matchesFilters(const QFileInfo &fileInfo) const;
    bool matchesFilters(QDirEntryInfo::Iterator &iterator) const;
    bool matchesFilters(const QFileInfo &fileInfo, const QString &fileName) const;
    bool matchesFilters(QDirEntryInfo::Native &native) const;
};
 
void QDirListingPrivate::init()
{
    if (nameFilters.contains("*"_L1))
        nameFilters.clear();
 
#if QT_CONFIG(regularexpression)
    nameRegExps.reserve(size_t(nameFilters.size()));
 
    const bool isCase = iteratorFlags.testAnyFlags(QDirListing::IteratorFlag::CaseSensitive);
    const auto cs = isCase ? Qt::CaseSensitive : Qt::CaseInsensitive;
    for (const auto &filter : std::as_const(nameFilters))
        nameRegExps.emplace_back(QRegularExpression::fromWildcard(filter, cs));
#endif
}
 
/*!
    \internal
 
    Resets the iteration state (if any), so that calling begin()/cbegin()
    always starts iterating anew.
*/
void QDirListingPrivate::beginIterating()
{
    Q_ASSERT(std::holds_alternative<QDirEntryInfo::Native>(initialEntryInfo.content));
    QDirEntryInfo::Native &native = *std::get_if<QDirEntryInfo::Native>(&initialEntryInfo.content);
 
    // (Re-)select our operating mode. Note how std::variant::emplace will
    // recreate the object even if it matches the current type, which is
    // necessary for QDuplicateTracker.
    if (auto engine = QFileSystemEngine::createLegacyEngine(native.entry, native.metaData))
        data.emplace<EngineData>(std::move(engine));
    else
        data.emplace<NativeData>();
 
    pushDirectory(initialEntryInfo);
}
 
void QDirListingPrivate::pushDirectory(QDirEntryInfo &entryInfo)
{
    const bool followSymlinks =
            iteratorFlags.testAnyFlags(QDirListing::IteratorFlag::FollowDirSymlinks);
 
    if (auto *d = std::get_if<EngineData>(&data)) {
        const QString path = [&entryInfo] {
#ifdef Q_OS_WIN
            if (entryInfo.isSymLink())
                return entryInfo.canonicalFilePath();
#endif
            return entryInfo.filePath();
        }();
 
        // Stop link loops
        if (followSymlinks && d->visitedLinks.hasSeen(entryInfo.canonicalFilePath()))
            return;
 
#ifdef Q_OS_WIN
        if (entryInfo.isJunction() && d->visitedLinks.hasSeen(entryInfo.junctionTarget()))
            return;
#endif
 
        d->engine->setFileName(path);
        if (auto it = d->engine->beginEntryList(path, iteratorFlags, nameFilters)) {
            d->iterators.push(std::move(it));
        } else {
            // No iterator; no entry list.
        }
    } else if (auto *d = std::get_if<NativeData>(&data); true) {
        Q_ASSERT(d);
#ifndef QT_NO_FILESYSTEMITERATOR
        // In native mode, entryInfo is always Native: the initial entry is
        // (see beginIterating()) and QFileSystemIterator::advance() only ever
        // produces Native entries.
        Q_ASSERT(std::holds_alternative<QDirEntryInfo::Native>(entryInfo.content));
        const auto native = std::get_if<QDirEntryInfo::Native>(&entryInfo.content);
        auto it = std::make_unique<QFileSystemIterator>(native->entry, iteratorFlags);
 
        // Stop link loops
        if (followSymlinks) {
            QFileSystemNativeId id = it->nativeId();
            if (id.isValid() && d->visitedLinks.hasSeen(id))
                return;
        }
 
#ifdef Q_OS_WIN
        if (entryInfo.isJunction()) {
            QFileSystemNativeId id = it->nativeId();
            if (id.isValid() && d->visitedLinks.hasSeen(id))
                return;
        }
#endif
 
        d->iterators.push(std::move(it));
#endif
    }
}
 
bool QDirListingPrivate::entryMatches(QDirEntryInfo &entryInfo)
{
    checkAndPushDirectory(entryInfo);
    return matchesFilters(entryInfo);
}
 
/*!
    \internal
 
    Advances the internal iterator, either a QAbstractFileEngineIterator (e.g.
    QResourceFileEngineIterator) or a QFileSystemIterator (which uses low-level
    system methods, e.g. readdir() on Unix). The iterators are stored in a
    stack.
 
    A typical example of doing recursive iteration:
    - while iterating directory A we find a sub-dir B
    - an iterator for B is pushed to the stack
    - B's iterator is processed (stack.top()) first; then the loop
      goes back to processing A's iterator
*/
void QDirListingPrivate::advance()
{
    if (auto *d = std::get_if<EngineData>(&data)) {
        while (!d->iterators.empty()) {
            // Find the next valid iterator that matches the filters.
            // Always use top() because entryMatches() may modify `iterators`!
            while (d->iterators.top()->advance()) {
                QDirEntryInfo entryInfo{d->iterators.top().get()};
                if (entryMatches(entryInfo)) {
                    currentEntryInfo = std::move(entryInfo);
                    return;
                }
            }
 
            d->iterators.pop();
        }
    } else if (auto *d = std::get_if<NativeData>(&data); true) {
        Q_ASSERT(d);
#ifndef QT_NO_FILESYSTEMITERATOR
        while (!d->iterators.empty()) {
            // Find the next valid iterator that matches the filters.
            // Always use top() because entryMatches() may modify `iterators`!
            while (std::optional r = d->iterators.top()->advance()) {
                if (entryMatches(*r)) {
                    currentEntryInfo = std::move(*r);
                    return;
                }
            }
 
            d->iterators.pop();
        }
#endif
    }
}
 
static bool isDotOrDotDot(QStringView fileName)
{
    return fileName == "."_L1 || fileName == ".."_L1;
}
 
void QDirListingPrivate::checkAndPushDirectory(QDirEntryInfo &entryInfo)
{
    using F = QDirListing::IteratorFlag;
    // If we're doing flat iteration, we're done.
    if (!iteratorFlags.testAnyFlags(F::Recursive))
        return;
 
    // Follow symlinks only when asked
    if (!iteratorFlags.testAnyFlags(F::FollowDirSymlinks) && entryInfo.isSymLink())
        return;
 
    // Never follow . and ..
    if (isDotOrDotDot(entryInfo.fileName()))
        return;
 
    // No hidden directories unless requested
    const bool includeHidden = iteratorFlags.testAnyFlags(QDirListing::IteratorFlag::IncludeHidden);
    if (!includeHidden && entryInfo.isHidden())
        return;
 
    // Never follow non-directory entries
    if (!entryInfo.isDir())
        return;
 
    pushDirectory(entryInfo);
}
 
bool QDirListingPrivate::matchesFilters(QDirEntryInfo::Native &native) const
{
    using F = QDirListing::IteratorFlag;
    using M = QFileSystemMetaData;
 
    const QString fileName = native.entry.fileName();
    if (fileName.isEmpty())
        return false;
 
    // name filter
#if QT_CONFIG(regularexpression)
    const bool skipNameFilters = iteratorFlags.testAnyFlags(F::NoNameFiltersForDirs)
            && native.ensureFilled(M::DirectoryType).isDirectory();
    if (!skipNameFilters) {
        if (!regexMatchesName(fileName))
            return false;
    }
#endif // QT_CONFIG(regularexpression)
 
    if (isDotOrDotDot(fileName))
        return iteratorFlags.testFlags(F::IncludeDotAndDotDot);
 
    if (!iteratorFlags.testAnyFlag(F::IncludeHidden)
            && native.ensureFilled(M::HiddenAttribute).isHidden()) {
        return false;
    }
 
    if (iteratorFlags.testAnyFlags(F::IncludeBrokenSymlinks)
            && native.ensureFilled(M::LegacyLinkType).isLegacyLink()
            && !native.ensureFilled(M::ExistsAttribute).exists()) {
        return true;
    }
 
    if (iteratorFlags.testFlag(F::ResolveSymlinks)) {
        if (native.ensureFilled(M::LegacyLinkType).isLegacyLink()
                && !native.ensureFilled(M::ExistsAttribute).exists()) {
            return false; // Exclude broken symlinks; anything else will be filtered below
        }
    } else {
        constexpr auto f = F::ExcludeFiles | F::ExcludeDirs | F::ExcludeOther;
        const bool filterByTargetType = iteratorFlags.testAnyFlags(f);
        if (filterByTargetType && native.ensureFilled(M::LegacyLinkType).isLegacyLink())
            return false;
    }
 
    if (iteratorFlags.testAnyFlag(F::ExcludeOther)
            && !native.ensureFilled(M::FileType).isFile()
            && !native.ensureFilled(M::DirectoryType).isDirectory()
            && !native.ensureFilled(M::LegacyLinkType).isLegacyLink()) {
        return false;
    }
 
    if (iteratorFlags.testAnyFlags(F::ExcludeDirs)
            && native.ensureFilled(M::DirectoryType).isDirectory()) {
        return false;
    }
 
    if (iteratorFlags.testAnyFlags(F::ExcludeFiles) && native.ensureFilled(M::FileType).isFile())
        return false;
 
    return true;
}
 
bool QDirListingPrivate::matchesFilters(const QFileInfo &fileInfo, const QString &fileName) const
{
    using F = QDirListing::IteratorFlag;
 
    Q_ASSERT(!fileName.isEmpty());
 
    // name filter
#if QT_CONFIG(regularexpression)
    const bool skipNameFilters = iteratorFlags.testFlag(F::NoNameFiltersForDirs)
            && fileInfo.isDir();
    if (!skipNameFilters) {
        if (!regexMatchesName(fileName))
            return false;
    }
#endif // QT_CONFIG(regularexpression)
 
    if (isDotOrDotDot(fileName))
        return iteratorFlags.testFlag(F::IncludeDotAndDotDot);
 
    if (!iteratorFlags.testFlag(F::IncludeHidden) && fileInfo.isHidden())
        return false;
 
    const bool includeBrokenSymlinks = iteratorFlags.testAnyFlags(F::IncludeBrokenSymlinks);
    if (includeBrokenSymlinks && fileInfo.isSymLink() && !fileInfo.exists())
        return true;
 
    if (iteratorFlags.testFlag(F::ResolveSymlinks)) {
        if (fileInfo.isSymLink() && !fileInfo.exists())
            return false; // Exclude broken symlinks; anything else will be filtered below
    } else {
        constexpr auto f = F::ExcludeFiles | F::ExcludeDirs | F::ExcludeOther;
        const bool filterByTargetType = iteratorFlags.testAnyFlags(f);
        if (filterByTargetType && fileInfo.isSymLink())
            return false;
    }
 
    if (iteratorFlags.testFlag(F::ExcludeOther)
            && !fileInfo.isFile() && !fileInfo.isDir() && !fileInfo.isSymLink()) {
        return false;
    }
 
    if (iteratorFlags.testFlag(F::ExcludeDirs) && fileInfo.isDir())
        return false;
 
    if (iteratorFlags.testFlag(F::ExcludeFiles) && fileInfo.isFile())
        return false;
 
    return true;
}
 
bool QDirListingPrivate::matchesFilters(QDirEntryInfo::Iterator &iterator) const
{
    using F = QDirListing::IteratorFlag;
 
    const QString fileName = iterator.iterator->currentFileName();
    if (fileName.isEmpty())
        return false;
 
    // Fast path that doesn't require conversion to QFileInfo
    if (iteratorFlags.testFlag(F::IncludeHidden)
        && !iteratorFlags.testAnyFlags(
                F::NoNameFiltersForDirs |
                F::IncludeBrokenSymlinks |
                F::ResolveSymlinks |
                F::ExcludeFiles |
                F::ExcludeDirs |
                F::ExcludeOther)) {
 
#if QT_CONFIG(regularexpression)
        if (!regexMatchesName(fileName))
            return false;
#endif
        if (isDotOrDotDot(fileName))
            return iteratorFlags.testFlags(F::IncludeDotAndDotDot);
 
        return true;
    }
 
    // Conversion to QFileInfo can be expensife, but now we need to do it.
    return matchesFilters(iterator.ensureFileInfo(), fileName);
}
 
bool QDirListingPrivate::matchesFilters(const QFileInfo &fileInfo) const
{
    const QString fileName = fileInfo.fileName();
    return !fileName.isEmpty() && matchesFilters(fileInfo, fileName);
}
 
/*!
    \internal
 
    This function returns \c true if the current entry matches the filters
    (i.e., the current entry will be returned as part of the directory
    iteration); otherwise, \c false is returned.
*/
bool QDirListingPrivate::matchesFilters(QDirEntryInfo &entryInfo) const
{
    return std::visit([this](auto &e) { return matchesFilters(e); },
                      entryInfo.content);
}
 
bool QDirListingPrivate::hasIterators() const
{
    if (auto *d = std::get_if<EngineData>(&data))
        return !d->iterators.empty();
 
#if !defined(QT_NO_FILESYSTEMITERATOR)
    if (auto *d = std::get_if<NativeData>(&data))
        return !d->iterators.empty();
#endif
 
    return false;
}
 
/*!
    Constructs a QDirListing that can iterate over \a path.
 
    You can pass options via \a flags to control how the directory should
    be iterated.
 
    By default, \a flags is IteratorFlag::Default.
 
    \sa IteratorFlags
*/
QDirListing::QDirListing(const QString &path, IteratorFlags flags)
    : d(new QDirListingPrivate)
{
    d->initialEntryInfo.content = QDirEntryInfo::Native { QFileSystemEntry(path), {} };
    d->iteratorFlags = flags;
    d->init();
}
 
/*!
    Constructs a QDirListing that can iterate over \a path.
 
    You can pass options via \a flags to control how the directory should
    be iterated. By default, \a flags is IteratorFlag::Default.
 
    The listed entries will be filtered according to the file glob patterns
    in \a nameFilters, which are converted to a regular expression using
    QRegularExpression::fromWildcard (see QDir::setNameFilters() for more
    details).
 
    For example, the following iterator could be used to iterate over audio
    files:
 
    \snippet code/src_corelib_io_qdirlisting.cpp 2
 
    Sometimes you can filter by name more efficiently by iterating over the
    entries with a range-for loop, using string comparison. For example:
 
    \snippet code/src_corelib_io_qdirlisting.cpp 7
 
    \sa IteratorFlags, QDir::setNameFilters()
*/
QDirListing::QDirListing(const QString &path, const QStringList &nameFilters, IteratorFlags flags)
    : d(new QDirListingPrivate)
{
    d->initialEntryInfo.content = QDirEntryInfo::Native { QFileSystemEntry(path), {} };
    d->nameFilters = nameFilters;
    d->iteratorFlags = flags;
    d->init();
}
 
/*!
    \fn QDirListing::QDirListing(QDirListing &&other)
 
    Move constructor. Moves \a other into this QDirListing.
 
//! [partially-formed]
    \note The moved-from object \a other is placed in a partially-formed state,
    in which the only valid operations are destruction and assignment of a new
    value.
//! [partially-formed]
*/
 
/*!
    \fn QDirListing &QDirListing::operator=(QDirListing &&other)
 
    Move-assigns \a other to this QDirListing.
 
    \include qdirlisting.cpp partially-formed
*/
 
/*!
    Destroys the QDirListing.
*/
QDirListing::~QDirListing()
{
    delete d;
}
 
/*!
    Returns the directory path used to construct this QDirListing.
*/
QString QDirListing::iteratorPath() const
{
    return d->initialEntryInfo.filePath();
}
 
/*!
    Returns the set of IteratorFlags used to construct this QDirListing.
*/
QDirListing::IteratorFlags QDirListing::iteratorFlags() const
{
    return d->iteratorFlags;
}
 
/*!
    Returns the list of file name glob filters used to construct this
    QDirListing.
*/
QStringList QDirListing::nameFilters() const
{
    return d->nameFilters;
}
 
/*!
    \class QDirListing::const_iterator
    \since 6.8
    \inmodule QtCore
    \ingroup  io
 
    The iterator type returned by QDirListing::cbegin().
 
//! [dirlisting-iterator-behavior]
    \list
    \li This is a forward-only, single-pass iterator (you cannot iterate
        directory entries in reverse order)
    \li Can't be copied, only \c{std::move()}d.
    \li \include qdirlisting.cpp post-increment-partially-formed
    \li Doesn't allow random access
    \li Can be used in ranged-for loops; or with C++20 std::ranges algorithms
        that don't require random access iterators
    \li Dereferencing a valid iterator returns a \c{const DirEntry &}
    \li (c)end() returns a \l QDirListing::sentinel that signals the end of
        the iteration. Dereferencing an iterator that compares equal to end()
        is undefined behavior
    \endlist
//! [dirlisting-iterator-behavior]
 
    \include qdirlisting.cpp ranges-algorithms-note
 
    \sa QDirListing, QDirListing::sentinel, QDirListing::DirEntry
*/
 
/*!
    \typealias QDirListing::const_iterator::reference
 
    A typedef for \c {const QDirListing::DirEntry &}.
*/
 
/*!
    \typealias QDirListing::const_iterator::pointer
 
    A typedef for \c {const QDirListing::DirEntry *}.
*/
 
/*!
    \class QDirListing::sentinel
    \since 6.8
    \inmodule QtCore
    \ingroup  io
 
    \l QDirListing returns an object of this type to signal the end of
    iteration. Dereferencing a \l QDirListing::const_iterator that is
    equal to \c sentinel{} is undefined behavior.
 
    \include qdirlisting.cpp ranges-algorithms-note
 
    \sa QDirListing, QDirListing::const_iterator, QDirListing::DirEntry
*/
 
/*!
    \fn QDirListing::const_iterator QDirListing::begin() const
    \fn QDirListing::const_iterator QDirListing::cbegin() const
    \fn QDirListing::sentinel QDirListing::end() const
    \fn QDirListing::sentinel QDirListing::cend() const
 
    (c)begin() returns a QDirListing::const_iterator that can be used to
    iterate over directory entries.
 
    \include qdirlisting.cpp dirlisting-iterator-behavior
 
    \note Each time (c)begin() is called on the same QDirListing object,
    the internal state is reset and the iteration starts anew.
 
    (Some of the above restrictions are dictated by the underlying system
    library functions' implementation).
 
    For example:
    \snippet code/src_corelib_io_qdirlisting.cpp 0
 
    Here's how to find and read all files filtered by name, recursively:
    \snippet code/src_corelib_io_qdirlisting.cpp 1
 
//! [ranges-algorithms-note]
    \note The "classical" STL algorithms don't support iterator/sentinel, so
    you need to use C++20 std::ranges algorithms for QDirListing, or else a
    3rd-party library that provides range-based algorithms in C++17.
//! [ranges-algorithms-note]
 
    \sa QDirListing::DirEntry
*/
QDirListing::const_iterator QDirListing::begin() const
{
    d->beginIterating();
    const_iterator it{d};
    ++it;
    return it;
}
 
/*!
    \fn const QDirListing::DirEntry &QDirListing::const_iterator::operator*() const
 
    Returns a \c{const  QDirListing::DirEntry &} of the directory entry this
    iterator points to.
*/
 
/*!
    \fn const QDirListing::DirEntry *QDirListing::const_iterator::operator->() const
 
    Returns a \c{const QDirListing::DirEntry *} to the directory entry this
    iterator points to.
*/
 
/*!
    \fn QDirListing::const_iterator::operator++()
 
    Pre-increment operator.
    Advances the iterator and returns a reference to it.
*/
 
/*!
    \fn void QDirListing::const_iterator::operator++(int)
 
    Post-increment operator.
 
    \include qdirlisting.cpp std-input-iterator-tag
 
//! [post-increment-partially-formed]
    The return value of post-increment on objects that model
    \c 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 \c void.
//! [post-increment-partially-formed]
*/
 
/*!
    \internal
 
    Implements the actual advancing. Not a member function to avoid forcing
    DirEntry objects (and therefore const_iterator ones) onto the stack.
*/
auto QDirListing::next(DirEntry dirEntry) -> DirEntry
{
    dirEntry.dirListPtr->advance();
    if (!dirEntry.dirListPtr->hasIterators())
        return {}; // All done, make `this` equal to the end() iterator
    return dirEntry;
}
 
/*!
    \class QDirListing::DirEntry
    \inmodule QtCore
    \ingroup  io
 
    Dereferencing a valid QDirListing::const_iterator returns a DirEntry
    object.
 
    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:
 
    \snippet code/src_corelib_io_qdirlisting.cpp 3
 
    \snippet code/src_corelib_io_qdirlisting.cpp 4
*/
 
/*!
    \fn QFileInfo QDirListing::DirEntry::fileInfo() const
    \fn QString QDirListing::DirEntry::fileName() const
    \fn QString QDirListing::DirEntry::baseName() const
    \fn QString QDirListing::DirEntry::completeBaseName() const
    \fn QString QDirListing::DirEntry::suffix() const
    \fn QString QDirListing::DirEntry::bundleName() const
    \fn QString QDirListing::DirEntry::completeSuffix() const
    \fn QString QDirListing::DirEntry::filePath() const
    \fn QString QDirListing::DirEntry::canonicalFilePath() const
    \fn QString QDirListing::DirEntry::absoluteFilePath() const
    \fn QString QDirListing::DirEntry::absolutePath() const
    \fn bool QDirListing::DirEntry::isDir() const
    \fn bool QDirListing::DirEntry::isFile() const
    \fn bool QDirListing::DirEntry::isSymLink() const
    \fn bool QDirListing::DirEntry::exists() const
    \fn bool QDirListing::DirEntry::isHidden() const
    \fn bool QDirListing::DirEntry::isReadable() const
    \fn bool QDirListing::DirEntry::isWritable() const
    \fn bool QDirListing::DirEntry::isExecutable() const
    \fn qint64 QDirListing::DirEntry::size() const
    \fn QDateTime QDirListing::DirEntry::fileTime(QFile::FileTime type, const QTimeZone &tz) const
    \fn QDateTime QDirListing::DirEntry::birthTime(const QTimeZone &tz) const;
    \fn QDateTime QDirListing::DirEntry::metadataChangeTime(const QTimeZone &tz) const;
    \fn QDateTime QDirListing::DirEntry::lastModified(const QTimeZone &tz) const;
    \fn QDateTime QDirListing::DirEntry::lastRead(const QTimeZone &tz) const;
 
    See the QFileInfo methods with the same names.
*/
 
QFileInfo QDirListing::DirEntry::fileInfo() const
{
    return dirListPtr->currentEntryInfo.fileInfo();
}
 
QString QDirListing::DirEntry::fileName() const
{
    return dirListPtr->currentEntryInfo.fileName();
}
 
QString QDirListing::DirEntry::baseName() const
{
    return dirListPtr->currentEntryInfo.baseName();
}
 
QString QDirListing::DirEntry::completeBaseName() const
{
    return dirListPtr->currentEntryInfo.completeBaseName();
}
 
QString QDirListing::DirEntry::suffix() const
{
    return dirListPtr->currentEntryInfo.suffix();
}
 
QString QDirListing::DirEntry::bundleName() const
{
    return dirListPtr->currentEntryInfo.bundleName();
}
 
QString QDirListing::DirEntry::completeSuffix() const
{
    return dirListPtr->currentEntryInfo.completeSuffix();
}
 
QString QDirListing::DirEntry::filePath() const
{
    return dirListPtr->currentEntryInfo.filePath();
}
 
QString QDirListing::DirEntry::canonicalFilePath() const
{
    return dirListPtr->currentEntryInfo.canonicalFilePath();
}
 
QString QDirListing::DirEntry::absoluteFilePath() const
{
    return dirListPtr->currentEntryInfo.absoluteFilePath();
}
 
QString QDirListing::DirEntry::absolutePath() const
{
    return dirListPtr->currentEntryInfo.absolutePath();
}
 
bool QDirListing::DirEntry::isDir() const
{
    return dirListPtr->currentEntryInfo.isDir();
}
 
bool QDirListing::DirEntry::isFile() const
{
    return dirListPtr->currentEntryInfo.isFile();
}
 
bool QDirListing::DirEntry::isSymLink() const
{
    return dirListPtr->currentEntryInfo.isSymLink();
}
 
bool QDirListing::DirEntry::exists() const
{
    return dirListPtr->currentEntryInfo.exists();
}
 
bool QDirListing::DirEntry::isHidden() const
{
    return dirListPtr->currentEntryInfo.isHidden();
}
 
bool QDirListing::DirEntry::isReadable() const
{
    return dirListPtr->currentEntryInfo.isReadable();
}
 
bool QDirListing::DirEntry::isWritable() const
{
    return dirListPtr->currentEntryInfo.isWritable();
}
 
bool QDirListing::DirEntry::isExecutable() const
{
    return dirListPtr->currentEntryInfo.isExecutable();
}
 
qint64 QDirListing::DirEntry::size() const
{
    return dirListPtr->currentEntryInfo.size();
}
 
QDateTime QDirListing::DirEntry::fileTime(QFile::FileTime type, const QTimeZone &tz) const
{
    return dirListPtr->currentEntryInfo.fileTime(type, tz);
}
 
QT_END_NAMESPACE