From Jason Turner

[fs.class.rec.dir.itr]

C++14 → C++17 8.4 KB 258 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpdbekmagv/{from.md → to.md} +255 -0
tmp/tmpdbekmagv/{from.md → to.md} RENAMED
@@ -0,0 +1,255 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Class `recursive_directory_iterator` <a id="fs.class.rec.dir.itr">[[fs.class.rec.dir.itr]]</a>
2
+
3
+ An object of type `recursive_directory_iterator` provides an iterator
4
+ for a sequence of `directory_entry` elements representing the files in a
5
+ directory or in an *implementation-defined* directory-like file type,
6
+ and its sub-directories.
7
+
8
+ ``` cpp
9
+ namespace std::filesystem {
10
+ class recursive_directory_iterator {
11
+ public:
12
+ using iterator_category = input_iterator_tag;
13
+ using value_type = directory_entry;
14
+ using difference_type = ptrdiff_t;
15
+ using pointer = const directory_entry*;
16
+ using reference = const directory_entry&;
17
+
18
+ // [fs.rec.dir.itr.members], constructors and destructor
19
+ recursive_directory_iterator() noexcept;
20
+ explicit recursive_directory_iterator(const path& p);
21
+ recursive_directory_iterator(const path& p, directory_options options);
22
+ recursive_directory_iterator(const path& p, directory_options options,
23
+ error_code& ec) noexcept;
24
+ recursive_directory_iterator(const path& p, error_code& ec) noexcept;
25
+ recursive_directory_iterator(const recursive_directory_iterator& rhs);
26
+ recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
27
+ ~recursive_directory_iterator();
28
+
29
+ // [fs.rec.dir.itr.members], observers
30
+ directory_options options() const;
31
+ int depth() const;
32
+ bool recursion_pending() const;
33
+
34
+ const directory_entry& operator*() const;
35
+ const directory_entry* operator->() const;
36
+
37
+ // [fs.rec.dir.itr.members], modifiers
38
+ recursive_directory_iterator&
39
+ operator=(const recursive_directory_iterator& rhs);
40
+ recursive_directory_iterator&
41
+ operator=(recursive_directory_iterator&& rhs) noexcept;
42
+
43
+ recursive_directory_iterator& operator++();
44
+ recursive_directory_iterator& increment(error_code& ec) noexcept;
45
+
46
+ void pop();
47
+ void pop(error_code& ec);
48
+ void disable_recursion_pending();
49
+
50
+ // other members as required by [input.iterators], input iterators
51
+ };
52
+ }
53
+ ```
54
+
55
+ Calling `options`, `depth`, `recursion_pending`, `pop` or
56
+ `disable_recursion_pending` on an iterator that is not dereferenceable
57
+ results in undefined behavior.
58
+
59
+ The behavior of a `recursive_directory_iterator` is the same as a
60
+ `directory_iterator` unless otherwise specified.
61
+
62
+ [*Note 1*: If the directory structure being iterated over contains
63
+ cycles then the end iterator may be unreachable. — *end note*]
64
+
65
+ #### `recursive_directory_iterator` members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
66
+
67
+ ``` cpp
68
+ recursive_directory_iterator() noexcept;
69
+ ```
70
+
71
+ *Effects:* Constructs the end iterator.
72
+
73
+ ``` cpp
74
+ explicit recursive_directory_iterator(const path& p);
75
+ recursive_directory_iterator(const path& p, directory_options options);
76
+ recursive_directory_iterator(const path& p, directory_options options, error_code& ec) noexcept;
77
+ recursive_directory_iterator(const path& p, error_code& ec) noexcept;
78
+ ```
79
+
80
+ *Effects:* Constructs a iterator representing the first entry in the
81
+ directory `p` resolves to, if any; otherwise, the end iterator. However,
82
+ if
83
+
84
+ ``` cpp
85
+ (options & directory_options::skip_permission_denied) != directory_options::none
86
+ ```
87
+
88
+ and construction encounters an error indicating that permission to
89
+ access `p` is denied, constructs the end iterator and does not report an
90
+ error.
91
+
92
+ *Postconditions:* `options() == options` for the signatures with a
93
+ `directory_options` argument, otherwise
94
+ `options() == directory_options::none`.
95
+
96
+ *Throws:* As specified in  [[fs.err.report]].
97
+
98
+ [*Note 1*: To iterate over the current directory, use
99
+ `recursive_directory_iterator(".")` rather than
100
+ `recursive_directory_iterator("")`. — *end note*]
101
+
102
+ [*Note 2*: By default, `recursive_directory_iterator` does not follow
103
+ directory symlinks. To follow directory symlinks, specify `options` as
104
+ `directory_options::follow_directory_symlink` — *end note*]
105
+
106
+ ``` cpp
107
+ recursive_directory_iterator(const recursive_directory_iterator& rhs);
108
+ ```
109
+
110
+ *Effects:* Constructs an object of class `recursive_directory_iterator`.
111
+
112
+ *Postconditions:*
113
+
114
+ - `options() == rhs.options()`
115
+ - `depth() == rhs.depth()`
116
+ - `recursion_pending() == rhs.recursion_pending()`
117
+
118
+ ``` cpp
119
+ recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
120
+ ```
121
+
122
+ *Effects:* Constructs an object of class `recursive_directory_iterator`.
123
+
124
+ *Postconditions:* `options()`, `depth()`, and `recursion_pending()` have
125
+ the values that `rhs.options()`, `rhs.depth()`, and
126
+ `rhs.recursion_pending()`, respectively, had before the function call.
127
+
128
+ ``` cpp
129
+ recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
130
+ ```
131
+
132
+ *Effects:* If `*this` and `rhs` are the same object, the member has no
133
+ effect.
134
+
135
+ *Postconditions:*
136
+
137
+ - `options() == rhs.options()`
138
+ - `depth() == rhs.depth()`
139
+ - `recursion_pending() == rhs.recursion_pending()`
140
+
141
+ *Returns:* `*this`.
142
+
143
+ ``` cpp
144
+ recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;
145
+ ```
146
+
147
+ *Effects:* If `*this` and `rhs` are the same object, the member has no
148
+ effect.
149
+
150
+ *Postconditions:* `options()`, `depth()`, and `recursion_pending()` have
151
+ the values that `rhs.options()`, `rhs.depth()`, and
152
+ `rhs.recursion_pending()`, respectively, had before the function call.
153
+
154
+ *Returns:* `*this`.
155
+
156
+ ``` cpp
157
+ directory_options options() const;
158
+ ```
159
+
160
+ *Returns:* The value of the argument passed to the constructor for the
161
+ `options` parameter, if present, otherwise `directory_options::none`.
162
+
163
+ *Throws:* Nothing.
164
+
165
+ ``` cpp
166
+ int depth() const;
167
+ ```
168
+
169
+ *Returns:* The current depth of the directory tree being traversed.
170
+
171
+ [*Note 3*: The initial directory is depth `0`, its immediate
172
+ subdirectories are depth `1`, and so forth. — *end note*]
173
+
174
+ *Throws:* Nothing.
175
+
176
+ ``` cpp
177
+ bool recursion_pending() const;
178
+ ```
179
+
180
+ *Returns:* `true` if `disable_recursion_pending()` has not been called
181
+ subsequent to the prior construction or increment operation, otherwise
182
+ `false`.
183
+
184
+ *Throws:* Nothing.
185
+
186
+ ``` cpp
187
+ recursive_directory_iterator& operator++();
188
+ recursive_directory_iterator& increment(error_code& ec) noexcept;
189
+ ```
190
+
191
+ *Effects:* As specified for the prefix increment operation of Input
192
+ iterators ([[input.iterators]]), except that:
193
+
194
+ - If there are no more entries at the current depth, then if
195
+ `depth() != 0` iteration over the parent directory resumes; otherwise
196
+ `*this = recursive_directory_iterator()`.
197
+ - Otherwise if
198
+ ``` cpp
199
+ recursion_pending() && is_directory((*this)->status()) &&
200
+ (!is_symlink((*this)->symlink_status()) ||
201
+ (options() & directory_options::follow_directory_symlink) != directory_options::none)
202
+ ```
203
+
204
+ then either directory `(*this)->path()` is recursively iterated into
205
+ or, if
206
+ ``` cpp
207
+ (options() & directory_options::skip_permission_denied) != directory_options::none
208
+ ```
209
+
210
+ and an error occurs indicating that permission to access directory
211
+ `(*this)->path()` is denied, then directory `(*this)->path()` is
212
+ treated as an empty directory and no error is reported.
213
+
214
+ *Returns:* `*this`.
215
+
216
+ *Throws:* As specified in  [[fs.err.report]].
217
+
218
+ ``` cpp
219
+ void pop();
220
+ void pop(error_code& ec);
221
+ ```
222
+
223
+ *Effects:* If `depth() == 0`, set `*this` to
224
+ `recursive_directory_iterator()`. Otherwise, cease iteration of the
225
+ directory currently being iterated over, and continue iteration over the
226
+ parent directory.
227
+
228
+ *Throws:* As specified in  [[fs.err.report]].
229
+
230
+ ``` cpp
231
+ void disable_recursion_pending();
232
+ ```
233
+
234
+ *Postconditions:* `recursion_pending() == false`.
235
+
236
+ [*Note 4*: `disable_recursion_pending``()` is used to prevent unwanted
237
+ recursion into a directory. — *end note*]
238
+
239
+ #### `recursive_directory_iterator` non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
240
+
241
+ These functions enable use of `recursive_directory_iterator` with
242
+ range-based for statements.
243
+
244
+ ``` cpp
245
+ recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
246
+ ```
247
+
248
+ *Returns:* `iter`.
249
+
250
+ ``` cpp
251
+ recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
252
+ ```
253
+
254
+ *Returns:* `recursive_directory_iterator()`.
255
+