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

NAME
     std::optional::emplace - std::optional::emplace

Synopsis
	template<  class...  Args  >				     (1)  (since
     C++17)
	T& emplace( Args&&... args );				      (constexpr
     since C++20)
	template<  class  U,  class...	Args  > 			  (since
     C++17)
	T& emplace( std::initializer_list<U> ilist, Args&&...	 (2)  (constexpr
     since C++20)
	args );

	Constructs  the  contained  value  in-place. If *this already contains a
     value before
	the call, the contained value is destroyed by calling its destructor.

	1) Initializes the contained value by direct-initializing (but not
	direct-list-initializing) with	std::forward<Args>(args)...  as  parame-
     ters.
	2)  Initializes  the  contained  value	by  calling its constructor with
     ilist,
	std::forward<Args>(args)... as parameters. This overload participates in
     overload
	resolution only if std::is_constructible<T, std::initializer_list<U>&,
	Args&&...>::value is true.

Parameters
	args... 	-	 the arguments to pass to the constructor
	ilist		-	 the initializer list to pass to the constructor

Type requirements
	-
	T must be constructible from Args... for overload (1)
	-
	T must be constructible from std::initializer_list and Args... for over-
     load (2)

Return value
	A reference to the new contained value.

Exceptions
	Any exception thrown by the selected constructor of T. If  an  exception
     is thrown,
	*this does not contain a value after this call (the previously contained
     value, if
	any, had been destroyed).

Example
     // Run this code

      #include <iostream>
      #include <optional>

      struct A
      {
	  std::string s;

	  A(std::string   str)	:  s(std::move(str)),  id{n++}	{  note("+  con-
     structed"); }
	  ~A() { note("~ destructed"); }
	  A(const A& o) : s(o.s), id{n++} { note("+ copy constructed"); }
	  A(A&& o) : s(std::move(o.s)), id{n++} { note("+ move constructed"); }

	  A& operator=(const A& other)
	  {
	      s = other.s;
	      note("= copy assigned");
	      return *this;
	  }

	  A& operator=(A&& other)
	  {
	      s = std::move(other.s);
	      note("= move assigned");
	      return *this;
	  }

	  inline static int n{};
	  int id{};
	  void note(auto s) { std::cout << "  " << s << " #" << id << '\n'; }
      };

      int main()
      {
	  std::optional<A> opt;

	  std::cout << "Assign:\n";
	  opt = A("Lorem ipsum	dolor  sit  amet,  consectetur	adipiscing  elit
     nec.");

	  std::cout << "Emplace:\n";
	  // As opt contains a value it will also destroy that value
	  opt.emplace("Lorem ipsum dolor sit amet, consectetur efficitur.");

	  std::cout << "End example\n";
      }

Output:
      Assign:
	+ constructed #0
	+ move constructed #1
	~ destructed #0
      Emplace:
	~ destructed #1
	+ constructed #2
      End example
	~ destructed #2

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	  DR	Applied to		Behavior as published		    Cor-
     rect behavior
	P2231R1 C++20	   emplace was not constexpr while the required     made
     constexpr
			   operations can be constexpr in C++20

See also
	operator= assigns contents
		  (public member function)

http://cppreference.com 	   2024.06.10	       std::optional::emplace(3)
home | help