#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 }
	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

Friends
class	QDir

class	QDirPrivate

class	QDirIteratorPrivate

class	QAbstractFileEngine

class	QFileInfoGatherer

Detailed Description

Definition at line 24 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 files, directories and symbolic links, including broken symlinks (where the target doesn't exist). 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 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. With this flag, broken symbolic links (where the target doesn't exist) are excluded. 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.

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

Definition at line 27 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 561 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 (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, QDir::setNameFilters()

Definition at line 585 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 49 of file qdirlisting.h.

◆ ~QDirListing()

QDirListing::~QDirListing ( )

Destroys the QDirListing.

Definition at line 639 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 756 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 139 of file qdirlisting.h.

◆ cend()

sentinel QDirListing::cend ( ) const

inline

Definition at line 141 of file qdirlisting.h.

References end().

Here is the call graph for this function:

◆ constBegin()

const_iterator QDirListing::constBegin ( ) const

inline

Definition at line 144 of file qdirlisting.h.

◆ constEnd()

sentinel QDirListing::constEnd ( ) const

inline

Definition at line 145 of file qdirlisting.h.

References end().

Here is the call graph for this function:

◆ end()

sentinel QDirListing::end ( ) const

inline

Definition at line 140 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 655 of file qdirlisting.cpp.

◆ iteratorPath()

QString QDirListing::iteratorPath ( ) const

Returns the directory path used to construct this QDirListing.

Definition at line 647 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 664 of file qdirlisting.cpp.

◆ swap()

void QDirListing::swap ( QDirListing & other )

inlinenoexcept

Definition at line 53 of file qdirlisting.h.

Friends And Related Symbol Documentation

◆ QAbstractFileEngine

friend class QAbstractFileEngine

friend

Definition at line 163 of file qdirlisting.h.

◆ QDir

friend class QDir

friend

Definition at line 160 of file qdirlisting.h.

◆ QDirIteratorPrivate

friend class QDirIteratorPrivate

friend

Definition at line 162 of file qdirlisting.h.

◆ QDirPrivate

friend class QDirPrivate

friend

Definition at line 161 of file qdirlisting.h.

◆ QFileInfoGatherer

friend class QFileInfoGatherer

friend

Definition at line 164 of file qdirlisting.h.

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

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

Classes

Public Types

Public Member Functions

Friends

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()

Friends And Related Symbol Documentation

◆ QAbstractFileEngine

◆ QDir

◆ QDirIteratorPrivate

◆ QDirPrivate

◆ QFileInfoGatherer