FreeBSD Manual Pages
std::filesy...ory_iterator(3) C++ Standard Libarystd::filesy...ory_iterator(3) NAME std::filesystem::directory_iterator - std::filesystem::directory_itera- tor Synopsis Defined in header <filesystem> class directory_iterator; (since C++17) directory_iterator is a LegacyInputIterator that iterates over the directory_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 pathnames dot and dot-dot are skipped. If the directory_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 in- crementing 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. Member types Member type Definition value_type std::filesystem::directory_entry difference_type std::ptrdiff_t pointer const std::filesystem::directory_entry* reference const std::filesystem::directory_entry& iterator_category std::input_iterator_tag Member functions constructor constructs a directory iterator (public member function) destructor default destructor (public member function) operator= assigns contents (public member function) operator* accesses the pointed-to entry operator-> (public member function) increment advances to the next entry operator++ (public member function) Non-member functions begin(std::filesystem::directory_iterator) range-based for loop sup- port end(std::filesystem::directory_iterator) (function) (C++17) Additionally, operator== and operator!= are (until C++20) operator== is (since C++20) provided as required by LegacyInputIterator. It is unspecified whether operator!= is provided because it can be synthesized from operator==, and (since C++20) whether an equality operator is a member or non-mem- ber. Helper templates namespace std::ranges { template<> (since inline constexpr bool C++20) enable_borrowed_range<std::filesystem::directory_iterator> = true; } namespace std::ranges { template<> (since inline constexpr bool enable_view<std::filesystem::directory_itera- tor> = C++20) true; } These specializations for directory_iterator make it a bor- rowed_range and a view. Notes Many low-level OS APIs for directory traversal retrieve file attrib- utes along with the next directory entry. The constructors and the non-const member functions of std::filesystem::directory_iterator store these attributes, if any, in the pointed-to std::filesystem::directory_entry without calling directory_entry::refresh, which makes it possible to examine the at- tributes of the directory entries as they are being iterated over, without making additional system calls. Example // Run this code #include <algorithm> #include <filesystem> #include <fstream> #include <iostream> int main() { const std::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 loop for (auto const& dir_entry : std::filesystem::directory_itera- tor{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}, [](const auto& dir_entry) { std::cout << dir_entry << '\n'; }); std::cout << "\nrecursive_directory_iterator:\n"; for (auto const& dir_entry : std::filesystem::recursive_direc- tory_iterator{sandbox}) std::cout << dir_entry << '\n'; // delete the sandbox dir and all contents within it, including subdirs std::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" Defect reports The following behavior-changing defect reports were applied retroac- tively to previously published C++ standards. DR Applied to Behavior as published Correct behavior LWG 3480 C++20 directory_iterator was neither a borrowed_range it is both nor a view See also recursive_directory_iterator an iterator to the contents of a direc- tory and its (C++17) subdirectories (class) directory_options options for iterating directory con- tents (C++17) (enum) directory_entry a directory entry (C++17) (class) http://cppreference.com 2024.06.10 std::filesy...ory_iterator(3)
NAME | Synopsis | Member types | Member functions | Non-member functions | Notes | Example | Possible output: | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::filesystem::directory_iterator&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>