29 Input/output library [input.output]

29.11 File systems [filesystems]

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

1
#
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
  };
}
2
#
directory_­iterator meets the Cpp17InputIterator requirements ([input.iterators]).
3
#
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.
4
#
The end iterator is not dereferenceable.
5
#
Two end iterators are always equal.
An end iterator shall not be equal to a non-end iterator.
6
#
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/=.
7
#
Directory iteration shall not yield directory entries for the current (dot) and parent (dot-dot) directories.
8
#
The order of directory entries obtained by dereferencing successive increments of a directory_­iterator is unspecified.
9
#
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
]
10
#
[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
]
11
#
[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;
1
#
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);
2
#
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.
3
#
Throws: As specified in [fs.err.report].
4
#
[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;
5
#
Postconditions: *this has the original value of rhs.
🔗
directory_iterator& operator=(const directory_iterator& rhs); directory_iterator& operator=(directory_iterator&& rhs) noexcept;
6
#
Effects: If *this and rhs are the same object, the member has no effect.
7
#
Postconditions: *this has the original value of rhs.
8
#
Returns: *this.
🔗
directory_iterator& operator++(); directory_iterator& increment(error_code& ec);
9
#
Effects: As specified for the prefix increment operation of Input iterators.
10
#
Returns: *this.
11
#
Throws: As specified in [fs.err.report].

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

1
#
These functions enable range access for directory_­iterator.
🔗
directory_iterator begin(directory_iterator iter) noexcept;
2
#
Returns: iter.
🔗
directory_iterator end(const directory_iterator&) noexcept;
3
#
Returns: directory_­iterator().