C++

Reference

<string>

string

public member function
<string>

std::string::insert

string (1)
 string& insert (size_t pos, const string& str);
substring (2)
 string& insert (size_t pos, const string& str, size_t subpos, size_t sublen);
c-string (3)
 string& insert (size_t pos, const char* s);
buffer (4)
 string& insert (size_t pos, const char* s, size_t n);
fill (5)
 string& insert (size_t pos, size_t n, char c);    void insert (iterator p, size_t n, char c);
single character (6)
iterator insert (iterator p, char c);
range (7)
template <class InputIterator>   void insert (iterator p, InputIterator first, InputIterator last);
string (1)
 string& insert (size_t pos, const string& str);
substring (2)
 string& insert (size_t pos, const string& str, size_t subpos, size_t sublen);
c-string (3)
 string& insert (size_t pos, const char* s);
buffer (4)
 string& insert (size_t pos, const char* s, size_t n);
fill (5)
 string& insert (size_t pos,   size_t n, char c);iterator insert (const_iterator p, size_t n, char c);
single character (6)
iterator insert (const_iterator p, char c);
range (7)
template <class InputIterator>iterator insert (iterator p, InputIterator first, InputIterator last);
initializer list (8)
 string& insert (const_iterator p, initializer_list<char> il);
string (1)
 string& insert (size_t pos, const string& str);
substring (2)
 string& insert (size_t pos, const string& str, size_t subpos, size_t sublen = npos);
c-string (3)
 string& insert (size_t pos, const char* s);
buffer (4)
 string& insert (size_t pos, const char* s, size_t n);
fill (5)
 string& insert (size_t pos,   size_t n, char c);iterator insert (const_iterator p, size_t n, char c);
single character (6)
iterator insert (const_iterator p, char c);
range (7)
template <class InputIterator>iterator insert (iterator p, InputIterator first, InputIterator last);
initializer list (8)
 string& insert (const_iterator p, initializer_list<char> il);
Insert into string
Inserts additional characters into the string right before the character indicated by pos (or p):

(1) string
Inserts a copy of str.
(2) substring
Inserts a copy of a substring of str. The substring is the portion of str that begins at the character position subpos and spans sublen characters (or until the end of str, if either str is too short or if sublen is npos).
(3) c-string
Inserts a copy of the string formed by the null-terminated character sequence (C-string) pointed by s.
(4) buffer
Inserts a copy of the first n characters in the array of characters pointed by s.
(5) fill
Inserts n consecutive copies of character c.
(6) single character
Inserts character c.
(7) range
Inserts a copy of the sequence of characters in the range [first,last), in the same order.
(8) initializer list
Inserts a copy of each of the characters in il, in the same order.

size_t is an unsigned integral type (the same as member type string::size_type).

Parameters

pos
Insertion point: The new contents are inserted before the character at position pos.
If this is greater than the object's length, it throws out_of_range.
Note: The first character is denoted by a value of 0 (not 1).
str
Another string object.
subpos
Position of the first character in str that is inserted into the object as a substring.
If this is greater than str's length, it throws out_of_range.
Note: The first character in str is denoted by a value of 0 (not 1).
sublen
Length of the substring to be copied (if the string is shorter, as many characters as possible are copied).
A value of npos indicates all characters until the end of str.
s
Pointer to an array of characters (such as a c-string).
n
Number of characters to insert.
c
Character value.
p
Iterator pointing to the insertion point: The new contents are inserted before the character pointed by p.
iterator is a member type, defined as a random access iterator type that points to characters of the string.
first, last
Input iterators to the initial and final positions in a range. The range used is [first,last), which includes all the characters between first and last, including the character pointed by first but not the character pointed by last.
The function template argument InputIterator shall be an input iterator type that points to elements of a type convertible to char.
il
An initializer_list object.
These objects are automatically constructed from initializer list declarators.

Return value

The signatures returning a reference to string, return *this.
Those returning an iterator, return an iterator pointing to the first character inserted.

Member type iterator is a random access iterator type that points to characters of the string.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
// inserting into a string
#include <iostream>
#include <string>

int main ()
{
  std::string str="to be question";
  std::string str2="the ";
  std::string str3="or not to be";
  std::string::iterator it;

  // used in the same order as described above:
  str.insert(6,str2);                 // to be (the )question
  str.insert(6,str3,3,4);             // to be (not )the question
  str.insert(10,"that is cool",8);    // to be not (that is )the question
  str.insert(10,"to be ");            // to be not (to be )that is the question
  str.insert(15,1,':');               // to be not to be(:) that is the question
  it = str.insert(str.begin()+5,','); // to be(,) not to be: that is the question
  str.insert (str.end(),3,'.');       // to be, not to be: that is the question(...)
  str.insert (it+2,str3.begin(),str3.begin()+3); // (or )

  std::cout << str << '\n';
  return 0;
}
Output:
to be, or not to be: that is the question...


Complexity

Unspecified, but generally up to linear in the new string length.

Iterator validity

Any iterators, pointers and references related to this object may be invalidated.

Data races

The object is modified.

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the string.

If s does not point to an array long enough, or if either p or the range specified by [first,last) is not valid, it causes undefined behavior.

If pos is greater than the string length, or if subpos is greater than str's length, an out_of_range exception is thrown.
If the resulting string length would exceed the max_size, a length_error exception is thrown.
A bad_alloc exception is thrown if the function needs to allocate storage and fails.

See also

string::append
Append to string (public member function)
string::replace
Replace portion of string (public member function)
string::substr
Generate substring (public member function)
string::operator=
String assignment (public member function)
string::operator+=
Append to string (public member function)