std::filesy...ce_filename(3)

💅 NAME 💅

std::filesystem::directory_entry::replace_filename — like, that's the whole name, it's a member function of std::filesystem::directory_entry and it lives in the C++ Standard Library, bestie. It swaps out the filename of a directory entry. Obsessed.

---

✨ SYNOPSIS ✨

void replace_filename( const std::filesystem::path& p );

(1) (since C++17)

void replace_filename( const std::filesystem::path& p,
                       std::error_code& ec );

(2) (since C++17)

---

🦋 DESCRIPTION 🦋

Okay so what this does: it changes the filename of the directory entry. ✨

Effectively, it modifies the path member by calling path.replace_filename(p), and then it calls refresh to update the cached attributes. Lowkey important: if an error occurs, the values of the cached attributes are unspecified. 🙈

Heads up bestie: this function does not commit any changes to the filesystem. It's giving "vibes only, no actual disk writes." 💅

---

🎀 PARAMETERS 🎀

• p — the path to append to the parent path of the currently stored path.
• ec — out-parameter for error reporting in the non-throwing overload.

---

⭐ RETURN VALUE ⭐

None. Nothing. Nada. (none) 🫶

---

🔥 EXCEPTIONS 🔥

Any overload not marked noexcept may throw std::bad_alloc if memory allocation fails. 😭

1. Throws std::filesystem::filesystem_error on underlying OS API errors, constructed with p as the first path argument and the OS error code as the error code argument.
2. Sets a std::error_code& parameter to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur.

---

🌸 EXAMPLE 🌸

// Run this code

#include <filesystem>
#include <iostream>

int main()
{
    namespace fs = std::filesystem;
    {
        fs::directory_entry entry{"alpha"};
        std::cout << entry << '\n';
        entry.replace_filename("omega");
        std::cout << entry << '\n';
    }
    {
        fs::directory_entry entry{"/alpha/"};
        std::cout << entry << '\n';
        entry.replace_filename("omega");
        std::cout << entry << '\n';
    }
}

🌈 Output 🌈

"alpha"
"omega"
"/alpha/"
"/alpha/omega"

---

👑 SEE ALSO 👑

• assign — assigns contents (public member function)
• replace_filename — replaces the last path component with another path (public member function of std::filesystem::path)

---

and that's the whole page, bestie — go forth and replace filenames responsibly 🧚💖

Sign-off time 🎀: this iconic little page comes from cppreference.com, dated 2024.06.10 — std::filesy...ce_filename(3), the manual entry that ate and left no crumbs. 💅🌸