From Jason Turner

[fs.class.directory_iterator]

C++17 → C++20 6.7 KB 180 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/tmpmb6ngvvx/{from.md → to.md} +0 -177
tmp/tmpmb6ngvvx/{from.md → to.md} RENAMED
@@ -1,177 +0,0 @@
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
-