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

FreeBSD Manual Pages

  
 
  

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
       constructed
	  through  std::allocator_traits::construct,  which   typically	  uses
       placement-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 past-the-end iterator, are invalidated.
       No 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  Em-
       placeConstructible.

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 ex-
       ception guarantee).

Example
	  The following	code uses emplace_back to append  an  object  of  type
       President 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 <string>
	#include <cassert>
	#include <iostream>

	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.coun-
       try)), 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.

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		  2022.07.31	   std::deque::emplace_back(3)

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

home | help