std::basic_string::insert - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::basic_string::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)
basic_string& insert( size_type pos, basic_string_view<CharT, Traits> sv ); | (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 (effectively calls Traits::length(s).
3) Inserts the first `count` characters from the character string pointed to by `s` at the position `index`. `s` 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 pointed by `pos`
8) Inserts characters from the range `[first, last)` before the element pointed by `pos`. This overload does not participate in overload resolution if `InputIt` does not satisfy `InputIterator`. (since C++11)
9) Inserts elements from initializer list `ilist` before the element pointed by `pos`
10) Inserts the elements from the string view `sv` before the element pointed by `pos`, as if by insert(pos, sv.data(), sv.size())
11) Converts `t` to a string view `sv` as if by std::basic_string_view<CharT, Traits> sv = t;, then inserts, before the element 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.

### [edit] 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
sv | - | std::basic_string_view 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 `InputIterator`.

### [edit] 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`)

### [edit] Exceptions

1) std::out_of_range if index > size() and std::length_error if size() + count > max_size().
2) std::out_of_range if index > size() and std::length_error if size() + Traits::length(s) > max_size().
3) std::out_of_range if index > size() and std::length_error if size() + count > max_size().
4) std::out_of_range if index > size() and std::length_error if size() + str.size() > max_size().
5) Throws exceptions on the following conditions:
a) std::out_of_range if index > size().
b) std::out_of_range if index_str > str.size().
c) std::length_error if size() + ins_count > max_size() where `ins_count` is the number of characters that will be inserted.
6-9) (none)
10) std::out_of_range if index > size() and std::length_error if size() + sv.size() > max_size().
11) Throws exceptions on the following conditions:
a) std::out_of_range if index > size().
b) std::out_of_range if index_str > sv.size().
c) std::length_error if size() + ins_count > max_size() where `ins_count` is the number of characters that will be inserted.

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

### [edit] 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);
    }

### [edit] See also

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

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