Defined in header <filesystem> | ||
class directory_iterator; | (since C++17) | |
directory_iterator is aLegacyInputIterator that iterates over thedirectory_entry elements of a directory (but does not visit the subdirectories). The iteration order is unspecified, except that each directory entry is visited only once. The special pathnamesdot anddot-dot are skipped.
If thedirectory_iterator reports an error or is advanced past the last directory entry, it becomes equal to the default-constructed iterator, also known as the end iterator. Two end iterators are always equal, dereferencing or incrementing the end iterator is undefined behavior.
If a file or a directory is deleted or added to the directory tree after the directory iterator has been created, it is unspecified whether the change would be observed through the iterator.
Contents |
| Member type | Definition |
value_type | std::filesystem::directory_entry |
difference_type | std::ptrdiff_t |
pointer | conststd::filesystem::directory_entry* |
reference | conststd::filesystem::directory_entry& |
iterator_category | std::input_iterator_tag |
| constructs a directory iterator (public member function)[edit] | |
(destructor) | default destructor (public member function)[edit] |
| assigns contents (public member function)[edit] | |
| accesses the pointed-to entry (public member function)[edit] | |
| advances to the next entry (public member function)[edit] |
| range-based for loop support (function)[edit] |
Additionally,operator== andoperator!= are(until C++20)operator== is(since C++20) provided as required byLegacyInputIterator.
It is unspecifiedwhetheroperator!= is provided because it can be synthesized fromoperator==, and(since C++20) whether an equality operator is a member or non-member.
template<> constexprbool | (since C++20) | |
template<> constexprbool | (since C++20) | |
These specializations fordirectory_iterator make it aborrowed_range and aview.
Many low-level OS APIs for directory traversal retrieve file attributes along with the next directory entry. The constructors and the non-const member functions ofstd::filesystem::directory_iterator store these attributes, if any, in the pointed-tostd::filesystem::directory_entry without callingdirectory_entry::refresh, which makes it possible to examine the attributes of the directory entries as they are being iterated over, without making additional system calls.
#include <algorithm>#include <filesystem>#include <fstream>#include <iostream> int main(){conststd::filesystem::path sandbox{"sandbox"};std::filesystem::create_directories(sandbox/"dir1"/"dir2");std::ofstream{sandbox/"file1.txt"};std::ofstream{sandbox/"file2.txt"}; std::cout<<"directory_iterator:\n";// directory_iterator can be iterated using a range-for loopfor(autoconst& dir_entry: std::filesystem::directory_iterator{sandbox})std::cout<< dir_entry.path()<<'\n'; std::cout<<"\ndirectory_iterator as a range:\n";// directory_iterator behaves as a range in other ways, too std::ranges::for_each( std::filesystem::directory_iterator{sandbox},[](constauto& dir_entry){std::cout<< dir_entry<<'\n';}); std::cout<<"\nrecursive_directory_iterator:\n";for(autoconst& dir_entry:std::filesystem::recursive_directory_iterator{sandbox})std::cout<< dir_entry<<'\n'; // delete the sandbox dir and all contents within it, including subdirsstd::filesystem::remove_all(sandbox);}
Possible output:
directory_iterator:"sandbox/file2.txt""sandbox/file1.txt""sandbox/dir1" directory_iterator as a range:"sandbox/file2.txt""sandbox/file1.txt""sandbox/dir1" recursive_directory_iterator:"sandbox/file2.txt""sandbox/file1.txt""sandbox/dir1""sandbox/dir1/dir2"
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 3480 | C++20 | directory_iterator was neither aborrowed_range nor aview | it is both |
(C++17) | an iterator to the contents of a directory and its subdirectories (class)[edit] |
(C++17) | options for iterating directory contents (enum)[edit] |
(C++17) | a directory entry (class)[edit] |
