string::insert

string& insert ( size_t pos1, const string& str );

Inserts a copy of the entire string object str at character position pos1.

string& insert ( size_t pos1, const string& str, size_t pos2, size_t n );

Inserts a copy of a substring of str at character position pos1. The substring is the portion of str that begins at the character position pos2 and takes up to n characters (it takes less than n if the end of str is reached before).

string& insert ( size_t pos1, const char * s, size_t n );

Inserts at the character position pos1, a copy of the string formed by the first n characters in the array of characters pointed by s.

string& insert ( size_t pos1, const char * s );

Inserts at character position pos1, a copy of the string formed by the null-terminated character sequence (C string) pointed by s. The length of this caracter sequence is determined by the first ocurrence of a null character (as determined by traits.length(s)).

string& insert ( size_t pos1, size_t n, char c );

Inserts a string formed by a repetition of character c, n times, at the character position pos1.

iterator insert ( iterator p, char c );

Inserts a copy of character c at the position referred by iterator p and returns an iterator referring to this position where it has been inserted.

void insert ( iterator p, size_t n, char c );

Inserts a string formed by the repetition of character c, n times, at the position referred by iterator p.

template<class InputIterator> void insert (iterator p, InputIterator first, InputIterator last);

Inserts at the internal position referred by p the content made up of the characters that go from the element referred by iterator first to the element right before the one referred by iterator last.

Parameters

str

Another object of class string whose content is entirely or partially inserted into the content.

pos1

Position within the string where the additional content is to be inserted. Notice that the first position has a value of 0, not 1.
If the position passed is past the end of the string, an out_of_range exception is thrown.

pos2

Starting position of the substring of str that has the content to be inserted. Notice that the first position has also a value of 0.
If the position passed is past the end of str, an out_of_range exception is thrown.

n

Number of characters to insert.

s

Array with a sequence of characters.
In the third member function version, the length is determined by parameter n, even including null characters in the content.
By contrast, in the fourth member version, s is a null-terminated character, and therefore its length is determined only by the first occurrence of a null character.

c

Character value to be used to be repeated n times as the inserted content.

p

Iterator referring to an element part of the string, where the additional content is to be inserted.
This is an iterator of the string::iterator member type, which is a compiler specific iterator type suitable to iterate through the elements of this object.

start

Iterator referring to the beginning of a sequence of characters whose content is to be inserted in the string.

last

Iterator referring to the past-the-end element of the sequence of characters to be inserted.

Return Value

Example

// inserting into a string
#include <iostream>
#include <string>
using namespace std;

int main ()
{
  string str="to be question";
  string str2="the ";
  string str3="or not to be";
  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 )

  cout << str << endl;
  return 0;
}

to be, or not to be: that is the question...

Basic template member declarations

typedef typename Allocator::size_type size_type;
basic_string& insert ( size_type pos1, const basic_string& str );
basic_string& insert ( size_type pos1, const basic_string& str,
                       size_type pos2, size_type n );
basic_string& insert ( size_type pos1, const charT* s, size_type n );
basic_string& insert ( size_type pos1, const charT* s );
basic_string& insert ( size_type pos1, size_type n, charT c );
     iterator insert ( iterator p, charT c );
         void insert ( iterator p, size_type n, charT c );
template <class InputIterator>
         void insert ( iterator p, 
                       InputIterator first, InputIterator last );

See also