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 |
- Lista de todos los miembros, incluidos los miembros heredados
- QDirListing forma parte de Entrada/Salida y Redes.
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.
| Constante | Valor | Descripción |
|---|---|---|
QDirListing::IteratorFlag::Default | 0x000000 | Muestra 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::ExcludeFiles | 0x000004 | No muestra archivos normales. Cuando se combina con ResolveSymlinks, también se excluirán los enlaces simbólicos a archivos normales. |
QDirListing::IteratorFlag::ExcludeDirs | 0x000008 | No muestra los directorios. Cuando se combina con ResolveSymlinks, también se excluirán los enlaces simbólicos a directorios. |
QDirListing::IteratorFlag::ExcludeOther | 0x000010 | [desde la versión 6.10] No mostrar las entradas del sistema de archivos que no sean directorios, archivos normales o enlaces simbólicos.
|
QDirListing::IteratorFlag::ResolveSymlinks | 0x000020 | Filtra 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::IncludeBrokenSymlinks | 0x001000 | [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::FilesOnly | ExcludeDirs | ExcludeOther | Solo se mostrarán los archivos normales. Cuando se combina con ResolveSymlinks, también se mostrarán los enlaces simbólicos a archivos. |
QDirListing::IteratorFlag::DirsOnly | ExcludeFiles | ExcludeOther | Solo se mostrarán los directorios. Cuando se combina con «ResolveSymlinks», también se mostrarán los enlaces simbólicos a directorios. |
QDirListing::IteratorFlag::IncludeHidden | 0x000040 | Muestra las entradas ocultas. Cuando se combina con Recursive, la iteración se extenderá también a los subdirectorios ocultos. |
QDirListing::IteratorFlag::IncludeDotAndDotDot | 0x000080 | Muestra las entradas especiales « . » y « .. ». |
QDirListing::IteratorFlag::CaseSensitive | 0x000100 | Los 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::Recursive | 0x000400 | Enumera 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::FollowDirSymlinks | 0x000800 | Cuando 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_iteratores 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 devuelvevoid. - 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.