22 General utilities library [utilities]

22.1 General [utilities.general]

1
#
This Clause describes utilities that are generally useful in C++ programs; some of these utilities are used by other elements of the C++ standard library.
These utilities are summarized in Table 61.
Table 61: General utilities library summary [tab:utilities.summary]
Subclause
Header
Utility components
<utility>
Pairs
Tuples
<tuple>
Optional objects
<optional>
Variants
<variant>
Storage for any type
<any>
Expected objects
<expected>
Fixed-size sequences of bits
<bitset>
Function objects
<functional>
Type indexes
<typeindex>
Execution policies
<execution>
Primitive numeric conversions
<charconv>
Formatting
<format>
Bit manipulation
<bit>
Debugging
<debugging>

22.2 Utility components [utility]

22.2.1 Header <utility> synopsis [utility.syn]

1
#
The header <utility> contains some basic function and class templates that are used throughout the rest of the library.
// all freestanding #include <compare> // see [compare.syn] #include <initializer_list> // see [initializer.list.syn] namespace std { // [utility.swap], swap template<class T> constexpr void swap(T& a, T& b) noexcept(see below); template<class T, size_t N> constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>); // [utility.exchange], exchange template<class T, class U = T> constexpr T exchange(T& obj, U&& new_val) noexcept(see below); // [forward], forward/move template<class T> constexpr T&& forward(remove_reference_t<T>& t) noexcept; template<class T> constexpr T&& forward(remove_reference_t<T>&& t) noexcept; template<class T, class U> [[nodiscard]] constexpr auto forward_like(U&& x) noexcept -> see below; template<class T> constexpr remove_reference_t<T>&& move(T&&) noexcept; template<class T> constexpr conditional_t< !is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&> move_if_noexcept(T& x) noexcept; // [utility.as.const], as_const template<class T> constexpr add_const_t<T>& as_const(T& t) noexcept; template<class T> void as_const(const T&&) = delete; // [declval], declval template<class T> add_rvalue_reference_t<T> declval() noexcept; // as unevaluated operand // [utility.intcmp], integer comparison functions template<class T, class U> constexpr bool cmp_equal(T t, U u) noexcept; template<class T, class U> constexpr bool cmp_not_equal(T t, U u) noexcept; template<class T, class U> constexpr bool cmp_less(T t, U u) noexcept; template<class T, class U> constexpr bool cmp_greater(T t, U u) noexcept; template<class T, class U> constexpr bool cmp_less_equal(T t, U u) noexcept; template<class T, class U> constexpr bool cmp_greater_equal(T t, U u) noexcept; template<class R, class T> constexpr bool in_range(T t) noexcept; // [utility.underlying], to_underlying template<class T> constexpr underlying_type_t<T> to_underlying(T value) noexcept; // [utility.unreachable], unreachable [[noreturn]] void unreachable(); // [intseq], compile-time integer sequences template<class T, T...> struct integer_sequence; template<size_t... I> using index_sequence = integer_sequence<size_t, I...>; template<class T, T N> using make_integer_sequence = integer_sequence<T, see below>; template<size_t N> using make_index_sequence = make_integer_sequence<size_t, N>; template<class... T> using index_sequence_for = make_index_sequence<sizeof...(T)>; // [pairs], class template pair template<class T1, class T2> struct pair; template<class T1, class T2, class U1, class U2, template<class> class TQual, template<class> class UQual> requires requires { typename pair<common_reference_t<TQual<T1>, UQual<U1>>, common_reference_t<TQual<T2>, UQual<U2>>>; } struct basic_common_reference<pair<T1, T2>, pair<U1, U2>, TQual, UQual> { using type = pair<common_reference_t<TQual<T1>, UQual<U1>>, common_reference_t<TQual<T2>, UQual<U2>>>; }; template<class T1, class T2, class U1, class U2> requires requires { typename pair<common_type_t<T1, U1>, common_type_t<T2, U2>>; } struct common_type<pair<T1, T2>, pair<U1, U2>> { using type = pair<common_type_t<T1, U1>, common_type_t<T2, U2>>; }; // [pairs.spec], pair specialized algorithms template<class T1, class T2, class U1, class U2> constexpr bool operator==(const pair<T1, T2>&, const pair<U1, U2>&); template<class T1, class T2, class U1, class U2> constexpr common_comparison_category_t<synth-three-way-result<T1, U1>, synth-three-way-result<T2, U2>> operator<=>(const pair<T1, T2>&, const pair<U1, U2>&); template<class T1, class T2> constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y))); template<class T1, class T2> constexpr void swap(const pair<T1, T2>& x, const pair<T1, T2>& y) noexcept(noexcept(x.swap(y))); template<class T1, class T2> constexpr see below make_pair(T1&&, T2&&); // [pair.astuple], tuple-like access to pair template<class T> struct tuple_size; template<size_t I, class T> struct tuple_element; template<class T1, class T2> struct tuple_size<pair<T1, T2>>; template<size_t I, class T1, class T2> struct tuple_element<I, pair<T1, T2>>; template<size_t I, class T1, class T2> constexpr tuple_element_t<I, pair<T1, T2>>& get(pair<T1, T2>&) noexcept; template<size_t I, class T1, class T2> constexpr tuple_element_t<I, pair<T1, T2>>&& get(pair<T1, T2>&&) noexcept; template<size_t I, class T1, class T2> constexpr const tuple_element_t<I, pair<T1, T2>>& get(const pair<T1, T2>&) noexcept; template<size_t I, class T1, class T2> constexpr const tuple_element_t<I, pair<T1, T2>>&& get(const pair<T1, T2>&&) noexcept; template<class T1, class T2> constexpr T1& get(pair<T1, T2>& p) noexcept; template<class T1, class T2> constexpr const T1& get(const pair<T1, T2>& p) noexcept; template<class T1, class T2> constexpr T1&& get(pair<T1, T2>&& p) noexcept; template<class T1, class T2> constexpr const T1&& get(const pair<T1, T2>&& p) noexcept; template<class T2, class T1> constexpr T2& get(pair<T1, T2>& p) noexcept; template<class T2, class T1> constexpr const T2& get(const pair<T1, T2>& p) noexcept; template<class T2, class T1> constexpr T2&& get(pair<T1, T2>&& p) noexcept; template<class T2, class T1> constexpr const T2&& get(const pair<T1, T2>&& p) noexcept; // [pair.piecewise], pair piecewise construction struct piecewise_construct_t { explicit piecewise_construct_t() = default; }; inline constexpr piecewise_construct_t piecewise_construct{}; template<class... Types> class tuple; // defined in <tuple> // in-place construction struct in_place_t { explicit in_place_t() = default; }; inline constexpr in_place_t in_place{}; template<class T> struct in_place_type_t { explicit in_place_type_t() = default; }; template<class T> constexpr in_place_type_t<T> in_place_type{}; template<size_t I> struct in_place_index_t { explicit in_place_index_t() = default; }; template<size_t I> constexpr in_place_index_t<I> in_place_index{}; // nontype argument tag template<auto V> struct nontype_t { explicit nontype_t() = default; }; template<auto V> constexpr nontype_t<V> nontype{}; }

22.2.2 swap [utility.swap]

🔗
template<class T> constexpr void swap(T& a, T& b) noexcept(see below);
1
#
Constraints: is_move_constructible_v<T> is true and is_move_assignable_v<T> is true.
2
#
Preconditions: Type T meets the Cpp17MoveConstructible (Table 31) and Cpp17MoveAssignable (Table 33) requirements.
3
#
Effects: Exchanges values stored in two locations.
4
#
Remarks: The exception specification is equivalent to: is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>
🔗
template<class T, size_t N> constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);
5
#
Constraints: is_swappable_v<T> is true.
6
#
Preconditions: a[i] is swappable with ([swappable.requirements]) b[i] for all i in the range [0, N).
7
#
Effects: As if by swap_ranges(a, a + N, b).

22.2.3 exchange [utility.exchange]

🔗
template<class T, class U = T> constexpr T exchange(T& obj, U&& new_val) noexcept(see below);
1
#
Effects: Equivalent to: T old_val = std::move(obj); obj = std::forward<U>(new_val); return old_val;
2
#
Remarks: The exception specification is equivalent to: is_nothrow_move_constructible_v<T> && is_nothrow_assignable_v<T&, U>

22.2.4 Forward/move helpers [forward]

1
#
The library provides templated helper functions to simplify applying move semantics to an lvalue and to simplify the implementation of forwarding functions.
All functions specified in this subclause are signal-safe.
🔗
template<class T> constexpr T&& forward(remove_reference_t<T>& t) noexcept; template<class T> constexpr T&& forward(remove_reference_t<T>&& t) noexcept;
2
#
Mandates: For the second overload, is_lvalue_reference_v<T> is false.
3
#
Returns: static_cast<T&&>(t).
4
#
[Example 1: template<class T, class A1, class A2> shared_ptr<T> factory(A1&& a1, A2&& a2) { return shared_ptr<T>(new T(std::forward<A1>(a1), std::forward<A2>(a2))); } struct A { A(int&, const double&); }; void g() { shared_ptr<A> sp1 = factory<A>(2, 1.414); // error: 2 will not bind to int& int i = 2; shared_ptr<A> sp2 = factory<A>(i, 1.414); // OK }
In the first call to factory, A1 is deduced as int, so 2 is forwarded to A's constructor as an rvalue.
In the second call to factory, A1 is deduced as int&, so i is forwarded to A's constructor as an lvalue.
In both cases, A2 is deduced as double, so 1.414 is forwarded to A's constructor as an rvalue.
— end example]
🔗
template<class T, class U> constexpr auto forward_like(U&& x) noexcept -> see below;
5
#
Mandates: T is a referenceable type ([defns.referenceable]).
6
#
  • (6.1)
    Let COPY_CONST(A, B) be const B if A is a const type, otherwise B.
  • (6.2)
    Let OVERRIDE_REF(A, B) be remove_reference_t<B>&& if A is an rvalue reference type, otherwise B&.
  • (6.3)
    Let V be OVERRIDE_REF(T&&, COPY_CONST(remove_reference_t<T>, remove_reference_t<U>))
7
#
Returns: static_cast<V>(x).
8
#
Remarks: The return type is V.
9
#
[Example 2: struct accessor { vector<string>* container; decltype(auto) operator[](this auto&& self, size_t i) { return std::forward_like<decltype(self)>((*container)[i]); } }; void g() { vector v{"a"s, "b"s}; accessor a{&v}; string& x = a[0]; // OK, binds to lvalue reference string&& y = std::move(a)[0]; // OK, is rvalue reference string const&& z = std::move(as_const(a))[1]; // OK, is const&& string& w = as_const(a)[1]; // error: will not bind to non-const } — end example]
🔗
template<class T> constexpr remove_reference_t<T>&& move(T&& t) noexcept;
10
#
Returns: static_cast<remove_reference_t<T>&&>(t).
11
#
[Example 3: template<class T, class A1> shared_ptr<T> factory(A1&& a1) { return shared_ptr<T>(new T(std::forward<A1>(a1))); } struct A { A(); A(const A&); // copies from lvalues A(A&&); // moves from rvalues }; void g() { A a; shared_ptr<A> sp1 = factory<A>(a); // “a'' binds to A(const A&) shared_ptr<A> sp2 = factory<A>(std::move(a)); // “a'' binds to A(A&&) }
In the first call to factory, A1 is deduced as A&, so a is forwarded as a non-const lvalue.
This binds to the constructor A(const A&), which copies the value from a.
In the second call to factory, because of the call std​::​move(a), A1 is deduced as A, so a is forwarded as an rvalue.
This binds to the constructor A(A&&), which moves the value from a.
— end example]
🔗
template<class T> constexpr conditional_t< !is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&> move_if_noexcept(T& x) noexcept;
12
#
Returns: std​::​move(x).

22.2.5 Function template as_const [utility.as.const]

🔗
template<class T> constexpr add_const_t<T>& as_const(T& t) noexcept;
1
#
Returns: t.

22.2.6 Function template declval [declval]

1
#
The library provides the function template declval to simplify the definition of expressions which occur as unevaluated operands.
🔗
template<class T> add_rvalue_reference_t<T> declval() noexcept; // as unevaluated operand
2
#
Mandates: This function is not odr-used ([basic.def.odr]).
3
#
Remarks: The template parameter T of declval may be an incomplete type.
4
#
[Example 1: 
template<class To, class From> decltype(static_cast<To>(declval<From>())) convert(From&&); declares a function template convert which only participates in overload resolution if the type From can be explicitly converted to type To.
For another example see class template common_type ([meta.trans.other]).
— end example]

22.2.7 Integer comparison functions [utility.intcmp]

🔗
template<class T, class U> constexpr bool cmp_equal(T t, U u) noexcept;
1
#
Mandates: Both T and U are standard integer types or extended integer types ([basic.fundamental]).
2
#
Effects: Equivalent to: using UT = make_unsigned_t<T>; using UU = make_unsigned_t<U>; if constexpr (is_signed_v<T> == is_signed_v<U>) return t == u; else if constexpr (is_signed_v<T>) return t < 0 ? false : UT(t) == u; else return u < 0 ? false : t == UU(u);
🔗
template<class T, class U> constexpr bool cmp_not_equal(T t, U u) noexcept;
3
#
Effects: Equivalent to: return !cmp_equal(t, u);
🔗
template<class T, class U> constexpr bool cmp_less(T t, U u) noexcept;
4
#
Mandates: Both T and U are standard integer types or extended integer types ([basic.fundamental]).
5
#
Effects: Equivalent to: using UT = make_unsigned_t<T>; using UU = make_unsigned_t<U>; if constexpr (is_signed_v<T> == is_signed_v<U>) return t < u; else if constexpr (is_signed_v<T>) return t < 0 ? true : UT(t) < u; else return u < 0 ? false : t < UU(u);
🔗
template<class T, class U> constexpr bool cmp_greater(T t, U u) noexcept;
6
#
Effects: Equivalent to: return cmp_less(u, t);
🔗
template<class T, class U> constexpr bool cmp_less_equal(T t, U u) noexcept;
7
#
Effects: Equivalent to: return !cmp_greater(t, u);
🔗
template<class T, class U> constexpr bool cmp_greater_equal(T t, U u) noexcept;
8
#
Effects: Equivalent to: return !cmp_less(t, u);
🔗
template<class R, class T> constexpr bool in_range(T t) noexcept;
9
#
Mandates: Both T and R are standard integer types or extended integer types ([basic.fundamental]).
10
#
Effects: Equivalent to: return cmp_greater_equal(t, numeric_limits<R>::min()) && cmp_less_equal(t, numeric_limits<R>::max());
11
#
[Note 1: 
These function templates cannot be used to compare byte, char, char8_t, char16_t, char32_t, wchar_t, and bool.
— end note]

22.2.8 Function template to_underlying [utility.underlying]

🔗
template<class T> constexpr underlying_type_t<T> to_underlying(T value) noexcept;
1
#
Returns: static_cast<underlying_type_t<T>>(value).

22.2.9 Function unreachable [utility.unreachable]

🔗
[[noreturn]] void unreachable();
1
#
Preconditions: false is true.
[Note 1: 
This precondition cannot be satisfied, thus the behavior of calling unreachable is undefined.
— end note]
2
#
[Example 1: int f(int x) { switch (x) { case 0: case 1: return x; default: std::unreachable(); } } int a = f(1); // OK, a has value 1 int b = f(3); // undefined behavior — end example]

22.3 Pairs [pairs]

22.3.1 General [pairs.general]

1
#
The library provides a template for heterogeneous pairs of values.
The library also provides a matching function template to simplify their construction and several templates that provide access to pair objects as if they were tuple objects (see [tuple.helper] and [tuple.elem]).

22.3.2 Class template pair [pairs.pair]

🔗
namespace std { template<class T1, class T2> struct pair { using first_type = T1; using second_type = T2; T1 first; T2 second; pair(const pair&) = default; pair(pair&&) = default; constexpr explicit(see below) pair(); constexpr explicit(see below) pair(const T1& x, const T2& y); template<class U1 = T1, class U2 = T2> constexpr explicit(see below) pair(U1&& x, U2&& y); template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>& p); template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>& p); template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>&& p); template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>&& p); template<pair-like P> constexpr explicit(see below) pair(P&& p); template<class... Args1, class... Args2> constexpr pair(piecewise_construct_t, tuple<Args1...> first_args, tuple<Args2...> second_args); constexpr pair& operator=(const pair& p); constexpr const pair& operator=(const pair& p) const; template<class U1, class U2> constexpr pair& operator=(const pair<U1, U2>& p); template<class U1, class U2> constexpr const pair& operator=(const pair<U1, U2>& p) const; constexpr pair& operator=(pair&& p) noexcept(see below); constexpr const pair& operator=(pair&& p) const; template<class U1, class U2> constexpr pair& operator=(pair<U1, U2>&& p); template<class U1, class U2> constexpr const pair& operator=(pair<U1, U2>&& p) const; template<pair-like P> constexpr pair& operator=(P&& p); template<pair-like P> constexpr const pair& operator=(P&& p) const; constexpr void swap(pair& p) noexcept(see below); constexpr void swap(const pair& p) const noexcept(see below); }; template<class T1, class T2> pair(T1, T2) -> pair<T1, T2>; }
1
#
Constructors and member functions of pair do not throw exceptions unless one of the element-wise operations specified to be called for that operation throws an exception.
2
#
The defaulted move and copy constructor, respectively, of pair is a constexpr function if and only if all required element-wise initializations for move and copy, respectively, would be constexpr-suitable ([dcl.constexpr]).
3
#
If (is_trivially_destructible_v<T1> && is_trivially_destructible_v<T2>) is true, then the destructor of pair is trivial.
4
#
pair<T, U> is a structural type ([temp.param]) if T and U are both structural types.
Two values p1 and p2 of type pair<T, U> are template-argument-equivalent ([temp.type]) if and only if p1.first and p2.first are template-argument-equivalent and p1.second and p2.second are template-argument-equivalent.
🔗
constexpr explicit(see below) pair();
5
#
Constraints:
  • (5.1)
    is_default_constructible_v<T1> is true and
  • (5.2)
    is_default_constructible_v<T2> is true.
6
#
Effects: Value-initializes first and second.
7
#
Remarks: The expression inside explicit evaluates to true if and only if either T1 or T2 is not implicitly default-constructible.
[Note 1: 
This behavior can be implemented with a trait that checks whether a const T1& or a const T2& can be initialized with {}.
— end note]
🔗
constexpr explicit(see below) pair(const T1& x, const T2& y);
8
#
Constraints:
  • (8.1)
    is_copy_constructible_v<T1> is true and
  • (8.2)
    is_copy_constructible_v<T2> is true.
9
#
Effects: Initializes first with x and second with y.
10
#
Remarks: The expression inside explicit is equivalent to: !is_convertible_v<const T1&, T1> || !is_convertible_v<const T2&, T2>
🔗
template<class U1 = T1, class U2 = T2> constexpr explicit(see below) pair(U1&& x, U2&& y);
11
#
Constraints:
  • (11.1)
    is_constructible_v<T1, U1> is true and
  • (11.2)
    is_constructible_v<T2, U2> is true.
12
#
Effects: Initializes first with std​::​forward<U1>(x) and second with std​::​forward<U2>(y).
13
#
Remarks: The expression inside explicit is equivalent to: !is_convertible_v<U1, T1> || !is_convertible_v<U2, T2>
This constructor is defined as deleted if reference_constructs_from_temporary_v<first_type, U1&&> is true or reference_constructs_from_temporary_v<second_type, U2&&> is true.
🔗
template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>& p); template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>& p); template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>&& p); template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>&& p); template<pair-like P> constexpr explicit(see below) pair(P&& p);
14
#
Let FWD(u) be static_cast<decltype(u)>(u).
15
#
Constraints:
  • (15.1)
    For the last overload, remove_cvref_t<P> is not a specialization of ranges​::​subrange,
  • (15.2)
    is_constructible_v<T1, decltype(get<0>(FWD(p)))> is true, and
  • (15.3)
    is_constructible_v<T2, decltype(get<1>(FWD(p)))> is true.
16
#
Effects: Initializes first with get<0>(FWD(p)) and second with get<1>(FWD(p)).
17
#
Remarks: The expression inside explicit is equivalent to: !is_convertible_v<decltype(get<0>(FWD(p))), T1> || !is_convertible_v<decltype(get<1>(FWD(p))), T2>
The constructor is defined as deleted if reference_constructs_from_temporary_v<first_type, decltype(get<0>(FWD(p)))> || reference_constructs_from_temporary_v<second_type, decltype(get<1>(FWD(p)))> is true.
🔗
template<class... Args1, class... Args2> constexpr pair(piecewise_construct_t, tuple<Args1...> first_args, tuple<Args2...> second_args);
18
#
Mandates:
  • (18.1)
    is_constructible_v<T1, Args1...> is true and
  • (18.2)
    is_constructible_v<T2, Args2...> is true.
19
#
Effects: Initializes first with arguments of types Args1... obtained by forwarding the elements of first_args and initializes second with arguments of types Args2... obtained by forwarding the elements of second_args.
(Here, forwarding an element x of type U within a tuple object means calling std​::​forward<U>(x).)
This form of construction, whereby constructor arguments for first and second are each provided in a separate tuple object, is called piecewise construction.
[Note 2: 
If a data member of pair is of reference type and its initialization binds it to a temporary object, the program is ill-formed ([class.base.init]).
— end note]
🔗
constexpr pair& operator=(const pair& p);
20
#
Effects: Assigns p.first to first and p.second to second.
21
#
Returns: *this.
22
#
Remarks: This operator is defined as deleted unless is_copy_assignable_v<T1> is true and is_copy_assignable_v<T2> is true.
🔗
constexpr const pair& operator=(const pair& p) const;
23
#
Constraints:
  • (23.1)
    is_copy_assignable_v<const T1> is true and
  • (23.2)
    is_copy_assignable_v<const T2> is true.
24
#
Effects: Assigns p.first to first and p.second to second.
25
#
Returns: *this.
🔗
template<class U1, class U2> constexpr pair& operator=(const pair<U1, U2>& p);
26
#
Constraints:
  • (26.1)
    is_assignable_v<T1&, const U1&> is true and
  • (26.2)
    is_assignable_v<T2&, const U2&> is true.
27
#
Effects: Assigns p.first to first and p.second to second.
28
#
Returns: *this.
🔗
template<class U1, class U2> constexpr const pair& operator=(const pair<U1, U2>& p) const;
29
#
Constraints:
  • (29.1)
    is_assignable_v<const T1&, const U1&> is true, and
  • (29.2)
    is_assignable_v<const T2&, const U2&> is true.
30
#
Effects: Assigns p.first to first and p.second to second.
31
#
Returns: *this.
🔗
constexpr pair& operator=(pair&& p) noexcept(see below);
32
#
Constraints:
  • (32.1)
    is_move_assignable_v<T1> is true and
  • (32.2)
    is_move_assignable_v<T2> is true.
33
#
Effects: Assigns std​::​forward<T1>(p.first) to first and std​::​forward<T2>(p.second) to second.
34
#
Returns: *this.
35
#
Remarks: The exception specification is equivalent to: is_nothrow_move_assignable_v<T1> && is_nothrow_move_assignable_v<T2>
🔗
constexpr const pair& operator=(pair&& p) const;
36
#
Constraints:
  • (36.1)
    is_assignable_v<const T1&, T1> is true and
  • (36.2)
    is_assignable_v<const T2&, T2> is true.
37
#
Effects: Assigns std​::​forward<T1>(p.first) to first and std​::​forward<T2>(p.second) to second.
38
#
Returns: *this.
🔗
template<class U1, class U2> constexpr pair& operator=(pair<U1, U2>&& p);
39
#
Constraints:
  • (39.1)
    is_assignable_v<T1&, U1> is true and
  • (39.2)
    is_assignable_v<T2&, U2> is true.
40
#
Effects: Assigns std​::​forward<U1>(p.first) first and std​::​forward<U2>(p.second) to second.
41
#
Returns: *this.
🔗
template<pair-like P> constexpr pair& operator=(P&& p);
42
#
Constraints:
43
#
Effects: Assigns get<0>(std​::​forward<P>(p)) to first and get<1>(std​::​forward<P>(p)) to second.
44
#
Returns: *this.
🔗
template<pair-like P> constexpr const pair& operator=(P&& p) const;
45
#
Constraints:
  • (45.1)
    different-from<P, pair> ([range.utility.helpers]) is true,
  • (45.2)
    remove_cvref_t<P> is not a specialization of ranges​::​subrange,
  • (45.3)
    is_assignable_v<const T1&, decltype(get<0>(std​::​forward<P>(p)))> is true, and
  • (45.4)
    is_assignable_v<const T2&, decltype(get<1>(std​::​forward<P>(p)))> is true.
46
#
Effects: Assigns get<0>(std​::​forward<P>(p)) to first and get<1>(std​::​forward<P>(p)) to second.
47
#
Returns: *this.
🔗
template<class U1, class U2> constexpr const pair& operator=(pair<U1, U2>&& p) const;
48
#
Constraints:
  • (48.1)
    is_assignable_v<const T1&, U1> is true, and
  • (48.2)
    is_assignable_v<const T2&, U2> is true.
49
#
Effects: Assigns std​::​forward<U1>(p.first) to first and std​::​forward<U2>(u.second) to second.
50
#
Returns: *this.
🔗
constexpr void swap(pair& p) noexcept(see below); constexpr void swap(const pair& p) const noexcept(see below);
51
#
Mandates:
  • (51.1)
    For the first overload, is_swappable_v<T1> is true and is_swappable_v<T2> is true.
  • (51.2)
    For the second overload, is_swappable_v<const T1> is true and is_swappable_v<const T2> is true.
52
#
Preconditions: first is swappable with ([swappable.requirements]) p.first and second is swappable with p.second.
53
#
Effects: Swaps first with p.first and second with p.second.
54
#
Remarks: The exception specification is equivalent to:
  • (54.1)
    is_nothrow_swappable_v<T1> && is_nothrow_swappable_v<T2> for the first overload, and
  • (54.2)
    is_nothrow_swappable_v<const T1> && is_nothrow_swappable_v<const T2> for the second overload.

22.3.3 Specialized algorithms [pairs.spec]

🔗
template<class T1, class T2, class U1, class U2> constexpr bool operator==(const pair<T1, T2>& x, const pair<U1, U2>& y);
1
#
Constraints: x.first == y.first and x.second == y.second are valid expressions and each of decltype(x.first == y.first) and decltype(x.second == y.second) models boolean-
testable.
2
#
Returns: x.first == y.first && x.second == y.second.
🔗
template<class T1, class T2, class U1, class U2> constexpr common_comparison_category_t<synth-three-way-result<T1, U1>, synth-three-way-result<T2, U2>> operator<=>(const pair<T1, T2>& x, const pair<U1, U2>& y);
3
#
Effects: Equivalent to: if (auto c = synth-three-way(x.first, y.first); c != 0) return c; return synth-three-way(x.second, y.second);
🔗
template<class T1, class T2> constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y))); template<class T1, class T2> constexpr void swap(const pair<T1, T2>& x, const pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));
4
#
Constraints:
  • (4.1)
    For the first overload, is_swappable_v<T1> is true and is_swappable_v<T2> is true.
  • (4.2)
    For the second overload, is_swappable_v<const T1> is true and is_swappable_v<const T2> is true.
5
#
Effects: Equivalent to x.swap(y).
🔗
template<class T1, class T2> constexpr pair<unwrap_ref_decay_t<T1>, unwrap_ref_decay_t<T2>> make_pair(T1&& x, T2&& y);
6
#
Returns: pair<unwrap_ref_decay_t<T1>, unwrap_ref_decay_t<T2>>(std::forward<T1>(x), std::forward<T2>(y))
7
#
[Example 1: 
In place of: return pair<int, double>(5, 3.1415926); // explicit types a C++ program may contain: return make_pair(5, 3.1415926); // types are deduced
— end example]

22.3.4 Tuple-like access to pair [pair.astuple]

🔗
template<class T1, class T2> struct tuple_size<pair<T1, T2>> : integral_constant<size_t, 2> { };
🔗
template<size_t I, class T1, class T2> struct tuple_element<I, pair<T1, T2>> { using type = see below ; };
1
#
Mandates: .
2
#
Type: The type T1 if I is 0, otherwise the type T2.
🔗
template<size_t I, class T1, class T2> constexpr tuple_element_t<I, pair<T1, T2>>& get(pair<T1, T2>& p) noexcept; template<size_t I, class T1, class T2> constexpr const tuple_element_t<I, pair<T1, T2>>& get(const pair<T1, T2>& p) noexcept; template<size_t I, class T1, class T2> constexpr tuple_element_t<I, pair<T1, T2>>&& get(pair<T1, T2>&& p) noexcept; template<size_t I, class T1, class T2> constexpr const tuple_element_t<I, pair<T1, T2>>&& get(const pair<T1, T2>&& p) noexcept;
3
#
Mandates: .
4
#
Returns:
  • (4.1)
    If I is 0, returns a reference to p.first.
  • (4.2)
    If I is 1, returns a reference to p.second.
🔗
template<class T1, class T2> constexpr T1& get(pair<T1, T2>& p) noexcept; template<class T1, class T2> constexpr const T1& get(const pair<T1, T2>& p) noexcept; template<class T1, class T2> constexpr T1&& get(pair<T1, T2>&& p) noexcept; template<class T1, class T2> constexpr const T1&& get(const pair<T1, T2>&& p) noexcept;
5
#
Mandates: T1 and T2 are distinct types.
6
#
Returns: A reference to p.first.
🔗
template<class T2, class T1> constexpr T2& get(pair<T1, T2>& p) noexcept; template<class T2, class T1> constexpr const T2& get(const pair<T1, T2>& p) noexcept; template<class T2, class T1> constexpr T2&& get(pair<T1, T2>&& p) noexcept; template<class T2, class T1> constexpr const T2&& get(const pair<T1, T2>&& p) noexcept;
7
#
Mandates: T1 and T2 are distinct types.
8
#
Returns: A reference to p.second.

22.3.5 Piecewise construction [pair.piecewise]

🔗
struct piecewise_construct_t { explicit piecewise_construct_t() = default; }; inline constexpr piecewise_construct_t piecewise_construct{};
1
#
The struct piecewise_construct_t is an empty class type used as a unique type to disambiguate constructor and function overloading.
Specifically, pair has a constructor with piecewise_construct_t as the first argument, immediately followed by two tuple arguments used for piecewise construction of the elements of the pair object.

22.4 Tuples [tuple]

22.4.1 General [tuple.general]

1
#
Subclause [tuple] describes the tuple library that provides a tuple type as the class template tuple that can be instantiated with any number of arguments.
Each template argument specifies the type of an element in the tuple.
Consequently, tuples are heterogeneous, fixed-size collections of values.
An instantiation of tuple with two arguments is similar to an instantiation of pair with the same two arguments.
2
#
In addition to being available via inclusion of the <tuple> header, ignore ([tuple.syn]) is available when <utility> ([utility]) is included.

22.4.2 Header <tuple> synopsis [tuple.syn]

🔗
// all freestanding #include <compare> // see [compare.syn] namespace std { // [tuple.tuple], class template tuple template<class... Types> class tuple; // [tuple.like], concept tuple-like template<class T> concept tuple-like = see below; // exposition only template<class T> concept pair-like = // exposition only tuple-like<T> && tuple_size_v<remove_cvref_t<T>> == 2; // [tuple.common.ref], common_reference related specializations template<tuple-like TTuple, tuple-like UTuple, template<class> class TQual, template<class> class UQual> struct basic_common_reference<TTuple, UTuple, TQual, UQual>; template<tuple-like TTuple, tuple-like UTuple> struct common_type<TTuple, UTuple>; // ignore struct ignore-type { // exposition only constexpr const ignore-type operator=(const auto &) const noexcept { return *this; } }; inline constexpr ignore-type ignore; // [tuple.creation], tuple creation functions template<class... TTypes> constexpr tuple<unwrap_ref_decay_t<TTypes>...> make_tuple(TTypes&&...); template<class... TTypes> constexpr tuple<TTypes&&...> forward_as_tuple(TTypes&&...) noexcept; template<class... TTypes> constexpr tuple<TTypes&...> tie(TTypes&...) noexcept; template<tuple-like... Tuples> constexpr tuple<CTypes...> tuple_cat(Tuples&&...); // [tuple.apply], calling a function with a tuple of arguments template<class F, tuple-like Tuple> constexpr decltype(auto) apply(F&& f, Tuple&& t) noexcept(see below); template<class T, tuple-like Tuple> constexpr T make_from_tuple(Tuple&& t); // [tuple.helper], tuple helper classes template<class T> struct tuple_size; // not defined template<class T> struct tuple_size<const T>; template<class... Types> struct tuple_size<tuple<Types...>>; template<size_t I, class T> struct tuple_element; // not defined template<size_t I, class T> struct tuple_element<I, const T>; template<size_t I, class... Types> struct tuple_element<I, tuple<Types...>>; template<size_t I, class T> using tuple_element_t = typename tuple_element<I, T>::type; // [tuple.elem], element access template<size_t I, class... Types> constexpr tuple_element_t<I, tuple<Types...>>& get(tuple<Types...>&) noexcept; template<size_t I, class... Types> constexpr tuple_element_t<I, tuple<Types...>>&& get(tuple<Types...>&&) noexcept; template<size_t I, class... Types> constexpr const tuple_element_t<I, tuple<Types...>>& get(const tuple<Types...>&) noexcept; template<size_t I, class... Types> constexpr const tuple_element_t<I, tuple<Types...>>&& get(const tuple<Types...>&&) noexcept; template<class T, class... Types> constexpr T& get(tuple<Types...>& t) noexcept; template<class T, class... Types> constexpr T&& get(tuple<Types...>&& t) noexcept; template<class T, class... Types> constexpr const T& get(const tuple<Types...>& t) noexcept; template<class T, class... Types> constexpr const T&& get(const tuple<Types...>&& t) noexcept; // [tuple.rel], relational operators template<class... TTypes, class... UTypes> constexpr bool operator==(const tuple<TTypes...>&, const tuple<UTypes...>&); template<class... TTypes, tuple-like UTuple> constexpr bool operator==(const tuple<TTypes...>&, const UTuple&); template<class... TTypes, class... UTypes> constexpr common_comparison_category_t<synth-three-way-result<TTypes, UTypes>...> operator<=>(const tuple<TTypes...>&, const tuple<UTypes...>&); template<class... TTypes, tuple-like UTuple> constexpr see below operator<=>(const tuple<TTypes...>&, const UTuple&); // [tuple.traits], allocator-related traits template<class... Types, class Alloc> struct uses_allocator<tuple<Types...>, Alloc>; // [tuple.special], specialized algorithms template<class... Types> constexpr void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(see below); template<class... Types> constexpr void swap(const tuple<Types...>& x, const tuple<Types...>& y) noexcept(see below); // [tuple.helper], tuple helper classes template<class T> constexpr size_t tuple_size_v = tuple_size<T>::value; }

22.4.3 Concept tuple-like [tuple.like]

🔗
template<class T> concept tuple-like = see below; // exposition only
1
#
A type T models and satisfies the exposition-only concept tuple-like if remove_cvref_t<T> is a specialization of array, complex, pair, tuple, or ranges​::​subrange.

22.4.4 Class template tuple [tuple.tuple]

22.4.4.1 General [tuple.tuple.general]

🔗
namespace std { template<class... Types> class tuple { public: // [tuple.cnstr], tuple construction constexpr explicit(see below) tuple(); constexpr explicit(see below) tuple(const Types&...); // only if sizeof...(Types) >= 1 template<class... UTypes> constexpr explicit(see below) tuple(UTypes&&...); // only if sizeof...(Types) >= 1 tuple(const tuple&) = default; tuple(tuple&&) = default; template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>&); template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>&); template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>&&); template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>&&); template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>&); // only if sizeof...(Types) == 2 template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>&); // only if sizeof...(Types) == 2 template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>&&); // only if sizeof...(Types) == 2 template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>&&); // only if sizeof...(Types) == 2 template<tuple-like UTuple> constexpr explicit(see below) tuple(UTuple&&); // allocator-extended constructors template<class Alloc> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a); template<class Alloc> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const Types&...); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, UTypes&&...); template<class Alloc> constexpr tuple(allocator_arg_t, const Alloc& a, const tuple&); template<class Alloc> constexpr tuple(allocator_arg_t, const Alloc& a, tuple&&); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&&); template<class Alloc, tuple-like UTuple> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, UTuple&&); // [tuple.assign], tuple assignment constexpr tuple& operator=(const tuple&); constexpr const tuple& operator=(const tuple&) const; constexpr tuple& operator=(tuple&&) noexcept(see below); constexpr const tuple& operator=(tuple&&) const; template<class... UTypes> constexpr tuple& operator=(const tuple<UTypes...>&); template<class... UTypes> constexpr const tuple& operator=(const tuple<UTypes...>&) const; template<class... UTypes> constexpr tuple& operator=(tuple<UTypes...>&&); template<class... UTypes> constexpr const tuple& operator=(tuple<UTypes...>&&) const; template<class U1, class U2> constexpr tuple& operator=(const pair<U1, U2>&); // only if sizeof...(Types) == 2 template<class U1, class U2> constexpr const tuple& operator=(const pair<U1, U2>&) const; // only if sizeof...(Types) == 2 template<class U1, class U2> constexpr tuple& operator=(pair<U1, U2>&&); // only if sizeof...(Types) == 2 template<class U1, class U2> constexpr const tuple& operator=(pair<U1, U2>&&) const; // only if sizeof...(Types) == 2 template<tuple-like UTuple> constexpr tuple& operator=(UTuple&&); template<tuple-like UTuple> constexpr const tuple& operator=(UTuple&&) const; // [tuple.swap], tuple swap constexpr void swap(tuple&) noexcept(see below); constexpr void swap(const tuple&) const noexcept(see below); }; template<class... UTypes> tuple(UTypes...) -> tuple<UTypes...>; template<class T1, class T2> tuple(pair<T1, T2>) -> tuple<T1, T2>; template<class Alloc, class... UTypes> tuple(allocator_arg_t, Alloc, UTypes...) -> tuple<UTypes...>; template<class Alloc, class T1, class T2> tuple(allocator_arg_t, Alloc, pair<T1, T2>) -> tuple<T1, T2>; template<class Alloc, class... UTypes> tuple(allocator_arg_t, Alloc, tuple<UTypes...>) -> tuple<UTypes...>; }
1
#
If a program declares an explicit or partial specialization of tuple, the program is ill-formed, no diagnostic required.

22.4.4.2 Construction [tuple.cnstr]

1
#
In the descriptions that follow, let i be in the range [0, sizeof...(Types)) in order, be the type in Types, and be the type in a template parameter pack named UTypes, where indexing is zero-based.
2
#
For each tuple constructor, an exception is thrown only if the construction of one of the types in Types throws an exception.
3
#
The defaulted move and copy constructor, respectively, of tuple is a constexpr function if and only if all required element-wise initializations for move and copy, respectively, would be constexpr-suitable ([dcl.constexpr]).
The defaulted move and copy constructor of tuple<> are constexpr functions.
4
#
If is_trivially_destructible_v<> is true for all , then the destructor of tuple is trivial.
5
#
The default constructor of tuple<> is trivial.
🔗
constexpr explicit(see below) tuple();
6
#
Constraints: is_default_constructible_v<> is true for all i.
7
#
Effects: Value-initializes each element.
8
#
Remarks: The expression inside explicit evaluates to true if and only if is not copy-list-initializable from an empty list for at least one i.
[Note 1: 
This behavior can be implemented with a trait that checks whether a const & can be initialized with {}.
— end note]
🔗
constexpr explicit(see below) tuple(const Types&...);
9
#
Constraints: sizeof...(Types)  ≥ 1 and is_copy_constructible_v<> is true for all i.
10
#
Effects: Initializes each element with the value of the corresponding parameter.
11
#
Remarks: The expression inside explicit is equivalent to: !conjunction_v<is_convertible<const Types&, Types>...>
🔗
template<class... UTypes> constexpr explicit(see below) tuple(UTypes&&... u);
12
#
Let disambiguating-constraint be:
  • (12.1)
    negation<is_same<remove_cvref_t<>, tuple>> if sizeof...(Types) is 1;
  • (12.2)
    otherwise, bool_constant<!is_same_v<remove_cvref_t<>, allocator_arg_t> || is_-
    same_v<remove_cvref_t<>, allocator_arg_t>>     if sizeof...(Types) is 2 or 3;
  • (12.3)
    otherwise, true_type.
13
#
Constraints:
  • (13.1)
    sizeof...(Types) equals sizeof...(UTypes),
  • (13.2)
    sizeof...(Types)  ≥ 1, and
  • (13.3)
    conjunction_v<disambiguating-constraint, is_constructible<Types, UTypes>...> is
    true.
14
#
Effects: Initializes the elements in the tuple with the corresponding value in std​::​forward<UTypes>(u).
15
#
Remarks: The expression inside explicit is equivalent to: !conjunction_v<is_convertible<UTypes, Types>...>
This constructor is defined as deleted if (reference_constructs_from_temporary_v<Types, UTypes&&> || ...) is true.
🔗
tuple(const tuple& u) = default;
16
#
Mandates: is_copy_constructible_v<> is true for all i.
17
#
Effects: Initializes each element of *this with the corresponding element of u.
🔗
tuple(tuple&& u) = default;
18
#
Constraints: is_move_constructible_v<> is true for all i.
19
#
Effects: For all i, initializes the element of *this with std​::​forward<>(get<i>(u)).
🔗
template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>& u); template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>& u); template<class... UTypes> constexpr explicit(see below) tuple(tuple<UTypes...>&& u); template<class... UTypes> constexpr explicit(see below) tuple(const tuple<UTypes...>&& u);
20
#
Let I be the pack 0, 1, ..., (sizeof...(Types) - 1).

Let FWD(u) be static_cast<decltype(u)>(u).
21
#
Constraints:
  • (21.1)
    sizeof...(Types) equals sizeof...(UTypes), and
  • (21.2)
    (is_constructible_v<Types, decltype(get<I>(FWD(u)))> && ...) is true, and
  • (21.3)
    either sizeof...(Types) is not 1, or (when Types... expands to T and UTypes... expands to U) is_convertible_v<decltype(u), T>, is_constructible_v<T, decltype(u)>, and is_same_v<T, U> are all false.
22
#
Effects: For all i, initializes the element of *this with get<i>(FWD(u)).
23
#
Remarks: The expression inside explicit is equivalent to: !(is_convertible_v<decltype(get<I>(FWD(u))), Types> && ...)
The constructor is defined as deleted if (reference_constructs_from_temporary_v<Types, decltype(get<I>(FWD(u)))> || ...) is true.
🔗
template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>& u); template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>& u); template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>&& u); template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>&& u);
24
#
Let FWD(u) be static_cast<decltype(u)>(u).
25
#
Constraints:
  • (25.1)
    sizeof...(Types) is 2,
  • (25.2)
    is_constructible_v<, decltype(get<0>(FWD(u)))> is true, and
  • (25.3)
    is_constructible_v<, decltype(get<1>(FWD(u)))> is true.
26
#
Effects: Initializes the first element with get<0>(FWD(u)) and the second element with get<1>(FWD(​u)).
27
#
Remarks: The expression inside explicit is equivalent to: !is_convertible_v<decltype(get<0>(FWD(u))), > || !is_convertible_v<decltype(get<1>(FWD(u))), >
The constructor is defined as deleted if reference_constructs_from_temporary_v<, decltype(get<0>(FWD(u)))> || reference_constructs_from_temporary_v<, decltype(get<1>(FWD(u)))> is true.
🔗
template<tuple-like UTuple> constexpr explicit(see below) tuple(UTuple&& u);
28
#
Let I be the pack 0, 1, …, (sizeof...(Types) - 1).
29
#
Constraints:
  • (29.1)
    different-from<UTuple, tuple> ([range.utility.helpers]) is true,
  • (29.2)
    remove_cvref_t<UTuple> is not a specialization of ranges​::​subrange,
  • (29.3)
    sizeof...(Types) equals tuple_size_v<remove_cvref_t<UTuple>>,
  • (29.4)
    (is_constructible_v<Types, decltype(get<I>(std​::​forward<UTuple>(u)))> && ...) is true, and
  • (29.5)
    either sizeof...(Types) is not 1, or (when Types... expands to T) is_convertible_v<UTuple, T> and is_constructible_v<T, UTuple> are both false.
30
#
Effects: For all i, initializes the element of *this with get<i>(std​::​forward<UTuple>(u)).
31
#
Remarks: The expression inside explicit is equivalent to: !(is_convertible_v<decltype(get<I>(std::forward<UTuple>(u))), Types> && ...)
The constructor is defined as deleted if (reference_constructs_from_temporary_v<Types, decltype(get<I>(std::forward<UTuple>(u)))> || ...) is true.
🔗
template<class Alloc> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a); template<class Alloc> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const Types&...); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, UTypes&&...); template<class Alloc> constexpr tuple(allocator_arg_t, const Alloc& a, const tuple&); template<class Alloc> constexpr tuple(allocator_arg_t, const Alloc& a, tuple&&); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&); template<class Alloc, class... UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&&); template<class Alloc, tuple-like UTuple> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, UTuple&&);
32
#
Preconditions: Alloc meets the Cpp17Allocator requirements ([allocator.requirements.general]).
33
#
Effects: Equivalent to the preceding constructors except that each element is constructed with uses-allocator construction.

22.4.4.3 Assignment [tuple.assign]

1
#
For each tuple assignment operator, an exception is thrown only if the assignment of one of the types in Types throws an exception.
In the function descriptions that follow, let i be in the range [0, sizeof...​(Types)) in order, be the type in Types, and be the type in a template parameter pack named UTypes, where indexing is zero-based.
🔗
constexpr tuple& operator=(const tuple& u);
2
#
Effects: Assigns each element of u to the corresponding element of *this.
3
#
Returns: *this.
4
#
Remarks: This operator is defined as deleted unless is_copy_assignable_v<> is true for all i.
🔗
constexpr const tuple& operator=(const tuple& u) const;
5
#
Constraints: (is_copy_assignable_v<const Types> && ...) is true.
6
#
Effects: Assigns each element of u to the corresponding element of *this.
7
#
Returns: *this.
🔗
constexpr tuple& operator=(tuple&& u) noexcept(see below);
8
#
Constraints: is_move_assignable_v<> is true for all i.
9
#
Effects: For all i, assigns std​::​forward<>(get<i>(u)) to get<i>(*this).
10
#
Returns: *this.
11
#
Remarks: The exception specification is equivalent to the logical and of the following expressions: is_nothrow_move_assignable_v<> where is the type in Types.
🔗
constexpr const tuple& operator=(tuple&& u) const;
12
#
Constraints: (is_assignable_v<const Types&, Types> && ...) is true.
13
#
Effects: For all i, assigns std​::​forward<T>(get<i>(u)) to get<i>(*this).
14
#
Returns: *this.
🔗
template<class... UTypes> constexpr tuple& operator=(const tuple<UTypes...>& u);
15
#
Constraints:
  • (15.1)
    sizeof...(Types) equals sizeof...(UTypes) and
  • (15.2)
    is_assignable_v<&, const &> is true for all i.
16
#
Effects: Assigns each element of u to the corresponding element of *this.
17
#
Returns: *this.
🔗
template<class... UTypes> constexpr const tuple& operator=(const tuple<UTypes...>& u) const;
18
#
Constraints:
  • (18.1)
    sizeof...(Types) equals sizeof...(UTypes) and
  • (18.2)
    (is_assignable_v<const Types&, const UTypes&> && ...) is true.
19
#
Effects: Assigns each element of u to the corresponding element of *this.
20
#
Returns: *this.
🔗
template<class... UTypes> constexpr tuple& operator=(tuple<UTypes...>&& u);
21
#
Constraints:
  • (21.1)
    sizeof...(Types) equals sizeof...(UTypes) and
  • (21.2)
    is_assignable_v<&, > is true for all i.
22
#
Effects: For all i, assigns std​::​forward<>(get<i>(u)) to get<i>(*this).
23
#
Returns: *this.
🔗
template<class... UTypes> constexpr const tuple& operator=(tuple<UTypes...>&& u) const;
24
#
Constraints:
  • (24.1)
    sizeof...(Types) equals sizeof...(UTypes) and
  • (24.2)
    (is_assignable_v<const Types&, UTypes> && ...) is true.
25
#
Effects: For all i, assigns std​::​forward<U>(get<i>(u)) to get<i>(*this).
26
#
Returns: *this.
🔗
template<class U1, class U2> constexpr tuple& operator=(const pair<U1, U2>& u);
27
#
Constraints:
  • (27.1)
    sizeof...(Types) is 2 and
  • (27.2)
    is_assignable_v<&, const U1&> is true, and
  • (27.3)
    is_assignable_v<&, const U2&> is true.
28
#
Effects: Assigns u.first to the first element of *this and u.second to the second element of *this.
29
#
Returns: *this.
🔗
template<class U1, class U2> constexpr const tuple& operator=(const pair<U1, U2>& u) const;
30
#
Constraints:
  • (30.1)
    sizeof...(Types) is 2,
  • (30.2)
    is_assignable_v<const &, const U1&> is true, and
  • (30.3)
    is_assignable_v<const &, const U2&> is true.
31
#
Effects: Assigns u.first to the first element and u.second to the second element.
32
#
Returns: *this.
🔗
template<class U1, class U2> constexpr tuple& operator=(pair<U1, U2>&& u);
33
#
Constraints:
  • (33.1)
    sizeof...(Types) is 2 and
  • (33.2)
    is_assignable_v<&, U1> is true, and
  • (33.3)
    is_assignable_v<&, U2> is true.
34
#
Effects: Assigns std​::​forward<U1>(u.first) to the first element of *this and
std​::​forward<U2>(u.second) to the second element of *this.
35
#
Returns: *this.
🔗
template<class U1, class U2> constexpr const tuple& operator=(pair<U1, U2>&& u) const;
36
#
Constraints:
  • (36.1)
    sizeof...(Types) is 2,
  • (36.2)
    is_assignable_v<const &, U1> is true, and
  • (36.3)
    is_assignable_v<const &, U2> is true.
37
#
Effects: Assigns std​::​forward<U1>(u.first) to the first element and
std​::​forward<U2>(u.second) to the second element.
38
#
Returns: *this.
🔗
template<tuple-like UTuple> constexpr tuple& operator=(UTuple&& u);
39
#
Constraints:
  • (39.1)
    different-from<UTuple, tuple> ([range.utility.helpers]) is true,
  • (39.2)
    remove_cvref_t<UTuple> is not a specialization of ranges​::​subrange,
  • (39.3)
    sizeof...(Types) equals tuple_size_v<remove_cvref_t<UTuple>>, and,
  • (39.4)
    is_assignable_v<&, decltype(get<i>(std​::​forward<UTuple>(u)))> is true for all i.
40
#
Effects: For all i, assigns get<i>(std​::​forward<UTuple>(u)) to get<i>(*this).
41
#
Returns: *this.
🔗
template<tuple-like UTuple> constexpr const tuple& operator=(UTuple&& u) const;
42
#
Constraints:
  • (42.1)
    different-from<UTuple, tuple> ([range.utility.helpers]) is true,
  • (42.2)
    remove_cvref_t<UTuple> is not a specialization of ranges​::​subrange,
  • (42.3)
    sizeof...(Types) equals tuple_size_v<remove_cvref_t<UTuple>>, and,
  • (42.4)
    is_assignable_v<const &, decltype(get<i>(std​::​forward<UTuple>(u)))> is true for all i.
43
#
Effects: For all i, assigns get<i>(std​::​forward<UTuple>(u)) to get<i>(*this).
44
#
Returns: *this.

22.4.4.4 swap [tuple.swap]

🔗
constexpr void swap(tuple& rhs) noexcept(see below); constexpr void swap(const tuple& rhs) const noexcept(see below);
1
#
Let i be in the range [0, sizeof...(Types)) in order.
2
#
Mandates:
  • (2.1)
    For the first overload, (is_swappable_v<Types> && ...) is true.
  • (2.2)
    For the second overload, (is_swappable_v<const Types> && ...) is true.
3
#
Preconditions: For all i, get<i>(*this) is swappable with ([swappable.requirements]) get<i>(rhs).
4
#
Effects: For each i, calls swap for get<i>(*this) and get<i>(rhs).
5
#
Throws: Nothing unless one of the element-wise swap calls throws an exception.
6
#
Remarks: The exception specification is equivalent to
  • (6.1)
    (is_nothrow_swappable_v<Types> && ...) for the first overload and
  • (6.2)
    (is_nothrow_swappable_v<const Types> && ...) for the second overload.

22.4.5 Tuple creation functions [tuple.creation]

🔗
template<class... TTypes> constexpr tuple<unwrap_ref_decay_t<TTypes>...> make_tuple(TTypes&&... t);
1
#
Returns: tuple<unwrap_ref_decay_t<TTypes>...>(std​::​forward<TTypes>(t)...).
2
#
[Example 1: 
int i; float j; make_tuple(1, ref(i), cref(j)); creates a tuple of type tuple<int, int&, const float&>.
— end example]
🔗
template<class... TTypes> constexpr tuple<TTypes&&...> forward_as_tuple(TTypes&&... t) noexcept;
3
#
Effects: Constructs a tuple of references to the arguments in t suitable for forwarding as arguments to a function.
Because the result may contain references to temporary objects, a program shall ensure that the return value of this function does not outlive any of its arguments (e.g., the program should typically not store the result in a named variable).
4
#
Returns: tuple<TTypes&&...>(std​::​forward<TTypes>(t)...).
🔗
template<class... TTypes> constexpr tuple<TTypes&...> tie(TTypes&... t) noexcept;
5
#
Returns: tuple<TTypes&...>(t...).
6
#
[Example 2: 
tie functions allow one to create tuples that unpack tuples into variables.
ignore can be used for elements that are not needed: int i; std::string s; tie(i, ignore, s) = make_tuple(42, 3.14, "C++"); // i == 42, s == "C++"
— end example]
🔗
template<tuple-like... Tuples> constexpr tuple<CTypes...> tuple_cat(Tuples&&... tpls);
7
#
Let n be sizeof...(Tuples).
For every integer :
  • (7.1)
    Let be the type in Tuples.
  • (7.2)
    Let be remove_cvref_t<>.
  • (7.3)
    Let be the element in the function parameter pack tpls.
  • (7.4)
    Let be tuple_size_v<>.
  • (7.5)
    Let be tuple_element_t<k, >.
  • (7.6)
    Let be get<k>(std​::​forward<>()).
  • (7.7)
    Let be a pack of the types .
  • (7.8)
    Let be a pack of the expressions .
The types in CTypes are equal to the ordered sequence of the expanded packs of types ..., ..., …, ....
Let celems be the ordered sequence of the expanded packs of expressions ..., …, ....
8
#
Mandates: (is_constructible_v<CTypes, decltype(celems)> && ...) is true.
9
#
Returns: tuple<CTypes...>(celems...).

22.4.6 Calling a function with a tuple of arguments [tuple.apply]

🔗
template<class F, tuple-like Tuple> constexpr decltype(auto) apply(F&& f, Tuple&& t) noexcept(see below);
1
#
Effects: Given the exposition-only function template: namespace std { template<class F, tuple-like Tuple, size_t... I> constexpr decltype(auto) apply-impl(F&& f, Tuple&& t, index_sequence<I...>) { // exposition only return INVOKE(std::forward<F>(f), get<I>(std::forward<Tuple>(t))...); // see [func.require] } }
Equivalent to: return apply-impl(std::forward<F>(f), std::forward<Tuple>(t), make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
2
#
Remarks: Let I be the pack 0, 1, ..., (tuple_size_v<remove_reference_t<Tuple>> - 1).
The exception specification is equivalent to: noexcept(invoke(std::forward<F>(f), get<I>(std::forward<Tuple>(t))...))
🔗
template<class T, tuple-like Tuple> constexpr T make_from_tuple(Tuple&& t);
3
#
Mandates: If tuple_size_v<remove_reference_t<Tuple>> is 1, then reference_constructs_from_temporary_v<T, decltype(get<0>(declval<Tuple>()))> is false.
4
#
Effects: Given the exposition-only function template: namespace std { template<class T, tuple-like Tuple, size_t... I> requires is_constructible_v<T, decltype(get<I>(declval<Tuple>()))...> constexpr T make-from-tuple-impl(Tuple&& t, index_sequence<I...>) { // exposition only return T(get<I>(std::forward<Tuple>(t))...); } }
Equivalent to: return make-from-tuple-impl<T>( std::forward<Tuple>(t), make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
[Note 1: 
The type of T must be supplied as an explicit template parameter, as it cannot be deduced from the argument list.
— end note]

22.4.7 Tuple helper classes [tuple.helper]

🔗
template<class T> struct tuple_size;
1
#
Except where specified otherwise, all specializations of tuple_size meet the Cpp17UnaryTypeTrait requirements ([meta.rqmts]) with a base characteristic of integral_constant<size_t, N> for some N.
🔗
template<class... Types> struct tuple_size<tuple<Types...>> : public integral_constant<size_t, sizeof...(Types)> { };
🔗
template<size_t I, class... Types> struct tuple_element<I, tuple<Types...>> { using type = TI; };
2
#
Mandates: I < sizeof...(Types).
3
#
Type: TI is the type of the element of Types, where indexing is zero-based.
🔗
template<class T> struct tuple_size<const T>;
4
#
Let TS denote tuple_size<T> of the cv-unqualified type T.
If the expression TS​::​value is well-formed when treated as an unevaluated operand, then each specialization of the template meets the Cpp17UnaryTypeTrait requirements ([meta.rqmts]) with a base characteristic of integral_constant<size_t, TS::value>
Otherwise, it has no member value.
5
#
Access checking is performed as if in a context unrelated to TS and T.
Only the validity of the immediate context of the expression is considered.
[Note 1: 
The compilation of the expression can result in side effects such as the instantiation of class template specializations and function template specializations, the generation of implicitly-defined functions, and so on.
Such side effects are not in the “immediate context” and can result in the program being ill-formed.
— end note]
6
#
In addition to being available via inclusion of the <tuple> header, the template is available when any of the headers <array>, <ranges>, or <utility> are included.
🔗
template<size_t I, class T> struct tuple_element<I, const T>;
7
#
Let TE denote tuple_element_t<I, T> of the cv-unqualified type T.
Then each specialization of the template meets the Cpp17TransformationTrait requirements ([meta.rqmts]) with a member typedef type that names the type add_const_t<TE>.
8
#
In addition to being available via inclusion of the <tuple> header, the template is available when any of the headers <array>, <ranges>, or <utility> are included.

22.4.8 Element access [tuple.elem]

🔗
template<size_t I, class... Types> constexpr tuple_element_t<I, tuple<Types...>>& get(tuple<Types...>& t) noexcept; template<size_t I, class... Types> constexpr tuple_element_t<I, tuple<Types...>>&& get(tuple<Types...>&& t) noexcept; // #1 template<size_t I, class... Types> constexpr const tuple_element_t<I, tuple<Types...>>& get(const tuple<Types...>& t) noexcept; // #2 template<size_t I, class... Types> constexpr const tuple_element_t<I, tuple<Types...>>&& get(const tuple<Types...>&& t) noexcept;
1
#
Mandates: I < sizeof...(Types).
2
#
Returns: A reference to the element of t, where indexing is zero-based.
3
#
[Note 1: 
For the overload marked #1, if a type T in Types is some reference type X&, the return type is X&, not X&&.
However, if the element type is a non-reference type T, the return type is T&&.
— end note]
4
#
[Note 2: 
Constness is shallow.
For the overload marked #2, if a type T in Types is some reference type X&, the return type is X&, not const X&.
However, if the element type is a non-reference type T, the return type is const T&.
This is consistent with how constness is defined to work for non-static data members of reference type.
— end note]
🔗
template<class T, class... Types> constexpr T& get(tuple<Types...>& t) noexcept; template<class T, class... Types> constexpr T&& get(tuple<Types...>&& t) noexcept; template<class T, class... Types> constexpr const T& get(const tuple<Types...>& t) noexcept; template<class T, class... Types> constexpr const T&& get(const tuple<Types...>&& t) noexcept;
5
#
Mandates: The type T occurs exactly once in Types.
6
#
Returns: A reference to the element of t corresponding to the type T in Types.
7
#
[Example 1: const tuple<int, const int, double, double> t(1, 2, 3.4, 5.6); const int& i1 = get<int>(t); // OK, i1 has value 1 const int& i2 = get<const int>(t); // OK, i2 has value 2 const double& d = get<double>(t); // error: type double is not unique within t — end example]
8
#
[Note 3: 
The reason get is a non-member function is that if this functionality had been provided as a member function, code where the type depended on a template parameter would have required using the template keyword.
— end note]

22.4.9 Relational operators [tuple.rel]

🔗
template<class... TTypes, class... UTypes> constexpr bool operator==(const tuple<TTypes...>& t, const tuple<UTypes...>& u); template<class... TTypes, tuple-like UTuple> constexpr bool operator==(const tuple<TTypes...>& t, const UTuple& u);
1
#
For the first overload let UTuple be tuple<UTypes...>.
2
#
Constraints: For all i, where 0  ≤ i < sizeof...(TTypes), get<i>(t) == get<i>(u) is a valid expression and decltype(get<i>(t) == get<i>(u)) models boolean-testable.
sizeof...(TTypes) equals tuple_size_v<UTuple>.
3
#
Returns: true if get<i>(t) == get<i>(u) for all i, otherwise false.
[Note 1: 
If sizeof...(TTypes) equals zero, returns true.
— end note]
4
#
Remarks:
  • (4.1)
    The elementary comparisons are performed in order from the zeroth index upwards.
    No comparisons or element accesses are performed after the first equality comparison that evaluates to false.
  • (4.2)
    The second overload is to be found via argument-dependent lookup ([basic.lookup.argdep]) only.
🔗
template<class... TTypes, class... UTypes> constexpr common_comparison_category_t<synth-three-way-result<TTypes, UTypes>...> operator<=>(const tuple<TTypes...>& t, const tuple<UTypes...>& u); template<class... TTypes, tuple-like UTuple> constexpr common_comparison_category_t<synth-three-way-result<TTypes, Elems>...> operator<=>(const tuple<TTypes...>& t, const UTuple& u);
5
#
For the second overload, Elems denotes the pack of types tuple_element_t<0, UTuple>, tuple_element_t<1, UTuple>, …, tuple_element_t<tuple_size_v<UTuple> - 1, UTuple>.
6
#
Effects: Performs a lexicographical comparison between t and u.
If sizeof...(TTypes) equals zero, returns strong_ordering​::​equal.
Otherwise, equivalent to: if (auto c = synth-three-way(get<0>(t), get<0>(u)); c != 0) return c; return <=> ; where for some r is a tuple containing all but the first element of r.
7
#
Remarks: The second overload is to be found via argument-dependent lookup ([basic.lookup.argdep]) only.
8
#
[Note 2: 
The above definition does not require t (or u) to be constructed.
It might not even be possible, as t and u are not required to be copy constructible.
Also, all comparison operator functions are short circuited; they do not perform element accesses beyond what is needed to determine the result of the comparison.
— end note]

22.4.10 common_reference related specializations [tuple.common.ref]

1
#
In the descriptions that follow:
  • (1.1)
    Let TTypes be a pack formed by the sequence of tuple_element_t<i, TTuple> for every integer .
  • (1.2)
    Let UTypes be a pack formed by the sequence of tuple_element_t<i, UTuple> for every integer .
🔗
template<tuple-like TTuple, tuple-like UTuple, template<class> class TQual, template<class> class UQual> struct basic_common_reference<TTuple, UTuple, TQual, UQual> { using type = see below; };
2
#
Constraints:
  • (2.1)
    TTuple is a specialization of tuple or UTuple is a specialization of tuple.
  • (2.2)
    is_same_v<TTuple, decay_t<TTuple>> is true.
  • (2.3)
    is_same_v<UTuple, decay_t<UTuple>> is true.
  • (2.4)
    tuple_size_v<TTuple> equals tuple_size_v<UTuple>.
  • (2.5)
    tuple<common_reference_t<TQual<TTypes>, UQual<UTypes>>...> denotes a type.
The member typedef-name type denotes the type tuple<common_reference_t<TQual<TTypes>, UQual<UTypes>>...>.
🔗
template<tuple-like TTuple, tuple-like UTuple> struct common_type<TTuple, UTuple> { using type = see below; };
3
#
Constraints:
  • (3.1)
    TTuple is a specialization of tuple or UTuple is a specialization of tuple.
  • (3.2)
    is_same_v<TTuple, decay_t<TTuple>> is true.
  • (3.3)
    is_same_v<UTuple, decay_t<UTuple>> is true.
  • (3.4)
    tuple_size_v<TTuple> equals tuple_size_v<UTuple>.
  • (3.5)
    tuple<common_type_t<TTypes, UTypes>...> denotes a type.
The member typedef-name type denotes the type tuple<common_type_t<TTypes, UTypes>...>.

22.4.11 Tuple traits [tuple.traits]

🔗
template<class... Types, class Alloc> struct uses_allocator<tuple<Types...>, Alloc> : true_type { };
1
#
Preconditions: Alloc meets the Cpp17Allocator requirements ([allocator.requirements.general]).
2
#
[Note 1: 
Specialization of this trait informs other library components that tuple can be constructed with an allocator, even though it does not have a nested allocator_type.
— end note]

22.4.12 Tuple specialized algorithms [tuple.special]

🔗
template<class... Types> constexpr void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(see below); template<class... Types> constexpr void swap(const tuple<Types...>& x, const tuple<Types...>& y) noexcept(see below);
1
#
Constraints:
  • (1.1)
    For the first overload, (is_swappable_v<Types> && ...) is true.
  • (1.2)
    For the second overload, (is_swappable_v<const Types> && ...) is true.
2
#
Effects: As if by x.swap(y).
3
#
Remarks: The exception specification is equivalent to: noexcept(x.swap(y))

22.5 Optional objects [optional]

22.5.1 General [optional.general]

1
#
Subclause [optional] describes class template optional that represents optional objects.
An optional object is an object that contains the storage for another object and manages the lifetime of this contained object, if any.
The contained object may be initialized after the optional object has been initialized, and may be destroyed before the optional object has been destroyed.
The initialization state of the contained object is tracked by the optional object.

22.5.2 Header <optional> synopsis [optional.syn]

🔗
// mostly freestanding #include <compare> // see [compare.syn] namespace std { // [optional.optional], class template optional template<class T> class optional; // partially freestanding template<class T> constexpr bool ranges::enable_view<optional<T>> = true; template<class T> constexpr auto format_kind<optional<T>> = range_format::disabled; template<class T> concept is-derived-from-optional = requires(const T& t) { // exposition only []<class U>(const optional<U>&){ }(t); }; // [optional.nullopt], no-value state indicator struct nullopt_t{see below}; inline constexpr nullopt_t nullopt(unspecified); // [optional.bad.access], class bad_optional_access class bad_optional_access; // [optional.relops], relational operators template<class T, class U> constexpr bool operator==(const optional<T>&, const optional<U>&); template<class T, class U> constexpr bool operator!=(const optional<T>&, const optional<U>&); template<class T, class U> constexpr bool operator<(const optional<T>&, const optional<U>&); template<class T, class U> constexpr bool operator>(const optional<T>&, const optional<U>&); template<class T, class U> constexpr bool operator<=(const optional<T>&, const optional<U>&); template<class T, class U> constexpr bool operator>=(const optional<T>&, const optional<U>&); template<class T, three_way_comparable_with<T> U> constexpr compare_three_way_result_t<T, U> operator<=>(const optional<T>&, const optional<U>&); // [optional.nullops], comparison with nullopt template<class T> constexpr bool operator==(const optional<T>&, nullopt_t) noexcept; template<class T> constexpr strong_ordering operator<=>(const optional<T>&, nullopt_t) noexcept; // [optional.comp.with.t], comparison with T template<class T, class U> constexpr bool operator==(const optional<T>&, const U&); template<class T, class U> constexpr bool operator==(const T&, const optional<U>&); template<class T, class U> constexpr bool operator!=(const optional<T>&, const U&); template<class T, class U> constexpr bool operator!=(const T&, const optional<U>&); template<class T, class U> constexpr bool operator<(const optional<T>&, const U&); template<class T, class U> constexpr bool operator<(const T&, const optional<U>&); template<class T, class U> constexpr bool operator>(const optional<T>&, const U&); template<class T, class U> constexpr bool operator>(const T&, const optional<U>&); template<class T, class U> constexpr bool operator<=(const optional<T>&, const U&); template<class T, class U> constexpr bool operator<=(const T&, const optional<U>&); template<class T, class U> constexpr bool operator>=(const optional<T>&, const U&); template<class T, class U> constexpr bool operator>=(const T&, const optional<U>&); template<class T, class U> requires (!is-derived-from-optional<U>) && three_way_comparable_with<T, U> constexpr compare_three_way_result_t<T, U> operator<=>(const optional<T>&, const U&); // [optional.specalg], specialized algorithms template<class T> constexpr void swap(optional<T>&, optional<T>&) noexcept(see below); template<class T> constexpr optional<decay_t<T>> make_optional(T&&); template<class T, class... Args> constexpr optional<T> make_optional(Args&&... args); template<class T, class U, class... Args> constexpr optional<T> make_optional(initializer_list<U> il, Args&&... args); // [optional.hash], hash support template<class T> struct hash; template<class T> struct hash<optional<T>>; }

22.5.3 Class template optional [optional.optional]

22.5.3.1 General [optional.optional.general]

🔗
namespace std { template<class T> class optional { public: using value_type = T; using iterator = implementation-defined; // see [optional.iterators] using const_iterator = implementation-defined; // see [optional.iterators] // [optional.ctor], constructors constexpr optional() noexcept; constexpr optional(nullopt_t) noexcept; constexpr optional(const optional&); constexpr optional(optional&&) noexcept(see below); template<class... Args> constexpr explicit optional(in_place_t, Args&&...); template<class U, class... Args> constexpr explicit optional(in_place_t, initializer_list<U>, Args&&...); template<class U = T> constexpr explicit(see below) optional(U&&); template<class U> constexpr explicit(see below) optional(const optional<U>&); template<class U> constexpr explicit(see below) optional(optional<U>&&); // [optional.dtor], destructor constexpr ~optional(); // [optional.assign], assignment constexpr optional& operator=(nullopt_t) noexcept; constexpr optional& operator=(const optional&); constexpr optional& operator=(optional&&) noexcept(see below); template<class U = T> constexpr optional& operator=(U&&); template<class U> constexpr optional& operator=(const optional<U>&); template<class U> constexpr optional& operator=(optional<U>&&); template<class... Args> constexpr T& emplace(Args&&...); template<class U, class... Args> constexpr T& emplace(initializer_list<U>, Args&&...); // [optional.swap], swap constexpr void swap(optional&) noexcept(see below); // [optional.iterators], iterator support constexpr iterator begin() noexcept; constexpr const_iterator begin() const noexcept; constexpr iterator end() noexcept; constexpr const_iterator end() const noexcept; // [optional.observe], observers constexpr const T* operator->() const noexcept; constexpr T* operator->() noexcept; constexpr const T& operator*() const & noexcept; constexpr T& operator*() & noexcept; constexpr T&& operator*() && noexcept; constexpr const T&& operator*() const && noexcept; constexpr explicit operator bool() const noexcept; constexpr bool has_value() const noexcept; constexpr const T& value() const &; // freestanding-deleted constexpr T& value() &; // freestanding-deleted constexpr T&& value() &&; // freestanding-deleted constexpr const T&& value() const &&; // freestanding-deleted template<class U> constexpr T value_or(U&&) const &; template<class U> constexpr T value_or(U&&) &&; // [optional.monadic], monadic operations template<class F> constexpr auto and_then(F&& f) &; template<class F> constexpr auto and_then(F&& f) &&; template<class F> constexpr auto and_then(F&& f) const &; template<class F> constexpr auto and_then(F&& f) const &&; template<class F> constexpr auto transform(F&& f) &; template<class F> constexpr auto transform(F&& f) &&; template<class F> constexpr auto transform(F&& f) const &; template<class F> constexpr auto transform(F&& f) const &&; template<class F> constexpr optional or_else(F&& f) &&; template<class F> constexpr optional or_else(F&& f) const &; // [optional.mod], modifiers constexpr void reset() noexcept; private: T* val; // exposition only }; template<class T> optional(T) -> optional<T>; }
1
#
Any instance of optional<T> at any given time either contains a value or does not contain a value.
When an instance of optional<T> contains a value, it means that an object of type T, referred to as the optional object's contained value, is allocated within the storage of the optional object.
Implementations are not permitted to use additional storage, such as dynamic memory, to allocate its contained value.
When an object of type optional<T> is contextually converted to bool, the conversion returns true if the object contains a value; otherwise the conversion returns false.
2
#
When an optional<T> object contains a value, member val points to the contained value.
3
#
T shall be a type other than cv in_place_t or cv nullopt_t that meets the Cpp17Destructible requirements (Table 35).

22.5.3.2 Constructors [optional.ctor]

1
#
The exposition-only variable template converts-from-any-cvref is used by some constructors for optional.
template<class T, class W> constexpr bool converts-from-any-cvref = // exposition only disjunction_v<is_constructible<T, W&>, is_convertible<W&, T>, is_constructible<T, W>, is_convertible<W, T>, is_constructible<T, const W&>, is_convertible<const W&, T>, is_constructible<T, const W>, is_convertible<const W, T>>;
🔗
constexpr optional() noexcept; constexpr optional(nullopt_t) noexcept;
2
#
Postconditions: *this does not contain a value.
3
#
Remarks: No contained value is initialized.
For every object type T these constructors are constexpr constructors ([dcl.constexpr]).
🔗
constexpr optional(const optional& rhs);
4
#
Effects: If rhs contains a value, direct-non-list-initializes the contained value with *rhs.
5
#
Postconditions: rhs.has_value() == this->has_value().
6
#
Throws: Any exception thrown by the selected constructor of T.
7
#
Remarks: This constructor is defined as deleted unless is_copy_constructible_v<T> is true.
If is_trivially_copy_constructible_v<T> is true, this constructor is trivial.
🔗
constexpr optional(optional&& rhs) noexcept(see below);
8
#
Constraints: is_move_constructible_v<T> is true.
9
#
Effects: If rhs contains a value, direct-non-list-initializes the contained value with std​::​move(*rhs).
rhs.has_value() is unchanged.
10
#
Postconditions: rhs.has_value() == this->has_value().
11
#
Throws: Any exception thrown by the selected constructor of T.
12
#
Remarks: The exception specification is equivalent to is_nothrow_move_constructible_v<T>.
If is_trivially_move_constructible_v<T> is true, this constructor is trivial.
🔗
template<class... Args> constexpr explicit optional(in_place_t, Args&&... args);
13
#
Constraints: is_constructible_v<T, Args...> is true.
14
#
Effects: Direct-non-list-initializes the contained value with std​::​forward<Args>(args)....
15
#
Postconditions: *this contains a value.
16
#
Throws: Any exception thrown by the selected constructor of T.
17
#
Remarks: If T's constructor selected for the initialization is a constexpr constructor, this constructor is a constexpr constructor.
🔗
template<class U, class... Args> constexpr explicit optional(in_place_t, initializer_list<U> il, Args&&... args);
18
#
Constraints: is_constructible_v<T, initializer_list<U>&, Args...> is true.
19
#
Effects: Direct-non-list-initializes the contained value with il, std​::​forward<Args>(args)....
20
#
Postconditions: *this contains a value.
21
#
Throws: Any exception thrown by the selected constructor of T.
22
#
Remarks: If T's constructor selected for the initialization is a constexpr constructor, this constructor is a constexpr constructor.
🔗
template<class U = T> constexpr explicit(see below) optional(U&& v);
23
#
Constraints:
  • (23.1)
    is_constructible_v<T, U> is true,
  • (23.2)
    is_same_v<remove_cvref_t<U>, in_place_t> is false,
  • (23.3)
    is_same_v<remove_cvref_t<U>, optional> is false, and
  • (23.4)
    if T is cv bool, remove_cvref_t<U> is not a specialization of optional.
24
#
Effects: Direct-non-list-initializes the contained value with std​::​forward<U>(v).
25
#
Postconditions: *this contains a value.
26
#
Throws: Any exception thrown by the selected constructor of T.
27
#
Remarks: If T's selected constructor is a constexpr constructor, this constructor is a constexpr constructor.
The expression inside explicit is equivalent to: !is_convertible_v<U, T>
🔗
template<class U> constexpr explicit(see below) optional(const optional<U>& rhs);
28
#
Constraints:
  • (28.1)
    is_constructible_v<T, const U&> is true, and
  • (28.2)
    if T is not cv bool, converts-from-any-cvref<T, optional<U>> is false.
29
#
Effects: If rhs contains a value, direct-non-list-initializes the contained value with *rhs.
30
#
Postconditions: rhs.has_value() == this->has_value().
31
#
Throws: Any exception thrown by the selected constructor of T.
32
#
Remarks: The expression inside explicit is equivalent to: !is_convertible_v<const U&, T>
🔗
template<class U> constexpr explicit(see below) optional(optional<U>&& rhs);
33
#
Constraints:
  • (33.1)
    is_constructible_v<T, U> is true, and
  • (33.2)
    if T is not cv bool, converts-from-any-cvref<T, optional<U>> is false.
34
#
Effects: If rhs contains a value, direct-non-list-initializes the contained value with std​::​move(*rhs).
rhs.has_value() is unchanged.
35
#
Postconditions: rhs.has_value() == this->has_value().
36
#
Throws: Any exception thrown by the selected constructor of T.
37
#
Remarks: The expression inside explicit is equivalent to: !is_convertible_v<U, T>

22.5.3.3 Destructor [optional.dtor]

🔗
constexpr ~optional();
1
#
Effects: If is_trivially_destructible_v<T> != true and *this contains a value, calls val->T::~T()
2
#
Remarks: If is_trivially_destructible_v<T> is true, then this destructor is trivial.

22.5.3.4 Assignment [optional.assign]

🔗
constexpr optional<T>& operator=(nullopt_t) noexcept;
1
#
Effects: If *this contains a value, calls val->T​::​~T() to destroy the contained value; otherwise no effect.
2
#
Postconditions: *this does not contain a value.
3
#
Returns: *this.
🔗
constexpr optional<T>& operator=(const optional& rhs);
4
#
Effects: See Table 62.
Table 62: optional​::​operator=(const optional&) effects [tab:optional.assign.copy]
*this contains a value
*this does not contain a value
rhs contains a value
assigns *rhs to the contained value
direct-non-list-initializes the contained value with *rhs
rhs does not contain a value
destroys the contained value by calling val->T​::​~T()
no effect
5
#
Postconditions: rhs.has_value() == this->has_value().
6
#
Returns: *this.
7
#
Remarks: If any exception is thrown, the result of the expression this->has_value() remains unchanged.
If an exception is thrown during the call to T's copy constructor, no effect.
If an exception is thrown during the call to T's copy assignment, the state of its contained value is as defined by the exception safety guarantee of T's copy assignment.
This operator is defined as deleted unless is_copy_constructible_v<T> is true and is_copy_assignable_v<T> is true.
If is_trivially_copy_constructible_v<T> && is_trivially_copy_assignable_v<T> && is_trivially_destructible_v<T> is true, this assignment operator is trivial.
🔗
constexpr optional& operator=(optional&& rhs) noexcept(see below);
8
#
Constraints: is_move_constructible_v<T> is true and is_move_assignable_v<T> is true.
9
#
Effects: See Table 63.
The result of the expression rhs.has_value() remains unchanged.
Table 63: optional​::​operator=(optional&&) effects [tab:optional.assign.move]
*this contains a value
*this does not contain a value
rhs contains a value
assigns std​::​move(*rhs) to the contained value
direct-non-list-initializes the contained value with std​::​move(*rhs)
rhs does not contain a value
destroys the contained value by calling val->T​::​~T()
no effect
10
#
Postconditions: rhs.has_value() == this->has_value().
11
#
Returns: *this.
12
#
Remarks: The exception specification is equivalent to: is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T>
13
#
If any exception is thrown, the result of the expression this->has_value() remains unchanged.
If an exception is thrown during the call to T's move constructor, the state of *rhs.val is determined by the exception safety guarantee of T's move constructor.
If an exception is thrown during the call to T's move assignment, the state of *val and *rhs.val is determined by the exception safety guarantee of T's move assignment.
If is_trivially_move_constructible_v<T> && is_trivially_move_assignable_v<T> && is_trivially_destructible_v<T> is true, this assignment operator is trivial.
🔗
template<class U = T> constexpr optional<T>& operator=(U&& v);
14
#
Constraints:
  • (14.1)
    is_same_v<remove_cvref_t<U>, optional> is false,
  • (14.2)
    conjunction_v<is_scalar<T>, is_same<T, decay_t<U>>> is false,
  • (14.3)
    is_constructible_v<T, U> is true, and
  • (14.4)
    is_assignable_v<T&, U> is true.
15
#
Effects: If *this contains a value, assigns std​::​forward<U>(v) to the contained value; otherwise direct-non-list-initializes the contained value with std​::​forward<U>(v).
16
#
Postconditions: *this contains a value.
17
#
Returns: *this.
18
#
Remarks: If any exception is thrown, the result of the expression this->has_value() remains unchanged.
If an exception is thrown during the call to T's constructor, the state of v is determined by the exception safety guarantee of T's constructor.
If an exception is thrown during the call to T's assignment, the state of *val and v is determined by the exception safety guarantee of T's assignment.
🔗
template<class U> constexpr optional<T>& operator=(const optional<U>& rhs);
19
#
Constraints:
  • (19.1)
    is_constructible_v<T, const U&> is true,
  • (19.2)
    is_assignable_v<T&, const U&> is true,
  • (19.3)
    converts-from-any-cvref<T, optional<U>> is false,
  • (19.4)
    is_assignable_v<T&, optional<U>&> is false,
  • (19.5)
    is_assignable_v<T&, optional<U>&&> is false,
  • (19.6)
    is_assignable_v<T&, const optional<U>&> is false, and
  • (19.7)
    is_assignable_v<T&, const optional<U>&&> is false.
20
#
Effects: See Table 64.
Table 64: optional​::​operator=(const optional<U>&) effects [tab:optional.assign.copy.templ]
*this contains a value
*this does not contain a value
rhs contains a value
assigns *rhs to the contained value
direct-non-list-initializes the contained value with *rhs
rhs does not contain a value
destroys the contained value by calling val->T​::​~T()
no effect
21
#
Postconditions: rhs.has_value() == this->has_value().
22
#
Returns: *this.
23
#
Remarks: If any exception is thrown, the result of the expression this->has_value() remains unchanged.
If an exception is thrown during the call to T's constructor, the state of *rhs.val is determined by the exception safety guarantee of T's constructor.
If an exception is thrown during the call to T's assignment, the state of *val and *rhs.val is determined by the exception safety guarantee of T's assignment.
🔗
template<class U> constexpr optional<T>& operator=(optional<U>&& rhs);
24
#
Constraints:
  • (24.1)
    is_constructible_v<T, U> is true,
  • (24.2)
    is_assignable_v<T&, U> is true,
  • (24.3)
    converts-from-any-cvref<T, optional<U>> is false,
  • (24.4)
    is_assignable_v<T&, optional<U>&> is false,
  • (24.5)
    is_assignable_v<T&, optional<U>&&> is false,
  • (24.6)
    is_assignable_v<T&, const optional<U>&> is false, and
  • (24.7)
    is_assignable_v<T&, const optional<U>&&> is false.
25
#
Effects: See Table 65.
The result of the expression rhs.has_value() remains unchanged.
Table 65: optional​::​operator=(optional<U>&&) effects [tab:optional.assign.move.templ]
*this contains a value
*this does not contain a value
rhs contains a value
assigns std​::​move(*rhs) to the contained value
direct-non-list-initializes the contained value with std​::​move(*rhs)
rhs does not contain a value
destroys the contained value by calling val->T​::​~T()
no effect
26
#
Postconditions: rhs.has_value() == this->has_value().
27
#
Returns: *this.
28
#
Remarks: If any exception is thrown, the result of the expression this->has_value() remains unchanged.
If an exception is thrown during the call to T's constructor, the state of *rhs.val is determined by the exception safety guarantee of T's constructor.
If an exception is thrown during the call to T's assignment, the state of *val and *rhs.val is determined by the exception safety guarantee of T's assignment.
🔗
template<class... Args> constexpr T& emplace(Args&&... args);
29
#
Mandates: is_constructible_v<T, Args...> is true.
30
#
Effects: Calls *this = nullopt.
Then direct-non-list-initializes the contained value with std​::​forward​<Args>(args)....
31
#
Postconditions: *this contains a value.
32
#
Returns: A reference to the new contained value.
33
#
Throws: Any exception thrown by the selected constructor of T.
34
#
Remarks: If an exception is thrown during the call to T's constructor, *this does not contain a value, and the previous *val (if any) has been destroyed.
🔗
template<class U, class... Args> constexpr T& emplace(initializer_list<U> il, Args&&... args);
35
#
Constraints: is_constructible_v<T, initializer_list<U>&, Args...> is true.
36
#
Effects: Calls *this = nullopt.
Then direct-non-list-initializes the contained value with il, std​::​​forward<Args>(args)....
37
#
Postconditions: *this contains a value.
38
#
Returns: A reference to the new contained value.
39
#
Throws: Any exception thrown by the selected constructor of T.
40
#
Remarks: If an exception is thrown during the call to T's constructor, *this does not contain a value, and the previous *val (if any) has been destroyed.

22.5.3.5 Swap [optional.swap]

🔗
constexpr void swap(optional& rhs) noexcept(see below);
1
#
Mandates: is_move_constructible_v<T> is true.
2
#
Preconditions: T meets the Cpp17Swappable requirements ([swappable.requirements]).
3
#
Effects: See Table 66.
Table 66: optional​::​swap(optional&) effects [tab:optional.swap]
*this contains a value
*this does not contain a value
rhs contains a value
calls swap(*(*this), *rhs)
direct-non-list-initializes the contained value of *this with std​::​move(*rhs), followed by rhs.val->T​::​~T(); postcondition is that *this contains a value and rhs does not contain a value
rhs does not contain a value
direct-non-list-initializes the contained value of rhs with std​::​move(*(*this)), followed by val->T​::​~T(); postcondition is that *this does not contain a value and rhs contains a value
no effect
4
#
Throws: Any exceptions thrown by the operations in the relevant part of Table 66.
5
#
Remarks: The exception specification is equivalent to: is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T>
6
#
If any exception is thrown, the results of the expressions this->has_value() and rhs.has_value() remain unchanged.
If an exception is thrown during the call to function swap, the state of *val and *rhs.val is determined by the exception safety guarantee of swap for lvalues of T.
If an exception is thrown during the call to T's move constructor, the state of *val and *rhs.val is determined by the exception safety guarantee of T's move constructor.

22.5.3.6 Iterator support [optional.iterators]

🔗
using iterator = implementation-defined; using const_iterator = implementation-defined;
1
#
These types model contiguous_iterator ([iterator.concept.contiguous]), meet the Cpp17RandomAccessIterator requirements ([random.access.iterators]), and meet the requirements for constexpr iterators ([iterator.requirements.general]), with value type remove_cv_t<T>.
The reference type is T& for iterator and const T& for const_iterator.
2
#
All requirements on container iterators ([container.reqmts]) apply to optional​::​iterator and optional​::​const_iterator as well.
3
#
Any operation that initializes or destroys the contained value of an optional object invalidates all iterators into that object.
🔗
constexpr iterator begin() noexcept; constexpr const_iterator begin() const noexcept;
4
#
Returns: If has_value() is true, an iterator referring to the contained value.
Otherwise, a past-the-end iterator value.
🔗
constexpr iterator end() noexcept; constexpr const_iterator end() const noexcept;
5
#
Returns: begin() + has_value().

22.5.3.7 Observers [optional.observe]

🔗
constexpr const T* operator->() const noexcept; constexpr T* operator->() noexcept;
1
#
Preconditions: *this contains a value.
2
#
Returns: val.
3
#
Remarks: These functions are constexpr functions.
🔗
constexpr const T& operator*() const & noexcept; constexpr T& operator*() & noexcept;
4
#
Preconditions: *this contains a value.
5
#
Returns: *val.
6
#
Remarks: These functions are constexpr functions.
🔗
constexpr T&& operator*() && noexcept; constexpr const T&& operator*() const && noexcept;
7
#
Preconditions: *this contains a value.
8
#
Effects: Equivalent to: return std​::​move(*val);
🔗
constexpr explicit operator bool() const noexcept;
9
#
Returns: true if and only if *this contains a value.
10
#
Remarks: This function is a constexpr function.
🔗
constexpr bool has_value() const noexcept;
11
#
Returns: true if and only if *this contains a value.
12
#
Remarks: This function is a constexpr function.
🔗
constexpr const T& value() const &; constexpr T& value() &;
13
#
Effects: Equivalent to: return has_value() ? *val : throw bad_optional_access();
🔗
constexpr T&& value() &&; constexpr const T&& value() const &&;
14
#
Effects: Equivalent to: return has_value() ? std::move(*val) : throw bad_optional_access();
🔗
template<class U> constexpr T value_or(U&& v) const &;
15
#
Mandates: is_copy_constructible_v<T> && is_convertible_v<U&&, T> is true.
16
#
Effects: Equivalent to: return has_value() ? **this : static_cast<T>(std::forward<U>(v));
🔗
template<class U> constexpr T value_or(U&& v) &&;
17
#
Mandates: is_move_constructible_v<T> && is_convertible_v<U&&, T> is true.
18
#
Effects: Equivalent to: return has_value() ? std::move(**this) : static_cast<T>(std::forward<U>(v));

22.5.3.8 Monadic operations [optional.monadic]

🔗
template<class F> constexpr auto and_then(F&& f) &; template<class F> constexpr auto and_then(F&& f) const &;
1
#
Let U be invoke_result_t<F, decltype(*val)>.
2
#
Mandates: remove_cvref_t<U> is a specialization of optional.
3
#
Effects: Equivalent to: if (*this) { return invoke(std::forward<F>(f), *val); } else { return remove_cvref_t<U>(); }
🔗
template<class F> constexpr auto and_then(F&& f) &&; template<class F> constexpr auto and_then(F&& f) const &&;
4
#
Let U be invoke_result_t<F, decltype(std​::​move(*val))>.
5
#
Mandates: remove_cvref_t<U> is a specialization of optional.
6
#
Effects: Equivalent to: if (*this) { return invoke(std::forward<F>(f), std::move(*val)); } else { return remove_cvref_t<U>(); }
🔗
template<class F> constexpr auto transform(F&& f) &; template<class F> constexpr auto transform(F&& f) const &;
7
#
Let U be remove_cv_t<invoke_result_t<F, decltype(*val)>>.
8
#
Mandates: U is a non-array object type other than in_place_t or nullopt_t.
The declaration U u(invoke(std::forward<F>(f), *val)); is well-formed for some invented variable u.
[Note 1: 
There is no requirement that U is movable ([dcl.init.general]).
— end note]
9
#
Returns: If *this contains a value, an optional<U> object whose contained value is direct-non-list-initialized with invoke(std​::​forward<F>(f), *val); otherwise, optional<U>().
🔗
template<class F> constexpr auto transform(F&& f) &&; template<class F> constexpr auto transform(F&& f) const &&;
10
#
Let U be remove_cv_t<invoke_result_t<F, decltype(std​::​move(*val))>>.
11
#
Mandates: U is a non-array object type other than in_place_t or nullopt_t.
The declaration U u(invoke(std::forward<F>(f), std::move(*val))); is well-formed for some invented variable u.
[Note 2: 
There is no requirement that U is movable ([dcl.init.general]).
— end note]
12
#
Returns: If *this contains a value, an optional<U> object whose contained value is direct-non-list-initialized with invoke(std​::​forward<F>(f), std​::​move(*val)); otherwise, optional<U>().
🔗
template<class F> constexpr optional or_else(F&& f) const &;
13
#
Constraints: F models invocable<> and T models copy_constructible.
14
#
Mandates: is_same_v<remove_cvref_t<invoke_result_t<F>>, optional> is true.
15
#
Effects: Equivalent to: if (*this) { return *this; } else { return std::forward<F>(f)(); }
🔗
template<class F> constexpr optional or_else(F&& f) &&;
16
#
Constraints: F models invocable<> and T models move_constructible.
17
#
Mandates: is_same_v<remove_cvref_t<invoke_result_t<F>>, optional> is true.
18
#
Effects: Equivalent to: if (*this) { return std::move(*this); } else { return std::forward<F>(f)(); }

22.5.3.9 Modifiers [optional.mod]

🔗
constexpr void reset() noexcept;
1
#
Effects: If *this contains a value, calls val->T​::​~T() to destroy the contained value; otherwise no effect.
2
#
Postconditions: *this does not contain a value.

22.5.4 No-value state indicator [optional.nullopt]

🔗
struct nullopt_t{see below}; inline constexpr nullopt_t nullopt(unspecified);
1
#
The struct nullopt_t is an empty class type used as a unique type to indicate the state of not containing a value for optional objects.
In particular, optional<T> has a constructor with nullopt_t as a single argument; this indicates that an optional object not containing a value shall be constructed.
2
#
Type nullopt_t shall not have a default constructor or an initializer-list constructor, and shall not be an aggregate.

22.5.5 Class bad_optional_access [optional.bad.access]

namespace std { class bad_optional_access : public exception { public: // see [exception] for the specification of the special member functions const char* what() const noexcept override; }; }
1
#
The class bad_optional_access defines the type of objects thrown as exceptions to report the situation where an attempt is made to access the value of an optional object that does not contain a value.
🔗
const char* what() const noexcept override;
2
#
Returns: An implementation-defined ntbs.

22.5.6 Relational operators [optional.relops]

🔗
template<class T, class U> constexpr bool operator==(const optional<T>& x, const optional<U>& y);
1
#
Constraints: The expression *x == *y is well-formed and its result is convertible to bool.
[Note 1:  — end note]
2
#
Returns: If x.has_value() != y.has_value(), false; otherwise if x.has_value() == false, true; otherwise *x == *y.
3
#
Remarks: Specializations of this function template for which *x == *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator!=(const optional<T>& x, const optional<U>& y);
4
#
Constraints: The expression *x != *y is well-formed and its result is convertible to bool.
5
#
Returns: If x.has_value() != y.has_value(), true; otherwise, if x.has_value() == false, false; otherwise *x != *y.
6
#
Remarks: Specializations of this function template for which *x != *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator<(const optional<T>& x, const optional<U>& y);
7
#
Constraints: *x < *y is well-formed and its result is convertible to bool.
8
#
Returns: If !y, false; otherwise, if !x, true; otherwise *x < *y.
9
#
Remarks: Specializations of this function template for which *x < *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator>(const optional<T>& x, const optional<U>& y);
10
#
Constraints: The expression *x > *y is well-formed and its result is convertible to bool.
11
#
Returns: If !x, false; otherwise, if !y, true; otherwise *x > *y.
12
#
Remarks: Specializations of this function template for which *x > *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator<=(const optional<T>& x, const optional<U>& y);
13
#
Constraints: The expression *x <= *y is well-formed and its result is convertible to bool.
14
#
Returns: If !x, true; otherwise, if !y, false; otherwise *x <= *y.
15
#
Remarks: Specializations of this function template for which *x <= *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator>=(const optional<T>& x, const optional<U>& y);
16
#
Constraints: The expression *x >= *y is well-formed and its result is convertible to bool.
17
#
Returns: If !y, true; otherwise, if !x, false; otherwise *x >= *y.
18
#
Remarks: Specializations of this function template for which *x >= *y is a core constant expression are constexpr functions.
🔗
template<class T, three_way_comparable_with<T> U> constexpr compare_three_way_result_t<T, U> operator<=>(const optional<T>& x, const optional<U>& y);
19
#
Returns: If x && y, *x <=> *y; otherwise x.has_value() <=> y.has_value().
20
#
Remarks: Specializations of this function template for which *x <=> *y is a core constant expression are constexpr functions.

22.5.7 Comparison with nullopt [optional.nullops]

🔗
template<class T> constexpr bool operator==(const optional<T>& x, nullopt_t) noexcept;
1
#
Returns: !x.
🔗
template<class T> constexpr strong_ordering operator<=>(const optional<T>& x, nullopt_t) noexcept;
2
#
Returns: x.has_value() <=> false.

22.5.8 Comparison with T [optional.comp.with.t]

🔗
template<class T, class U> constexpr bool operator==(const optional<T>& x, const U& v);
1
#
Constraints: The expression *x == v is well-formed and its result is convertible to bool.
[Note 1:  — end note]
2
#
Effects: Equivalent to: return x.has_value() ? *x == v : false;
🔗
template<class T, class U> constexpr bool operator==(const T& v, const optional<U>& x);
3
#
Constraints: The expression v == *x is well-formed and its result is convertible to bool.
4
#
Effects: Equivalent to: return x.has_value() ? v == *x : false;
🔗
template<class T, class U> constexpr bool operator!=(const optional<T>& x, const U& v);
5
#
Constraints: The expression *x != v is well-formed and its result is convertible to bool.
6
#
Effects: Equivalent to: return x.has_value() ? *x != v : true;
🔗
template<class T, class U> constexpr bool operator!=(const T& v, const optional<U>& x);
7
#
Constraints: The expression v != *x is well-formed and its result is convertible to bool.
8
#
Effects: Equivalent to: return x.has_value() ? v != *x : true;
🔗
template<class T, class U> constexpr bool operator<(const optional<T>& x, const U& v);
9
#
Constraints: The expression *x < v is well-formed and its result is convertible to bool.
10
#
Effects: Equivalent to: return x.has_value() ? *x < v : true;
🔗
template<class T, class U> constexpr bool operator<(const T& v, const optional<U>& x);
11
#
Constraints: The expression v < *x is well-formed and its result is convertible to bool.
12
#
Effects: Equivalent to: return x.has_value() ? v < *x : false;
🔗
template<class T, class U> constexpr bool operator>(const optional<T>& x, const U& v);
13
#
Constraints: The expression *x > v is well-formed and its result is convertible to bool.
14
#
Effects: Equivalent to: return x.has_value() ? *x > v : false;
🔗
template<class T, class U> constexpr bool operator>(const T& v, const optional<U>& x);
15
#
Constraints: The expression v > *x is well-formed and its result is convertible to bool.
16
#
Effects: Equivalent to: return x.has_value() ? v > *x : true;
🔗
template<class T, class U> constexpr bool operator<=(const optional<T>& x, const U& v);
17
#
Constraints: The expression *x <= v is well-formed and its result is convertible to bool.
18
#
Effects: Equivalent to: return x.has_value() ? *x <= v : true;
🔗
template<class T, class U> constexpr bool operator<=(const T& v, const optional<U>& x);
19
#
Constraints: The expression v <= *x is well-formed and its result is convertible to bool.
20
#
Effects: Equivalent to: return x.has_value() ? v <= *x : false;
🔗
template<class T, class U> constexpr bool operator>=(const optional<T>& x, const U& v);
21
#
Constraints: The expression *x >= v is well-formed and its result is convertible to bool.
22
#
Effects: Equivalent to: return x.has_value() ? *x >= v : false;
🔗
template<class T, class U> constexpr bool operator>=(const T& v, const optional<U>& x);
23
#
Constraints: The expression v >= *x is well-formed and its result is convertible to bool.
24
#
Effects: Equivalent to: return x.has_value() ? v >= *x : true;
🔗
template<class T, class U> requires (!is-derived-from-optional<U>) && three_way_comparable_with<T, U> constexpr compare_three_way_result_t<T, U> operator<=>(const optional<T>& x, const U& v);
25
#
Effects: Equivalent to: return x.has_value() ? *x <=> v : strong_ordering​::​less;

22.5.9 Specialized algorithms [optional.specalg]

🔗
template<class T> constexpr void swap(optional<T>& x, optional<T>& y) noexcept(noexcept(x.swap(y)));
1
#
Constraints: is_move_constructible_v<T> is true and is_swappable_v<T> is true.
2
#
Effects: Calls x.swap(y).
🔗
template<class T> constexpr optional<decay_t<T>> make_optional(T&& v);
3
#
Returns: optional<decay_t<T>>(std​::​forward<T>(v)).
🔗
template<class T, class...Args> constexpr optional<T> make_optional(Args&&... args);
4
#
Effects: Equivalent to: return optional<T>(in_place, std​::​forward<Args>(args)...);
🔗
template<class T, class U, class... Args> constexpr optional<T> make_optional(initializer_list<U> il, Args&&... args);
5
#
Effects: Equivalent to: return optional<T>(in_place, il, std​::​forward<Args>(args)...);

22.5.10 Hash support [optional.hash]

🔗
template<class T> struct hash<optional<T>>;
1
#
The specialization hash<optional<T>> is enabled ([unord.hash]) if and only if hash<remove_const_t<T>> is enabled.
When enabled, for an object o of type optional<T>, if o.has_value() == true, then hash<optional<T>>()(o) evaluates to the same value as hash<remove_const_t<T>>()(*o); otherwise it evaluates to an unspecified value.
The member functions are not guaranteed to be noexcept.

22.6 Variants [variant]

22.6.1 General [variant.general]

1
#
A variant object holds and manages the lifetime of a value.
If the variant holds a value, that value's type has to be one of the template argument types given to variant.
These template arguments are called alternatives.
2
#
In [variant], GET denotes a set of exposition-only function templates ([variant.get]).

22.6.2 Header <variant> synopsis [variant.syn]

// mostly freestanding #include <compare> // see [compare.syn] namespace std { // [variant.variant], class template variant template<class... Types> class variant; // [variant.helper], variant helper classes template<class T> struct variant_size; // not defined template<class T> struct variant_size<const T>; template<class T> constexpr size_t variant_size_v = variant_size<T>::value; template<class... Types> struct variant_size<variant<Types...>>; template<size_t I, class T> struct variant_alternative; // not defined template<size_t I, class T> struct variant_alternative<I, const T>; template<size_t I, class T> using variant_alternative_t = typename variant_alternative<I, T>::type; template<size_t I, class... Types> struct variant_alternative<I, variant<Types...>>; inline constexpr size_t variant_npos = -1; // [variant.get], value access template<class T, class... Types> constexpr bool holds_alternative(const variant<Types...>&) noexcept; template<size_t I, class... Types> constexpr variant_alternative_t<I, variant<Types...>>& get(variant<Types...>&); // freestanding-deleted template<size_t I, class... Types> constexpr variant_alternative_t<I, variant<Types...>>&& get(variant<Types...>&&); // freestanding-deleted template<size_t I, class... Types> constexpr const variant_alternative_t<I, variant<Types...>>& get(const variant<Types...>&); // freestanding-deleted template<size_t I, class... Types> constexpr const variant_alternative_t<I, variant<Types...>>&& get(const variant<Types...>&&); // freestanding-deleted template<class T, class... Types> constexpr T& get(variant<Types...>&); // freestanding-deleted template<class T, class... Types> constexpr T&& get(variant<Types...>&&); // freestanding-deleted template<class T, class... Types> constexpr const T& get(const variant<Types...>&); // freestanding-deleted template<class T, class... Types> constexpr const T&& get(const variant<Types...>&&); // freestanding-deleted template<size_t I, class... Types> constexpr add_pointer_t<variant_alternative_t<I, variant<Types...>>> get_if(variant<Types...>*) noexcept; template<size_t I, class... Types> constexpr add_pointer_t<const variant_alternative_t<I, variant<Types...>>> get_if(const variant<Types...>*) noexcept; template<class T, class... Types> constexpr add_pointer_t<T> get_if(variant<Types...>*) noexcept; template<class T, class... Types> constexpr add_pointer_t<const T> get_if(const variant<Types...>*) noexcept; // [variant.relops], relational operators template<class... Types> constexpr bool operator==(const variant<Types...>&, const variant<Types...>&); template<class... Types> constexpr bool operator!=(const variant<Types...>&, const variant<Types...>&); template<class... Types> constexpr bool operator<(const variant<Types...>&, const variant<Types...>&); template<class... Types> constexpr bool operator>(const variant<Types...>&, const variant<Types...>&); template<class... Types> constexpr bool operator<=(const variant<Types...>&, const variant<Types...>&); template<class... Types> constexpr bool operator>=(const variant<Types...>&, const variant<Types...>&); template<class... Types> requires (three_way_comparable<Types> && ...) constexpr common_comparison_category_t<compare_three_way_result_t<Types>...> operator<=>(const variant<Types...>&, const variant<Types...>&); // [variant.visit], visitation template<class Visitor, class... Variants> constexpr see below visit(Visitor&&, Variants&&...); template<class R, class Visitor, class... Variants> constexpr R visit(Visitor&&, Variants&&...); // [variant.monostate], class monostate struct monostate; // [variant.monostate.relops], monostate relational operators constexpr bool operator==(monostate, monostate) noexcept; constexpr strong_ordering operator<=>(monostate, monostate) noexcept; // [variant.specalg], specialized algorithms template<class... Types> constexpr void swap(variant<Types...>&, variant<Types...>&) noexcept(see below); // [variant.bad.access], class bad_variant_access class bad_variant_access; // [variant.hash], hash support template<class T> struct hash; template<class... Types> struct hash<variant<Types...>>; template<> struct hash<monostate>; }

22.6.3 Class template variant [variant.variant]

22.6.3.1 General [variant.variant.general]

namespace std { template<class... Types> class variant { public: // [variant.ctor], constructors constexpr variant() noexcept(see below); constexpr variant(const variant&); constexpr variant(variant&&) noexcept(see below); template<class T> constexpr variant(T&&) noexcept(see below); template<class T, class... Args> constexpr explicit variant(in_place_type_t<T>, Args&&...); template<class T, class U, class... Args> constexpr explicit variant(in_place_type_t<T>, initializer_list<U>, Args&&...); template<size_t I, class... Args> constexpr explicit variant(in_place_index_t<I>, Args&&...); template<size_t I, class U, class... Args> constexpr explicit variant(in_place_index_t<I>, initializer_list<U>, Args&&...); // [variant.dtor], destructor constexpr ~variant(); // [variant.assign], assignment constexpr variant& operator=(const variant&); constexpr variant& operator=(variant&&) noexcept(see below); template<class T> constexpr variant& operator=(T&&) noexcept(see below); // [variant.mod], modifiers template<class T, class... Args> constexpr T& emplace(Args&&...); template<class T, class U, class... Args> constexpr T& emplace(initializer_list<U>, Args&&...); template<size_t I, class... Args> constexpr variant_alternative_t<I, variant<Types...>>& emplace(Args&&...); template<size_t I, class U, class... Args> constexpr variant_alternative_t<I, variant<Types...>>& emplace(initializer_list<U>, Args&&...); // [variant.status], value status constexpr bool valueless_by_exception() const noexcept; constexpr size_t index() const noexcept; // [variant.swap], swap constexpr void swap(variant&) noexcept(see below); // [variant.visit], visitation template<class Self, class Visitor> constexpr decltype(auto) visit(this Self&&, Visitor&&); template<class R, class Self, class Visitor> constexpr R visit(this Self&&, Visitor&&); }; }
1
#
Any instance of variant at any given time either holds a value of one of its alternative types or holds no value.
When an instance of variant holds a value of alternative type T, it means that a value of type T, referred to as the variant object's contained value, is allocated within the storage of the variant object.
Implementations are not permitted to use additional storage, such as dynamic memory, to allocate the contained value.
2
#
All types in Types shall meet the Cpp17Destructible requirements (Table 35).
3
#
A program that instantiates the definition of variant with no template arguments is ill-formed.
4
#
If a program declares an explicit or partial specialization of variant, the program is ill-formed, no diagnostic required.

22.6.3.2 Constructors [variant.ctor]

1
#
In the descriptions that follow, let i be in the range [0, sizeof...(Types)), and be the type in Types.
🔗
constexpr variant() noexcept(see below);
2
#
Constraints: is_default_constructible_v<> is true.
3
#
Effects: Constructs a variant holding a value-initialized value of type .
4
#
Postconditions: valueless_by_exception() is false and index() is 0.
5
#
Throws: Any exception thrown by the value-initialization of .
6
#
Remarks: This function is constexpr if and only if the value-initialization of the alternative type would be constexpr-suitable ([dcl.constexpr]).
The exception specification is equivalent to is_nothrow_default_constructible_v<>.
[Note 1: 
See also class monostate.
— end note]
🔗
constexpr variant(const variant& w);
7
#
Effects: If w holds a value, initializes the variant to hold the same alternative as w and direct-initializes the contained value with GET<j>(w), where j is w.index().
Otherwise, initializes the variant to not hold a value.
8
#
Throws: Any exception thrown by direct-initializing any for all i.
9
#
Remarks: This constructor is defined as deleted unless is_copy_constructible_v<> is true for all i.
If is_trivially_copy_constructible_v<> is true for all i, this constructor is trivial.
🔗
constexpr variant(variant&& w) noexcept(see below);
10
#
Constraints: is_move_constructible_v<> is true for all i.
11
#
Effects: If w holds a value, initializes the variant to hold the same alternative as w and direct-initializes the contained value with GET<j>(std​::​move(w)), where j is w.index().
Otherwise, initializes the variant to not hold a value.
12
#
Throws: Any exception thrown by move-constructing any for all i.
13
#
Remarks: The exception specification is equivalent to the logical and of is_nothrow_move_constructible_v<> for all i.
If is_trivially_move_constructible_v<> is true for all i, this constructor is trivial.
🔗
template<class T> constexpr variant(T&& t) noexcept(see below);
14
#
Let be a type that is determined as follows: build an imaginary function FUN() for each alternative type for which x[] = {std​::​forward<T>(t)}; is well-formed for some invented variable x.
The overload FUN() selected by overload resolution for the expression FUN(std​::​forward<T>(​t)) defines the alternative which is the type of the contained value after construction.
15
#
Constraints:
  • (15.1)
    sizeof...(Types) is nonzero,
  • (15.2)
    is_same_v<remove_cvref_t<T>, variant> is false,
  • (15.3)
    remove_cvref_t<T> is neither a specialization of in_place_type_t nor a specialization of in_place_index_t,
  • (15.4)
    is_constructible_v<, T> is true, and
  • (15.5)
    the expression FUN(​std​::​forward<T>(t)) (with FUN being the above-mentioned set of imaginary functions) is well-formed.
    [Note 2: 
    variant<string, string> v("abc"); is ill-formed, as both alternative types have an equally viable constructor for the argument.
    — end note]
16
#
Effects: Initializes *this to hold the alternative type and direct-non-list-initializes the contained value with std​::​forward<T>(t).
17
#
Postconditions: holds_alternative<>(*this) is true.
18
#
Throws: Any exception thrown by the initialization of the selected alternative .
19
#
Remarks: The exception specification is equivalent to is_nothrow_constructible_v<, T>.
If 's selected constructor is a constexpr constructor, this constructor is a constexpr constructor.
🔗
template<class T, class... Args> constexpr explicit variant(in_place_type_t<T>, Args&&... args);
20
#
Constraints:
  • (20.1)
    There is exactly one occurrence of T in Types... and
  • (20.2)
    is_constructible_v<T, Args...> is true.
21
#
Effects: Direct-non-list-initializes the contained value of type T with std​::​forward<Args>(args)....
22
#
Postconditions: holds_alternative<T>(*this) is true.
23
#
Throws: Any exception thrown by calling the selected constructor of T.
24
#
Remarks: If T's selected constructor is a constexpr constructor, this constructor is a constexpr constructor.
🔗
template<class T, class U, class... Args> constexpr explicit variant(in_place_type_t<T>, initializer_list<U> il, Args&&... args);
25
#
Constraints:
  • (25.1)
    There is exactly one occurrence of T in Types... and
  • (25.2)
    is_constructible_v<T, initializer_list<U>&, Args...> is true.
26
#
Effects: Direct-non-list-initializes the contained value of type T with il, std​::​forward<Args>(​args)....
27
#
Postconditions: holds_alternative<T>(*this) is true.
28
#
Throws: Any exception thrown by calling the selected constructor of T.
29
#
Remarks: If T's selected constructor is a constexpr constructor, this constructor is a constexpr constructor.
🔗
template<size_t I, class... Args> constexpr explicit variant(in_place_index_t<I>, Args&&... args);