From Jason Turner

[fs.class.directory_iterator]

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