string::replace

string& replace ( size_t pos1, size_t n1, const string& str );
string& replace ( iterator i1, iterator i2, const string& str );

The section is replaced by a copy of the entire string object str.

string& replace ( size_t pos1, size_t n1, const string& str, size_t pos2, size_t n2 );

The section is replaced by a copy of a substring of str. The substring is the portion of str that begins at the character position pos2 and takes up to n2 characters (it takes less than n2 if the end of the string is reached before).

string& replace ( size_t pos1, size_t n1, const char * s, size_t n2 );
string& replace ( iterator i1, iterator i2, const char * s, size_t n2 );

The section is replaced by a copy of the string formed by the first n2 characters in the array of characters pointed by s.

string& replace ( size_t pos1, size_t n1, const char * s );
string& replace ( iterator i1, iterator i2, const char * s );

The section is replaced by 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& replace ( size_t pos1, size_t n1, size_t n2, char c );
string& replace ( iterator i1, iterator i2, size_t n2, char c );

The section is replaced by a repetition of character c, n2 times.

template<class InputIterator> string& replace (iterator i1, iterator i2, InputIterator j1, InputIterator j2);

The section is replaced by the content made up of the characters that go from the element referred by iterator j1 to the element right before the one referred by iterator j2.

Parameters

str

Another object of class string whose content is entirely or partially used as the replacement.

pos1

Position within the string of the first character of the section to be replaced. 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.

n1

Length of the section to be replaced within the string. If this is longer than the actual length of the string, the function replaces the entire segction between pos1 and the end of the string.

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.

n2

Length in characters of the replacement string. If the source of characters is not long enough, only the amount of characters until the end of that source is used as replacement.

s

Array with a sequence of characters. In the third group of member versions, this does not need to be a null-terminated sequence, since its length is determined by parameter n2, but in the fourth group it does, because the end of the sequence of characters is precisely determined by the first occurrence of a null character.

c

Character value to be used to be repeated n2 times as the replacement content.

i1,i2

Iterators referring to the beginning and the end of the section in the string to be replaced.

j1,j2

Iterators referring to the beginning and the end of a sequence of characters whose content is used as replacement.

Return Value

Example

// replacing in a string
#include <iostream>
#include <string>
using namespace std;

int main ()
{
  string base="this is a test string.";
  string str2="n example";
  string str3="sample phrase";
  string str4="useful.";

  // function versions used in the same order as described above:

  // Using positions:                 0123456789*123456789*12345
  string str=base;                // "this is a test string."
  str.replace(9,5,str2);          // "this is an example string."
  str.replace(19,6,str3,7,6);     // "this is an example phrase."
  str.replace(8,10,"just all",6); // "this is just a phrase."
  str.replace(8,6,"a short");     // "this is a short phrase."
  str.replace(22,1,3,'!');        // "this is a short phrase!!!"

  // Using iterators:                      0123456789*123456789*
  string::iterator it = str.begin();   //  ^
  str.replace(it,str.end()-3,str3);    // "sample phrase!!!"
  str.replace(it,it+6,"replace it",7); // "replace phrase!!!"
  it+=8;                               //          ^
  str.replace(it,it+6,"is cool");      // "replace is cool!!!"
  str.replace(it+4,str.end()-4,4,'o'); // "replace is cooool!!!"
  it+=3;                               //             ^
  str.replace(it,str.end(),str4.begin(),str4.end());
                                       // "replace is useful."
  cout << str << endl;
  return 0;
}

replace is useful.

Basic template member declarations

typedef typename Allocator::size_type size_type;
basic_string& replace ( size_type pos1, size_type n1,
                          const basic_string& str );
basic_string& replace ( iterator i1, iterator i2,
                          const basic_string& str );
basic_string& replace ( size_type pos1, size_type n1,
                          const basic_string& str,
                          size_type pos2, size_type n2 );
basic_string& replace ( size_type pos1, size_type n1,
                          const charT* s, size_type n2 );
basic_string& replace ( iterator i1, iterator i2,
                          const charT* s, size_type n2 );
basic_string& replace ( size_type pos1, size_type n1,
                          const charT* s );
basic_string& replace ( iterator i1, iterator i2,
                          const charT* s );
basic_string& replace ( size_type pos1, size_type n1,
                          size_type n2, charT c );
basic_string& replace ( iterator i1, iterator i2,
                          size_type n2, charT c );
template <class InputIterator>
  basic_string& replace ( iterator i1, iterator i2,
                   InputIterator first,InputIterator last );

See also