##### 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) |
basic_string& insert( size_type index, const basic_string& str, size_type index_str, size_type count ); | (5) |
| (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( 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`
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] 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=66587"