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

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

Вставляет символы в строку.

1) Вставляет count копий символа ch в позицию index.

2) Вставляет оканчивающуюся нулём строку, на которую указывает s, в позицию index. Длина строки определяется по первому нулевому символу с помощью Traits::length(s).

3) Вставляет символы из диапазона [s, s + count) в позицию index. Диапазон может содержать нулевые символы.

4) Вставляет строку str в позицию index.

5) Вставляет строку, полученную с помощью str.substr(s_index, count) в позицию index.

6) Вставляет символ ch перед символом, на который указывает pos.

7) Вставляет count копий символа ch перед элементом (если таковой есть), на который указывает pos.

8) Вставляет символы из диапазона [first, last) перед элементом (если таковой есть), на который указывает pos, как если бы с помощью insert(pos - begin(), basic_string(first, last, get_allocator())).

Эта перегрузка не участвует в разрешении перегрузки, если InputIt не удовлетворяет LegacyInputIterator.

(начиная с C++11)

9) Вставляет элементы из списка инициализации ilist перед элементом (если таковой есть), на который указывает pos.

10) Неявно преобразует t в строковое представление sv как если бы с помощью std::basic_string_view<CharT, Traits> sv = t;, затем вставляет элементы из sv перед элементом (если таковой есть), на который указывает index, как если бы с помощью insert(index, sv.data(), sv.size()).

Эта перегрузка участвует в разрешении перегрузки только если std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> является true и std::is_convertible_v<const StringViewLike&, const CharT*> является false.

11) Неявно преобразует t в строковое представление sv как если бы с помощью std::basic_string_view<CharT, Traits> sv = t;, затем вставляет перед элементом (если таковой есть), на который указывает index, символы из подпредставления [t_index, t_index + count) из sv.

Если запрошенное подпредставление выходит за конец sv, или если count == npos, результирующее подпредставление является [t_index, sv.size()).
Если t_index > sv.size(), или если index > size(), генерируется std::out_of_range.

Эта перегрузка участвует в разрешении перегрузки только если std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> является true и std::is_convertible_v<const StringViewLike&, const CharT*> является false.

Если pos не является корректным итератором для *this, поведение не определено.

Параметры

index	-	позиция, на которую будет вставлено содержимое
pos	-	итератор, перед которым будут вставлены символы
ch	-	символ для вставки
count	-	количество символов для вставки
s	-	указатель на строку символов для вставки
str	-	строка для вставки
first, last	-	диапазон, определяющий символы для вставки
s_index	-	позиция первого символа в str для вставки
ilist	-	std::initializer_list для вставки символов из
t	-	объект (преобразуемый в std::basic_string_view ) для вставки символов из
t_index	-	позиция первого символа в t для вставки
Требования к типам
- `InputIt` должен удовлетворять требованиям LegacyInputIterator .

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

1-5) * this

6-9) Итератор, указывающий на копию первой вставленной буквы или pos если символы не были вставлены ( count == 0 или first == last или ilist. size ( ) == 0 )

10,11) * this

Исключения

1-4,10) Выбрасывает std::out_of_range если index > size ( ) .

5) Выбрасывает std::out_of_range если index > size ( ) или если s_index > str. size ( ) .

11) Выбрасывает std::out_of_range если index > size ( ) или если t_index > sv. size ( ) .

Во всех случаях генерирует исключение std::length_error если size ( ) + ins_count > max_size ( ) где ins_count - количество символов, которые будут вставлены.

Во всех случаях, если std:: allocator_traits < Allocator > :: allocate выбрасывает исключение, оно перевыбрасывается.

(since C++20)

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

Пример

Запустить этот код

#include <cassert>
#include <iterator>
#include <string>
using namespace std::string_literals;
int main()
{
    std::string s = "xmplr";
    // insert(size_type index, size_type count, char ch)
    s.insert(0, 1, 'E');
    assert("Exmplr" == s);
    // insert(size_type index, const char* s)
    s.insert(2, "e");
    assert("Exemplr" == s);
    // insert(size_type index, string const& str)
    s.insert(6, "a"s);
    assert("Exemplar" == s);
    // insert(size_type index, string const& str,
    //        size_type s_index, size_type count)
    s.insert(8, " is an example string."s, 0, 14);
    assert("Exemplar is an example" == s);
    // insert(const_iterator pos, char ch)
    s.insert(s.cbegin() + s.find_first_of('n') + 1, ':');
    assert("Exemplar is an: example" == s);
    // insert(const_iterator pos, size_type count, char ch)
    s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '=');
    assert("Exemplar is an:== example" == s);
    // insert(const_iterator pos, InputIt first, InputIt last)
    {
        std::string seq = " string";
        s.insert(s.begin() + s.find_last_of('e') + 1,
            std::begin(seq), std::end(seq));
        assert("Exemplar is an:== example string" == s);
    }
    // insert(const_iterator pos, std::initializer_list<char>)
    s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'});
    assert("Exemplar is an:== example string." == s);
}

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

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

DR	Применяется к	Поведение в опубликованной версии	Корректное поведение
LWG 7	C++98	перегрузка (8) ссылалась на несуществующую перегрузку	корректно ссылается на перегрузку (4)
LWG 847	C++98	не было гарантии безопасности исключений	добавлена строгая гарантия безопасности исключений
LWG 2946	C++17	перегрузка (10) вызывала неоднозначность в некоторых случаях	устранено путём преобразования в шаблон

Смотрите также

insert_range (C++23)	вставляет диапазон символов (публичная функция-член)
append	добавляет символы в конец (публичная функция-член)
push_back	добавляет символ в конец (публичная функция-член)

Поддержка компиляторов
Автономное и размещённое
Язык
Стандартная библиотека
Заголовки стандартной библиотеки
Именованные требования
Макросы проверки возможностей (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