public member function
<string>

std::basic_string::operator+=

string (1)
basic_string& operator+= (const basic_string& str);
c-string (2)
basic_string& operator+= (const charT* s);
character (3)
basic_string& operator+= (charT c);
string (1)
basic_string& operator+= (const basic_string& str);
c-string (2)
basic_string& operator+= (const charT* s);
character (3)
basic_string& operator+= (charT c);
initializer list (4)
basic_string& operator+= (initializer_list<charT> il);
Append to string
Extends the basic_string by appending additional characters at the end of its current value:

(See member function append for additional appending options).

Parameters

str
A basic_string object of the same type (with the same class template arguments charT, traits and Alloc), whose value is copied at the end.
s
Pointer to a null-terminated sequence of characters.
The sequence is copied at the end of the string.
The length is determined by calling traits_type::length(s).
c
A character, which is appended to the current value of the string.
il
An initializer_list object.
These objects are automatically constructed from initializer list declarators.
The characters are appended to the string, in the same order.

charT is basic_string's character type (i.e., its first template parameter).

Return Value

*this

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// string::operator+=
#include <iostream>
#include <string>

int main ()
{
  std::string name ("John");
  std::string family ("Smith");
  name += " K. ";         // c-string
  name += family;         // string
  name += '\n';           // character

  std::cout << name;
  return 0;
}

Output:
John K. Smith


Complexity

Unspecified, but generally up to linear in the new string length.

Iterator validity

Any iterators, pointers and references related to this object may be invalidated.

Data races

The object is modified.

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the basic_string.

If the resulting string length would exceed the max_size, a length_error exception is thrown.
If the type uses the default allocator, a bad_alloc exception is thrown if the function needs to allocate storage and fails.

See also