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

FreeBSD Manual Pages

  
 
  

home | help 
std::list::emplace(3)	      C++ Standard Libary	 std::list::emplace(3)

NAME
       std::list::emplace - std::list::emplace

Synopsis
	  template<   class...	Args  >					(since
       C++11)
	  iterator emplace( const_iterator pos,	Args&&... args );

	  Inserts a new	element	into the container directly before pos.

	  The element is constructed through std::allocator_traits::construct,
       which uses
	  placement-new	to construct the element in-place at a	location  pro-
       vided by	the
	  container.

	  The arguments	args...	are forwarded to the constructor as
	  std::forward<Args>(args)....	args...	may directly or	indirectly re-
       fer to a	value in
	  the container.

	  No iterators or references are invalidated.

Parameters
	  pos	      -	       iterator	before which the new element  will  be
       constructed
	  args	       -	arguments to forward to	the constructor	of the
       element

Type requirements
	  -
	  T (the container's element type) must	meet the requirements  of  Em-
       placeConstructible.

Return value
	  Iterator pointing to the emplaced element.

Complexity
	  Constant.

Exceptions
	  If  an  exception is thrown (e.g. by the constructor), the container
       is left
	  unmodified, as if this function was never called  (strong  exception
       guarantee).

Example
       // Run this code

	#include <iostream>
	#include <string>
	#include <list>

	struct A {
	    std::string	s;
	    A(std::string  str)	 :  s(std::move(str))	{  std::cout <<	" con-
       structed\n"; }
	    A(const A& o) : s(o.s) { std::cout << " copy constructed\n"; }
	    A(A&& o) : s(std::move(o.s)) { std::cout <<	" move constructed\n";
       }
	    A& operator=(const A& other) {
		s = other.s;
		std::cout << " copy assigned\n";
		return *this;
	    }
	    A& operator=(A&& other) {
		s = std::move(other.s);
		std::cout << " move assigned\n";
		return *this;
	    }
	};

	int main()
	{
	    std::list<A> container;

	    std::cout << "construct 2 times A:\n";
	    A two { "two" };
	    A three { "three" };

	    std::cout << "emplace:\n";
	    container.emplace(container.end(), "one");

	    std::cout << "emplace with A&:\n";
	    container.emplace(container.end(), two);

	    std::cout << "emplace with A&&:\n";
	    container.emplace(container.end(), std::move(three));

	    std::cout << "content:\n";
	    for	(const auto& obj : container)
		std::cout << ' ' << obj.s;
	    std::cout << '\n';
	}

Output:
	construct 2 times A:
	 constructed
	 constructed
	emplace:
	 constructed
	emplace	with A&:
	 copy constructed
	emplace	with A&&:
	 move constructed
	content:
	 one two three

	 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
	  LWG  2164  C++11	 it  was  not  clear whether the arguments can
       clarified
			      refer to the container

See also
	  insert       inserts elements
		       (public member function)
	  emplace_back constructs an element in-place at the end
	  (C++11)      (public member function)

http://cppreference.com		  2022.07.31		 std::list::emplace(3)

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

home | help