Revision control
++ // 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
++ 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