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

> C++ Atlas: `cppatlas.com/w/cpp/string/basic_string/insert` | Source: https://en.cppreference.com/w/cpp/string/basic_string/insert | Domain: Strings | Standards: C++11, C++14, C++17, C++20, C++23

Inserts characters into the string.

## Official Specification Summary (cppreference)

```cpp
basic_string& insert( size_type index, size_type count, CharT ch ); // (1) (constexpr since C++20)

basic_string& insert( size_type index, const CharT* s ); // (2) (constexpr since C++20)

basic_string& insert( size_type index, const CharT* s, size_type count ); // (3) (constexpr since C++20)

basic_string& insert( size_type index, const basic_string& str ); // (4) (constexpr since C++20)

basic_string& insert( size_type index, const basic_string& str,
                      size_type s_index, size_type count ); // (5) (until C++14)

basic_string& insert( size_type index, const basic_string& str,
                      size_type s_index, size_type count = npos ); // (5) (since C++14) (constexpr since C++20)

iterator insert( iterator pos, CharT ch ); // (6) (until C++11)

iterator insert( const_iterator pos, CharT ch ); // (6) (since C++11) (constexpr since C++20)

void insert( iterator pos, size_type count, CharT ch ); // (7) (until C++11)

iterator insert( const_iterator pos, size_type count, CharT ch ); // (7) (since C++11) (constexpr since C++20)

template< class InputIt >
void insert( iterator pos, InputIt first, InputIt last ); // (8) (until C++11)

template< class InputIt >
iterator insert( const_iterator pos, InputIt first, InputIt last ); // (8) (since C++11) (constexpr since C++20)

iterator insert( const_iterator pos, std::initializer_list<CharT> ilist ); // (9) (since C++11) (constexpr since C++20)

template< class StringViewLike >
basic_string& insert( size_type index, const StringViewLike& t ); // (10) (since C++17) (constexpr since C++20)

template< class StringViewLike >
basic_string& insert( size_type index, const StringViewLike& t,
                      size_type t_index, size_type count = npos ); // (11) (since C++17) (constexpr since C++20)
```

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(s_index, 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`, as if by `insert(pos - begin(), basic_string(first, last, get_allocator()))`.

   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 `index`, as if by `insert(index, sv.data(), sv.size())`.

This overload participates in overload resolution only if `std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>>` is `true` and `std::is_convertible_v<const StringViewLike&, 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 `index`, the characters from the subview `[t_index,` `t_index + count)` of `sv`.

   - If the requested subview lasts past the end of `sv`, or if `count == npos`, the resulting subview is `[t_index,` `sv.size())`.
   - If `t_index > sv.size()`, or if `index > size()`, `std::out_of_range` is thrown.

This overload participates in overload resolution only if `std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>>` is `true` and `std::is_convertible_v<const StringViewLike&, const CharT*>` is `false`.

If `pos` is not a valid iterator on `*this`, the behavior is undefined.

### 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
- `s_index` - position of the first character in `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
- `t_index` - position of the first character in `t` to insert

**Type requirements**

- `InputIt` must meet the requirements of *LegacyInputIterator*.

### Return value

1-5) `*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`)

10,11) `*this`

### Exceptions

1-4,10) Throws `std::out_of_range` if `index > size()`.

5) Throws `std::out_of_range` if `index > size()` or if `s_index > str.size()`.

11) Throws `std::out_of_range` if `index > size()` or if `t_index > 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.

In all cases, if `std::allocator_traits<Allocator>::allocate` throws an exception, it is rethrown. (since C++20)

If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).

### Example

```cpp
#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);
}
```

### 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 7 | C++98 | overload (8) referred to a non-existing overload | refers to overload (4) correctly |
| LWG 847 | C++98 | there was no exception safety guarantee | added strong exception safety guarantee |
| LWG 2946 | C++17 | overload (10) caused ambiguity in some cases | avoided by making it a template |

### See also

- [`insert_range`](https://en.cppreference.com/w/cpp/string/basic_string/insert_range) (C++23): inserts a range of characters (public member function)
- [`append`](https://en.cppreference.com/w/cpp/string/basic_string/append): appends characters to the end (public member function)
- [`push_back`](https://en.cppreference.com/w/cpp/string/basic_string/push_back): appends a character to the end (public member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/string/basic_string/insert (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.