// optional<T>版のオーバーロード
template <class... Args>
T& emplace(Args&&... args);                                        // (1) C++17
template <class... Args>
constexpr T& emplace(Args&&... args);                              // (1) C++23

template <class U, class... Args>
T& emplace(std::initializer_list<U> il, Args&&... args);           // (2) C++17
template <class U, class... Args>
constexpr T& emplace(std::initializer_list<U> il, Args&&... args); // (2) C++23

// optional<T&>版のオーバーロード (C++26)
template <class U>
constexpr T& emplace(U&& u) noexcept(see below);                   // (3) C++26

概要

要素型のコンストラクタ引数から直接構築する。

• (1) : 可変個の引数をとり、それを型Tのコンストラクタ引数として渡して、この関数内で型Tの有効値を構築して保持する
• (2) : 初期化子リストと可変個の引数をとり、それらを型Tのコンストラクタ引数として渡して、この関数内で型Tの有効値を構築して保持する
• (3) : optional<T&>の参照先を再束縛する。変換可能な単一引数を受け取る

optional<T>では (1), (2) が定義され、optional<T&>では (3) のみが定義される。

テンプレートパラメータ制約

• (1) : is_constructible_v<T, Args&&...> == trueであること
• (3) : is_constructible_v<T&, U> == trueであり、reference_constructs_from_temporary_v<T&, U> == falseであること

効果

• (1), (2) : まずreset()メンバ関数を呼び出す
  • (1) : 型Tの有効値を、std::forward<Args>(args)...を引数として構築する
  • (2) : 型Tの有効値を、ilとstd::forward<Args>(args)...を引数として構築する
• (3) : 参照先をuに再束縛する

戻り値

代入された有効値への参照を返す。

例外

型Tの選択されたコンストラクタが、任意の例外を送出する可能性がある。

例外安全性

型Tのコンストラクタが例外を送出した場合、*thisは有効値を含まない状態となり、元々保持していた有効値は破棄される。

備考

• (2) : このオーバーロードは主に、コンテナをアロケータ付きで、初期化子リスト代入するためにある
• (3) : 一時オブジェクトから参照を構築するとダングリングになるケースでは、このオーバーロードは削除定義される

例

#include <iostream>
#include <optional>
#include <string>
#include <vector>

int main()
{
  // (1)
  {
    std::optional<std::string> p;

    // std::stringのコンストラクタ引数を渡して、
    // emplace関数内でstringオブジェクトを構築する。
    p.emplace(3, 'A');
    std::cout << "(1) : " << p.value() << std::endl;
  }

  // (2)
  {
    std::optional<std::vector<int>> p;

    // 初期化子リストとアロケータから、
    // emplace関数内でvectorオブジェクトを構築する。
    std::allocator<int> alloc;
    p.emplace({3, 1, 4}, alloc);

    std::cout << "(2) :" << std::endl;
    for (int x : p.value()) {
      std::cout << "  " << x << std::endl;
    }
  }
}

出力

(1) : AAA
(2) :
  3
  1
  4

バージョン

言語

• C++17

処理系

• Clang: 4.0.1 ✅
• GCC: 7.2 ✅
• Visual C++: ??

参照

• N3406 A proposal to add a utility class to represent optional objects (Revision 2)
• LWG Issue 2857. {variant,optional,any}::emplace should return the constructed value
• P0084R2 Emplace Return Type (Revision 2)
• P2231R1 Missing constexpr in std::optional and std::variant
• P2988R12 std::optional<T&>
  • C++26で参照型T&に対する部分特殊化を追加
• LWG Issue 2746. Inconsistency between requirements for emplace between optional and variant
  • C++26で、emplaceの制約がRequires（ハードエラー）からConstraints（SFINAE）に統一された（cpprefjpでは「テンプレートパラメータ制約」として記載済み）
• LWG Issue 4300. Missing Returns: element in optional<T&>::emplace
  • C++26で、optional<T&>版 (3) の戻り値が*val（参照先）であることが明記された（cpprefjpの戻り値記述は全オーバーロード共通で既にこれを含む）