std::experi...stem::rename(3)

okay so this is the std::experi...stem::rename(3) page from the C++ Standard Libary manual — yes, that’s literally the manual name, typo and all, and I’m obsessed 💅. It’s giving filesystem TS realness, and we’re gonna get through every detail together, bestie. 🫶

💅 NAME 💅

std::experimental::filesystem::rename - std::experimental::filesystem::rename

Two names, same icon, no cap. ✨

🦋 Synopsis 🦋

Defined in header <experimental/filesystem> — that’s the include, bestie. The signatures are literally:

void rename( const path& old_p, const path& new_p );
void rename( const path& old_p, const path& new_p, std::error_code&
       (filesystem TS)
          ec );

It moves or renames the filesystem object identified by old_p to new_p, as if by the POSIX rename:

• If old_p is a non-directory file, then new_p must be one of:
  • the same file as old_p or a hardlink to it: nothing is done in this case.
  • existing non-directory file: new_p is first deleted, then, without allowing other processes to observe new_p as deleted, the pathname new_p is linked to the file and old_p is unlinked from the file. Write permissions are required to both the directory that contains old_p and the directory that contains new_p.
  • non-existing file in an existing directory: The pathname new_p is linked to the file and old_p is unlinked from the file. Write permissions are required to both the directory that contains old_p and the directory that contains new_p.
• If old_p is a directory, then new_p must be one of:
  • the same directory as old_p or a hardlink to it: nothing is done in this case.
  • existing directory: new_p is deleted if empty on POSIX systems, but this may be an error on other systems. If not an error, then new_p is first deleted, then, without allowing other processes to observe new_p as deleted, the pathname new_p is linked to the directory and old_p is unlinked from the directory. Write permissions are required to both the directory that contains old_p and the directory that contains new_p.
  • non-existing directory, not ending with a directory separator, and whose parent directory exists: The pathname new_p is linked to the directory and old_p is unlinked from the directory. Write permissions are required to both the directory that contains old_p and the directory that contains new_p.
• Symlinks are not followed: if old_p is a symlink, it is itself renamed, not its target. If new_p is an existing symlink, it is itself erased, not its target.

Rename fails if 😭

• new_p ends with dot or with dot-dot.
• new_p names a non-existing directory ending with a directory separator.
• old_p is a directory which is an ancestor of new_p.

🌸 Parameters 🌸

• old_p — path to move or rename
• new_p — target path for the move/rename operation
• ec — out-parameter for error reporting in the non-throwing overload

🎀 Return value 🎀

(none) — no return value, periodt. 💅

🔥 Exceptions 🔥

The overload that does not take an error_code& parameter throws filesystem_error on underlying OS API errors, constructed with old_p as the first argument, new_p as the second argument, and the OS error code as the error code argument. std::bad_alloc may be thrown if memory allocation fails. The overload taking an error_code& parameter sets it to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur. This overload has noexcept specification: noexcept

👑 Example 👑

okay this example is literally right here, bestie — run it if you want:

// Run this code

        #include <experimental/filesystem>
        #include <fstream>
        #include <iostream>
        namespace fs = std::experimental::filesystem;

        int main()
        {
            fs::path p = fs::current_path() / "sandbox";
            fs::create_directories(p/"from");
            std::ofstream(p/"from/file1.txt").put('a');
            fs::create_directory(p/"to");

        //  fs::rename(p/"from/file1.txt", p/"to/"); // error: to is a
       directory
            fs::rename(p/"from/file1.txt", p/"to/file2.txt"); // OK
        //  fs::rename(p/"from", p/"to"); // error: to is not empty
            fs::rename(p/"from", p/"to/subdir"); // OK

            fs::remove_all(p);
        }

🌈 See also 🌈

• rename — renames a file (function)
• remove — removes a file or empty directory
• remove_all — removes a file or directory and all its contents, recursively (function)

🏷️ Categories: 🏷️

• Noindexed pages
• unconditionally noexcept

🙈 Hidden categories: 🙈

• Pages with unreviewed unconditional noexcept template
• Pages with unreviewed noexcept template

---

okay that’s the whole page, mwah 💋 — sourced from http://cppreference.com, version/date 2024.06.10, page std::experi...stem::rename(3). bye bestie! 🫶✨