Directory Iterators

1namespace fs = std::filesystem;

We can navigate through a directory using a fs::directory_iterator pair. By passing a fs::path to this type, we can define the directory we want to iterate through.

The default constructor for fs::directory_iterator returns a sentinel, which we can use to indicate when we've iterated through all the files and directories in the path. We cover iterators and sentinels in more detail in these lessons:

To use these iterators manually, we can increment our starting iterator until it becomes equal to the default-constructed sentinel:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::directory_iterator Start{R"(c:\test)"};  
7  fs::directory_iterator End{};                
8
9  for (auto Iter{Start}; Iter != End; ++Iter) {
10    std::cout << Iter->path().string() << '\n';
11  }
12}

1c:\test\file.txt
2c:\test\hello.backup
3c:\test\hello.txt
4c:\test\subdirectory

Instead of working with iterators directly, we can use them to create a subrange. We can then use this subrange to apply range-based techniques. Below, we iterate through a directory using a range-based for loop:

1#include <filesystem>
2#include <iostream>
3#include <ranges>
4namespace fs = std::filesystem;
5
6int main() {
7  using std::ranges::subrange;
8
9  subrange DirectoryEntries{
10    fs::directory_iterator{R"(c:\test)"}};
11
12  for (const auto& Entry : DirectoryEntries) {
13    std::cout << Entry.path().string() << '\n';
14  }
15}

1c:\test\file.txt
2c:\test\hello.backup
3c:\test\hello.txt
4c:\test\subdirectory

Below, we use a range-based algorithm (std::ranges::for_each) to output some additional information about the contents of our directory:

1#include <filesystem>
2#include <iostream>
3#include <ranges>
4namespace fs = std::filesystem;
5
6void Log(const fs::directory_entry& Entry) {
7  std::cout << Entry.path().string();
8
9  if (Entry.is_directory()) {
10    std::cout << " (Directory)\n";
11  } else if (Entry.is_regular_file()) {
12    std::cout << " ("
13      << Entry.file_size() << " Bytes)\n";
14  }
15}
16
17int main() {
18  using std::ranges::subrange;
19
20  std::ranges::for_each(
21    fs::directory_iterator{R"(c:\test)"}, Log);
22}

1c:\test\file.txt (0 Bytes)
2c:\test\hello.backup (24 Bytes)
3c:\test\hello.txt (24 Bytes)
4c:\test\subdirectory (Directory)

By default, the fs::directory_iterator only iterates through the first level of entries within our directory. If an entry is a subdirectory, we will not navigate into it.

We could build this logic ourselves, by implementing recursive behavior when fs::is_directory returns true. However, the standard library has built this for us, in the form of the fs::recursive_directory_iterator

The recursive directory iterator works the same way as the fs::directory_iterator, except it will navigate into any subdirectories it finds along the way.

The following code is almost identical to the previous example. Only a single line (which we've highlighted) has been changed, switching our iterator type:

1#include <filesystem>
2#include <iostream>
3#include <ranges>
4namespace fs = std::filesystem;
5
6int main() {
7  using std::ranges::subrange;
8
9   subrange DirectoryEntries{
10     fs::recursive_directory_iterator{
11       R"(c:\test)"}};
12
13  for (const auto& Entry : DirectoryEntries) {
14    std::cout << Entry.path().string();
15
16    if (Entry.is_directory()) {
17      std::cout << " (Directory)\n";
18    } else if (Entry.is_regular_file()) {
19      std::cout << " (" << Entry.file_size()
20        << " Bytes)\n";
21    }
22  }
23}

We can now navigate into subdirectories:

1c:\test\file.txt (0 Bytes)
2c:\test\hello.backup (24 Bytes)
3c:\test\hello.txt (24 Bytes)
4c:\test\subdirectory (Directory)
5c:\test\subdirectory\deep.txt (10 Bytes)

The recursive iterator has an additional method, called depth(). This will return the depth of the recursion, ie, how deeply nested the current directory entry is, relative to our starting point:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::recursive_directory_iterator Start{
7      R"(c:\test)"};
8  fs::recursive_directory_iterator End{};
9
10  for (auto Iter{Start}; Iter != End; ++Iter) {
11    std::cout << "Depth " << Iter.depth()
12              << " - " << Iter->path().string()
13              << '\n';
14  }
15}

1Depth 0 - c:\test\file.txt
2Depth 0 - c:\test\hello.backup
3Depth 0 - c:\test\hello.txt
4Depth 0 - c:\test\subdirectory
5Depth 1 - c:\test\subdirectory\deep.txt

Up next, we'll start working with file streams. These are the main ways we create, read, and update files within our file systems.

In this lesson, we've explored the essentials of directory iteration, demonstrating how to navigate and manage file systems using fs::directory_iterator and fs::recursive_directory_iterator.

Key Takeaways

• Utilizing fs::directory_iterator: Learned how to utilize fs::directory_iterator to traverse a directory, handling each file and subdirectory within a given path using a straightforward for-loop.
• Creating Subranges with Iterators: Gained skills in generating subranges from directory iterators, unlocking the ability to use range-based techniques and algorithms in our subdirectory.
• Navigating Deeply with fs::recursive_directory_iterator: Explored the use of fs::recursive_directory_iterator for deep navigation into directories, automatically iterating through all subdirectories.
• Employing the Depth Method: Acquired knowledge on using the depth() method of the recursive directory iterator to ascertain the level of recursion and understand the hierarchy of files and directories.