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

NAME
     std::deque::erase - std::deque::erase

Synopsis
	iterator erase( iterator pos ); 			 (until C++11)
	iterator erase( const_iterator pos );			 (since C++11)
	iterator    erase(    iterator	  first,    iterator	last	);   (1)
     (until C++11)
	iterator     erase(	const_iterator	   first,		     (2)
     (since C++11)
	const_iterator last );

	Erases the specified elements from the container.

	1) Removes the element at pos.
	2) Removes the elements in the range [first, last).

	All iterators and references are invalidated, unless the erased elements
     are at the
	end  or at the beginning of the container, in which case only the itera-
     tors and
	references to the erased elements are invalidated. The end() iterator is
     also
	invalidated unless the erased elements are at the beginning of the  con-
     tainer and the
	last element is not erased.

	The iterator pos must be valid and dereferenceable. Thus the end() iter-
     ator (which
	is valid, but is not dereferenceable) cannot be used as a value for pos.

	The iterator first does not need to be dereferenceable if first == last:
     erasing an
	empty range is a no-op.

Parameters
	pos	    - iterator to the element to remove
	first, last - range of elements to remove

Type requirements
	-
	T must meet the requirements of MoveAssignable.

Return value
	Iterator following the last removed element.

	1)  If	pos  refers  to the last element, then the end() iterator is re-
     turned.
	2) If last == end() prior to removal, then the updated end() iterator is
     returned.
	If [first, last) is an empty range, then last is returned.

Exceptions
	Does not throw unless an exception is thrown by the assignment	operator
     of T.

Complexity
	Linear:  the  number  of calls to the destructor of T is the same as the
     number of
	elements erased, the number of calls to the assignment operator of T  is
     no more than
	the  lesser of the number of elements before the erased elements and the
     number of
	elements after the erased elements.

Notes
	When container elements need to be erased based on a  predicate,  rather
     than
	iterating  the	container  and	calling  unary erase, the iterator range
     overload is
	generally used with std::remove()/std::remove_if() to minimise the  num-
     ber of moves
	of the remaining (non-removed) elements, this is the erase-remove idiom.
	std::erase_if() replaces the erase-remove idiom.
	(since C++20)

Example
     // Run this code

      #include <deque>
      #include <iostream>

      void print_container(const std::deque<int>& c)
      {
	  for (int i : c)
	      std::cout << i << ' ';
	  std::cout << '\n';
      }

      int main()
      {
	  std::deque<int> c{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
	  print_container(c);

	  c.erase(c.begin());
	  print_container(c);

	  c.erase(c.begin() + 2, c.begin() + 5);
	  print_container(c);

	  // Erase all even numbers
	  for (std::deque<int>::iterator it = c.begin(); it != c.end();)
	  {
	      if (*it % 2 == 0)
		  it = c.erase(it);
	      else
		  ++it;
	  }
	  print_container(c);
      }

Output:
      0 1 2 3 4 5 6 7 8 9
      1 2 3 4 5 6 7 8 9
      1 2 6 7 8 9
      1 7 9

	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
			   first was required to be
	LWG  151 C++98	    dereferenceable, which		    not required
     if
			   made the behavior of clearing an empty  first == last
			   deque undefined
								   it is invali-
     dated if the
	LWG 638 C++98	   the past-the-end iterator was not	   elements are
			   invalidated				    erased  from
     the middle or
								   the end

See also
	erase(std::deque)    erases all elements satisfying specific criteria
	erase_if(std::deque) (function template)
	(C++20)
	clear		     clears the contents
			     (public member function)

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