std::basic_string::append(3)

💖 NAME 💖

Okay so welcome to std::basic_string::append(3), bestie — this page comes from the C++ Standard Libary manual (yes, that spelling is staying, it's iconic 💅). The name of this whole serve is std::basic_string::append — std::basic_string::append, and it's literally the member function for adding more characters to the end of a string. Periodt.

---

🌸 Synopsis 🌸

basic_string& append( size_type count, CharT ch );              (1) (constexpr since C++20)
basic_string& append( const basic_string& str );                (2) (constexpr since C++20)
basic_string& append( const basic_string& str,
                      size_type pos, size_type count );          (3) (until C++14)
basic_string& append( const basic_string& str,
                      size_type pos, size_type count = npos );   (3) (since C++14) (constexpr since C++20)
basic_string& append( const CharT* s, size_type count );         (4) (constexpr since C++20)
basic_string& append( const CharT* s );                          (5) (constexpr since C++20)
template< class InputIt >
basic_string& append( InputIt first, InputIt last );             (6) (constexpr since C++20)
basic_string& append( std::initializer_list<CharT> ilist );      (7) (since C++11) (constexpr since C++20)
template< class StringViewLike >
basic_string& append( const StringViewLike& t );                 (8) (since C++17) (constexpr since C++20)
template< class StringViewLike >
basic_string& append( const StringViewLike& t,
                      size_type pos, size_type count = npos );   (9) (since C++17) (constexpr since C++20)

Appends additional characters to the string. That's the whole vibe, but the overloads each have their own little personality, so let's get into it.

1. Appends count copies of character ch. ✨
2. Appends string str. 💖
3. Appends a substring [pos, pos + count) of str.
   • If the requested substring lasts past the end of the string, or if count == npos, the appended substring is [pos, size()).
   • If pos > str.size(), std::out_of_range is thrown. Not cute.
4. Appends characters in the range [s, s + count). This range can contain null characters. If [s, s + count) is not a valid range, the behavior is undefined. That's a real warning, bestie — undefined behavior is not a slay.
5. Appends the null-terminated character string pointed to by s, as if by append(s, Traits::length(s)).
6. Appends characters in the range [first, last).
   • Until C++11: this overload has the same effect as overload (1) if InputIt is an integral type.
   • Since C++11: this overload only participates in overload resolution if InputIt qualifies as a LegacyInputIterator.
7. Appends characters from the initializer list ilist.
8. Implicitly converts t to a string view sv as if by std::basic_string_view<CharT, Traits> sv = t;, then appends all characters from sv as if by append(sv.data(), sv.size()). This overload participates in overload resolution only if std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const StringViewLike&, const CharT*> is false.
9. Implicitly converts t to a string view sv as if by std::basic_string_view<CharT, Traits> sv = t;, then appends the characters from the subview [pos, pos + count) of sv.
   • If the requested subview extends past the end of sv, or if count == npos, the appended subview is [pos, sv.size()).
   • If pos >= sv.size(), std::out_of_range is thrown. Again: rude, but that's the rule. This overload participates in overload resolution only if std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const StringViewLike&, const CharT*> is false.

---

🎀 Parameters 🎀

• count — number of characters to append
• pos — the index of the first character to append
• ch — character value to append
• first, last — range of characters to append
• str — string to append
• s — pointer to the character string to append
• ilist — initializer list with the characters to append
• t — object convertible to std::basic_string_view with the characters to append

---

🫶 Return value 🫶

*this

Bestie, that return value is why you can chain calls like it's nothing. Main character behavior, honestly.

---

🦋 Complexity 🦋

There are no standard complexity guarantees, typical implementations behave similar to std::vector::insert(). So like… don't quote me on the exact Big-O, because the standard isn't giving us one.

---

💜 Exceptions 💜

If the operation would result in size() > max_size(), throws std::length_error.

If an exception is thrown for any reason, this function has no effect — it has the strong exception safety guarantee. That's a very "we may have failed, but we did not leave a mess" moment.

---

🌈 Example 🌈

// Run this code

#include <iostream>
#include <string>

int main()
{
    std::basic_string<char> str = "string";
    const char* cptr = "C-string";
    const char carr[] = "Two and one";

    std::string output;

    // 1) Append a char 3 times.
    // Notice, this is the only overload accepting chars.
    output.append(3, '*');
    std::cout << "1) " << output << '\n';

    // 2) Append a whole string
    output.append(str);
    std::cout << "2) " << output << '\n';

    // 3) Append part of a string (last 3 letters, in this case)
    output.append(str, 3, 3);
    std::cout << "3) " << output << '\n';

    // 4) Append part of a C-string
    // Notice, because `append` returns *this, we can chain calls together
    output.append(1, ' ').append(carr, 4);
    std::cout << "4) " << output << '\n';

    // 5) Append a whole C-string
    output.append(cptr);
    std::cout << "5) " << output << '\n';

    // 6) Append range
    output.append(&carr[3], std::end(carr));
    std::cout << "6) " << output << '\n';

    // 7) Append initializer list
    output.append({' ', 'l', 'i', 's', 't'});
    std::cout << "7) " << output << '\n';
}

Output:

1) ***
2) ***string
3) ***stringing
4) ***stringing Two
5) ***stringing Two C-string
6) ***stringing Two C-string and one
7) ***stringing Two C-string and one list

---

🍓 Defect reports 🍓

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 847 — applied to C++98; behavior as published: there was no exception safety guarantee; correct behavior: added strong exception safety guarantee.
• LWG 2946 — applied to C++17; behavior as published: overload (8) causes ambiguity in some cases; correct behavior: avoided by making it a template.

---

👑 See also 👑

• append_range — appends a range of characters to the end (C++23) (public member function)
• operator+= — appends characters to the end (public member function)
• strcat — concatenates two strings (function)
• strncat — concatenates a certain amount of characters of two strings (function)
• wcscat — appends a copy of one wide string to another (function)
• wcsncat — appends a certain amount of wide characters from one wide string to another (function)

---

And that's the tea, bestie 💋: the source is http://cppreference.com, the page version/date is 2024.06.10, and the footer title is std::basic_string::append(3). Go forth and append responsibly — or at least with main character energy. 🎀✨