public member function
<string>

std::string::erase

sequence (1)
 string& erase (size_t pos = 0, size_t len = npos);
character (2)
iterator erase (iterator p);
range (3)
     iterator erase (iterator first, iterator last);
sequence (1)
 string& erase (size_t pos = 0, size_t len = npos);
character (2)
iterator erase (const_iterator p);
range (3)
iterator erase (const_iterator first, const_iterator last);
Erase characters from string
Erases part of the string, reducing its length:

(1) sequence
Erases the portion of the string value that begins at the character position pos and spans len characters (or until the end of the string, if either the content is too short or if len is string::npos.
Notice that the default argument erases all characters in the string (like member function clear).
(2) character
Erases the character pointed by p.
(3) range
Erases the sequence of characters in the range [first,last).

Parameters

pos
Position of the first character to be erased.
If this is greater than the string length, it throws out_of_range.
Note: The first character in str is denoted by a value of 0 (not 1).
len
Number of characters to erase (if the string is shorter, as many characters as possible are erased).
A value of string::npos indicates all characters until the end of the string.
p
Iterator to the character to be removed.
first, last
Iterators specifying a range within the string] to be removed: [first,last). i.e., the range includes all the characters between first and last, including the character pointed by first but not the one pointed by last.


size_t is an unsigned integral type (the same as member type string::size_type).
Member types iterator and const_iterator are random access iterator types that point to characters of the string.

Return value

The sequence version (1) returns *this.
The others return an iterator referring to the character that now occupies the position of the first character erased, or string::end if no such character exists.

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
// string::erase
#include <iostream>
#include <string>

int main ()
{
  std::string str ("This is an example sentence.");
  std::cout << str << '\n';
                                           // "This is an example sentence."
  str.erase (10,8);                        //            ^^^^^^^^
  std::cout << str << '\n';
                                           // "This is an sentence."
  str.erase (str.begin()+9);               //           ^
  std::cout << str << '\n';
                                           // "This is a sentence."
  str.erase (str.begin()+5, str.end()-9);  //       ^^^^^
  std::cout << str << '\n';
                                           // "This sentence."
  return 0;
}
Output:
This is an example sentence.
This is an sentence.
This is a sentence.
This sentence.


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 pos is greater than the string length, an out_of_range exception is thrown.

An invalid p in (2), or an invalid range in (3), causes undefined behavior.
For (1) and (3), if an exception is thrown, there are no changes in the string (strong guarantee).
For (2), it never throws exceptions (no-throw guarantee).

If pos is greater than the string length, an out_of_range exception is thrown.

An invalid range in (3), causes undefined behavior.

See also