File System Paths

In the previous lessons, we represented our file paths as simple strings, but the standard library provides a dedicated class for this: std::filesystem::path.

This type provides additional utility specific to working with the file system. We’ll alias it to fs::path in this lesson.

Creating fs::path Objects

We can create fs::path objects using simple strings:

1#include <filesystem>
2namespace fs = std::filesystem;
3
4int main() {
5  fs::path Location{R"(c:\test)"};
6}

We can get the string representation of a path using the string() method, which is useful when we want to display it:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::path Location{R"(c:\test)"};
7
8  std::cout << Location.string();
9}

1c:\test

Using fs::path Objects with Directory Entries

The fs::directory_entry constructor we’ve been using in the previous lesson accepts an fs::path argument:

1#include <filesystem>
2namespace fs = std::filesystem;
3
4int main() {
5  fs::path Location{R"(c:\test)"};
6  fs::directory_entry File{Location};
7}

Since fs::path can be created from a string, our fs::path objects were being created implicitly:

1#include <filesystem>
2namespace fs = std::filesystem;
3
4int main() {
5  // Implicitly converting raw string to fs::path
6  fs::directory_entry File{R"(c:\test)"};
7}

We can get the fs::path associated with a fs::directory_entry using the path() method:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::directory_entry Entry{R"(c:\test)"};
7
8  std::cout << Entry.path().string();
9}

1c:\test

Accessing fs::path Components

A variety of methods give us access to specific parts of the path. These also return fs::path objects, so in the following example we use the string() method to display them:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::path Location{R"(c:\test\hello.txt)"};
7
8  std::cout << "File Name: "
9            << Location.filename().string();
10
11  std::cout << "\nFile Stem: "
12            << Location.stem().string();
13
14  std::cout << "\nFile Extension: "
15            << Location.extension().string();
16
17  std::cout << "\nParent Path: "
18            << Location.parent_path().string();
19
20  std::cout << "\nRoot Path: "
21            << Location.root_name().string();
22}

1File Name: hello.txt
2File Stem: hello
3File Extension: .txt
4Parent Path: c:\test
5Root Path: c:

Equivalent boolean methods return true or false based on the existence of any of these path components.

We can access these by prepending has_ to the method names. For example, has_filename() and has_extension()

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::path Directory{R"(c:\test\)"};
7  if (!Directory.has_filename()) {
8    std::cout << Directory.string()
9              << " has no file name\n";
10  }
11
12  fs::path File{R"(c:\hi.txt)"};
13  if (File.has_extension()) {
14    std::cout << File.string()
15              << " has a file extension";
16  }
17}

1c:\test\ has no file name
2c:\hi.txt has a file extension

Note that the result of these functions is based only on the format of the provided string. For example, the has_filename() method returns true if it appears that the provided string has a filename.

To access the file system and check whether there really is a file at that path, we need to create a fs::directory_entry, not just a fs::path. We can then call a method like is_regular_file(), as we covered in the previous lesson.

Working with fs::path file names

When working with paths, a common requirement is to manipulate the file name. We have some methods to help us there:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::path File{R"(c:\test\hello.txt)"};
7  std::cout << File.string() << '\n';
8
9  File.replace_filename("world.txt");
10  std::cout << File.string() << '\n';
11
12  File.replace_extension("doc");
13  std::cout << File.string() << '\n';
14
15  File.remove_filename();
16  std::cout << File.string();
17}

1c:\test\hello.txt
2c:\test\world.txt
3c:\test\world.doc
4c:\test\

Use cases for these methods typically come up when we're creating reusable functions.

For example, the following function creates a file, but the location of the file it creates is derived from an argument. In this case, it will create the file c:\test\hello.backup:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5void CreateBackup(const fs::path& Path) {
6  fs::path Backup{Path};
7  Backup.replace_extension("backup");
8  fs::copy_file(Path, Backup);
9}
10
11int main() {
12  CreateBackup(R"(c:\test\hello.txt)");
13}

Appending to an fs::path

The fs::path type also overrides the /= operator, which allows us to create paths to subdirectories or files. This is done by automatically appending separators that are appropriate to the underlying operating system:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::path File{R"(c:\)"};
7  std::cout << File.string() << '\n';
8
9  File /= "test";
10  std::cout << File.string() << '\n';
11
12  File /= "hello.txt";
13  std::cout << File.string() << '\n';
14}

1c:\
2c:\test
3c:\test\hello.txt

This operator, and most of the fs::path methods, returns a reference to the original object. This allows them to be chained:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::path File{R"(c:\test\hello.txt)"};
7  std::cout << File.string() << '\n';
8
9  File.remove_filename() /= "subdirectory";  
10  std::cout << File.string() << '\n';
11
12  (File /= "nested") /= "directory";
13  std::cout << File.string();
14}

1c:\test\hello.txt
2c:\test\subdirectory
3c:\test\subdirectory\nested\directory

Relative Paths

All the paths we’ve shown so far have been absolute paths. If we wanted to access files in an exact location, we should use absolute paths.

However, if we want to access files in a location relative to where our program is installed, we don’t necessarily know the exact location in advance. For this, we use relative paths.

Relative paths are based on another directory, often referred to as the current path or current working directory.

We can check if a path is relative or absolute using the is_relative() and is_absolute() methods:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::path A{R"(c:\test\hello.txt)"};
7  if (A.is_absolute()) {
8    std::cout << "A is Absolute";
9  }
10
11  fs::path B{R"(hello.txt)"};
12  if (B.is_relative()) {
13    std::cout << "B is Relative";
14  }
15}

1A is Absolute
2B is Relative

We can retrieve the current path that relative paths are based on using the current_path() method. Its default value depends on our settings, but we can pass a new path to that function to set a new current path for our relative paths:

1#include <filesystem>
2#include <iostream>
3namespace fs = std::filesystem;
4
5int main() {
6  fs::directory_entry Entry{R"(hello.txt)"};
7
8  std::cout
9      << "The default working directory is:\n"
10      << fs::current_path().string();
11
12  if (!Entry.exists()) {
13    std::cout << "\nThe file was not found\n\n";
14  }
15
16  // Setting the current path to a new lcoation
17  fs::current_path(R"(c:\test)");
18
19  std::cout << "The current working directory "
20               "was changed to:\n"
21            << fs::current_path().string();
22
23  if (Entry.exists()) {
24    std::cout << "\nThe file was found!";
25  }
26}

1The working directory is:
2C:\Users\ryan\repos\cpp
3The file was not found
4
5The working directory was changed to:
6c:\test
7The file was found!

Summary

In this lesson, we explored the versatile capabilities of std::filesystem::path, demonstrating how to create, manipulate, and use file paths effectively. We covered various operations from basic path creation to advanced manipulations.

Key Takeaways

• Learned to create and use fs::path objects for representing and manipulating file paths.
• Explored methods to access and modify different components of a file path, like filename, extension, and parent path.
• Discovered how to append subdirectories or files to a path using the /= operator, with examples demonstrating path chaining.
• Understood the distinction between absolute and relative paths and how to determine the type of a given path.
• Gained insights into setting and retrieving the current working directory using fs::current_path().

Next Lesson

Directory Iterators

An introduction to iterating through the file system, using directory iterators and recursive directory iterators

ContinueView Course