31 Input/output library [input.output]

31.12 File systems [filesystems]

31.12.11 Class directory_iterator [fs.class.directory.iterator]

31.12.11.1 General [fs.class.directory.iterator.general]

An object of type directory_iterator provides an iterator for a sequence of directory_entry elements representing the path and any cached attribute values ([fs.class.directory.entry]) for each file in a directory or in an implementation-defined directory-like file type.
[Note 1: 
For iteration into subdirectories, see class recursive_directory_iterator ([fs.class.rec.dir.itr]).
— end note]
namespace std::filesystem { class directory_iterator { public: using iterator_category = input_iterator_tag; using value_type = directory_entry; using difference_type = ptrdiff_t; using pointer = const directory_entry*; using reference = const directory_entry&; // [fs.dir.itr.members], member functions directory_iterator() noexcept; explicit directory_iterator(const path& p); directory_iterator(const path& p, directory_options options); directory_iterator(const path& p, error_code& ec); directory_iterator(const path& p, directory_options options, error_code& ec); directory_iterator(const directory_iterator& rhs); directory_iterator(directory_iterator&& rhs) noexcept; ~directory_iterator(); directory_iterator& operator=(const directory_iterator& rhs); directory_iterator& operator=(directory_iterator&& rhs) noexcept; const directory_entry& operator*() const; const directory_entry* operator->() const; directory_iterator& operator++(); directory_iterator& increment(error_code& ec); bool operator==(default_sentinel_t) const noexcept { return *this == directory_iterator(); } // other members as required by [input.iterators], input iterators }; }
directory_iterator meets the Cpp17InputIterator requirements ([input.iterators]).
If an iterator of type directory_iterator reports an error or is advanced past the last directory element, that iterator shall become equal to the end iterator value.
The directory_iterator default constructor shall create an iterator equal to the end iterator value, and this shall be the only valid iterator for the end condition.
The end iterator is not dereferenceable.
Two end iterators are always equal.
An end iterator shall not be equal to a non-end iterator.
The result of calling the path() member of the directory_entry object obtained by dereferencing a directory_iterator is a reference to a path object composed of the directory argument from which the iterator was constructed with the filename of the directory entry appended as if by operator/=.
Directory iteration shall not yield directory entries for the current (dot) and parent (dot-dot) directories.
The order of directory entries obtained by dereferencing successive increments of a directory_iterator is unspecified.
Constructors and non-const directory_iterator member functions store the values of any cached attributes ([fs.class.directory.entry]) in the directory_entry element returned by operator*().
directory_iterator member functions shall not directly or indirectly call any directory_entry refresh function.
[Note 2: 
The exact mechanism for storing cached attribute values is not exposed to users.
For exposition, class directory_iterator is shown in [fs.class.directory.entry] as a friend of class directory_entry.
— end note]
[Note 3: 
A path obtained by dereferencing a directory iterator might not actually exist; it could be a symbolic link to a non-existent file.
Recursively walking directory trees for purposes of removing and renaming entries might invalidate symbolic links that are being followed.
— end note]
[Note 4: 
If a file is removed from or added to a directory after the construction of a directory_iterator for the directory, it is unspecified whether or not subsequently incrementing the iterator will ever result in an iterator referencing the removed or added directory entry.
See POSIX readdir.
— end note]

31.12.11.2 Members [fs.dir.itr.members]

directory_iterator() noexcept;
Effects: Constructs the end iterator.
explicit directory_iterator(const path& p); directory_iterator(const path& p, directory_options options); directory_iterator(const path& p, error_code& ec); directory_iterator(const path& p, directory_options options, error_code& ec);
Effects: For the directory that p resolves to, constructs an iterator for the first element in a sequence of directory_entry elements representing the files in the directory, if any; otherwise the end iterator.
However, if (options & directory_options::skip_permission_denied) != directory_options::none and construction encounters an error indicating that permission to access p is denied, constructs the end iterator and does not report an error.
Throws: As specified in [fs.err.report].
[Note 1: 
To iterate over the current directory, use directory_iterator(".") rather than directory_iterator("").
— end note]
directory_iterator(const directory_iterator& rhs); directory_iterator(directory_iterator&& rhs) noexcept;
Postconditions: *this has the original value of rhs.
directory_iterator& operator=(const directory_iterator& rhs); directory_iterator& operator=(directory_iterator&& rhs) noexcept;
Effects: If *this and rhs are the same object, the member has no effect.
Postconditions: *this has the original value of rhs.
Returns: *this.
directory_iterator& operator++(); directory_iterator& increment(error_code& ec);
Effects: As specified for the prefix increment operation of Input iterators.
Returns: *this.
Throws: As specified in [fs.err.report].

31.12.11.3 Non-member functions [fs.dir.itr.nonmembers]

These functions enable range access for directory_iterator.
directory_iterator begin(directory_iterator iter) noexcept;
Returns: iter.
directory_iterator end(directory_iterator) noexcept;
Returns: directory_iterator().