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 в string view 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 в string view 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.

Если 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 выбрасывает исключение, оно повторно выбрасывается.

(с 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	добавляет символ в конец (открытая функция-член)

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