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) Добавляет символы из строкового представления 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) Добавить символ 3 раза.
    // Примечание: Это единственная перегрузка, принимающая символы “CharT”.
    result.append(3, '*');
    assert(result == "***");
    // 2) Добавить C-строку фиксированной длины
    result.append(cptr, 5);
    assert(result == "***C-str");
    // 3) Добавить нуль-терминированную C-строку
    // Примечание: Поскольку “append” возвращает *this, мы можем объединять вызовы в цепочку.
    result.append(1, ' ').append(cptr);
    assert(result == "***C-str C-string");
    // 6) Добавить всю строку
    result.append(1, ' ').append(str);
    assert(result == "***C-str C-string std::string");
    // 7) Добавить часть строки
    result.append(str, 3, 2);
    assert(result == "***C-str C-string std::string::");
    // 8) Добавить диапазон
    result.append(&carr[2], &carr[3]);
    assert(result == "***C-str C-string std::string::n");
    // 9) Добавить список инициализации
    result.append({'p', 'o', 's'});
    assert(result == "***C-str C-string std::string::npos");
}

Отчёты о дефектах

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

DR	Applied to	Behavior as published	Correct behavior
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	добавляет определённое количество широких символов из одной широкой строки в другую (функция)

Поддержка компиляторов
Автономное и hosted окружение
Язык
Стандартная библиотека
Заголовки стандартной библиотеки
Именованные требования
Макросы тестирования возможностей (C++20)
Библиотека поддержки языка
Библиотека концепций (C++20)
Библиотека диагностики
Библиотека управления памятью
Библиотека метапрограммирования (C++11)
Библиотека общих утилит
Библиотека контейнеров
Библиотека итераторов
Библиотека диапазонов (C++20)
Библиотека алгоритмов
Библиотека строк
Библиотека обработки текста
Библиотека численных операций
Библиотека даты и времени
Библиотека ввода/вывода
Библиотека файловой системы (C++17)
Библиотека поддержки параллелизма (C++11)
Библиотека управления выполнением (C++26)
Технические спецификации
Указатель символов
Внешние библиотеки

Классы
basic_string
basic_string_view (C++17)
char_traits

ru.cppreference.net

Namespaces

Variants