QDirIterator Class Reference

The QDirIterator class provides an iterator for directory entrylists. More...

#include <qdiriterator.h>

Public Types
enum	IteratorFlag { NoIteratorFlags = 0x0, FollowSymlinks = 0x1, Subdirectories = 0x2 }
	This enum describes flags that you can combine to configure the behavior of QDirIterator. More...

Public Functions
QFileInfo	fileInfo () const
	Returns a QFileInfo for the current directory entry. More...
QString	fileName () const
	Returns the file name for the current directory entry, without the path prepended. More...
QString	filePath () const
	Returns the full file path for the current directory entry. More...
bool	hasNext () const
	Returns true if there is at least one more entry in the directory; otherwise, false is returned. More...
QString	next ()
	Advances the iterator to the next entry, and returns the file path of this new entry. More...
QString	path () const
	Returns the base directory of the iterator. More...
	QDirIterator (const QDir &dir, IteratorFlags flags=NoIteratorFlags)
	Constructs a QDirIterator that can iterate over dir's entrylist, using dir's name filters and regular filters. More...
	QDirIterator (const QString &path, IteratorFlags flags=NoIteratorFlags)
	Constructs a QDirIterator that can iterate over path. More...
	QDirIterator (const QString &path, QDir::Filters filter, IteratorFlags flags=NoIteratorFlags)
	Constructs a QDirIterator that can iterate over path, with no name filtering and filters for entry filtering. More...
	QDirIterator (const QString &path, const QStringList &nameFilters, QDir::Filters filters=QDir::NoFilter, IteratorFlags flags=NoIteratorFlags)
	Constructs a QDirIterator that can iterate over path, using nameFilters and filters. More...
virtual	~QDirIterator ()
	Destroys the QDirIterator. More...

Properties
QScopedPointer< QDirIteratorPrivate >	d

Friends
class	QDir

Detailed Description

The QDirIterator class provides an iterator for directory entrylists.

Since

4.3

You can use QDirIterator 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(), QDirIterator does not support sorting.

The QDirIterator constructor takes a QDir or a directory as argument. After construction, the iterator is located before the first directory entry. Here's how to iterate over all the entries sequentially:

QDirIterator it("/etc", QDirIterator::Subdirectories);
while (it.hasNext()) {
    qDebug() << it.next();

    // /etc/.
    // /etc/..
    // /etc/X11
    // /etc/X11/fs
    // ...
}

The next() function returns the path to the next directory entry and advances the iterator. You can also call filePath() to get the current file path without advancing the iterator. The fileName() function returns only the name of the file, similar to how QDir::entryList() works. You can also call fileInfo() to get a QFileInfo for the current entry.

Unlike Qt's container iterators, QDirIterator is uni-directional (i.e., you cannot iterate directories in reverse order) and does not allow random access.

QDirIterator works with all supported file engines, and is implemented using QAbstractFileEngineIterator.

See also

QDir, QDir::entryList(), QAbstractFileEngineIterator

Definition at line 54 of file qdiriterator.h.

Enumerations

IteratorFlag

enum QDirIterator::IteratorFlag

This enum describes flags that you can combine to configure the behavior of QDirIterator.

• NoIteratorFlags The default value, representing no flags. The iterator will return entries for the assigned path.

• Subdirectories List entries inside all subdirectories as well.

• FollowSymlinks When combined with Subdirectories, this flag enables iterating through all subdirectories of the assigned path, following all symbolic links. Symbolic link loops (e.g., "link" => "." or "link" => "..") are automatically detected and ignored.

Enumerator
NoIteratorFlags
FollowSymlinks
Subdirectories

Definition at line 56 of file qdiriterator.h.

                      {
        NoIteratorFlags = 0x0,
        FollowSymlinks = 0x1,
        Subdirectories = 0x2
    };

Constructors and Destructors

QDirIterator() [1/4]

QDirIterator::QDirIterator	(	const QDir &	dir,
		IteratorFlags	flags = NoIteratorFlags
	)

Constructs a QDirIterator that can iterate over dir's entrylist, using dir's name filters and regular filters.

You can pass options via flags to decide how the directory should be iterated.

By default, flags is NoIteratorFlags, which provides the same behavior as in QDir::entryList().

The sorting in dir is ignored.

Note

To list symlinks that point to non existing files, QDir::System must be passed to the flags.

See also

hasNext(), next(), IteratorFlags

Definition at line 424 of file qdiriterator.cpp.

{
    // little trick to get hold of the QDirPrivate while there is no API on QDir to give it to us
    class MyQDir : public QDir { public: const QDirPrivate *priv() const { return d_ptr.constData(); } };
    const QDirPrivate *other = static_cast<const MyQDir*>(&dir)->priv();
    d.reset(new QDirIteratorPrivate(other->dirEntry, other->nameFilters, other->filters, flags, !other->fileEngine.isNull()));
}

QDirIterator() [2/4]

QDirIterator::QDirIterator	(	const QString &	path,
		IteratorFlags	flags = NoIteratorFlags
	)

Constructs a QDirIterator that can iterate over path.

You can pass options via flags to decide how the directory should be iterated.

By default, flags is NoIteratorFlags, which provides the same behavior as in QDir::entryList().

Note

To list symlinks that point to non existing files, QDir::System must be passed to the flags.

See also

hasNext(), next(), IteratorFlags

Definition at line 462 of file qdiriterator.cpp.

    : d(new QDirIteratorPrivate(QFileSystemEntry(path), QStringList(), QDir::NoFilter, flags))
{
}

QDirIterator() [3/4]

QDirIterator::QDirIterator	(	const QString &	path,
		QDir::Filters	filters,
		IteratorFlags	flags = NoIteratorFlags
	)

Constructs a QDirIterator that can iterate over path, with no name filtering and filters for entry filtering.

You can pass options via flags to decide how the directory should be iterated.

By default, filters is QDir::NoFilter, and flags is NoIteratorFlags, which provides the same behavior as in QDir::entryList().

Note

To list symlinks that point to non existing files, QDir::System must be passed to the flags.

See also

hasNext(), next(), IteratorFlags

Definition at line 445 of file qdiriterator.cpp.

    : d(new QDirIteratorPrivate(QFileSystemEntry(path), QStringList(), filters, flags))
{
}

QDirIterator() [4/4]

QDirIterator::QDirIterator	(	const QString &	path,
		const QStringList &	nameFilters,
		QDir::Filters	filters = QDir::NoFilter,
		IteratorFlags	flags = NoIteratorFlags
	)

Constructs a QDirIterator that can iterate over path, using nameFilters and filters.

You can pass options via flags to decide how the directory should be iterated.

By default, flags is NoIteratorFlags, which provides the same behavior as QDir::entryList().

Note

To list symlinks that point to non existing files, QDir::System must be passed to the flags.

See also

hasNext(), next(), IteratorFlags

Definition at line 480 of file qdiriterator.cpp.

    : d(new QDirIteratorPrivate(QFileSystemEntry(path), nameFilters, filters, flags))
{
}

~QDirIterator()

QDirIterator::~QDirIterator ( )

virtual

Destroys the QDirIterator.

Definition at line 489 of file qdiriterator.cpp.

{
}

Functions

fileInfo()

QFileInfo QDirIterator::fileInfo

(

)

const

Returns a QFileInfo for the current directory entry.

See also

filePath(), fileName()

Definition at line 557 of file qdiriterator.cpp.

Referenced by QNetworkDiskCache::expire(), QDirPrivate::initFileLists(), and QSslSocketPrivate::systemCaCertificates().

{
    return d->currentFileInfo;
}

fileName()

QString QDirIterator::fileName

(

)

const

Returns the file name for the current directory entry, without the path prepended.

This function is convenient when iterating a single directory. When using the QDirIterator::Subdirectories flag, you can use filePath() to get the full path.

See also

filePath(), fileInfo()

Definition at line 537 of file qdiriterator.cpp.

Referenced by QAbstractFileEngine::entryList(), and qmlFilesInDirectory().

{
    return d->currentFileInfo.fileName();
}

filePath()

QString QDirIterator::filePath

(

)

const

Returns the full file path for the current directory entry.

See also

fileInfo(), fileName()

Definition at line 547 of file qdiriterator.cpp.

Referenced by next().

{
    return d->currentFileInfo.filePath();
}

hasNext()

bool QDirIterator::hasNext

(

)

const

Returns true if there is at least one more entry in the directory; otherwise, false is returned.

See also

next(), fileName(), filePath(), fileInfo()

Definition at line 515 of file qdiriterator.cpp.

Referenced by QSslSocketPrivate::ensureCiphersAndCertsLoaded(), QAbstractFileEngine::entryList(), QNetworkDiskCache::expire(), QSslCertificate::fromPath(), QDirPrivate::initFileLists(), qmlFilesInDirectory(), QFileSystemModel::remove(), and QSslSocketPrivate::systemCaCertificates().

{
    if (d->engine)
        return !d->fileEngineIterators.isEmpty();
    else
#ifndef QT_NO_FILESYSTEMITERATOR
        return !d->nativeIterators.isEmpty();
#else
        return false;
#endif
}

next()

QString QDirIterator::next

(

)

Advances the iterator to the next entry, and returns the file path of this new entry.

If hasNext() returns false, this function does nothing, and returns a null QString.

You can call fileName() or filePath() to get the current entry file name or path, or fileInfo() to get a QFileInfo for the current entry.

See also

hasNext(), fileName(), filePath(), fileInfo()

Definition at line 503 of file qdiriterator.cpp.

Referenced by QAbstractFileEngine::entryList(), QNetworkDiskCache::expire(), QSslCertificate::fromPath(), QDirPrivate::initFileLists(), qmlFilesInDirectory(), QFileSystemModel::remove(), and QSslSocketPrivate::systemCaCertificates().

{
    d->advance();
    return filePath();
}

path()

QString QDirIterator::path

(

)

const

Returns the base directory of the iterator.

Definition at line 565 of file qdiriterator.cpp.

{
    return d->dirEntry.filePath();
}

Friends and Related Functions

QDir

friend class QDir

friend

Definition at line 88 of file qdiriterator.h.

Properties

d

QScopedPointer<QDirIteratorPrivate> QDirIterator::d

private

Definition at line 87 of file qdiriterator.h.

Referenced by fileInfo(), fileName(), filePath(), hasNext(), next(), and path().

---

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

• /src/corelib/io/qdiriterator.h
• /src/corelib/io/qdiriterator.cpp