From Jason Turner

[fs.class.directory.entry]

C++17 → C++20 10.7 KB 341 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpwvgsbwrk/{from.md → to.md} +338 -0
tmp/tmpwvgsbwrk/{from.md → to.md} RENAMED
@@ -0,0 +1,338 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Class `directory_entry` <a id="fs.class.directory.entry">[[fs.class.directory.entry]]</a>
2
+
3
+ ``` cpp
4
+ namespace std::filesystem {
5
+ class directory_entry {
6
+ public:
7
+ // [fs.dir.entry.cons], constructors and destructor
8
+ directory_entry() noexcept = default;
9
+ directory_entry(const directory_entry&) = default;
10
+ directory_entry(directory_entry&&) noexcept = default;
11
+ explicit directory_entry(const filesystem::path& p);
12
+ directory_entry(const filesystem::path& p, error_code& ec);
13
+ ~directory_entry();
14
+
15
+ // assignments
16
+ directory_entry& operator=(const directory_entry&) = default;
17
+ directory_entry& operator=(directory_entry&&) noexcept = default;
18
+
19
+ // [fs.dir.entry.mods], modifiers
20
+ void assign(const filesystem::path& p);
21
+ void assign(const filesystem::path& p, error_code& ec);
22
+ void replace_filename(const filesystem::path& p);
23
+ void replace_filename(const filesystem::path& p, error_code& ec);
24
+ void refresh();
25
+ void refresh(error_code& ec) noexcept;
26
+
27
+ // [fs.dir.entry.obs], observers
28
+ const filesystem::path& path() const noexcept;
29
+ operator const filesystem::path&() const noexcept;
30
+ bool exists() const;
31
+ bool exists(error_code& ec) const noexcept;
32
+ bool is_block_file() const;
33
+ bool is_block_file(error_code& ec) const noexcept;
34
+ bool is_character_file() const;
35
+ bool is_character_file(error_code& ec) const noexcept;
36
+ bool is_directory() const;
37
+ bool is_directory(error_code& ec) const noexcept;
38
+ bool is_fifo() const;
39
+ bool is_fifo(error_code& ec) const noexcept;
40
+ bool is_other() const;
41
+ bool is_other(error_code& ec) const noexcept;
42
+ bool is_regular_file() const;
43
+ bool is_regular_file(error_code& ec) const noexcept;
44
+ bool is_socket() const;
45
+ bool is_socket(error_code& ec) const noexcept;
46
+ bool is_symlink() const;
47
+ bool is_symlink(error_code& ec) const noexcept;
48
+ uintmax_t file_size() const;
49
+ uintmax_t file_size(error_code& ec) const noexcept;
50
+ uintmax_t hard_link_count() const;
51
+ uintmax_t hard_link_count(error_code& ec) const noexcept;
52
+ file_time_type last_write_time() const;
53
+ file_time_type last_write_time(error_code& ec) const noexcept;
54
+ file_status status() const;
55
+ file_status status(error_code& ec) const noexcept;
56
+ file_status symlink_status() const;
57
+ file_status symlink_status(error_code& ec) const noexcept;
58
+
59
+ bool operator==(const directory_entry& rhs) const noexcept;
60
+ strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
61
+
62
+ private:
63
+ filesystem::path pathobject; // exposition only
64
+ friend class directory_iterator; // exposition only
65
+ };
66
+ }
67
+ ```
68
+
69
+ A `directory_entry` object stores a `path` object and may store
70
+ additional objects for file attributes such as hard link count, status,
71
+ symlink status, file size, and last write time.
72
+
73
+ Implementations should store such additional file attributes during
74
+ directory iteration if their values are available and storing the values
75
+ would allow the implementation to eliminate file system accesses by
76
+ `directory_entry` observer functions [[fs.op.funcs]]. Such stored file
77
+ attribute values are said to be *cached*.
78
+
79
+ [*Note 1*: For purposes of exposition, class `directory_iterator`
80
+ [[fs.class.directory.iterator]] is shown above as a friend of class
81
+ `directory_entry`. Friendship allows the `directory_iterator`
82
+ implementation to cache already available attribute values directly into
83
+ a `directory_entry` object without the cost of an unneeded call to
84
+ `refresh()`. — *end note*]
85
+
86
+ [*Example 1*:
87
+
88
+ ``` cpp
89
+ using namespace std::filesystem;
90
+
91
+ // use possibly cached last write time to minimize disk accesses
92
+ for (auto&& x : directory_iterator("."))
93
+ {
94
+ std::cout << x.path() << " " << x.last_write_time() << std::endl;
95
+ }
96
+
97
+ // call refresh() to refresh a stale cache
98
+ for (auto&& x : directory_iterator("."))
99
+ {
100
+ lengthy_function(x.path()); // cache becomes stale
101
+ x.refresh();
102
+ std::cout << x.path() << " " << x.last_write_time() << std::endl;
103
+ }
104
+ ```
105
+
106
+ On implementations that do not cache the last write time, both loops
107
+ will result in a potentially expensive call to the
108
+ `std::filesystem::last_write_time` function. On implementations that do
109
+ cache the last write time, the first loop will use the cached value and
110
+ so will not result in a potentially expensive call to the
111
+ `std::filesystem::last_write_time` function. The code is portable to any
112
+ implementation, regardless of whether or not it employs caching.
113
+
114
+ — *end example*]
115
+
116
+ #### Constructors <a id="fs.dir.entry.cons">[[fs.dir.entry.cons]]</a>
117
+
118
+ ``` cpp
119
+ explicit directory_entry(const filesystem::path& p);
120
+ directory_entry(const filesystem::path& p, error_code& ec);
121
+ ```
122
+
123
+ *Effects:* Calls `refresh()` or `refresh(ec)`, respectively.
124
+
125
+ *Ensures:* `path() == p` if no error occurs, otherwise
126
+ `path() == filesystem::path()`.
127
+
128
+ *Throws:* As specified in  [[fs.err.report]].
129
+
130
+ #### Modifiers <a id="fs.dir.entry.mods">[[fs.dir.entry.mods]]</a>
131
+
132
+ ``` cpp
133
+ void assign(const filesystem::path& p);
134
+ void assign(const filesystem::path& p, error_code& ec);
135
+ ```
136
+
137
+ *Effects:* Equivalent to `pathobject = p`, then `refresh()` or
138
+ `refresh(ec)`, respectively. If an error occurs, the values of any
139
+ cached attributes are unspecified.
140
+
141
+ *Throws:* As specified in  [[fs.err.report]].
142
+
143
+ ``` cpp
144
+ void replace_filename(const filesystem::path& p);
145
+ void replace_filename(const filesystem::path& p, error_code& ec);
146
+ ```
147
+
148
+ *Effects:* Equivalent to `pathobject.replace_filename(p)`, then
149
+ `refresh()` or `refresh(ec)`, respectively. If an error occurs, the
150
+ values of any cached attributes are unspecified.
151
+
152
+ *Throws:* As specified in  [[fs.err.report]].
153
+
154
+ ``` cpp
155
+ void refresh();
156
+ void refresh(error_code& ec) noexcept;
157
+ ```
158
+
159
+ *Effects:* Stores the current values of any cached attributes of the
160
+ file `p` resolves to. If an error occurs, an error is
161
+ reported [[fs.err.report]] and the values of any cached attributes are
162
+ unspecified.
163
+
164
+ *Throws:* As specified in  [[fs.err.report]].
165
+
166
+ [*Note 1*: Implementations of `directory_iterator`
167
+ [[fs.class.directory.iterator]] are prohibited from directly or
168
+ indirectly calling the `refresh` function since it must access the
169
+ external file system, and the objective of caching is to avoid
170
+ unnecessary file system accesses. — *end note*]
171
+
172
+ #### Observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
173
+
174
+ Unqualified function names in the *Returns:* elements of the
175
+ `directory_entry` observers described below refer to members of the
176
+ `std::filesystem` namespace.
177
+
178
+ ``` cpp
179
+ const filesystem::path& path() const noexcept;
180
+ operator const filesystem::path&() const noexcept;
181
+ ```
182
+
183
+ *Returns:* `pathobject`.
184
+
185
+ ``` cpp
186
+ bool exists() const;
187
+ bool exists(error_code& ec) const noexcept;
188
+ ```
189
+
190
+ *Returns:* `exists(this->status())` or `exists(this->status(ec))`,
191
+ respectively.
192
+
193
+ *Throws:* As specified in  [[fs.err.report]].
194
+
195
+ ``` cpp
196
+ bool is_block_file() const;
197
+ bool is_block_file(error_code& ec) const noexcept;
198
+ ```
199
+
200
+ *Returns:* `is_block_file(this->status())` or
201
+ `is_block_file(this->status(ec))`, respectively.
202
+
203
+ *Throws:* As specified in  [[fs.err.report]].
204
+
205
+ ``` cpp
206
+ bool is_character_file() const;
207
+ bool is_character_file(error_code& ec) const noexcept;
208
+ ```
209
+
210
+ *Returns:* `is_character_file(this->status())` or
211
+ `is_character_file(this->status(ec))`, respectively.
212
+
213
+ *Throws:* As specified in  [[fs.err.report]].
214
+
215
+ ``` cpp
216
+ bool is_directory() const;
217
+ bool is_directory(error_code& ec) const noexcept;
218
+ ```
219
+
220
+ *Returns:* `is_directory(this->status())` or
221
+ `is_directory(this->status(ec))`, respectively.
222
+
223
+ *Throws:* As specified in  [[fs.err.report]].
224
+
225
+ ``` cpp
226
+ bool is_fifo() const;
227
+ bool is_fifo(error_code& ec) const noexcept;
228
+ ```
229
+
230
+ *Returns:* `is_fifo(this->status())` or `is_fifo(this->status(ec))`,
231
+ respectively.
232
+
233
+ *Throws:* As specified in  [[fs.err.report]].
234
+
235
+ ``` cpp
236
+ bool is_other() const;
237
+ bool is_other(error_code& ec) const noexcept;
238
+ ```
239
+
240
+ *Returns:* `is_other(this->status())` or `is_other(this->status(ec))`,
241
+ respectively.
242
+
243
+ *Throws:* As specified in  [[fs.err.report]].
244
+
245
+ ``` cpp
246
+ bool is_regular_file() const;
247
+ bool is_regular_file(error_code& ec) const noexcept;
248
+ ```
249
+
250
+ *Returns:* `is_regular_file(this->status())` or
251
+ `is_regular_file(this->status(ec))`, respectively.
252
+
253
+ *Throws:* As specified in  [[fs.err.report]].
254
+
255
+ ``` cpp
256
+ bool is_socket() const;
257
+ bool is_socket(error_code& ec) const noexcept;
258
+ ```
259
+
260
+ *Returns:* `is_socket(this->status())` or `is_socket(this->status(ec))`,
261
+ respectively.
262
+
263
+ *Throws:* As specified in  [[fs.err.report]].
264
+
265
+ ``` cpp
266
+ bool is_symlink() const;
267
+ bool is_symlink(error_code& ec) const noexcept;
268
+ ```
269
+
270
+ *Returns:* `is_symlink(this->symlink_status())` or
271
+ `is_symlink(this->symlink_status(ec))`, respectively.
272
+
273
+ *Throws:* As specified in  [[fs.err.report]].
274
+
275
+ ``` cpp
276
+ uintmax_t file_size() const;
277
+ uintmax_t file_size(error_code& ec) const noexcept;
278
+ ```
279
+
280
+ *Returns:* If cached, the file size attribute value. Otherwise,
281
+ `file_size(path())` or `file_size(path(), ec)`, respectively.
282
+
283
+ *Throws:* As specified in  [[fs.err.report]].
284
+
285
+ ``` cpp
286
+ uintmax_t hard_link_count() const;
287
+ uintmax_t hard_link_count(error_code& ec) const noexcept;
288
+ ```
289
+
290
+ *Returns:* If cached, the hard link count attribute value. Otherwise,
291
+ `hard_link_count(path())` or `hard_link_count(path(), ec)`,
292
+ respectively.
293
+
294
+ *Throws:* As specified in  [[fs.err.report]].
295
+
296
+ ``` cpp
297
+ file_time_type last_write_time() const;
298
+ file_time_type last_write_time(error_code& ec) const noexcept;
299
+ ```
300
+
301
+ *Returns:* If cached, the last write time attribute value. Otherwise,
302
+ `last_write_time(path())` or `last_write_time(path(), ec)`,
303
+ respectively.
304
+
305
+ *Throws:* As specified in  [[fs.err.report]].
306
+
307
+ ``` cpp
308
+ file_status status() const;
309
+ file_status status(error_code& ec) const noexcept;
310
+ ```
311
+
312
+ *Returns:* If cached, the status attribute value. Otherwise,
313
+ `status(path())` or `status(path(), ec)`, respectively.
314
+
315
+ *Throws:* As specified in  [[fs.err.report]].
316
+
317
+ ``` cpp
318
+ file_status symlink_status() const;
319
+ file_status symlink_status(error_code& ec) const noexcept;
320
+ ```
321
+
322
+ *Returns:* If cached, the symlink status attribute value. Otherwise,
323
+ `symlink_status(path())` or `symlink_status(path(), ec)`, respectively.
324
+
325
+ *Throws:* As specified in  [[fs.err.report]].
326
+
327
+ ``` cpp
328
+ bool operator==(const directory_entry& rhs) const noexcept;
329
+ ```
330
+
331
+ *Returns:* `pathobject == rhs.pathobject`.
332
+
333
+ ``` cpp
334
+ strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
335
+ ```
336
+
337
+ *Returns:* `pathobject <=> rhs.pathobject`.
338
+