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)

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`

### [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 | - | initializer list to insert the characters from
Type requirements
- `InputIt` must meet the requirements of `InputIterator`.

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

### [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) Throws exceptions on the following conditions:
a) std::out_of_range if index > size().
b) std::length_error if size() + str.size() > max_size() where `ins_count` is the number of characters that will be inserted.
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)

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

### [edit] Example

Until C++

Run this code

    #include <cassert>
    #include <string>

    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, char* s)
        s.insert(2, "e");
        assert("Exemplr" == s);

        // insert(size_type index, string const& str)
        s.insert(6, std::string("a"));
        assert("Exemplar" == s);

        // insert(size_type index, string const& str,
        //     size_type index_str, size_type count)
        s.insert(8, std::string(" is an example string."), 0, 14);
        assert("Exemplar is an example" == s);

        // insert(iterator pos, char ch)
        s.insert(s.begin() + s.find_first_of('n') + 1, ':');
        assert("Exemplar is an: example" == s);

        // insert(iterator pos, size_type count, char ch)
        s.insert(s.begin() + s.find_first_of(':') + 1, 2, '=');
        assert("Exemplar is an:== example" == s);

        // insert(iterator pos, InputIt first, InputIt last)
        {
            std::string const seq(" suitable");
            s.insert(s.begin() + s.find_last_of('=') + 1,
                seq.begin(), seq.end());
            assert("Exemplar is an:== suitable example" == s);
        }
    }

C++11

Run this code

    #include <cassert>
    #include <iterator>
    #include <string>

    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, char* s)
        s.insert(2, "e");
        assert("Exemplr" == s);

        // insert(size_type index, string const& str)
        s.insert(6, std::string("a"));
        assert("Exemplar" == s);

        // insert(size_type index, string const& str,
        //     size_type index_str, size_type count)
        s.insert(8, std::string(" is an example string."), 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 const 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>)
        {
            std::initializer_list<char> const period = { '.' };
            s.insert(s.cbegin() + s.find_first_of('g') + 1, period);
            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=70342"