From cppreference.com
basic_string&append(size_typecount,CharTch); (1)(constexpr since C++20)basic_string&append(constCharT*s,size_typecount); (2)(constexpr since C++20)basic_string&append(constCharT*s); (3)(constexpr since C++20)template<classSV>basic_string&append(constSV&t); (4)(since C++17)
(constexpr since C++20)template<classSV>basic_string&append(constSV&t,size_typepos,size_typecount=npos); (5)(since C++17)
(constexpr since C++20)basic_string&append(constbasic_string&str); (6)(constexpr since C++20)basic_string&append(constbasic_string&str,size_typepos,size_typecount); (7)(until C++14)basic_string&append(constbasic_string&str,size_typepos,size_typecount=npos);(since C++14)
(constexpr since C++20)template<classInputIt>basic_string&append(InputItfirst,InputItlast); (8)(constexpr since C++20)basic_string&append(std::initializer_list<CharT>ilist); (9)(since C++11)
(constexpr since C++20)Appends additional characters to the string.
1) Appends count copies of character ch.
2) Appends characters in the range [s, s+count).
If [s, s+count) is not a
, the behavior is undefined.
3) Equivalent to returnappend(s,Traits::length(s));.
4,5) Appends characters in a string view sv constructed from t.
If only t is provided, all characters in sv are appended.
If pos is also provided: If count is
, all characters in sv starting from pos are appended.
Otherwise, the std::min(count,sv.size()-pos) characters in sv starting from pos are appended.
These overloads participate in overload resolution only if all following conditions are satisfied:
std::is_convertible_v<constSV&,std::basic_string_view<CharT,Traits>> is true.
std::is_convertible_v<constSV&,constCharT*> is false.
4) Equivalent to std::basic_string_view<CharT,Traits>sv=t;
returnappend(sv.data(),sv.size());.
5) Equivalent to std::basic_string_view<CharT,Traits>sv=t;
returnappend(sv.substr(pos,count));.
6,7) Appends characters in another string str.
If only str is provided, all characters in it are appended.
If pos is also provided: If count is
, all characters in str starting from pos are appended.
Otherwise, the std::min(count,str.size()-pos) characters in str starting from pos are appended.
6) Equivalent to returnappend(str.data(),str.size());.
7) Equivalent to returnappend(std::basic_string_view<CharT,Traits>
(str).substr(pos,count));.
(since C++20)8) Equivalent to returnappend(basic_string(first,last,get_allocator()));.
This overload has the same effect as overload (1) if InputIt is an integral type.
(until C++11)This overload participates in overload resolution only if InputIt satisfies the requirements of
.
(since C++11)9) Equivalent to returnappend(ilist.begin(),ilist.size());.
Parameters
count - number of characters to append ch - character value to append s - pointer to the character string to append t - object convertible to
with the characters to append pos - the index of the first character to append str - string to append first, last - range of characters to append ilist - initializer list with the characters to append Return value
*this
Complexity
There are no standard complexity guarantees, typical implementations behave similar to
.
Exceptions
If the operation would cause
to exceed
, throws
.
If an exception is thrown for any reason, this function has no effect (
strong exception safety guarantee
).
Example
Run this code
#include<cassert>#include<string>intmain(){std::stringstr="std::string";constchar*cptr="C-string";constcharcarr[]="range";std::stringresult;// 1) Append a char 3 times.// Note: This is the only overload accepting “CharT”s.result.append(3,'*');assert(result=="***");// 2) Append a fixed-length C-stringresult.append(cptr,5);assert(result=="***C-str");// 3) Append a null-terminated C-string// Note: Because “append” returns *this, we can chain calls together.result.append(1,' ').append(cptr);assert(result=="***C-str C-string");// 6) Append a whole stringresult.append(1,' ').append(str);assert(result=="***C-str C-string std::string");// 7) Append part of a stringresult.append(str,3,2);assert(result=="***C-str C-string std::string::");// 8) Append rangeresult.append(&carr[2],&carr[3]);assert(result=="***C-str C-string std::string::n");// 9) Append initializer listresult.append({'p','o','s'});assert(result=="***C-str C-string std::string::npos");}Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++98 there was no exception safety guarantee added strong exception safety guarantee
C++98 the behavior of overload (7) was
undefined if pos>str.size() is truealways throws an exception in this case
C++98 overload (8) used a default constructed
allocator to construct the temporary string obtains the allocator
from
C++17 overload (4) causes ambiguity in some cases avoided by making it a template See also
(C++23)
appends a range of characters to the end
(public member function)
appends characters to the end
(public member function)
concatenates two strings
(function)
concatenates a certain amount of characters of two strings
(function)
appends a copy of one wide string to another
(function)
appends a certain amount of wide characters from one wide string to another
(function)