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

From cppreference.com
< cpp‎ | string‎ | basic string

basic_string& insert( size_type index, size_type count, CharT ch ); | (1) |
basic_string& insert( size_type index, const CharT* s ); | (2) |
basic_string& insert( size_type index, const CharT* s, size_type count ); | (3) |
basic_string& insert( size_type index, const basic_string& str ); | (4) |
| (5) |
basic_string& insert( size_type index, const basic_string& str, size_type index_str, size_type count ); |  | (until C++14)
basic_string& insert( size_type index, const basic_string& str, size_type index_str, size_type count = npos); |  | (since C++14)
| (6) |
iterator insert( iterator pos, CharT ch ); |  | (until C++11)
iterator insert( const_iterator pos, CharT ch ); |  | (since C++11)
| (7) |
void insert( iterator pos, size_type count, CharT ch ); |  | (until C++11)
iterator insert( const_iterator pos, size_type count, CharT ch ); |  | (since C++11)
| (8) |
template< class InputIt > void insert( iterator pos, InputIt first, InputIt last ); |  | (until C++11)
template< class InputIt > iterator insert( const_iterator pos, InputIt first, InputIt last ); |  | (since C++11)
iterator insert( const_iterator pos, std::initializer_list<CharT> ilist ); | (9) | (since C++11)
template < class T > basic_string& insert( size_type pos, const T& t ); | (10) | (since C++17)
template < class T > basic_string& insert( size_type index, const T& t, size_type index_str, size_type count = npos); | (11) | (since C++17)

Inserts characters into the string.

1) Inserts `count` copies of character `ch` at the position `index`
2) Inserts null-terminated character string pointed to by `s` at the position `index`. The length of the string is determined by the first null character using Traits::length(s).
3) Inserts the characters in the range `[s, s+count)` at the position `index`. The range can contain null characters.
4) Inserts string `str` at the position `index`
5) Inserts a string, obtained by str.substr(index_str, count) at the position `index`
6) Inserts character `ch` before the character pointed by `pos`
7) Inserts `count` copies of character `ch` before the element (if any) pointed by `pos`
8) Inserts characters from the range `[first, last)` before the element (if any) pointed by `pos`. This overload does not participate in overload resolution if `InputIt` does not satisfy LegacyInputIterator. (since C++11)
9) Inserts elements from initializer list `ilist` before the element (if any) pointed by `pos`
10) Implicitly converts `t` to a string view `sv` as if by std::basic_string_view<CharT, Traits> sv = t;, then inserts the elements from `sv` before the element (if any) pointed by `pos`, as if by insert(pos, sv.data(), sv.size()). 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.
11) Implicitly converts `t` to a string view `sv` as if by std::basic_string_view<CharT, Traits> sv = t;, then inserts, before the element (if any) pointed by `pos`, the characters from the subview `[index_str, index_str+count)` of `sv`. If the requested subview lasts past the end of `sv`, or if count == npos, the resulting subview is `[index_str, sv.size())`. If index_str > sv.size(), or if index > 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

index | - | position at which the content will be inserted
pos | - | iterator before which the characters will be inserted
ch | - | character to insert
count | - | number of characters to insert
s | - | pointer to the character string to insert
str | - | string to insert
first, last | - | range defining characters to insert
index_str | - | position of the first character in the string `str` to insert
ilist | - | std::initializer_list to insert the characters from
t | - | object (convertible to std::basic_string_view) to insert the characters from
Type requirements
- `InputIt` must meet the requirements of LegacyInputIterator.

### Return value

1-5,10-11) *this
6-9) An iterator which refers to the copy of the first inserted character or `pos` if no characters were inserted (`count==0` or `first==last` or `ilist.size()==0`)

### Exceptions

1-4, 10) std::out_of_range if index > size()
5) Throws std::out_of_range if index > size() or if index_str > str.size().
11) Throws std::out_of_range if index > size() or if index_str > sv.size().

In all cases, throws std::length_error if size() + ins_count > max_size() where `ins_count` is the number of characters that will be inserted and may throw any exceptions thrown by `Allocator::allocate`.

In any case, if an exception is thrown for any reason, this function has no effect (strong exception guarantee). | (since C++11)

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR | Applied to | Behavior as published | Correct behavior
--- | --- | --- | ---
LWG 2946 | C++17 | `string_view` overload causes ambiguity in some cases | avoided by making it a template

### Example

Run this code

    #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 index_str, 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);
    }

### See also

append | appends characters to the end (public member function)
push_back | appends a character to the end (public member function)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/insert&oldid=107716"