30 Input/output library [input.output]

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) noexcept;
    directory_iterator(const path& p, directory_options options,
                       error_code& ec) noexcept;
    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) noexcept;

    // other members as required by [input.iterators], input iterators
  };
}

directory_­iterator satisfies the requirements of an input iterator.

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 ]