29 Input/output library [input.output]

29.11 File systems [filesystems]

29.11.12 Class directory_­iterator [fs.class.directory.iterator]

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
:
For iteration into sub-directories, 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);

    // 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 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
:
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
:
Programs performing directory iteration may wish to test if the path obtained by dereferencing a directory iterator actually exists.
It could be a symbolic link to a non-existent file.
Programs recursively walking directory trees for purposes of removing and renaming entries may wish to avoid following symbolic links.
— end note
]
[Note
:
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_­r.
— end note
]

29.11.12.1 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
:
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].

29.11.12.2 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(const directory_iterator&) noexcept;
Returns: directory_­iterator().