En esta página

QDirListing Class

La clase QDirListing proporciona un iterador al estilo de la STL para las entradas de los directorios. Más información...

Encabezado: #include <QDirListing>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Desde: Qt 6.8

Tipos públicos

class DirEntry
(since 6.8) class const_iterator
(since 6.8) class sentinel
enum class IteratorFlag { Default, ExcludeFiles, ExcludeDirs, ExcludeOther, ResolveSymlinks, …, FollowDirSymlinks }
flags IteratorFlags

Funciones públicas

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

Descripción detallada

Puedes utilizar QDirListing para recorrer las entradas de un directorio una por una. Es similar a QDir::entryList() y QDir::entryInfoList(), pero, dado que muestra las entradas una por una en lugar de todas a la vez, se adapta mejor y resulta más adecuado para directorios de gran tamaño. También permite mostrar el contenido de los directorios de forma recursiva y seguir enlaces simbólicos. A diferencia de QDir::entryList(), QDirListing no admite la ordenación.

El constructor de QDirListing toma como argumento una cadena que representa la ruta del directorio. A continuación se explica cómo recorrer todas las entradas de forma recursiva:

using ItFlag = QDirListing::IteratorFlag;
for (const auto &dirEntry: QDirListing(u"/etc"_s, ItFlag::Recursive)) {
    qDebug() << dirEntry.filePath();
   // /etc/.
    // /etc/..
    // /etc/X11
    // /etc/X11/fs
    // ...
}

A continuación se explica cómo buscar y leer todos los archivos normales filtrados por nombre, de forma recursiva:

utilizando F = QDirListing::IteratorFlag;
QDirListing dirList(u"/sys"_s, QStringList{u"scaling_cur_freq"_s}, F::FilesOnly | F::Recursive);
for (const auto &dirEntry: dirList) {
    QFile f(dirEntry.filePath());
    if (f.open(QIODevice::ReadOnly))
        qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
}

A continuación se explica cómo listar solo los archivos normales, de forma recursiva:

using F = QDirListing::IteratorFlag;
const auto flags = F::FilesOnly | F::Recursive;
for (const auto &dirEntry : QDirListing(u"/etc"_s, flags)) {
    // ...
}

A continuación se explica cómo mostrar únicamente los archivos normales y los enlaces simbólicos a archivos normales, de forma recursiva:

using F = QDirListing::IteratorFlag;
const auto flags = F::FilesOnly | F::Recursive | F::ResolveSymlinks;
for (const auto &dirEntry : QDirListing(u"/etc"_s, flags)) {
    // ...
}

QDirListing::const_iterator imita el modelo std::input_iterator de C++20, es decir, es un iterador de una sola pasada, de solo avance y solo movimiento, que no permite el acceso aleatorio. Se puede utilizar en bucles «for» con rangos (o con algoritmos de rango de C++20 que no requieran iteradores de acceso aleatorio). Al desreferenciar un iterador válido se obtiene un objeto de tipo ` QDirListing::DirEntry `. El sentinela (c) `end()` marca el final de la iteración. Desreferenciar un iterador que sea igual a ` sentinel ` da lugar a un comportamiento indefinido.

QDirListing::DirEntry ofrece un subconjunto de la API de ` QFileInfo` (por ejemplo, `fileName()`, `filePath()`, `exists()`). Internamente, ` DirEntry ` solo construye un objeto ` QFileInfo ` si es necesario, es decir, si la información no ha sido ya obtenida por otras funciones del sistema. Puedes utilizar ` DirEntry::fileInfo()` para obtener un objeto ` QFileInfo`. Por ejemplo:

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

Véase también QDir y QDir::entryList().

Documentación sobre los tipos de miembros

enum class QDirListing::IteratorFlag
flags QDirListing::IteratorFlags

Esta clase de enumeración describe los indicadores que se pueden utilizar para configurar el comportamiento de QDirListing. Los valores de esta enumeración se pueden combinar mediante la operación OR bit a bit.

ConstanteValorDescripción
QDirListing::IteratorFlag::Default0x000000Muestra todas las entradas, es decir, archivos, directorios, enlaces simbólicos —incluidos los enlaces simbólicos rotos (en los que el destino no existe)— y archivos especiales (otros) del sistema; consulta «ExcludeOther» para obtener más detalles. Los archivos y directorios ocultos, así como las entradas especiales « . » y « .. », no se muestran de forma predeterminada.
QDirListing::IteratorFlag::ExcludeFiles0x000004No muestra archivos normales. Cuando se combina con ResolveSymlinks, también se excluirán los enlaces simbólicos a archivos normales.
QDirListing::IteratorFlag::ExcludeDirs0x000008No muestra los directorios. Cuando se combina con ResolveSymlinks, también se excluirán los enlaces simbólicos a directorios.
QDirListing::IteratorFlag::ExcludeOther0x000010[desde la versión 6.10] No mostrar las entradas del sistema de archivos que no sean directorios, archivos normales o enlaces simbólicos.
  • En Unix, una entrada especial (de otro tipo) del sistema de archivos es un FIFO, un socket, un dispositivo de caracteres o un dispositivo de bloques. Para más detalles, consulta la mknod página del manual.
  • En Windows (por razones históricas), los archivos de tipo « .lnk » se consideran entradas especiales (otras) del sistema de archivos.
QDirListing::IteratorFlag::ResolveSymlinks0x000020Filtra los enlaces simbólicos en función del tipo del destino del enlace, en lugar del propio enlace simbólico. Se excluyen los enlaces simbólicos rotos (en los que el destino no existe); establece IncludeBrokenSymlinks para incluirlos. Esta opción se ignora en los sistemas operativos que no admiten enlaces simbólicos.
QDirListing::IteratorFlag::IncludeBrokenSymlinks0x001000[desde la versión 6.11] Muestra los enlaces simbólicos rotos, en los que el destino no existe, independientemente del estado del indicador ResolveSymlinks. Este indicador se ignora en los sistemas operativos que no admiten enlaces simbólicos.
QDirListing::IteratorFlag::FilesOnlyExcludeDirs | ExcludeOtherSolo se mostrarán los archivos normales. Cuando se combina con ResolveSymlinks, también se mostrarán los enlaces simbólicos a archivos.
QDirListing::IteratorFlag::DirsOnlyExcludeFiles | ExcludeOtherSolo se mostrarán los directorios. Cuando se combina con «ResolveSymlinks», también se mostrarán los enlaces simbólicos a directorios.
QDirListing::IteratorFlag::IncludeHidden0x000040Muestra las entradas ocultas. Cuando se combina con Recursive, la iteración se extenderá también a los subdirectorios ocultos.
QDirListing::IteratorFlag::IncludeDotAndDotDot0x000080Muestra las entradas especiales « . » y « .. ».
QDirListing::IteratorFlag::CaseSensitive0x000100Los patrones glob de los filtros de nombre pasados al constructor de « QDirListing » se compararán distinguiendo entre mayúsculas y minúsculas (para más detalles, véase QDir::setNameFilters()).
QDirListing::IteratorFlag::Recursive0x000400Enumera también las entradas de todos los subdirectorios. Cuando se combina con FollowDirSymlinks, también se recorrerán los enlaces simbólicos a directorios.
QDirListing::IteratorFlag::FollowDirSymlinks0x000800Cuando se combina con Recursive, también se recorrerán los enlaces simbólicos a directorios. Los bucles de enlaces simbólicos (p. ej., enlace => . o enlace => ..) se detectan automáticamente y se ignoran.

El tipo IteratorFlags es un typedef para QFlags<IteratorFlag>. Almacena una combinación OR de valores de IteratorFlag.

Documentación de las funciones miembro

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

Crea un objeto `QDirListing` capaz de recorrer ` path`.

Se pueden pasar opciones a través de ` flags ` para controlar cómo se debe recorrer el directorio.

Por defecto, ` flags ` es ` IteratorFlag::Default`.

Véase también IteratorFlags.

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

Crea un objeto `QDirListing` que permite recorrer ` path`.

Se pueden pasar opciones a través de flags para controlar cómo se debe recorrer el directorio. Por defecto, flags es IteratorFlag::Default.

Las entradas de la lista se filtrarán según los patrones de búsqueda de archivos de nameFilters, que se convierten en una expresión regular mediante QRegularExpression::fromWildcard (véase QDir::setNameFilters() para más detalles).

Por ejemplo, se podría utilizar el siguiente iterador para recorrer los archivos de audio:

QDirListing audioFileIt(u"/home/johndoe/"_s, QStringList{u"*.mp3"_s, u"*.wav"_s},
                        QDirListing::IteratorFlag::FilesOnly);

A veces se puede filtrar por nombre de forma más eficiente iterando sobre las entradas con un bucle «range-for», utilizando la comparación de cadenas. Por ejemplo:

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

Véase también IteratorFlags y QDir::setNameFilters().

[noexcept] QDirListing::QDirListing(QDirListing &&other)

Constructor de traslado. Traslada other a este QDirListing.

Nota: El objeto del que se ha realizado el traslado, ` other `, queda en un estado parcialmente formado, en el que las únicas operaciones válidas son la destrucción y la asignación de un nuevo valor.

[noexcept] QDirListing::~QDirListing()

Destruye la « QDirListing ».

QDirListing::const_iterator QDirListing::begin() const

QDirListing::const_iterator QDirListing::cbegin() const

QDirListing::sentinel QDirListing::cend() const

QDirListing::sentinel QDirListing::end() const

(c)begin() devuelve un objeto ` QDirListing::const_iterator ` que se puede utilizar para recorrer las entradas del directorio.

  • Se trata de un iterador de una sola pasada y de avance único (no se pueden recorrer las entradas del directorio en orden inverso)
  • No se puede copiar, solo std::move()d.
  • El valor de retorno del postincremento en objetos que implementan std::input_iterator es parcialmente formado (una copia de un iterador que se ha avanzado desde entonces); las únicas operaciones válidas sobre dicho objeto son la destrucción y la asignación de un nuevo iterador. Por lo tanto, el operador de postincremento avanza el iterador y devuelve void.
  • No permite el acceso aleatorio
  • Se puede utilizar en bucles «for» con rango; o con los algoritmos de `std::ranges` de C++20 que no requieren iteradores de acceso aleatorio
  • La desreferenciación de un iterador válido devuelve un const DirEntry &
  • (c)end() devuelve un QDirListing::sentinel que indica el final de la iteración. Desreferenciar un iterador que se compara como igual a end() es un comportamiento indefinido

Nota: Cada vez que se llama a (c)begin() sobre el mismo objeto QDirListing, el estado interno se restablece y la iteración comienza de nuevo.

(Algunas de las restricciones anteriores vienen dictadas por la implementación de las funciones de la biblioteca del sistema subyacente).

Por ejemplo:

using ItFlag = QDirListing::IteratorFlag;
for (const auto &dirEntry: QDirListing(u"/etc"_s, ItFlag::Recursive)) {
    qDebug() << dirEntry.filePath();
   // /etc/.
    // /etc/..
    // /etc/X11
    // /etc/X11/fs
    // ...
}

A continuación se explica cómo buscar y leer todos los archivos filtrados por nombre, de forma recursiva:

utilizando F = QDirListing::IteratorFlag;
QDirListing dirList(u"/sys"_s, QStringList{u"scaling_cur_freq"_s}, F::FilesOnly | F::Recursive);
for (const auto &dirEntry: dirList) {
    QFile f(dirEntry.filePath());
    if (f.open(QIODevice::ReadOnly))
        qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
}

Nota: Los algoritmos «clásicos» de la STL no admiten iteradores ni centinelas, por lo que es necesario utilizar los algoritmos std::ranges de C++20 para QDirListing, o bien una biblioteca de terceros que ofrezca algoritmos basados en rangos en C++17.

Véase también QDirListing::DirEntry.

QDirListing::IteratorFlags QDirListing::iteratorFlags() const

Devuelve el conjunto de « IteratorFlags » utilizado para construir este « QDirListing ».

QString QDirListing::iteratorPath() const

Devuelve la ruta del directorio utilizada para crear este QDirListing.

QStringList QDirListing::nameFilters() const

Devuelve la lista de filtros de nombres de archivo glob utilizados para construir este QDirListing.

[noexcept] QDirListing &QDirListing::operator=(QDirListing &&other)

La operación «Move-assigns» asigna other a este QDirListing.

Nota: El objeto del que se ha realizado el traslado, other, pasa a un estado parcialmente formado, en el que las únicas operaciones válidas son la destrucción y la asignación de un nuevo valor.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.