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

NAME
     std::deque::emplace_back - std::deque::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)....

	All  iterators (including the end() iterator) are invalidated. No refer-
     ences 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::deque.  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 <deque>
      #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::deque<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::deque<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::deque::emplace_back(3)
home | help