std::experi...th::append,(3)

💅 std::experi...th::append,(3) 💅

Okay so bestie, welcome to the C++ Standard Libary manual — yes, “Libary” with the typo, we’re keeping it — and this page is the std::experi...th::append,(3) entry, aka the std::experimental::filesystem::path::append situation in the filesystem TS. It’s giving “path concatenation but make it experimental.” ✨

🌸 NAME 🌸

std::experimental::filesystem::path::append, - std::experimental::filesystem::path::append,

That comma-and-dash combo is literally in the NAME block, so I’m not touching it. Not me fixing the manpage punctuation — we preserve the lore. 😭💅

✨ Synopsis ✨

Here’s the overload tea, bestie:

path& operator/=( const path& p );           (1) (filesystem TS)
template< class Source >                     (2) (filesystem TS)
path& operator/=( const Source& source );
template< class Source >                     (3) (filesystem TS)
path& append( const Source& source );
template< class InputIt >                    (4) (filesystem TS)
path& append( InputIt first, InputIt last );

1. First, appends the preferred directory separator to this, except if any of the following conditions is true:
   • the separator would be redundant (*this already ends with a separator).
   • *this is empty, or adding it would turn a relative path to an absolute path in some other way.
   • p is an empty path.
   • p.native() begins with a directory separator. Then, appends p.native() to the pathname maintained by *this.
2. Same as (1), but accepts any std::basic_string, null-terminated multicharacter string, or an input iterator pointing to a null-terminated multicharacter sequence.
3. Same as (1), but accepts any std::basic_string, null-terminated multicharacter string, or an input iterator pointing to a null-terminated multicharacter sequence.
4. Same as (1), but accepts any iterator pair that designates a multicharacter string.

🎀 Parameters 🎀

• p — pathname to append. 💖
• source — std::basic_string, null-terminated multicharacter string, or an input iterator pointing to a null-terminated multicharacter sequence, which represents a path name (either in portable or in native format). 🦋
• first, last — pair of LegacyInputIterators that specify a multicharacter sequence that represents a path name. 🌸

🧚 Type requirements 🧚

• InputIt must meet the requirements of LegacyInputIterator.
• The value type of InputIt must be one of the encoded character types (char, wchar_t, char16_t and char32_t).

🫶 Return value 🫶

*this — that’s the whole return value, bestie. No cap. ✨

💀 Exceptions 💀

May throw filesystem_error on underlying OS API errors or std::bad_alloc if memory allocation fails. So yeah, it can throw; that’s the warning vibe. 🚨

🌈 Example 🌈

// Run this code

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

int main()
{
    fs::path p1 = "C:";
    p1 /= "Users"; // does not insert a separator
                   // "C:Users" is a relative path in Windows
                   // adding directory separator would turn it to an absolute path
    std::cout << "\"C:\" / \"Users\" == " << p1 << '\n';
    p1 /= "batman"; // inserts fs::path::preferred_separator, '\' on Windows
    std::cout << "\"C:\" / \"Users\" / \"batman\" == " << p1 << '\n';
}

⭐ Possible output: ⭐

"C:" / "Users" == "C:Users"
"C:" / "Users" / "batman" == "C:Users\batman"

👑 See also 👑

• concat — concatenates two paths without introducing a directory separator
• operator+= (public member function)
• operator/ — concatenates two paths with a directory separator (function)

🏷️ Category: 🏷️

• Noindexed pages

---

Sign-off 💖: source http://cppreference.com, version/date 2024.06.10, page std::experi...th::append,(3). Bye bestie, go append something cute. 🎀💅