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

NAME
     std::list::emplace_back - std::list::emplace_back

Synopsis
	template< class... Args >		   (since C++11)
	void emplace_back( Args&&... args );	   (until C++17)
	template< class... Args >		   (since C++17)
	reference emplace_back( Args&&... args );

	Appends  a  new element to the end of the container. The element is con-
     structed
	through std::allocator_traits::construct, which  typically  uses  place-
     ment-new to
	construct  the	element  in-place  at  the location provided by the con-
     tainer. The
	arguments  args...  are  forwarded  to	the  constructor  as   std::for-
     ward<Args>(args)....

	No iterators or references are invalidated.

Parameters
	args	      - 	 arguments  to forward to the constructor of the
     element

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

Return value
	(none)				     (until C++17)
	A reference to the inserted element. (since C++17)

Complexity
	Constant.

Exceptions
	If an exception is thrown, this function has no effect (strong exception
     guarantee).

Example
	The  following code uses emplace_back to append an object of type Presi-
     dent to a
	std::list. It demonstrates how emplace_back forwards parameters  to  the
     President
	constructor  and  shows  how using emplace_back avoids the extra copy or
     move operation
	required when using push_back.

     // Run this code

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

      struct President
      {
	  std::string name;
	  std::string country;
	  int year;

	  President(std::string p_name, std::string p_country, int p_year)
	      :     name(std::move(p_name)),	  country(std::move(p_country)),
     year(p_year)
	  {
	      std::cout << "I am being constructed.\n";
	  }

	  President(President&& other)
	      :  name(std::move(other.name)), country(std::move(other.country)),
     year(other.year)
	  {
	      std::cout << "I am being moved.\n";
	  }

	  President& operator=(const President& other) = default;
      };

      int main()
      {
	  std::list<President> elections;
	  std::cout << "emplace_back:\n";
	  auto& ref = elections.emplace_back("Nelson Mandela",	"South	Africa",
     1994);
	  assert(ref.year  ==  1994  &&  "uses a reference to the created object
     (C++17)");

	  std::list<President> reElections;
	  std::cout << "\npush_back:\n";
	  reElections.push_back(President("Franklin  Delano   Roosevelt",   "the
     USA", 1936));

	  std::cout << "\nContents:\n";
	  for (President const& president: elections)
	      std::cout << president.name << " was elected president of "
			<<  president.country  <<  "  in  " << president.year <<
     ".\n";

	  for (President const& president: reElections)
	      std::cout << president.name << " was re-elected president of "
			<< president.country << "  in  "  <<  president.year  <<
     ".\n";
      }

Output:
      emplace_back:
      I am being constructed.

      push_back:
      I am being constructed.
      I am being moved.

Contents:
      Nelson Mandela was elected president of South Africa in 1994.
      Franklin Delano Roosevelt was re-elected president of the USA in 1936.

See also
	push_back adds an element to the end
		  (public member function)
	emplace   constructs element in-place
	(C++11)   (public member function)

http://cppreference.com 	   2024.06.10	      std::list::emplace_back(3)
home | help