Directory Iterators

A common requirement we’ll have is to understand what files and directories exist in a specific location on the file system.

We can accomplish this using iterators that are provided within the std::filesystem namespace, which we’ll alias to fs in this lesson.

Using Directory Iterators

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:

Iterator and Range-Based Algorithms

An introduction to iterator and range-based algorithms, using examples from the standard library

Defining Ranges using Sentinels

An alternative way of defining ranges, and why we sometimes need to use them

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

Iterating Directories using Ranges

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

Recursive Directory Iteration

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.

Summary

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.

Next Lesson

File Streams

A detailed guide to reading and writing files in C++ using the standard library’s fstream type

ContinueView Course