QDirIterator Class | Qt Core (original) (raw)

Detailed Description

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:

Here's how to find and read all files filtered by name, recursively:

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

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

Note: This class is deprecated and may be removed in a Qt release. Use QDirListing instead.

Member Function Documentation

QDirIterator::QDirIterator(const QDir &dir, QDirIterator::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(), and IteratorFlags.

QDirIterator::QDirIterator(const QString &path, QDirIterator::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(), and IteratorFlags.

QDirIterator::QDirIterator(const QString &path, QDir::Filters filters, QDirIterator::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(), and IteratorFlags.

QDirIterator::QDirIterator(const QString &path, const QStringList &nameFilters, QDir::Filters filters = QDir::NoFilter, QDirIterator::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().

For example, the following iterator could be used to iterate over audio files:

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

See also hasNext(), next(), IteratorFlags, and QDir::setNameFilters().

[noexcept] QDirIterator::~QDirIterator()

Destroys the QDirIterator.

QFileInfo QDirIterator::fileInfo() const

Returns a QFileInfo for the current directory entry.

See also filePath() and 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() and fileInfo().

QString QDirIterator::filePath() const

Returns the full file path for the current directory entry.

See also fileInfo() and fileName().

bool QDirIterator::hasNext() const

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

See also next(), nextFileInfo(), fileName(), filePath(), and fileInfo().

QString QDirIterator::next()

Advances the iterator to the next entry, and returns the file path of this new entry. You should first check hasNext() before using this method, to avoid unexpected results.

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

Call nextFileInfo() instead of next() if you're interested in the QFileInfo.

See also hasNext(), nextFileInfo(), fileName(), filePath(), and fileInfo().

[since 6.3] QFileInfo QDirIterator::nextFileInfo()

Advances the iterator to the next entry, and returns the file info of this new entry. You should first check hasNext() before using this method, to avoid unexpected results.

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

Call next() instead of nextFileInfo() when all you need is the filePath().

This function was introduced in Qt 6.3.

See also hasNext(), fileName(), filePath(), and fileInfo().

QString QDirIterator::path() const

Returns the base directory of the iterator.