From Jason Turner

[fs.class.directory.iterator]

C++17 → C++20 6.5 KB 177 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/tmpkm521b_q/{from.md → to.md} +174 -0
tmp/tmpkm521b_q/{from.md → to.md} RENAMED
@@ -0,0 +1,174 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Class `directory_iterator` <a id="fs.class.directory.iterator">[[fs.class.directory.iterator]]</a>
2
+
3
+ An object of type `directory_iterator` provides an iterator for a
4
+ sequence of `directory_entry` elements representing the path and any
5
+ cached attribute values [[fs.class.directory.entry]] for each file in a
6
+ directory or in an *implementation-defined* directory-like file type.
7
+
8
+ [*Note 1*: For iteration into sub-directories, see class
9
+ `recursive_directory_iterator` [[fs.class.rec.dir.itr]]. — *end note*]
10
+
11
+ ``` cpp
12
+ namespace std::filesystem {
13
+ class directory_iterator {
14
+ public:
15
+ using iterator_category = input_iterator_tag;
16
+ using value_type = directory_entry;
17
+ using difference_type = ptrdiff_t;
18
+ using pointer = const directory_entry*;
19
+ using reference = const directory_entry&;
20
+
21
+ // [fs.dir.itr.members], member functions
22
+ directory_iterator() noexcept;
23
+ explicit directory_iterator(const path& p);
24
+ directory_iterator(const path& p, directory_options options);
25
+ directory_iterator(const path& p, error_code& ec);
26
+ directory_iterator(const path& p, directory_options options,
27
+ error_code& ec);
28
+ directory_iterator(const directory_iterator& rhs);
29
+ directory_iterator(directory_iterator&& rhs) noexcept;
30
+ ~directory_iterator();
31
+
32
+ directory_iterator& operator=(const directory_iterator& rhs);
33
+ directory_iterator& operator=(directory_iterator&& rhs) noexcept;
34
+
35
+ const directory_entry& operator*() const;
36
+ const directory_entry* operator->() const;
37
+ directory_iterator& operator++();
38
+ directory_iterator& increment(error_code& ec);
39
+
40
+ // other members as required by [input.iterators], input iterators
41
+ };
42
+ }
43
+ ```
44
+
45
+ `directory_iterator` meets the *Cpp17InputIterator* requirements
46
+ [[input.iterators]].
47
+
48
+ If an iterator of type `directory_iterator` reports an error or is
49
+ advanced past the last directory element, that iterator shall become
50
+ equal to the end iterator value. The `directory_iterator` default
51
+ constructor shall create an iterator equal to the end iterator value,
52
+ and this shall be the only valid iterator for the end condition.
53
+
54
+ The end iterator is not dereferenceable.
55
+
56
+ Two end iterators are always equal. An end iterator shall not be equal
57
+ to a non-end iterator.
58
+
59
+ The result of calling the `path()` member of the `directory_entry`
60
+ object obtained by dereferencing a `directory_iterator` is a reference
61
+ to a `path` object composed of the directory argument from which the
62
+ iterator was constructed with filename of the directory entry appended
63
+ as if by `operator/=`.
64
+
65
+ Directory iteration shall not yield directory entries for the current
66
+ (dot) and parent (dot-dot) directories.
67
+
68
+ The order of directory entries obtained by dereferencing successive
69
+ increments of a `directory_iterator` is unspecified.
70
+
71
+ Constructors and non-const `directory_iterator` member functions store
72
+ the values of any cached attributes [[fs.class.directory.entry]] in the
73
+ `directory_entry` element returned by `operator*()`.
74
+ `directory_iterator` member functions shall not directly or indirectly
75
+ call any `directory_entry` `refresh` function.
76
+
77
+ [*Note 2*: The exact mechanism for storing cached attribute values is
78
+ not exposed to users. For exposition, class `directory_iterator` is
79
+ shown in [[fs.class.directory.entry]] as a friend of class
80
+ `directory_entry`. — *end note*]
81
+
82
+ [*Note 3*: Programs performing directory iteration may wish to test if
83
+ the path obtained by dereferencing a directory iterator actually exists.
84
+ It could be a symbolic link to a non-existent file. Programs recursively
85
+ walking directory trees for purposes of removing and renaming entries
86
+ may wish to avoid following symbolic links. — *end note*]
87
+
88
+ [*Note 4*: If a file is removed from or added to a directory after the
89
+ construction of a `directory_iterator` for the directory, it is
90
+ unspecified whether or not subsequently incrementing the iterator will
91
+ ever result in an iterator referencing the removed or added directory
92
+ entry. See POSIX `readdir_r`. — *end note*]
93
+
94
+ #### Members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
95
+
96
+ ``` cpp
97
+ directory_iterator() noexcept;
98
+ ```
99
+
100
+ *Effects:* Constructs the end iterator.
101
+
102
+ ``` cpp
103
+ explicit directory_iterator(const path& p);
104
+ directory_iterator(const path& p, directory_options options);
105
+ directory_iterator(const path& p, error_code& ec);
106
+ directory_iterator(const path& p, directory_options options, error_code& ec);
107
+ ```
108
+
109
+ *Effects:* For the directory that `p` resolves to, constructs an
110
+ iterator for the first element in a sequence of `directory_entry`
111
+ elements representing the files in the directory, if any; otherwise the
112
+ end iterator. However, if
113
+
114
+ ``` cpp
115
+ (options & directory_options::skip_permission_denied) != directory_options::none
116
+ ```
117
+
118
+ and construction encounters an error indicating that permission to
119
+ access `p` is denied, constructs the end iterator and does not report an
120
+ error.
121
+
122
+ *Throws:* As specified in  [[fs.err.report]].
123
+
124
+ [*Note 1*: To iterate over the current directory, use
125
+ `directory_iterator(".")` rather than
126
+ `directory_iterator("")`. — *end note*]
127
+
128
+ ``` cpp
129
+ directory_iterator(const directory_iterator& rhs);
130
+ directory_iterator(directory_iterator&& rhs) noexcept;
131
+ ```
132
+
133
+ *Ensures:* `*this` has the original value of `rhs`.
134
+
135
+ ``` cpp
136
+ directory_iterator& operator=(const directory_iterator& rhs);
137
+ directory_iterator& operator=(directory_iterator&& rhs) noexcept;
138
+ ```
139
+
140
+ *Effects:* If `*this` and `rhs` are the same object, the member has no
141
+ effect.
142
+
143
+ *Ensures:* `*this` has the original value of `rhs`.
144
+
145
+ *Returns:* `*this`.
146
+
147
+ ``` cpp
148
+ directory_iterator& operator++();
149
+ directory_iterator& increment(error_code& ec);
150
+ ```
151
+
152
+ *Effects:* As specified for the prefix increment operation of Input
153
+ iterators [[input.iterators]].
154
+
155
+ *Returns:* `*this`.
156
+
157
+ *Throws:* As specified in  [[fs.err.report]].
158
+
159
+ #### Non-member functions <a id="fs.dir.itr.nonmembers">[[fs.dir.itr.nonmembers]]</a>
160
+
161
+ These functions enable range access for `directory_iterator`.
162
+
163
+ ``` cpp
164
+ directory_iterator begin(directory_iterator iter) noexcept;
165
+ ```
166
+
167
+ *Returns:* `iter`.
168
+
169
+ ``` cpp
170
+ directory_iterator end(const directory_iterator&) noexcept;
171
+ ```
172
+
173
+ *Returns:* `directory_iterator()`.
174
+