Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       std::deque::insert - std::deque::insert

Synopsis
	  iterator insert( iterator pos, const T& value	);	       (until
								       C++11)
	  iterator insert( const_iterator pos, const T&	value	       (since
	  );							       C++11)
	  iterator insert( const_iterator pos, T&& value );	   (2) (since
								       C++11)
	  void	  insert(    iterator	pos,   size_type   count,   const   T&
       (until
	  value								    );
       C++11)
	  iterator	 insert(       const_iterator	   pos,	     size_type
       (since
	  count,   const   T&	value	 );				   (1)
       C++11)
	  template<		   class	       InputIt		     >
       (until
	  void	  insert(    iterator	 pos,	 InputIt    first,     InputIt
       C++11)
	  last );						   (3)
	  template< class InputIt >
								       (4)
       (since
	  iterator	      insert(		 const_iterator		  pos,
       C++11)

	  InputIt first, InputIt last );
	  iterator	     insert(		const_iterator		  pos,
       (5)     (since
	  std::initializer_list<T>		     ilist		    );
       C++11)

	  Inserts elements at the specified location in	the container.

	  1-2) inserts value before pos
	  3) inserts count copies of the value before pos
	  4) inserts elements from range [first, last) before pos.

	  This overload	has the	same effect as overload	(3) if InputIt	is  an
       (until C++11)
	  integral type.
	  This overload	participates in	overload resolution only if InputIt
	  qualifies  as	LegacyInputIterator, to	avoid ambiguity	with the over-
       load (since C++11)
	  (3).

	  The behavior is undefined if	first  and  last  are  iterators  into
       *this.
	  5) inserts elements from initializer list ilist before pos.

	  All iterators, including the past-the-end iterator, are invalidated.
       References are
	  invalidated  too,  unless  pos  == begin() or	pos == end(), in which
       case they are not
	  invalidated.

Parameters
	  pos		       -	  iterator before  which  the  content
       will be inserted.
					  pos may be the end() iterator
	  value		       -	  element value	to insert
	  count		       -	  number of elements to	insert
	  first,  last		 -	     the  range	of elements to insert,
       can't be	iterators
					  into container for which  insert  is
       called
	  ilist			-	   initializer list to insert the val-
       ues from

Type requirements
	  -
	  T must meet the requirements of CopyAssignable and CopyInsertable in
       order to	use
	  overload (1).
	  -
	  T must meet the requirements of MoveAssignable and MoveInsertable in
       order to	use
	  overload (2).
	  -
	  T must meet the requirements of CopyAssignable and CopyInsertable in
       order to	use
	  overload (3).
	  -
	  T must meet the requirements of EmplaceConstructible in order	to use
       overload	(4,5).
	  -
	  T must meet the requirements of Swappable, MoveAssignable,  MoveCon-
       structible and
	  MoveInsertable in order to use overload (4,5). (since	C++17)

Return value
	  1-2) Iterator	pointing to the	inserted value
	  3)  Iterator	pointing  to  the  first  element  inserted, or	pos if
       count==0.
	  4) Iterator pointing to  the	first  element	inserted,  or  pos  if
       first==last.
	  5)  Iterator pointing	to the first element inserted, or pos if ilist
       is empty.

Complexity
	  1-2) Constant	plus linear in the lesser of the distances between pos
       and either of
	  the ends of the container.
	  3) Linear in count plus linear in the	lesser of  the	distances  be-
       tween pos and either
	  of the ends of the container.
	  4) Linear in std::distance(first, last) plus linear in the lesser of
       the distances
	  between pos and either of the	ends of	the container.
	  5) Linear in ilist.size() plus linear	in the lesser of the distances
       between pos and
	  either of the	ends of	the container.

Exceptions
	  If  an exception is thrown when inserting a single element at	either
       end, this
	  function has no effect (strong exception guarantee).

Example
       // Run this code

	#include <iostream>
	#include <iterator>
	#include <deque>

	void print(int id, const std::deque<int>& container)
	{
	    std::cout << id << ". ";
	    for	(const int x: container) {
		 std::cout << x	<< ' ';
	    }
	    std::cout << '\n';
	}

	int main ()
	{
	    std::deque<int> c1(3, 100);
	    print(1, c1);

	    auto it = c1.begin();
	    it = c1.insert(it, 200);
	    print(2, c1);

	    c1.insert(it, 2, 300);
	    print(3, c1);

	    // reset `it` to the begin:
	    it = c1.begin();

	    std::deque<int> c2(2, 400);
	    c1.insert(std::next(it, 2),	c2.begin(), c2.end());
	    print(4, c1);

	    int	arr[] =	{ 501,502,503 };
	    c1.insert(c1.begin(), arr, arr + std::size(arr));
	    print(5, c1);

	    c1.insert(c1.end(),	{ 601,602,603 }	);
	    print(6, c1);
	}

Output:
	1. 100 100 100
	2. 200 100 100 100
	3. 300 300 200 100 100 100
	4. 300 300 400 400 200 100 100 100
	5. 501 502 503 300 300 400 400 200 100 100 100
	6. 501 502 503 300 300 400 400 200 100 100 100 601 602 603

See also
	  emplace    constructs	element	in-place
	  (C++11)    (public member function)
	  push_front inserts an	element	to the beginning
		     (public member function)
	  push_back  adds an element to	the end
		     (public member function)
	  inserter   creates a std::insert_iterator of type inferred from  the
       argument
		     (function template)

http://cppreference.com		  2022.07.31		 std::deque::insert(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::deque::insert&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help