#include <qdirlisting.h>

Collaboration diagram for QDirListing:

Classes
class	const_iterator
class	DirEntry
	\inmodule QtCore More...
class	sentinel
	\typealias QDirListing::const_iterator::reference More...

Public Types
enum class	IteratorFlag { Default = 0x000000 , ExcludeFiles = 0x000004 , ExcludeDirs = 0x000008 , ExcludeOther = 0x000010 , ResolveSymlinks = 0x000020 , FilesOnly = ExcludeDirs \| ExcludeOther , DirsOnly = ExcludeFiles \| ExcludeOther , IncludeHidden = 0x000040 , IncludeDotAndDotDot = 0x000080 , CaseSensitive = 0x000100 , Recursive = 0x000400 , FollowDirSymlinks = 0x000800 , IncludeBrokenSymlinks = 0x001000 , NoNameFiltersForDirs = 0x040000 }
	This enum class describes flags that can be used to configure the behavior of QDirListing. More...

Public Member Functions
Q_CORE_EXPORT	QDirListing (const QString &path, IteratorFlags flags=IteratorFlag::Default)
	Constructs a QDirListing that can iterate over path.
Q_CORE_EXPORT	QDirListing (const QString &path, const QStringList &nameFilters, IteratorFlags flags=IteratorFlag::Default)
	Constructs a QDirListing that can iterate over path.
	QDirListing (QDirListing &&other) noexcept
void	swap (QDirListing &other) noexcept
Q_CORE_EXPORT	~QDirListing ()
	Destroys the QDirListing.
Q_CORE_EXPORT QString	iteratorPath () const
	Returns the directory path used to construct this QDirListing.
Q_CORE_EXPORT IteratorFlags	iteratorFlags () const
	Returns the set of IteratorFlags used to construct this QDirListing.
Q_CORE_EXPORT QStringList	nameFilters () const
	Returns the list of file name glob filters used to construct this QDirListing.
Q_CORE_EXPORT const_iterator	begin () const
const_iterator	cbegin () const
sentinel	end () const
sentinel	cend () const
const_iterator	constBegin () const
sentinel	constEnd () const

Detailed Description

Definition at line 26 of file qdirlisting.h.

Member Enumeration Documentation

◆ IteratorFlag

enum class QDirListing::IteratorFlag

strong

This enum class describes flags that can be used to configure the behavior of QDirListing.

\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:

        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 */) { /* ... */ }
        }

See also: QDir, QDir::entryList()

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 (other) system files, see ExcludeOther for details. Hidden files and directories and the special entries {.} and {..} 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 ExcludeOther [since 6.10] Don't list file system entries that are not directories, regular files, or symbolic links. \list

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}{mknod} manual page.
On Windows (for historical reasons) .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 IncludeBrokenSymlinks [since 6.11] 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 {.} and {..} 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

Enumerator
Default
ExcludeFiles
ExcludeDirs
ExcludeOther
ResolveSymlinks
FilesOnly
DirsOnly
IncludeHidden
IncludeDotAndDotDot
CaseSensitive
Recursive
FollowDirSymlinks
IncludeBrokenSymlinks
NoNameFiltersForDirs

Definition at line 29 of file qdirlisting.h.

Constructor & Destructor Documentation

◆ QDirListing() [1/3]

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

explicit

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

Definition at line 452 of file qdirlisting.cpp.

References QDirListingPrivate::init().

Here is the call graph for this function:

◆ QDirListing() [2/3]

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

explicit

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, 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:

QDirListing audioFileIt(u"/home/johndoe/"_s, QStringList{u"*.mp3"_s, u"*.wav"_s},

QDirListing::IteratorFlag::FilesOnly);

Sometimes you can filter by name more efficiently by iterating over the entries with a range-for loop, using string comparison. For example:

        using F = QDirListing::IteratorFlag;
        const auto flags = F::FilesOnly | F::Recursive | F::ResolveSymlinks;
        for (const auto &dirEntry : QDirListing(u"/usr"_s, flags)) {
            // Faster than using name filters, filter ".txt" and ".html" files
            // using QString API
            const QString fileName = dirEntry.fileName();
            if (fileName.endsWith(".txt"_L1) || fileName.endsWith(".html"_L1)) {
                // ...
            }
        }
    }

See also: IteratorFlags, QDir::setNameFilters()

Definition at line 483 of file qdirlisting.cpp.

References QDirListingPrivate::init().

Here is the call graph for this function:

◆ QDirListing() [3/3]

QDirListing::QDirListing ( QDirListing && other )

inlinenoexcept

Definition at line 55 of file qdirlisting.h.

◆ ~QDirListing()

QDirListing::~QDirListing ( )

Destroys the QDirListing.

Definition at line 515 of file qdirlisting.cpp.

Member Function Documentation

◆ begin()

QDirListing::const_iterator QDirListing::begin ( ) const

\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

Definition at line 632 of file qdirlisting.cpp.

References QDirListingPrivate::beginIterating(), and QDirListing::const_iterator::operator++().

Here is the call graph for this function:

◆ cbegin()

const_iterator QDirListing::cbegin ( ) const

inline

Definition at line 145 of file qdirlisting.h.

◆ cend()

sentinel QDirListing::cend ( ) const

inline

Definition at line 147 of file qdirlisting.h.

References end().

Here is the call graph for this function:

◆ constBegin()

const_iterator QDirListing::constBegin ( ) const

inline

Definition at line 150 of file qdirlisting.h.

◆ constEnd()

sentinel QDirListing::constEnd ( ) const

inline

Definition at line 151 of file qdirlisting.h.

References end().

Here is the call graph for this function:

◆ end()

sentinel QDirListing::end ( ) const

inline

Definition at line 146 of file qdirlisting.h.

Referenced by cend(), and constEnd().

Here is the caller graph for this function:

◆ iteratorFlags()

QDirListing::IteratorFlags QDirListing::iteratorFlags ( ) const

Returns the set of IteratorFlags used to construct this QDirListing.

Definition at line 531 of file qdirlisting.cpp.

◆ iteratorPath()

QString QDirListing::iteratorPath ( ) const

Returns the directory path used to construct this QDirListing.

Definition at line 523 of file qdirlisting.cpp.

◆ nameFilters()

QStringList QDirListing::nameFilters ( ) const

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

Definition at line 540 of file qdirlisting.cpp.

◆ swap()

void QDirListing::swap ( QDirListing & other )

inlinenoexcept

Definition at line 59 of file qdirlisting.h.

The documentation for this class was generated from the following files:

qtbase/src/corelib/io/qdirlisting.h (a64bc279969b2cf8da6d0c07bf01683e57a8a30c)
qtbase/src/corelib/io/qdirlisting.cpp (a64bc279969b2cf8da6d0c07bf01683e57a8a30c)

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ IteratorFlag

Constructor & Destructor Documentation

◆ QDirListing() [1/3]

◆ QDirListing() [2/3]

◆ QDirListing() [3/3]

◆ ~QDirListing()

Member Function Documentation

◆ begin()

◆ cbegin()

◆ cend()

◆ constBegin()

◆ constEnd()

◆ end()

◆ iteratorFlags()

◆ iteratorPath()

◆ nameFilters()

◆ swap()