std::basic_string<CharT,Traits,Allocator>::append

basic_string& append( size_type count, CharT ch );	(1)	(constexpr начиная с C++20)
basic_string& append( const CharT* s, size_type count );	(2)	(constexpr начиная с C++20)
basic_string& append( const CharT* s );	(3)	(constexpr начиная с C++20)
template< class SV > basic_string& append( const SV& t );	(4)	(начиная с C++17) (constexpr начиная с C++20)
template< class SV > basic_string& append( const SV& t, size_type pos, size_type count = npos );	(5)	(начиная с C++17) (constexpr начиная с C++20)
basic_string& append( const basic_string& str );	(6)	(constexpr начиная с C++20)
basic_string& append( const basic_string& str, size_type pos, size_type count );	(7)	(до C++14)
basic_string& append( const basic_string& str, size_type pos, size_type count = npos );	(7)		(начиная с C++14) (constexpr начиная с C++20)
template< class InputIt > basic_string& append( InputIt first, InputIt last );	(8)	(constexpr начиная с C++20)
basic_string& append( std::initializer_list<CharT> ilist );	(9)	(начиная с C++11) (constexpr начиная с C++20)

Добавляет символы в конец строки.

1) Добавляет count копий символа ch.

2) Добавляет символы из диапазона [s, s + count).

Если [s, s + count) не является допустимым диапазоном, поведение не определено.

3) Эквивалентно return append(s, Traits::length(s));.

4,5) Добавляет символы из string view sv, созданного из t.

Если указан только t, добавляются все символы из sv.
Если также указан pos:
- Если count равен npos, добавляются все символы из sv, начиная с pos.
- В противном случае добавляются std::min(count, sv.size() - pos) символов из sv, начиная с pos.

Эти перегрузки участвуют в разрешении перегрузки, только если выполнены все следующие условия:

std::is_convertible_v<const SV&, std::basic_string_view<CharT, Traits>> — это true.
std::is_convertible_v<const SV&, const CharT*> — это false.

4) Эквивалентно std::basic_string_view<CharT, Traits> sv = t;return append(sv.data(), sv.size());.

5) Эквивалентно std::basic_string_view<CharT, Traits> sv = t;return append(sv.substr(pos, count));.

6,7) Добавляет символы из другой строки str.

Если указан только str, добавляются все символы из неё.
Если также указан pos:
- Если count равен npos, добавляются все символы из str, начиная с pos.
- В противном случае добавляются std::min(count, str.size() - pos) символов из str, начиная с pos.

6) Эквивалентно return append(str.data(), str.size());.

7) Эквивалентно return append(std::basic_string_view<CharT, Traits>(str).substr(pos, count));. (начиная с C++20)

8) Эквивалентно return append(basic_string(first, last, get_allocator()));.

Эта перегрузка имеет тот же эффект, что и перегрузка (1), если `InputIt` является целочисленным типом.	(до C++11)
Эта перегрузка участвует в разрешении перегрузки, только если `InputIt` соответствует требованиям LegacyInputIterator.	(начиная с C++11)

9) Эквивалентно return append(ilist.begin(), ilist.size());.

Параметры

count	-	количество добавляемых символов
ch	-	добавляемый символ
s	-	указатель на добавляемую строку символов
t	-	объект, преобразуемый в `std::basic_string_view`, с добавляемыми символами
pos	-	индекс первого добавляемого символа
str	-	добавляемая строка
first, last	-	диапазон добавляемых символов
ilist	-	список инициализации с добавляемыми символами

Возвращаемое значение

*this

Сложность

Стандарт не устанавливает гарантий сложности; типичные реализации ведут себя аналогично std::vector::insert().

Исключения

Если в результате операции size() превысит max_size(), выбрасывается std::length_error.

5) Если pos > sv.size() равен true, выбрасывается std::out_of_range.

7) Если pos > str.size() равен true, выбрасывается std::out_of_range.

Если по какой-либо причине выбрасывается исключение, эта функция не оказывает никакого эффекта (строгая гарантия безопасности исключений).

Пример

#include <cassert>
#include <string>

int main()
{
    std::string str = "std::string";
    const char* cptr = "C-string";
    const char carr[] = "range";

    std::string result;

    // 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-string
    result.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 string
    result.append(1, ' ').append(str);
    assert(result == "***C-str C-string std::string");

    // 7) Append part of a string
    result.append(str, 3, 2);
    assert(result == "***C-str C-string std::string::");

    // 8) Append range
    result.append(&carr[2], &carr[3]);
    assert(result == "***C-str C-string std::string::n");

    // 9) Append initializer list
    result.append({'p', 'o', 's'});
    assert(result == "***C-str C-string std::string::npos");
}

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были применены задним числом к ранее опубликованным стандартам C++.

DR	Применяется к	Опубликованное поведение	Корректное поведение
LWG 847	C++98	гарантия безопасности исключений отсутствовала	добавлена строгая гарантия безопасности исключений
LWG 2250	C++98	поведение перегрузки (7) было не определено, если `pos > str.size()` равен `true`	в этом случае всегда выбрасывается исключение
LWG 2788	C++98	перегрузка (8) использовала аллокатор, созданный по умолчанию, для создания временной строки	аллокатор берётся из `get_allocator()`
LWG 2946	C++17	перегрузка (4) в некоторых случаях приводит к неоднозначности	проблема устранена превращением её в шаблон

См. также

append_range (C++23)	добавляет диапазон символов в конец (открытая функция-член)
operator+=	добавляет символы в конец (открытая функция-член)
strcat	объединяет две строки (функция)
strncat	объединяет заданное количество символов двух строк (функция)
wcscat	добавляет копию одной широкострочной строки к другой (функция)
wcsncat	добавляет заданное количество широких символов из одной широкострочной строки к другой (функция)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/string/basic_string/append