W3cubDocs

/C++

std::basic_string::append

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

Appends additional characters to the string.

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.

4) Appends the first count characters of character string pointed to by s. s can contain null characters.

5) Appends the null-terminated character string pointed to by s. The length of the string is determined by the first null character.

6) Appends characters in the range [first, last). This overload has the same effect as overload (1) if InputIt is an integral type.

7) Appends characters from the initializer list ilist.

8) Appends all characters from the string view sv as if by append(sv.data(), sv.size())

9) 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. This overload only participates in overload resolution if std::is_convertible_v<const T&, std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const T&, 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
sv	-	`std::basic_string_view` 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.

Example

#include <string>
#include <iostream>
 
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