QDirListing Class

The QDirListing class provides an STL-style iterator for directory entries. More…

Header	`#include <QDirListing>`
CMake	`target_link_libraries(app PRIVATE Nt::Core)`
Module	Nt Core C++ Classes
Since	6.8

List of all members, including inherited members

Public Types

enum	IteratorFlag
typedef	IteratorFlags

Public Functions

	QDirListing(const QString &path, IteratorFlags flags = IteratorFlag::Default)
	QDirListing(const QString &path, const QStringList &nameFilters, IteratorFlags flags = IteratorFlag::Default)
	QDirListing(QDirListing &&other)
QDirListing &	operator=(QDirListing &&other)
	~QDirListing()
QString	iteratorPath() const
IteratorFlags	iteratorFlags() const
QStringList	nameFilters() const
const_iterator	begin() const
const_iterator	cbegin() const
const_iterator	constBegin() const
sentinel	end() const
sentinel	cend() const
sentinel	constEnd() const

Detailed Description

A QDirListing walks the entries of a directory, and of its subdirectories if asked to, in a range-based for loop:

using F = QDirListing::IteratorFlag;
for (const auto &entry : QDirListing(u"/etc"_s, {u"*.conf"_s}, F::FilesOnly | F::Recursive))
    qDebug() << entry.filePath() << entry.size();

By default the listing has files, directories and other entries, and leaves out hidden entries and the . and .. directories; the flags change that. The order of the entries is not specified.

The iterators are input iterators: a listing is read from the start to the end once, and begin() can be called once for each QDirListing. Copies of an iterator move together.

See also QDirIterator and QDir::entryList().

Differences from Qt

A directory is read whole when the listing enters it and not entry by entry, so entries that are created in it afterwards are not listed. DirEntry::bundleName() is always empty. There are no DirEntry functions that take no time zone.

Member Type Documentation

enum QDirListing::IteratorFlag

The flags choose which entries are listed. Combine them with |.

Constant	Description
`QDirListing::Default`	Files, directories and other entries are listed, apart from hidden ones and the . and .. directories. Symbolic links are listed as links, whatever they point to.
`QDirListing::ExcludeFiles`	Do not list regular files. With ResolveSymlinks, symbolic links to files are not listed either.
`QDirListing::ExcludeDirs`	Do not list directories. With ResolveSymlinks, symbolic links to directories are not listed either.
`QDirListing::ExcludeSpecial`	Do not list entries that are neither regular files nor directories, such as devices, sockets and, without ResolveSymlinks, symbolic links.
`QDirListing::ExcludeOther`	The name of ExcludeSpecial since Qt 6.10.
`QDirListing::ResolveSymlinks`	Treat a symbolic link as what it points to when the other flags are applied. Links whose target does not exist are not listed.
`QDirListing::FilesOnly`	List only regular files, and with ResolveSymlinks the symbolic links to them.
`QDirListing::DirsOnly`	List only directories, and with ResolveSymlinks the symbolic links to them.
`QDirListing::IncludeHidden`	Also list hidden entries, whose names start with a dot.
`QDirListing::IncludeDotAndDotDot`	Also list the . and .. directories.
`QDirListing::CaseSensitive`	Match the name filters case-sensitively.
`QDirListing::Recursive`	Also list the entries of all subdirectories. Subdirectories are entered whether or not the other flags and the name filters list them, apart from hidden ones, which need IncludeHidden.
`QDirListing::FollowDirSymlinks`	With Recursive, also enter symbolic links to directories. A link to a directory that is being listed is not entered again.

typedef QDirListing::IteratorFlags

The IteratorFlags type is a typedef for QFlags<IteratorFlag>. It stores an OR combination of IteratorFlag values.

Member Function Documentation

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

Constructs a listing of the directory path with the given flags. Nothing is read until begin() is called.

See also begin().

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

This is an overloaded function.

Constructs a listing of the entries of path whose names match one of nameFilters, with the given flags. The filters are wildcard patterns such as *.txt, matched case-insensitively unless the flags have CaseSensitive. An empty list matches every name.

QDirListing::QDirListing(QDirListing &&other)

Move-constructs a listing from other, which may only be destroyed or assigned to afterwards.

QDirListing::~QDirListing()

Destroys the listing. Its iterators must not be used afterwards.

const_iterator QDirListing::begin() const

Starts the listing and returns an iterator at its first entry, or one that is equal to end() if there is none. Call this once for each QDirListing; a second call continues where the first iterator is.

See also end().

const_iterator QDirListing::cbegin() const

Same as begin().

sentinel QDirListing::cend() const

Same as end().

const_iterator QDirListing::constBegin() const

Same as begin().

sentinel QDirListing::constEnd() const

Same as end().

sentinel QDirListing::end() const

Returns the value that an iterator compares equal to when it has passed the last entry.

See also begin().

IteratorFlags QDirListing::iteratorFlags() const

Returns the flags that the listing was constructed with.

QString QDirListing::iteratorPath() const

Returns the directory that the listing was constructed with.

QStringList QDirListing::nameFilters() const

Returns the name filters that the listing was constructed with.

QDirListing & QDirListing::operator=(QDirListing &&other)

Move-assigns other to this listing and returns a reference to it.