home | help 
std::basic_string::erase(3)    C++ Standard Libary   std::basic_string::erase(3)

NAME
     std::basic_string::erase - std::basic_string::erase

Synopsis
	basic_string& erase(		  (constexpr since
	size_type index = 0,	      (1) C++20)
	size_type count = npos );
	iterator erase( iterator			   (until C++11)
	position );
	iterator erase( 				   (since C++11)
	const_iterator position );			   (constexpr since
				      (2)		   C++20)
	iterator erase( iterator					    (un-
     til C++11)
	first, iterator last );
	iterator		   erase(				     (3)
     (since C++11)
	const_iterator							  first,
     (constexpr since
	const_iterator				last			      );
     C++20)

	Removes specified characters from the string.

	1) Removes std::min(count, size() - index) characters starting at index.
	2) Removes the character at position.
	If position is not a dereferenceable iterator on *this, the behavior  is
     undefined.
	3) Removes the characters in the range [first, last).
	If  first  or last is not a valid iterator on *this, or [first, last) is
     not a valid
	range, the behavior is undefined.

Parameters
	index	    - first character to remove
	count	    - number of characters to remove
	position    - iterator to the character to remove
	first, last - range of the characters to remove

Return value
	1) *this
	2) Iterator pointing to the character immediately following the  charac-
     ter erased, or
	end() if no such character exists.
	3)  Iterator pointing to the character last pointed to before the erase,
     or end() if
	no such character exists.

Exceptions
	1) std::out_of_range if index > size().
	2,3) Throws nothing.

	If an exception is thrown for any reason, this function  has  no  effect
     (strong
	exception safety guarantee).

Example
     // Run this code

      #include <algorithm>
      #include <iostream>
      #include <iterator>
      #include <string>

      int main()
      {
	  std::string s = "This Is An Example";
	  std::cout << "1) " << s << '\n';

	  s.erase(7, 3); // erases " An" using overload (1)
	  std::cout << "2) " << s << '\n';

	  s.erase(std::find(s.begin(),	s.end(),  '  '));  //  erases first ' ';
     overload (2)
	  std::cout << "3) " << s << '\n';

	  s.erase(s.find(' ')); // trims from ' ' to  the  end	of  the  string;
     overload (1)
	  std::cout << "4) " << s << '\n';

	  auto	it  =  std::next(s.begin(), s.find('s')); // obtains iterator to
     the first 's'
	  s.erase(it, std::next(it, 2)); // erases "sI"; overload (3)
	  std::cout << "5) " << s << '\n';
      }

Output:
      1) This Is An Example
      2) This Is Example
      3) ThisIs Example
      4) ThisIs
      5) This

	Defect reports

	The following behavior-changing defect	reports  were  applied	retroac-
     tively to
	previously published C++ standards.

	  DR	Applied to	     Behavior as published		 Correct
     behavior
			   overload (3) did not erase the character   returns an
     iterator
	LWG  27   C++98      last pointed to, but it returned		pointing
     to that
			   the iterator pointing to the character     character
			   immediately following that character
			   overload (2) explicitly required position
	LWG 428 C++98	   to be  valid,  but				 removed
     the
			   SequenceContainer  requires	it to be	explicit
     requirement
			   dereferenceable (stricter)
	LWG 847 C++98	   there was  no  exception  safety  guarantee	   added
     strong exception
								      safety
     guarantee

See also
	clear clears the contents
	      (public member function)

http://cppreference.com 	   2024.06.10	     std::basic_string::erase(3)
home | help