cppdraft_translate/cppdraft/fs/class/directory/iterator.md

[fs.class.directory.iterator]

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]

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 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};}

2

#

directory_iterator meets theCpp17InputIterator 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 the 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 2:

The exact mechanism for storing cached attribute values is not exposed to users.

— end note]

10

#

[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]

11

#

[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;

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 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;

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 ofInput iterators.

10

#

Returns: *this.

11

#

Throws: As specified in [fs.err.report].

31.12.11.3 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(directory_iterator) noexcept;

3

#

Returns: directory_iterator().