std::filesy...e_extension(3)

🌸 NAME 🌸

okay bestie, welcome to std::filesy...e_extension(3) — this is the C++ Standard Libary page (yes, “Libary”, we’re keeping the spelling 💅). The star of the show is std::filesystem::path::replace_extension - std::filesystem::path::replace_extension. Like, the original repeats it after the dash, and we respect the lore. 🫶

✨ Synopsis ✨

path& replace_extension( const path& replacement = path() );  (since C++17)

This one replaces the extension with replacement, or removes it when you use the default value of replacement. No cap. Here’s the little ritual it does:

• First up, if this path has an extension(), it gets removed from the generic-format view of the pathname. 🧚
• Then a dot character is appended to the generic-format view of the pathname, but only if replacement is not empty and does not begin with a dot character. ⭐
• Then replacement is appended as if by operator+=(replacement). Slay. 💅

🎀 Parameters 🎀

• replacement — the extension to replace with. That’s the whole assignment, bestie.

💖 Return value 💖

*this — it literally returns itself. Main character energy, honestly. 👑

😭 Exceptions 😭

May throw implementation-defined exceptions. So like, it’s not giving “guaranteed safe nap” — implementation-defined means exactly that. 🙈

📝 Notes 📝

The type of replacement is std::filesystem::path even though it is not intended to represent an object on the file system, in order to correctly account for the filesystem character encoding. iykyk — it’s a path type doing encoding homework, not a filesystem object.

🧪 Example 🧪

bestie, run this code:

// Run this code

#include <filesystem>
#include <iomanip>
#include <iostream>
#include <utility>

int main()
{
    const int width1{18}, width2{11}; // columns' width

    std::cout << std::left << std::setw(width1) << "Path:"
              << std::setw(width2) << "Ext:" << "Result:\n";
    for (const auto& [p, e] : {
            std::make_pair("/foo/bar.jpg", ".png"),
            {"/foo/bar.jpg", "png"},
            {"/foo/bar.jpg", "."},
            {"/foo/bar.jpg", ""},
            {"/foo/bar.", "png"},
            {"/foo/bar", ".png"},
            {"/foo/bar", "png"},
            {"/foo/bar", "."},
            {"/foo/bar", ""},
            {"/foo/.", ".png"},
            {"/foo/.", "png"},
            {"/foo/.", "."},
            {"/foo/.", ""},
            {"/foo/", ".png"},
            {"/foo/", "png"}})
    {
        std::filesystem::path path{p}, ext{e};
        std::cout << std::setw(width1) << path << std::setw(width2) <<
       ext;
        path.replace_extension(ext);
        std::cout << path << '\n';
    }
}

🖥️ Output 🖥️

Path:             Ext:       Result:
"/foo/bar.jpg"    ".png"     "/foo/bar.png"
"/foo/bar.jpg"    "png"      "/foo/bar.png"
"/foo/bar.jpg"    "."        "/foo/bar."
"/foo/bar.jpg"    ""         "/foo/bar"
"/foo/bar."       "png"      "/foo/bar.png"
"/foo/bar"        ".png"     "/foo/bar.png"
"/foo/bar"        "png"      "/foo/bar.png"
"/foo/bar"        "."        "/foo/bar."
"/foo/bar"        ""         "/foo/bar"
"/foo/."          ".png"     "/foo/..png"
"/foo/."          "png"      "/foo/..png"
"/foo/."          "."        "/foo/.."
"/foo/."          ""         "/foo/."
"/foo/"           ".png"     "/foo/.png"
"/foo/"           "png"      "/foo/.png"

👀 See also 👀

• extension — returns the file extension path component (public member function)
• filename — returns the filename path component (public member function)
• stem — returns the stem path component (filename without the final extension) (public member function)
• has_extension — checks if the corresponding path element is not empty (public member function)

that’s the whole vibe, bestie 🫶 this page is from http://cppreference.com, dated 2024.06.10, and it’s the std::filesy...e_extension(3) page. mwah 💋✨