CKTIS / C++
Joining paths with `/` in `std::filesystem`
The path slash operator returns a new path without changing either operand. The right operand’s syntax determines whether it appends to or replaces some or all of the left path.
Version: ISO C++23; implementation support may vary
Syntax
#include <filesystem>
// Friend declaration inside std::filesystem::path (not a member):
friend path operator/(const path& lhs, const path& rhs);
// Typical use, with base of type std::filesystem::path:
base / "guide.txt"In <filesystem>, the label std::filesystem::operator/ refers to a path-joining operator, not division or a member function. Available since C++17, it is a non-member friend in std::filesystem, found by argument-dependent lookup (ADL), not qualified lookup. Write base / "guide.txt" with base of type path; the literal converts to path. Two string literals alone do not work with /.
lhs / rhs applies /= to a copy of lhs and returns a path by value. The member /= changes the left operand and returns a reference to it, whereas += concatenates native pathname text without inserting a separator. If rhs is absolute or has a root name different from lhs, it replaces the whole left path. Otherwise, a root directory in rhs discards the left root directory and relative part but preserves its root name. The right path is then appended without its root name, using the preferred separator where the rules require it. Even an empty right operand can add a trailing separator.
Joining does not normalize. p.lexically_normal() returns a new path, removing redundant . components and simplifying pairs like drafts/... p.lexically_relative(base) computes the route from base to p without normalizing either first. Its initial checks return an empty path, for example, if the root names differ or if any filename in the relative part of either path can be interpreted as a root name. Identical component sequences yield . only if the paths pass those checks.
p.is_absolute() tests absoluteness under the platform’s rules; / alone is absolute on POSIX but not on Windows. p.empty() tests whether the generic pathname is empty, not whether a directory is empty. p.begin() points to the first path component, not a character or directory entry; it returns p.end() for an empty path. Do not use iterators after p is destroyed or after calling a non-const member on it. p.generic_string() returns a std::string with / separators, with no UTF-8 guarantee.
These operations work on pathname syntax: they do not check file existence or resolve symbolic links. Joining can throw, for example std::bad_alloc. Neither / nor lexically_normal() guarantees that an untrusted path stays inside a chosen directory: roots, .., or symbolic links can defeat that assumption.
Examples
#include <filesystem>
#include <iostream>
namespace fs = std::filesystem;
int main() {
const fs::path base{"docs"};
const fs::path joined = base / "./drafts/../guide.txt";
const fs::path normal = joined.lexically_normal();
const fs::path relative = normal.lexically_relative(base);
std::cout << "base: " << base.generic_string() << '\n'
<< "joined: " << joined.generic_string() << '\n'
<< "normal: " << normal.generic_string() << '\n'
<< "relative: " << relative.generic_string() << '\n'
<< "first: " << normal.begin()->generic_string() << '\n'
<< std::boolalpha
<< "absolute: " << normal.is_absolute() << '\n'
<< "relative.empty(): " << relative.empty() << '\n';
}Result
base: docs joined: docs/./drafts/../guide.txt normal: docs/guide.txt relative: guide.txt first: docs absolute: false relative.empty(): false
The example shows that `base` is unchanged. The joined path still contains `.` and `..`; normalization removes them. The route from `docs` to the normalized path is `guide.txt`.
Related lessons
- C++ · Lesson 48 · Advanced · Version: 3
Sources
- C++ working draft: path non-member functions [fs.path.nonmember]
- C++ working draft: hidden friends [hidden.friends]
- C++ working draft: argument-dependent name lookup [basic.lookup.argdep]
- C++ working draft: path appends [fs.path.append]
- C++ working draft: path concatenation [fs.path.concat]
- C++ working draft: path generation [fs.path.gen]
- C++ working draft: path queries [fs.path.query]
- C++ working draft: path iterators [fs.path.itr]
- C++ working draft: generic pathname format [fs.path.generic]
- C++ working draft: filesystem error reporting [fs.err.report]
- cppreference: std::filesystem::operator/(std::filesystem::path)
- cppreference: std::filesystem::path::generic_string and related observers