std::basic_string::operator+=(3)

NAME
std::basic_string::operator+= - std::basic_string::operator+=

Synopsis
   basic_string& operator+=( const (until
   basic_string& str ); C++20)
   constexpr basic_string& operator+=( (since
   const basic_string& str ); C++20)
   basic_string& operator+=( CharT ch (until
   ); C++20)
   constexpr basic_string& operator+=( (since
   CharT ch ); C++20)
   basic_string& operator+=( const (until
   CharT* s ); C++20)
   constexpr basic_string& operator+=( (since
   const CharT* s ); C++20)
   basic_string& operator+=( (1) (since
   std::initializer_list<CharT> ilist C++11)
   ); (2) (until
                        C++20)
   constexpr basic_string& operator+=( (3) (since
   std::initializer_list<CharT> ilist C++20)
   ); (4)
   template < class StringViewLike > (since
   basic_string& operator+=( const C++17)
   StringViewLike& t ); (until
                        (5) C++20)
   template < class StringViewLike > (since
   constexpr basic_string& operator+=( C++20)
   const StringViewLike& t );
   Appends additional characters to the string.
   1) Appends string str
   2) Appends character ch
   3) Appends the null-terminated character string pointed to by s.
   4) Appends characters in the initializer list ilist.
   5) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT,
   Traits> sv = t;, then appends characters in the string view sv as if by append(sv).
   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
   str - string to append
   ch - character value to append
   s - pointer to a null-terminated character string to append
   ilist - std::initializer_list with the characters to append
   t - object (convertible to std::basic_string_view) with the characters to append

Return value
   *this

Complexity
   There are no standard complexity guarantees, typical implementations behave similar
   to std::vector::insert.

Exceptions
   If an exception is thrown for any reason, this function has no effect (strong
   exception guarantee).
   (since C++11)
   If the operation would result in size() > max_size(), throws std::length_error.

Notes
   Overload (2) can accept any types that are implicitly convertible to CharT. For
   std::string, where CharT is char, the set of acceptable types includes all
   arithmetic types. This may have unintended effects.
  Defect reports
   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.
      DR Applied to Behavior as published Correct behavior
   LWG 2946 C++17 string_view overload causes ambiguity in avoided by making it a
                       some cases template

Example
// Run this code
 #include <iostream>
 #include <iomanip>
 #include <string>
 int main()
 {
    std::string str;
    str.reserve(50); //reserves sufficient storage space to avoid memory reallocation
    std::cout << std::quoted(str) << '\n'; //empty string
    str += "This";
    std::cout << std::quoted(str) << '\n';
    str += std::string(" is ");
    std::cout << std::quoted(str) << '\n';
    str += 'a';
    std::cout << std::quoted(str) << '\n';
    str += {' ','s','t','r','i','n','g','.'};
    std::cout << std::quoted(str) << '\n';
    str += 76.85; // equivalent to str += static_cast<char>(76.85), might not be the intent
    std::cout << std::quoted(str) << '\n';
 }

Output:
 ""
 "This"
 "This is "
 "This is a"
 "This is a string."
 "This is a string.L"

See also
   append appends characters to the end
          (public member function)