1// Copyright (C) 2016 The Qt Company Ltd.
2// Copyright (C) 2024 Ahmad Samir <a.samirh78@gmail.com>
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
4// Qt-Security score:significant reason:default
5
6#ifndef QDIRLISTING_H
7#define QDIRLISTING_H
8
9#include <QtCore/qtdeprecationmarkers.h>
10#include <QtCore/qfiledevice.h>
11#include <QtCore/qflags.h>
12#include <QtCore/qtclasshelpermacros.h>
13#include <QtCore/qtcoreexports.h>
14#include <QtCore/qdatetime.h>
15
16#include <iterator>
17#include <utility>
18
19QT_BEGIN_NAMESPACE
20
21class QDirListingPrivate;
22class QFileInfo;
23class QDir;
24class QTimeZone;
25
26class QDirListing
27{
28public:
29 enum class IteratorFlag {
30 Default = 0x000000,
31 ExcludeFiles = 0x000004,
32 ExcludeDirs = 0x000008,
33#if QT_DEPRECATED_SINCE(6, 14)
34 ExcludeSpecial QT_DEPRECATED_VERSION_X_6_14("Use ExcludeOther instead.") = 0x000010,
35#endif
36 ExcludeOther = 0x000010,
37 ResolveSymlinks = 0x000020,
38 FilesOnly = ExcludeDirs | ExcludeOther,
39 DirsOnly = ExcludeFiles | ExcludeOther,
40 IncludeHidden = 0x000040,
41 IncludeDotAndDotDot = 0x000080,
42 CaseSensitive = 0x000100,
43 Recursive = 0x000400,
44 FollowDirSymlinks = 0x000800,
45 };
46 Q_DECLARE_FLAGS(IteratorFlags, IteratorFlag)
47
48 Q_CORE_EXPORT explicit QDirListing(const QString &path,
49 IteratorFlags flags = IteratorFlag::Default);
50 Q_CORE_EXPORT explicit QDirListing(const QString &path, const QStringList &nameFilters,
51 IteratorFlags flags = IteratorFlag::Default);
52
53 QDirListing(QDirListing &&other) noexcept
54 : d{std::exchange(obj&: other.d, new_val: nullptr)} {}
55 QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_MOVE_AND_SWAP(QDirListing)
56
57 void swap(QDirListing &other) noexcept { qt_ptr_swap(lhs&: d, rhs&: other.d); }
58
59 Q_CORE_EXPORT ~QDirListing();
60
61 Q_CORE_EXPORT QString iteratorPath() const;
62 Q_CORE_EXPORT IteratorFlags iteratorFlags() const;
63 Q_CORE_EXPORT QStringList nameFilters() const;
64
65 class DirEntry
66 {
67 friend class QDirListing;
68 QDirListingPrivate *dirListPtr = nullptr;
69 public:
70 Q_CORE_EXPORT QString fileName() const;
71 Q_CORE_EXPORT QString baseName() const;
72 Q_CORE_EXPORT QString completeBaseName() const;
73 Q_CORE_EXPORT QString suffix() const;
74 Q_CORE_EXPORT QString bundleName() const;
75 Q_CORE_EXPORT QString completeSuffix() const;
76 Q_CORE_EXPORT QString filePath() const;
77 Q_CORE_EXPORT bool isDir() const;
78 Q_CORE_EXPORT bool isFile() const;
79 Q_CORE_EXPORT bool isSymLink() const;
80 Q_CORE_EXPORT bool exists() const;
81 Q_CORE_EXPORT bool isHidden() const;
82 Q_CORE_EXPORT bool isReadable() const;
83 Q_CORE_EXPORT bool isWritable() const;
84 Q_CORE_EXPORT bool isExecutable() const;
85 Q_CORE_EXPORT QFileInfo fileInfo() const;
86 Q_CORE_EXPORT QString canonicalFilePath() const;
87 Q_CORE_EXPORT QString absoluteFilePath() const;
88 Q_CORE_EXPORT QString absolutePath() const;
89 Q_CORE_EXPORT qint64 size() const;
90
91 QDateTime birthTime(const QTimeZone &tz) const
92 { return fileTime(type: QFileDevice::FileBirthTime, tz); }
93 QDateTime metadataChangeTime(const QTimeZone &tz) const
94 { return fileTime(type: QFileDevice::FileMetadataChangeTime, tz); }
95 QDateTime lastModified(const QTimeZone &tz) const
96 { return fileTime(type: QFileDevice::FileModificationTime, tz); }
97 QDateTime lastRead(const QTimeZone &tz) const
98 { return fileTime(type: QFileDevice::FileAccessTime, tz); }
99 Q_CORE_EXPORT QDateTime fileTime(QFileDevice::FileTime type, const QTimeZone &tz) const;
100 };
101
102 class sentinel
103 {
104 friend constexpr bool operator==(sentinel, sentinel) noexcept { return true; }
105 friend constexpr bool operator!=(sentinel, sentinel) noexcept { return false; }
106 };
107
108 class const_iterator
109 {
110 Q_DISABLE_COPY(const_iterator)
111 friend class QDirListing;
112 explicit const_iterator(QDirListingPrivate *dp) { dirEntry.dirListPtr = dp; }
113 DirEntry dirEntry;
114 public:
115 using iterator_category = std::input_iterator_tag;
116 using value_type = DirEntry;
117 using difference_type = qint64;
118 using pointer = const value_type *;
119 using reference = const value_type &;
120
121 const_iterator() = default;
122 const_iterator(const_iterator &&) noexcept = default;
123 const_iterator &operator=(const_iterator &&) noexcept = default;
124
125 reference operator*() const { return dirEntry; }
126 pointer operator->() const { return &dirEntry; }
127 const_iterator &operator++() { dirEntry = next(dirEntry); return *this; }
128 void operator++(int) { ++*this; } // [iterator.concept.winc]/14 not required to return sth
129 private:
130 bool atEnd() const noexcept { return dirEntry.dirListPtr == nullptr; }
131 friend bool operator==(const const_iterator &lhs, sentinel) noexcept { return lhs.atEnd(); }
132#ifndef __cpp_impl_three_way_comparison
133 friend bool operator!=(const const_iterator &lhs, sentinel) noexcept
134 { return !operator==(lhs, sentinel{}); }
135 friend bool operator==(sentinel, const const_iterator &rhs) noexcept
136 { return operator==(lhs: rhs, sentinel{}); }
137 friend bool operator!=(sentinel, const const_iterator &rhs) noexcept
138 { return !operator==(sentinel{}, rhs); }
139#endif // __cpp_impl_three_way_comparison
140 };
141
142 Q_CORE_EXPORT const_iterator begin() const;
143 const_iterator cbegin() const { return begin(); }
144 sentinel end() const { return {}; }
145 sentinel cend() const { return end(); }
146
147 // Qt compatibility
148 const_iterator constBegin() const { return begin(); }
149 sentinel constEnd() const { return end(); }
150
151private:
152 Q_DISABLE_COPY(QDirListing)
153
154 Q_CORE_EXPORT static DirEntry next(DirEntry);
155
156 // Private constructor that is used in deprecated code paths.
157 // `uint` instead of QDir::Filters and QDirIterator::IteratorFlags
158 // because qdir.h can't be included here; qdiriterator.h can't included
159 // either, because it includes qdir.h
160 Q_CORE_EXPORT QDirListing(const QString &path, const QStringList &nameFilters, uint dirFilters,
161 uint qdirIteratorFlags = 0); // QDirIterator::NoIteratorFlags == 0x0
162
163 QDirListingPrivate *d;
164 friend class QDir;
165 friend class QDirPrivate;
166 friend class QDirIteratorPrivate;
167 friend class QAbstractFileEngine;
168 friend class QFileInfoGatherer;
169};
170
171Q_DECLARE_OPERATORS_FOR_FLAGS(QDirListing::IteratorFlags)
172
173QT_END_NAMESPACE
174
175#endif // QDIRLISTING_H
176

source code of qtbase/src/corelib/io/qdirlisting.h