utilities.tex

%!TEX root = std.tex

\rSec0[utilities]{General utilities library}

\rSec1[utilities.general]{General}

\pnum
This Clause describes utilities that are generally useful in \Cpp{} programs; some
of these utilities are used by other elements of the \Cpp{} standard library.
These utilities are summarized in \tref{utilities.summary}.

\begin{libsumtab}{General utilities library summary}{utilities.summary}
\ref{utility}               & Utility components                & \tcode{<utility>}     \\
\ref{pairs}                 & Pairs                             &                       \\ \rowsep
\ref{tuple}                 & Tuples                            & \tcode{<tuple>}       \\ \rowsep
\ref{optional}              & Optional objects                  & \tcode{<optional>}    \\ \rowsep
\ref{variant}               & Variants                          & \tcode{<variant>}     \\ \rowsep
\ref{any}                   & Storage for any type              & \tcode{<any>}         \\ \rowsep
\ref{expected}              & Expected objects                  & \tcode{<expected>}    \\ \rowsep
\ref{bitset}                & Fixed-size sequences of bits      & \tcode{<bitset>}      \\ \rowsep
\ref{function.objects}      & Function objects                  & \tcode{<functional>}  \\ \rowsep
\ref{bit}                   & Bit manipulation                  & \tcode{<bit>}         \\
\end{libsumtab}

\rSec1[utility]{Utility components}

\rSec2[utility.syn]{Header \tcode{<utility>} synopsis}

\pnum
The header \libheaderdef{utility}
contains some basic function and class templates that are used
throughout the rest of the library.

\begin{codeblock}
// all freestanding
#include <compare>              // see \ref{compare.syn}
#include <initializer_list>     // see \ref{initializer.list.syn}

namespace std {
  // \ref{utility.swap}, swap
  template<class T>
    constexpr void swap(T& a, T& b) noexcept(@\seebelow@);
  template<class T, size_t N>
    constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);

  // \ref{utility.exchange}, exchange
  template<class T, class U = T>
    constexpr T exchange(T& obj, U&& new_val) noexcept(@\seebelow@);

  // \ref{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>
    constexpr auto forward_like(U&& x) noexcept -> @\seebelow@;
  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;

  // \ref{utility.as.const}, \tcode{as_const}
  template<class T>
    constexpr add_const_t<T>& as_const(T& t) noexcept;
  template<class T>
    void as_const(const T&&) = delete;

  // \ref{declval}, declval
  template<class T>
    add_rvalue_reference_t<T> declval() noexcept;   // as unevaluated operand

  // \ref{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;

  // \ref{utility.underlying}, \tcode{to_underlying}
  template<class T>
    constexpr underlying_type_t<T> to_underlying(T value) noexcept;

  // \ref{utility.undefined}, undefined behavior
  [[noreturn]] void unreachable();
  void observable() noexcept;

  // \ref{intseq}, compile-time integer sequences%
\indexlibraryglobal{index_sequence}%
\indexlibraryglobal{make_index_sequence}%
\indexlibraryglobal{index_sequence_for}
  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, @\seebelow{}@>;
  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)>;

  // \ref{pairs}, class template \tcode{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>>;
  };

  // \ref{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<@\placeholder{synth-three-way-result}@<T1, U1>,
                                           @\placeholder{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 @\seebelow@ make_pair(T1&&, T2&&);

  // \ref{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;

  // \ref{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 \libheaderref{tuple}

  // in-place construction%
\indexlibraryglobal{in_place_t}%
\indexlibraryglobal{in_place}%
\indexlibraryglobal{in_place_type_t}%
\indexlibraryglobal{in_place_type}%
\indexlibraryglobal{in_place_index_t}%
\indexlibraryglobal{in_place_index}
  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{};

  // \tcode{nontype} argument tag%
\indexlibraryglobal{nontype_t}%
\indexlibraryglobal{nontype}
  template<auto V>
    struct nontype_t {
      explicit nontype_t() = default;
    };
  template<auto V> constexpr nontype_t<V> nontype{};

  // \ref{variant.monostate}, class \tcode{monostate}%
\indexlibraryglobal{monostate}
  struct monostate;

  // \ref{variant.monostate.relops}, \tcode{monostate} relational operators%
\indexlibrarymember{operator==}{monostate}%
\indexlibrarymember{operator<=>}{monostate}
  constexpr bool operator==(monostate, monostate) noexcept;
  constexpr strong_ordering operator<=>(monostate, monostate) noexcept;

  // \ref{variant.hash}, hash support%
\indexlibrarymember{hash}{monostate}
  template<class T> struct hash;
  template<> struct hash<monostate>;
}
\end{codeblock}

\rSec2[utility.swap]{\tcode{swap}}

\indexlibraryglobal{swap}%
\begin{itemdecl}
template<class T>
  constexpr void swap(T& a, T& b) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<T>} is \tcode{true} and
\tcode{is_move_assignable_v<T>} is \tcode{true}.

\pnum
\expects
Type
\tcode{T}
meets the
\oldconcept{MoveConstructible} (\tref{cpp17.moveconstructible})
and
\oldconcept{MoveAssignable} (\tref{cpp17.moveassignable})
requirements.

\pnum
\effects
Exchanges values stored in two locations.

\pnum
\remarks
The exception specification is equivalent to:

\begin{codeblock}
is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{swap}%
\begin{itemdecl}
template<class T, size_t N>
  constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_swappable_v<T>} is \tcode{true}.

\pnum
\expects
\tcode{a[i]} is swappable with\iref{swappable.requirements} \tcode{b[i]}
for all \tcode{i} in the range \range{0}{N}.

\pnum
\effects
As if by \tcode{swap_ranges(a, a + N, b)}.
\end{itemdescr}

\rSec2[utility.exchange]{\tcode{exchange}}

\indexlibraryglobal{exchange}%
\begin{itemdecl}
template<class T, class U = T>
  constexpr T exchange(T& obj, U&& new_val) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
T old_val = std::move(obj);
obj = std::forward<U>(new_val);
return old_val;
\end{codeblock}

\pnum
\remarks
The exception specification is equivalent to:
\begin{codeblock}
is_nothrow_move_constructible_v<T> && is_nothrow_assignable_v<T&, U>
\end{codeblock}
\end{itemdescr}


\rSec2[forward]{Forward/move helpers}

\pnum
The library provides templated helper functions to simplify
applying move semantics to an lvalue and to simplify the implementation
of forwarding functions.
\indextext{signal-safe!\idxcode{forward}}%
\indextext{signal-safe!\idxcode{move}}%
\indextext{signal-safe!\idxcode{move_if_noexcept}}%
All functions specified in this subclause are signal-safe\iref{support.signal}.

\indexlibraryglobal{forward}%
\indextext{\idxcode{forward}}%
\begin{itemdecl}
template<class T> constexpr T&& forward(remove_reference_t<T>& t) noexcept;
template<class T> constexpr T&& forward(remove_reference_t<T>&& t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
For the second overload, \tcode{is_lvalue_reference_v<T>} is \tcode{false}.

\pnum
\returns
\tcode{static_cast<T\&\&>(t)}.

\pnum
\begin{example}
\begin{codeblock}
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 \tcode{int\&}
  int i = 2;
  shared_ptr<A> sp2 = factory<A>(i, 1.414); // OK
}
\end{codeblock}
In the first call to \tcode{factory},
\tcode{A1} is deduced as \tcode{int}, so 2 is forwarded
to \tcode{A}'s constructor as an rvalue.
In the second call to \tcode{factory},
\tcode{A1} is deduced as \tcode{int\&}, so \tcode{i} is forwarded
to \tcode{A}'s constructor as an lvalue. In
both cases, \tcode{A2} is deduced as \tcode{double}, so
1.414 is forwarded to \tcode{A}'s constructor as an rvalue.
\end{example}
\end{itemdescr}

\indexlibraryglobal{forward_like}%
\begin{itemdecl}
template<class T, class U>
  constexpr auto forward_like(U&& x) noexcept -> @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{T} is a referenceable type\iref{defns.referenceable}.

\pnum
\begin{itemize}
\item
Let \tcode{\exposid{COPY_CONST}(A, B)} be \tcode{const B}
if \tcode{A} is a const type, otherwise \tcode{B}.
\item
Let \tcode{\exposid{OVERRIDE_REF}(A, B)} be \tcode{remove_reference_t<B>\&\&}
if \tcode{A} is an rvalue reference type, otherwise \tcode{B\&}.
\item
Let \tcode{V} be
\begin{codeblock}
@\exposid{OVERRIDE_REF}@(T&&, @\exposid{COPY_CONST}@(remove_reference_t<T>, remove_reference_t<U>))
\end{codeblock}
\end{itemize}

\pnum
\returns
\tcode{static_cast<V>(x)}.

\pnum
\remarks
The return type is \tcode{V}.

\pnum
\begin{example}
\begin{codeblock}
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 \tcode{const\&\&}
  string& w = as_const(a)[1];                   // error: will not bind to non-const
}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibrary{\idxcode{move}!function}%
\indextext{\idxcode{move}}%
\begin{itemdecl}
template<class T> constexpr remove_reference_t<T>&& move(T&& t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{static_cast<remove_reference_t<T>\&\&>(t)}.

\pnum
\begin{example}
\begin{codeblock}
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);                // ``\tcode{a}\!'' binds to \tcode{A(const A\&)}
  shared_ptr<A> sp2 = factory<A>(std::move(a));     // ``\tcode{a}\!'' binds to \tcode{A(A\&\&)}
}
\end{codeblock}
In the first call to \tcode{factory},
\tcode{A1} is deduced as \tcode{A\&}, so \tcode{a} is forwarded
as a non-const lvalue. This binds to the constructor \tcode{A(const A\&)},
which copies the value from \tcode{a}.
In the second call to \tcode{factory}, because of the call
\tcode{std::move(a)},
\tcode{A1} is deduced as \tcode{A}, so \tcode{a} is forwarded
as an rvalue. This binds to the constructor \tcode{A(A\&\&)},
which moves the value from \tcode{a}.
\end{example}
\end{itemdescr}

\indexlibraryglobal{move_if_noexcept}%
\begin{itemdecl}
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;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(x)}.
\end{itemdescr}

\rSec2[utility.as.const]{Function template \tcode{as_const}}

\indexlibraryglobal{as_const}%
\begin{itemdecl}
template<class T> constexpr add_const_t<T>& as_const(T& t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{t}.
\end{itemdescr}

\rSec2[declval]{Function template \tcode{declval}}

\pnum
The library provides the function template \tcode{declval} to simplify the definition of
expressions which occur as unevaluated operands\iref{term.unevaluated.operand}.

\indexlibraryglobal{declval}%
\begin{itemdecl}
template<class T> add_rvalue_reference_t<T> declval() noexcept;    // as unevaluated operand
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
This function is not odr-used\iref{term.odr.use}.

\pnum
\remarks
The template parameter \tcode{T} of \tcode{declval} may be an incomplete type.

\pnum
\begin{example}
\begin{codeblock}
template<class To, class From> decltype(static_cast<To>(declval<From>())) convert(From&&);
\end{codeblock}
declares a function template \tcode{convert} which only participates in overload resolution if the
type \tcode{From} can be explicitly converted to type \tcode{To}. For another example see class
template \tcode{common_type}\iref{meta.trans.other}.
\end{example}
\end{itemdescr}

\rSec2[utility.intcmp]{Integer comparison functions}

\indexlibraryglobal{cmp_equal}%
\begin{itemdecl}
template<class T, class U>
  constexpr bool cmp_equal(T t, U u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
Both \tcode{T} and \tcode{U} are standard integer types or
extended integer types\iref{basic.fundamental}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
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);
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{cmp_not_equal}%
\begin{itemdecl}
template<class T, class U>
  constexpr bool cmp_not_equal(T t, U u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return !cmp_equal(t, u);}
\end{itemdescr}

\indexlibraryglobal{cmp_less}%
\begin{itemdecl}
template<class T, class U>
  constexpr bool cmp_less(T t, U u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
Both \tcode{T} and \tcode{U} are standard integer types or
extended integer types\iref{basic.fundamental}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
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);
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{cmp_greater}%
\begin{itemdecl}
template<class T, class U>
  constexpr bool cmp_greater(T t, U u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return cmp_less(u, t);}
\end{itemdescr}

\indexlibraryglobal{cmp_less_equal}%
\begin{itemdecl}
template<class T, class U>
  constexpr bool cmp_less_equal(T t, U u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return !cmp_greater(t, u);}
\end{itemdescr}

\indexlibraryglobal{cmp_greater_equal}%
\begin{itemdecl}
template<class T, class U>
  constexpr bool cmp_greater_equal(T t, U u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return !cmp_less(t, u);}
\end{itemdescr}

\indexlibraryglobal{in_range}%
\begin{itemdecl}
template<class R, class T>
  constexpr bool in_range(T t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
Both \tcode{T} and \tcode{R} are standard integer types or
extended integer types\iref{basic.fundamental}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return cmp_greater_equal(t, numeric_limits<R>::min()) &&
       cmp_less_equal(t, numeric_limits<R>::max());
\end{codeblock}
\end{itemdescr}

\pnum
\begin{note}
These function templates cannot be used to compare
\tcode{byte},
\tcode{char},
\keyword{char8_t},
\keyword{char16_t},
\keyword{char32_t},
\keyword{wchar_t}, and
\tcode{bool}.
\end{note}

\rSec2[utility.underlying]{Function template \tcode{to_underlying}}

\indexlibraryglobal{to_underlying}%
\begin{itemdecl}
template<class T>
  constexpr underlying_type_t<T> to_underlying(T value) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{static_cast<underlying_type_t<T>>(value)}.
\end{itemdescr}

\rSec2[utility.undefined]{Undefined behavior}

\indexlibraryglobal{unreachable}%
\begin{itemdecl}
[[noreturn]] void unreachable();
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{false} is \tcode{true}.
\begin{note}
This precondition cannot be satisfied, thus the behavior
of calling \tcode{unreachable} is undefined.
\end{note}

\pnum
\begin{example}
\begin{codeblock}
int f(int x) {
  switch (x) {
  case 0:
  case 1:
    return x;
  default:
    std::unreachable();
  }
}
int a = f(1);           // OK, \tcode{a} has value \tcode{1}
int b = f(3);           // undefined behavior
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{observable}%
\begin{itemdecl}
void observable() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Establishes an observable checkpoint\iref{intro.abstract}.
\end{itemdescr}

\rSec1[pairs]{Pairs}

\rSec2[pairs.general]{General}

\pnum
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 \tcode{pair}
objects as if they were \tcode{tuple} objects (see~\ref{tuple.helper}
and~\ref{tuple.elem}).%
\indexlibraryglobal{pair}%
\indextext{\idxcode{pair}!tuple interface to}%
\indextext{\idxcode{tuple}!and pair@and \tcode{pair}}%

\rSec2[pairs.pair]{Class template \tcode{pair}}

\indexlibraryglobal{pair}%
\begin{codeblock}
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(@\seebelow@) pair();
    constexpr explicit(@\seebelow@) pair(const T1& x, const T2& y);
    template<class U1 = T1, class U2 = T2>
      constexpr explicit(@\seebelow@) pair(U1&& x, U2&& y);
    template<class U1, class U2>
      constexpr explicit(@\seebelow@) pair(pair<U1, U2>& p);
    template<class U1, class U2>
      constexpr explicit(@\seebelow@) pair(const pair<U1, U2>& p);
    template<class U1, class U2>
      constexpr explicit(@\seebelow@) pair(pair<U1, U2>&& p);
    template<class U1, class U2>
      constexpr explicit(@\seebelow@) pair(const pair<U1, U2>&& p);
    template<@\exposconcept{pair-like}@ P>
      constexpr explicit(@\seebelow@) 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(@\seebelow@);
    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<@\exposconcept{pair-like}@ P>
      constexpr pair& operator=(P&& p);
    template<@\exposconcept{pair-like}@ P>
      constexpr const pair& operator=(P&& p) const;

    constexpr void swap(pair& p) noexcept(@\seebelow@);
    constexpr void swap(const pair& p) const noexcept(@\seebelow@);
  };

  template<class T1, class T2>
    pair(T1, T2) -> pair<T1, T2>;
}
\end{codeblock}

\pnum
Constructors and member functions of \tcode{pair} do not throw exceptions unless one of
the element-wise operations specified to be called for that operation
throws an exception.

\pnum
The defaulted move and copy constructor, respectively, of \tcode{pair}
is a constexpr function if and only if all required element-wise
initializations for move and copy, respectively,
would be constexpr-suitable\iref{dcl.constexpr}.

\pnum
If \tcode{(is_trivially_destructible_v<T1> \&\& is_trivially_destructible_v<T2>)}
is \tcode{true}, then the destructor of \tcode{pair} is trivial.

\pnum
\tcode{pair<T, U>} is a structural type\iref{term.structural.type}
if \tcode{T} and \tcode{U} are both structural types.
Two values \tcode{p1} and \tcode{p2} of type \tcode{pair<T, U>}
are template-argument-equivalent\iref{temp.type} if and only if
\tcode{p1.first} and \tcode{p2.first} are template-argument-equivalent and
\tcode{p1.second} and \tcode{p2.second} are template-argument-equivalent.

\indexlibraryctor{pair}%
\begin{itemdecl}
constexpr explicit(@\seebelow@) pair();
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_default_constructible_v<T1>} is \tcode{true} and
\item \tcode{is_default_constructible_v<T2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Value-initializes \tcode{first} and \tcode{second}.

\pnum
\remarks
The expression inside \keyword{explicit} evaluates to \tcode{true}
if and only if either \tcode{T1} or
\tcode{T2} is not implicitly default-constructible.
\begin{note}
This behavior can be implemented with a trait that checks
whether a \tcode{const T1\&} or a \tcode{const T2\&}
can be initialized with \tcode{\{\}}.
\end{note}
\end{itemdescr}

\indexlibraryctor{pair}%
\begin{itemdecl}
constexpr explicit(@\seebelow@) pair(const T1& x, const T2& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_copy_constructible_v<T1>} is \tcode{true} and
\item \tcode{is_copy_constructible_v<T2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Initializes \tcode{first} with \tcode{x} and \tcode{second} with \tcode{y}.

\pnum
\remarks
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<const T1&, T1> || !is_convertible_v<const T2&, T2>
\end{codeblock}
\end{itemdescr}

\indexlibraryctor{pair}%
\begin{itemdecl}
template<class U1 = T1, class U2 = T2> constexpr explicit(@\seebelow@) pair(U1&& x, U2&& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<T1, U1>} is \tcode{true} and
\item \tcode{is_constructible_v<T2, U2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Initializes \tcode{first} with
\tcode{std::forward<U1>(x)} and \tcode{second}
with \tcode{std::forward<U2>(y)}.

\pnum
\remarks
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<U1, T1> || !is_convertible_v<U2, T2>
\end{codeblock}
This constructor is defined as deleted if
\tcode{reference_constructs_from_temporary_v<first_type, U1\&\&>}
is \tcode{true} or
\tcode{reference_constructs_from_temporary_v<second_type, U2\&\&>}
is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{pair}%
\begin{itemdecl}
template<class U1, class U2> constexpr explicit(@\seebelow@) pair(pair<U1, U2>& p);
template<class U1, class U2> constexpr explicit(@\seebelow@) pair(const pair<U1, U2>& p);
template<class U1, class U2> constexpr explicit(@\seebelow@) pair(pair<U1, U2>&& p);
template<class U1, class U2> constexpr explicit(@\seebelow@) pair(const pair<U1, U2>&& p);
template<@\exposconcept{pair-like}@ P> constexpr explicit(@\seebelow@) pair(P&& p);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{\exposid{FWD}(u)} be \tcode{static_cast<decltype(u)>(u)}.

\pnum
\constraints
\begin{itemize}
\item
For the last overload,
\tcode{remove_cvref_t<P>} is not a specialization of \tcode{ranges::subrange},
\item
\tcode{is_constructible_v<T1, decltype(get<0>(\exposid{FWD}(p)))>}
is \tcode{true}, and
\item
\tcode{is_constructible_v<T2, decltype(get<1>(\exposid{FWD}(p)))>}
is \tcode{true}.
\end{itemize}

\pnum
\effects
Initializes \tcode{first} with \tcode{get<0>(\exposid{FWD}(p))} and
\tcode{second} with \tcode{get<1>(\exposid{FWD}(p))}.

\pnum
\remarks
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<decltype(get<0>(@\exposid{FWD}@(p))), T1> ||
!is_convertible_v<decltype(get<1>(@\exposid{FWD}@(p))), T2>
\end{codeblock}
The constructor is defined as deleted if
\begin{codeblock}
reference_constructs_from_temporary_v<first_type, decltype(get<0>(@\exposid{FWD}@(p)))> ||
reference_constructs_from_temporary_v<second_type, decltype(get<1>(@\exposid{FWD}@(p)))>
\end{codeblock}
is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{pair}%
\begin{itemdecl}
template<class... Args1, class... Args2>
  constexpr pair(piecewise_construct_t,
                 tuple<Args1...> first_args, tuple<Args2...> second_args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\begin{itemize}
\item \tcode{is_constructible_v<T1, Args1...>} is \tcode{true} and
\item \tcode{is_constructible_v<T2, Args2...>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Initializes \tcode{first} with arguments of types
\tcode{Args1...} obtained by forwarding the elements of \tcode{first_args}
and initializes \tcode{second} with arguments of types \tcode{Args2...}
obtained by forwarding the elements of \tcode{second_args}. (Here, forwarding
an element \tcode{x} of type \tcode{U} within a \tcode{tuple} object means calling
\tcode{std::forward<U>(x)}.) This form of construction, whereby constructor
arguments for \tcode{first} and \tcode{second} are each provided in a separate
\tcode{tuple} object, is called \defn{piecewise construction}.
\begin{note}
If a data member of \tcode{pair} is of reference type and
its initialization binds it to a temporary object,
the program is ill-formed\iref{class.base.init}.
\end{note}
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
constexpr pair& operator=(const pair& p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Assigns \tcode{p.first} to \tcode{first} and \tcode{p.second} to \tcode{second}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
This operator is defined as deleted unless
\tcode{is_copy_assignable_v<T1>} is \tcode{true} and
\tcode{is_copy_assignable_v<T2>} is \tcode{true}.
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
constexpr const pair& operator=(const pair& p) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_copy_assignable_v<const T1>} is \tcode{true} and
\item
\tcode{is_copy_assignable_v<const T2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{p.first} to \tcode{first} and \tcode{p.second} to \tcode{second}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
template<class U1, class U2> constexpr pair& operator=(const pair<U1, U2>& p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_assignable_v<T1\&, const U1\&>} is \tcode{true} and
\item \tcode{is_assignable_v<T2\&, const U2\&>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{p.first} to \tcode{first} and \tcode{p.second} to \tcode{second}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
template<class U1, class U2> constexpr const pair& operator=(const pair<U1, U2>& p) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_assignable_v<const T1\&, const U1\&>} is \tcode{true}, and
\item
\tcode{is_assignable_v<const T2\&, const U2\&>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{p.first} to \tcode{first} and \tcode{p.second} to \tcode{second}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
constexpr pair& operator=(pair&& p) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_move_assignable_v<T1>} is \tcode{true} and
\item \tcode{is_move_assignable_v<T2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{std::forward<T1>(p.first)} to \tcode{first} and
\tcode{std::forward<T2>(p.second)} to \tcode{second}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The exception specification is equivalent to:
\begin{codeblock}
is_nothrow_move_assignable_v<T1> && is_nothrow_move_assignable_v<T2>
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
constexpr const pair& operator=(pair&& p) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_assignable_v<const T1\&, T1>} is \tcode{true} and
\item
\tcode{is_assignable_v<const T2\&, T2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{std::forward<T1>(p.first)} to \tcode{first} and
\tcode{std::forward<T2>(p.second)} to \tcode{second}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
template<class U1, class U2> constexpr pair& operator=(pair<U1, U2>&& p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_assignable_v<T1\&, U1>} is \tcode{true} and
\item \tcode{is_assignable_v<T2\&, U2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{std::forward<U1>(p.first)} \tcode{first} and
\tcode{std::forward<U2>(p.second)} to \tcode{second}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
template<@\exposconcept{pair-like}@ P> constexpr pair& operator=(P&& p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{\exposconcept{different-from}<P, pair>}\iref{range.utility.helpers}
is \tcode{true},
\item
\tcode{remove_cvref_t<P>} is not a specialization of \tcode{ranges::subrange},
\item
\tcode{is_assignable_v<T1\&, decltype(get<0>(std::forward<P>(p)))>}
is \tcode{true}, and
\item
\tcode{is_assignable_v<T2\&, decltype(get<1>(std::forward<P>(p)))>}
is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{get<0>(std::forward<P>(p))} to \tcode{first} and
\tcode{get<1>(std::forward<P>(p))} to \tcode{sec\-ond}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
template<@\exposconcept{pair-like}@ P> constexpr const pair& operator=(P&& p) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{\exposconcept{different-from}<P, pair>}\iref{range.utility.helpers}
is \tcode{true},
\item
\tcode{remove_cvref_t<P>} is not a specialization of \tcode{ranges::subrange},
\item
\tcode{is_assignable_v<const T1\&, decltype(get<0>(std::forward<P>(p)))>}
is \tcode{true}, and
\item
\tcode{is_assignable_v<const T2\&, decltype(get<1>(std::forward<P>(p)))>}
is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{get<0>(std::forward<P>(p))} to \tcode{first} and
\tcode{get<1>(std::forward<P>(p))} to \tcode{sec\-ond}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{pair}%
\begin{itemdecl}
template<class U1, class U2> constexpr const pair& operator=(pair<U1, U2>&& p) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_assignable_v<const T1\&, U1>} is \tcode{true}, and
\item
\tcode{is_assignable_v<const T2\&, U2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{std::forward<U1>(p.first)} to \tcode{first} and
\tcode{std::forward<U2>(u.second)} to \tcode{second}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{swap}{pair}%
\begin{itemdecl}
constexpr void swap(pair& p) noexcept(@\seebelow@);
constexpr void swap(const pair& p) const noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\begin{itemize}
\item
For the first overload,
\tcode{is_swappable_v<T1>} is \tcode{true} and
\tcode{is_swappable_v<T2>} is \tcode{true}.
\item
For the second overload,
\tcode{is_swappable_v<const T1>} is \tcode{true} and
\tcode{is_swappable_v<const T2>} is \tcode{true}.
\end{itemize}

\pnum
\expects
\tcode{first} is swappable with\iref{swappable.requirements} \tcode{p.first} and
\tcode{second} is swappable with \tcode{p.second}.

\pnum
\effects
Swaps
\tcode{first} with \tcode{p.first} and
\tcode{second} with \tcode{p.second}.

\pnum
\remarks
The exception specification is equivalent to:
\begin{itemize}
\item
\tcode{is_nothrow_swappable_v<T1> \&\& is_nothrow_swappable_v<T2>}
for the first overload, and
\item
\tcode{is_nothrow_swappable_v<const T1> \&\& is_nothrow_swappable_v<const T2>}
for the second overload.
\end{itemize}
\end{itemdescr}

\rSec2[pairs.spec]{Specialized algorithms}

\indexlibrarymember{operator==}{pair}%
\begin{itemdecl}
template<class T1, class T2, class U1, class U2>
  constexpr bool operator==(const pair<T1, T2>& x, const pair<U1, U2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{x.first == y.first} and \tcode{x.second == y.second} are
valid expressions and
each of \tcode{decltype(x.first == y.first)} and
\tcode{decltype(x.second == y.second)} models \exposconceptx{boolean-\newline testable}{boolean-testable}.

\pnum
\returns
\tcode{x.first == y.first \&\& x.second == y.second}.
\end{itemdescr}

\indexlibrarymember{operator<=>}{pair}%
\begin{itemdecl}
template<class T1, class T2, class U1, class U2>
  constexpr common_comparison_category_t<@\placeholder{synth-three-way-result}@<T1, U1>,
                                         @\placeholder{synth-three-way-result}@<T2, U2>>
    operator<=>(const pair<T1, T2>& x, const pair<U1, U2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
if (auto c = @\placeholdernc{synth-three-way}@(x.first, y.first); c != 0) return c;
return @\placeholdernc{synth-three-way}@(x.second, y.second);
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{swap}{pair}%
\begin{itemdecl}
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)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
For the first overload,
\tcode{is_swappable_v<T1>} is \tcode{true} and
\tcode{is_swappable_v<T2>} is \tcode{true}.
\item
For the second overload,
\tcode{is_swappable_v<const T1>} is \tcode{true} and
\tcode{is_swappable_v<const T2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Equivalent to \tcode{x.swap(y)}.
\end{itemdescr}

\indexlibraryglobal{make_pair}%
\begin{itemdecl}
template<class T1, class T2>
  constexpr pair<unwrap_ref_decay_t<T1>, unwrap_ref_decay_t<T2>> make_pair(T1&& x, T2&& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\begin{codeblock}
pair<unwrap_ref_decay_t<T1>,
     unwrap_ref_decay_t<T2>>(std::forward<T1>(x), std::forward<T2>(y))
\end{codeblock}
\end{itemdescr}

\pnum
\begin{example}
In place of:
\begin{codeblock}
return pair<int, double>(5, 3.1415926);     // explicit types
\end{codeblock}
a \Cpp{} program may contain:
\begin{codeblock}
return make_pair(5, 3.1415926);             // types are deduced
\end{codeblock}
\end{example}

\rSec2[pair.astuple]{Tuple-like access to pair}

\indexlibraryglobal{tuple_size}%
\begin{itemdecl}
template<class T1, class T2>
  struct tuple_size<pair<T1, T2>> : integral_constant<size_t, 2> { };
\end{itemdecl}

\indexlibraryglobal{tuple_element}%
\begin{itemdecl}
template<size_t I, class T1, class T2>
  struct tuple_element<I, pair<T1, T2>> {
    using type = @\seebelow@ ;
  };
\end{itemdecl}
\begin{itemdescr}
\pnum
\mandates
$\tcode{I} < 2$.

\pnum
\ctype
The type \tcode{T1} if \tcode{I} is 0, otherwise the type \tcode{T2}.
\end{itemdescr}

\indexlibrarymember{get}{pair}%
\begin{itemdecl}
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;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
$\tcode{I} < 2$.

\pnum
\returns
\begin{itemize}
\item If \tcode{I} is 0, returns a reference to \tcode{p.first}.
\item If \tcode{I} is 1, returns a reference to \tcode{p.second}.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{get}{pair}%
\begin{itemdecl}
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;
\end{itemdecl}

\begin{itemdescr}
% FIXME: This appears to be redundant: we can never select any of these
% functions if T1 and T2 are the same type, due to ambiguity with the
% overloads below.
\pnum
\mandates
\tcode{T1} and \tcode{T2} are distinct types.

\pnum
\returns
A reference to \tcode{p.first}.
\end{itemdescr}

\indexlibrarymember{get}{pair}%
\begin{itemdecl}
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;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{T1} and \tcode{T2} are distinct types.

\pnum
\returns
A reference to \tcode{p.second}.
\end{itemdescr}

\rSec2[pair.piecewise]{Piecewise construction}

\indexlibraryglobal{piecewise_construct_t}%
\indexlibraryglobal{piecewise_construct}%
\begin{itemdecl}
struct piecewise_construct_t {
  explicit piecewise_construct_t() = default;
};
inline constexpr piecewise_construct_t piecewise_construct{};
\end{itemdecl}

\pnum
The \keyword{struct} \tcode{piecewise_construct_t} is an empty class type
used as a unique type to disambiguate constructor and function overloading. Specifically,
\tcode{pair} has a constructor with \tcode{piecewise_construct_t} as the
first argument, immediately followed by two \tcode{tuple}\iref{tuple} arguments used
for piecewise construction of the elements of the \tcode{pair} object.

\rSec1[tuple]{Tuples}

\rSec2[tuple.general]{General}

\pnum
\indexlibraryglobal{tuple}%
Subclause~\ref{tuple} describes the tuple library that provides a tuple type as
the class template \tcode{tuple} that can be instantiated with any number
of arguments. Each template argument specifies
the type of an element in the \tcode{tuple}.  Consequently, tuples are
heterogeneous, fixed-size collections of values. An instantiation of \tcode{tuple} with
two arguments is similar to an instantiation of \tcode{pair} with the same two arguments.
See~\ref{pairs}.

\pnum
In addition to being available via inclusion of the \libheader{tuple} header,
\tcode{ignore}\iref{tuple.syn} is available when
\libheader{utility}\iref{utility} is included.

\rSec2[tuple.syn]{Header \tcode{<tuple>} synopsis}

\indexheader{tuple}%
\begin{codeblock}
// all freestanding
#include <compare>              // see \ref{compare.syn}

namespace std {
  // \ref{tuple.tuple}, class template \tcode{tuple}
  template<class... Types>
    class tuple;

  // \ref{tuple.like}, concept \exposconcept{tuple-like}
  template<class T>
    concept @\exposconcept{tuple-like}@ = @\seebelownc@;         // \expos
  template<class T>
    concept @\defexposconcept{pair-like}@ =                     // \expos
      @\exposconcept{tuple-like}@<T> && tuple_size_v<remove_cvref_t<T>> == 2;

  // \ref{tuple.common.ref}, \tcode{common_reference} related specializations
  template<@\exposconceptnc{tuple-like}@ TTuple, @\exposconceptnc{tuple-like}@ UTuple,
           template<class> class TQual, template<class> class UQual>
    struct basic_common_reference<TTuple, UTuple, TQual, UQual>;
  template<@\exposconceptnc{tuple-like}@ TTuple, @\exposconceptnc{tuple-like}@ UTuple>
    struct common_type<TTuple, UTuple>;

  // \tcode{ignore}
  struct @\exposidnc{ignore-type}@ {                      // \expos
    constexpr const @\exposid{ignore-type}@
      operator=(const auto &) const noexcept { return *this; }
  };
  inline constexpr @\exposid{ignore-type}@ ignore;

  // \ref{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<@\exposconceptnc{tuple-like}@... Tuples>
    constexpr tuple<CTypes...> tuple_cat(Tuples&&...);

  // \ref{tuple.apply}, calling a function with a tuple of arguments
  template<class F, @\exposconceptnc{tuple-like}@ Tuple>
    constexpr decltype(auto) apply(F&& f, Tuple&& t) noexcept(@\seebelow@);

  template<class T, @\exposconceptnc{tuple-like}@ Tuple>
    constexpr T make_from_tuple(Tuple&& t);

  // \ref{tuple.helper}, tuple helper classes
  template<class T> struct tuple_size;                  // \notdef
  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;     // \notdef
  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 @\libglobal{tuple_element_t}@ = typename tuple_element<I, T>::type;

  // \ref{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;

  // \ref{tuple.rel}, relational operators
  template<class... TTypes, class... UTypes>
    constexpr bool operator==(const tuple<TTypes...>&, const tuple<UTypes...>&);
  template<class... TTypes, @\exposconceptnc{tuple-like}@ UTuple>
    constexpr bool operator==(const tuple<TTypes...>&, const UTuple&);
  template<class... TTypes, class... UTypes>
    constexpr common_comparison_category_t<@\placeholdernc{synth-three-way-result}@<TTypes, UTypes>...>
      operator<=>(const tuple<TTypes...>&, const tuple<UTypes...>&);
  template<class... TTypes, @\exposconceptnc{tuple-like}@ UTuple>
    constexpr @\seebelownc@ operator<=>(const tuple<TTypes...>&, const UTuple&);

  // \ref{tuple.traits}, allocator-related traits
  template<class... Types, class Alloc>
    struct uses_allocator<tuple<Types...>, Alloc>;

  // \ref{tuple.special}, specialized algorithms
  template<class... Types>
    constexpr void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(@\seebelow@);
  template<class... Types>
    constexpr void swap(const tuple<Types...>& x, const tuple<Types...>& y) noexcept(@\seebelow@);

  // \ref{tuple.helper}, tuple helper classes
  template<class T>
    constexpr size_t @\libglobal{tuple_size_v}@ = tuple_size<T>::value;
}
\end{codeblock}

\rSec2[tuple.like]{Concept \ecname{tuple-like}}

\begin{itemdecl}
template<class T>
  concept @\defexposconcept{tuple-like}@ = @\seebelownc@;           // \expos
\end{itemdecl}

\begin{itemdescr}
\pnum
A type \tcode{T} models and satisfies
the exposition-only concept \exposconcept{tuple-like}
if \tcode{remove_cvref_t<T>} is a specialization of
\tcode{array}, \tcode{complex}, \tcode{pair}, \tcode{tuple}, or \tcode{ranges::subrange}.
\end{itemdescr}

\rSec2[tuple.tuple]{Class template \tcode{tuple}}

\rSec3[tuple.tuple.general]{General}

\indexlibraryglobal{tuple}%
\begin{codeblock}
namespace std {
  template<class... Types>
  class tuple {
  public:
    // \ref{tuple.cnstr}, \tcode{tuple} construction
    constexpr explicit(@\seebelow@) tuple();
    constexpr explicit(@\seebelow@) tuple(const Types&...);         // only if \tcode{sizeof...(Types) >= 1}
    template<class... UTypes>
      constexpr explicit(@\seebelow@) tuple(UTypes&&...);           // only if \tcode{sizeof...(Types) >= 1}

    tuple(const tuple&) = default;
    tuple(tuple&&) = default;

    template<class... UTypes>
      constexpr explicit(@\seebelow@) tuple(tuple<UTypes...>&);
    template<class... UTypes>
      constexpr explicit(@\seebelow@) tuple(const tuple<UTypes...>&);
    template<class... UTypes>
      constexpr explicit(@\seebelow@) tuple(tuple<UTypes...>&&);
    template<class... UTypes>
      constexpr explicit(@\seebelow@) tuple(const tuple<UTypes...>&&);

    template<class U1, class U2>
      constexpr explicit(@\seebelow@) tuple(pair<U1, U2>&);         // only if \tcode{sizeof...(Types) == 2}
    template<class U1, class U2>
      constexpr explicit(@\seebelow@) tuple(const pair<U1, U2>&);   // only if \tcode{sizeof...(Types) == 2}
    template<class U1, class U2>
      constexpr explicit(@\seebelow@) tuple(pair<U1, U2>&&);        // only if \tcode{sizeof...(Types) == 2}
    template<class U1, class U2>
      constexpr explicit(@\seebelow@) tuple(const pair<U1, U2>&&);  // only if \tcode{sizeof...(Types) == 2}

    template<@\exposconcept{tuple-like}@ UTuple>
      constexpr explicit(@\seebelow@) tuple(UTuple&&);

    // allocator-extended constructors
    template<class Alloc>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a);
    template<class Alloc>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, const Types&...);
    template<class Alloc, class... UTypes>
      constexpr explicit(@\seebelow@)
        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(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&);
    template<class Alloc, class... UTypes>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&);
    template<class Alloc, class... UTypes>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
    template<class Alloc, class... UTypes>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&&);
    template<class Alloc, class U1, class U2>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&);
    template<class Alloc, class U1, class U2>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
    template<class Alloc, class U1, class U2>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&);
    template<class Alloc, class U1, class U2>
      constexpr explicit(@\seebelow@)
        tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&&);

    template<class Alloc, @\exposconceptnc{tuple-like}@ UTuple>
      constexpr explicit(@\seebelow@) tuple(allocator_arg_t, const Alloc& a, UTuple&&);

    // \ref{tuple.assign}, \tcode{tuple} assignment
    constexpr tuple& operator=(const tuple&);
    constexpr const tuple& operator=(const tuple&) const;
    constexpr tuple& operator=(tuple&&) noexcept(@\seebelow@);
    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 \tcode{sizeof...(Types) == 2}
    template<class U1, class U2>
      constexpr const tuple& operator=(const pair<U1, U2>&) const;
                                                                // only if \tcode{sizeof...(Types) == 2}
    template<class U1, class U2>
      constexpr tuple& operator=(pair<U1, U2>&&);               // only if \tcode{sizeof...(Types) == 2}
    template<class U1, class U2>
      constexpr const tuple& operator=(pair<U1, U2>&&) const;   // only if \tcode{sizeof...(Types) == 2}

    template<@\exposconceptnc{tuple-like}@ UTuple>
      constexpr tuple& operator=(UTuple&&);
    template<@\exposconceptnc{tuple-like}@ UTuple>
      constexpr const tuple& operator=(UTuple&&) const;

    // \ref{tuple.swap}, \tcode{tuple} swap
    constexpr void swap(tuple&) noexcept(@\seebelow@);
    constexpr void swap(const tuple&) const noexcept(@\seebelow@);
  };

  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...>;
}
\end{codeblock}

\pnum
If a program declares an explicit or partial specialization of \tcode{tuple},
the program is ill-formed, no diagnostic required.

\rSec3[tuple.cnstr]{Construction}

\pnum
In the descriptions that follow, let $i$ be in the range
\range{0}{sizeof...(Types)} in order, $\tcode{T}_i$
be the $i^\text{th}$ type in \tcode{Types}, and
$\tcode{U}_i$ be the $i^\text{th}$ type in a template parameter pack named \tcode{UTypes}, where indexing
is zero-based.

\pnum
For each \tcode{tuple} constructor, an exception is thrown only if the construction of
one of the types in \tcode{Types} throws an exception.

\pnum
The defaulted move and copy constructor, respectively, of
\tcode{tuple} is a constexpr function if and only if all
required element-wise initializations for move and copy, respectively,
would be constexpr-suitable\iref{dcl.constexpr}.
The defaulted move and copy constructor of \tcode{tuple<>} are
constexpr functions.

\pnum
If \tcode{is_trivially_destructible_v<$\tcode{T}_i$>} is \tcode{true} for all $\tcode{T}_i$,
then the destructor of \tcode{tuple} is trivial.

\pnum
The default constructor of \tcode{tuple<>} is trivial.

\indexlibraryctor{tuple}%
\begin{itemdecl}
constexpr explicit(@\seebelow@) tuple();
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_default_constructible_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.

\pnum
\effects
Value-initializes each element.

\pnum
\remarks
The expression inside \keyword{explicit} evaluates to \tcode{true}
if and only if $\tcode{T}_i$ is not
copy-list-initializable from an empty list
for at least one $i$.
\begin{note}
This behavior can be implemented with a trait that checks whether
a \tcode{const $\tcode{T}_i$\&} can be initialized with \tcode{\{\}}.
\end{note}
\end{itemdescr}

\indexlibraryctor{tuple}%
\begin{itemdecl}
constexpr explicit(@\seebelow@) tuple(const Types&...);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
$\tcode{sizeof...(Types)} \geq 1$ and
\tcode{is_copy_constructible_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.

\pnum
\effects
Initializes each element with the value of the
corresponding parameter.

\pnum
\remarks
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!conjunction_v<is_convertible<const Types&, Types>...>
\end{codeblock}
\end{itemdescr}

\indexlibraryctor{tuple}%
\begin{itemdecl}
template<class... UTypes> constexpr explicit(@\seebelow@) tuple(UTypes&&... u);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \exposid{disambiguating-constraint} be:
\begin{itemize}
\item
\tcode{negation<is_same<remove_cvref_t<$\tcode{U}_0$>, tuple>>}
if \tcode{sizeof...(Types)} is 1;
\item
otherwise,
\tcode{bool_constant<!is_same_v<remove_cvref_t<$\tcode{U}_0$>, allocator_arg_t> ||
is_-\newline{}same_v<remove_cvref_t<$\tcode{T}_0$>, allocator_arg_t>>}
if \tcode{sizeof...(Types)} is 2 or 3;
\item
otherwise, \tcode{true_type}.
\end{itemize}

\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)},
\item
$\tcode{sizeof...(Types)} \geq 1$, and
\item
\tcode{conjunction_v<\exposid{disambiguating-constraint},
is_constructible<Types, UTypes>...>} is\newline \tcode{true}.
\end{itemize}

\pnum
\effects
Initializes the elements in the tuple with the
corresponding value in \tcode{std::forward<UTypes>(u)}.

\pnum
\remarks
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!conjunction_v<is_convertible<UTypes, Types>...>
\end{codeblock}
This constructor is defined as deleted if
\begin{codeblock}
(reference_constructs_from_temporary_v<Types, UTypes&&> || ...)
\end{codeblock}
is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{tuple}%
\begin{itemdecl}
tuple(const tuple& u) = default;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.

\pnum
\effects
Initializes each element of \tcode{*this} with the
corresponding element of \tcode{u}.
\end{itemdescr}

\indexlibraryctor{tuple}%
\begin{itemdecl}
tuple(tuple&& u) = default;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.

\pnum
\effects
For all $i$, initializes the $i^\text{th}$ element of \tcode{*this} with
\tcode{std::forward<$\tcode{T}_i$>(get<$i$>(u))}.
\end{itemdescr}

\indexlibraryctor{tuple}%
\begin{itemdecl}
template<class... UTypes> constexpr explicit(@\seebelow@) tuple(tuple<UTypes...>& u);
template<class... UTypes> constexpr explicit(@\seebelow@) tuple(const tuple<UTypes...>& u);
template<class... UTypes> constexpr explicit(@\seebelow@) tuple(tuple<UTypes...>&& u);
template<class... UTypes> constexpr explicit(@\seebelow@) tuple(const tuple<UTypes...>&& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{I} be the pack \tcode{0, 1, ..., (sizeof...(Types) - 1)}.\newline
Let \tcode{\exposid{FWD}(u)} be \tcode{static_cast<decltype(u)>(u)}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)}, and
\item
\tcode{(is_constructible_v<Types, decltype(get<I>(\exposid{FWD}(u)))> \&\& ...)}
is \tcode{true}, and
\item
either \tcode{sizeof...(Types)} is not 1, or
(when \tcode{Types...} expands to \tcode{T} and
\tcode{UTypes...} expands to \tcode{U})
\tcode{is_convertible_v<decltype(u), T>},
\tcode{is_constructible_v<T, decltype(u)>}, and
\tcode{is_same_v<T, U>} are all \tcode{false}.
\end{itemize}

\pnum
\effects
For all $i$, initializes the $i^\textrm{th}$ element of \tcode{*this}
with \tcode{get<$i$>(\exposid{FWD}(u))}.

\pnum
\remarks
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!(is_convertible_v<decltype(get<I>(@\exposid{FWD}@(u))), Types> && ...)
\end{codeblock}
The constructor is defined as deleted if
\begin{codeblock}
(reference_constructs_from_temporary_v<Types, decltype(get<I>(@\exposid{FWD}@(u)))> || ...)
\end{codeblock}
is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{tuple}%
\begin{itemdecl}
template<class U1, class U2> constexpr explicit(@\seebelow@) tuple(pair<U1, U2>& u);
template<class U1, class U2> constexpr explicit(@\seebelow@) tuple(const pair<U1, U2>& u);
template<class U1, class U2> constexpr explicit(@\seebelow@) tuple(pair<U1, U2>&& u);
template<class U1, class U2> constexpr explicit(@\seebelow@) tuple(const pair<U1, U2>&& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{\exposid{FWD}(u)} be \tcode{static_cast<decltype(u)>(u)}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} is 2,
\item
\tcode{is_constructible_v<$\tcode{T}_0$, decltype(get<0>(\exposid{FWD}(u)))>} is \tcode{true}, and
\item
\tcode{is_constructible_v<$\tcode{T}_1$, decltype(get<1>(\exposid{FWD}(u)))>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Initializes the first element with \tcode{get<0>(\exposid{FWD}(u))} and
the second element with \tcode{get<1>(\exposid{FWD}(\brk{}u))}.

\pnum
\remarks
The expression inside \tcode{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<decltype(get<0>(@\exposid{FWD}@(u))), @$\tcode{T}_0$@> ||
!is_convertible_v<decltype(get<1>(@\exposid{FWD}@(u))), @$\tcode{T}_1$@>
\end{codeblock}
The constructor is defined as deleted if
\begin{codeblock}
reference_constructs_from_temporary_v<@$\tcode{T}_0$@, decltype(get<0>(@\exposid{FWD}@(u)))> ||
reference_constructs_from_temporary_v<@$\tcode{T}_1$@, decltype(get<1>(@\exposid{FWD}@(u)))>
\end{codeblock}
is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{tuple}%
\begin{itemdecl}
template<@\exposconcept{tuple-like}@ UTuple>
  constexpr explicit(@\seebelow@) tuple(UTuple&& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{I} be the pack \tcode{0, 1, \ldots, (sizeof...(Types) - 1)}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{\exposconcept{different-from}<UTuple, tuple>}\iref{range.utility.helpers}
is \tcode{true},

\item
\tcode{remove_cvref_t<UTuple>}
is not a specialization of \tcode{ranges::subrange},

\item
\tcode{sizeof...(Types)}
equals \tcode{tuple_size_v<remove_cvref_t<UTuple>>},

\item
\tcode{(is_constructible_v<Types, decltype(get<I>(std::forward<UTuple>(u)))> \&\& ...)}
is\linebreak{} % Overfull
\tcode{true}, and

\item
either \tcode{sizeof...(Types)} is not 1, or
(when \tcode{Types...} expands to \tcode{T})
\tcode{is_convertible_v<UTuple, T>} and
\tcode{is_constructible_v<T, UTuple>} are both \tcode{false}.
\end{itemize}

\pnum
\effects
For all $i$, initializes the $i^\text{th}$ element of \tcode{*this} with
\tcode{get<$i$>(std::forward<UTuple>(u))}.

\pnum
\remarks
The expression inside \tcode{explicit} is equivalent to:
\begin{codeblock}
!(is_convertible_v<decltype(get<I>(std::forward<UTuple>(u))), Types> && ...)
\end{codeblock}
The constructor is defined as deleted if
\begin{codeblock}
(reference_constructs_from_temporary_v<Types, decltype(get<I>(std::forward<UTuple>(u)))>
 || ...)
\end{codeblock}
is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{tuple}%
\begin{itemdecl}
template<class Alloc>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a);
template<class Alloc>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, const Types&...);
template<class Alloc, class... UTypes>
  constexpr explicit(@\seebelow@)
    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(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&);
template<class Alloc, class... UTypes>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&);
template<class Alloc, class... UTypes>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
template<class Alloc, class... UTypes>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&&);
template<class Alloc, class U1, class U2>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&);
template<class Alloc, class U1, class U2>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
template<class Alloc, class U1, class U2>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&);
template<class Alloc, class U1, class U2>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&&);
template<class Alloc, @\exposconcept{tuple-like}@ UTuple>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, UTuple&&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{Alloc} meets
the \oldconcept{Allocator} requirements\iref{allocator.requirements.general}.

\pnum
\effects
Equivalent to the preceding constructors except that each element is constructed with
uses-allocator construction\iref{allocator.uses.construction}.
\end{itemdescr}

\rSec3[tuple.assign]{Assignment}

\pnum
For each \tcode{tuple} assignment operator, an exception is thrown only if the
assignment of one of the types in \tcode{Types} throws an exception.
In the function descriptions that follow, let $i$ be in the range \range{0}{sizeof...\brk{}(Types)}
in order, $\tcode{T}_i$ be the $i^\text{th}$ type in \tcode{Types},
and $\tcode{U}_i$ be the $i^\text{th}$ type in a
template parameter pack named \tcode{UTypes}, where indexing is zero-based.

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
constexpr tuple& operator=(const tuple& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Assigns each element of \tcode{u} to the corresponding
element of \tcode{*this}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
This operator is defined as deleted unless
\tcode{is_copy_assignable_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
constexpr const tuple& operator=(const tuple& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{(is_copy_assignable_v<const Types> \&\& ...)} is \tcode{true}.

\pnum
\effects
Assigns each element of \tcode{u} to the corresponding element of \tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
constexpr tuple& operator=(tuple&& u) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_assignable_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.

\pnum
\effects
For all $i$, assigns \tcode{std::forward<$\tcode{T}_i$>(get<$i$>(u))} to
\tcode{get<$i$>(*this)}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The exception specification is equivalent to the logical \logop{and} of the
following expressions:

\begin{codeblock}
is_nothrow_move_assignable_v<@$\mathtt{T}_i$@>
\end{codeblock}
where $\mathtt{T}_i$ is the $i^\text{th}$ type in \tcode{Types}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
constexpr const tuple& operator=(tuple&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{(is_assignable_v<const Types\&, Types> \&\& ...)} is \tcode{true}.

\pnum
\effects
For all $i$,
assigns \tcode{std::forward<T$_i$>(get<$i$>(u))} to \tcode{get<$i$>(*this)}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
template<class... UTypes> constexpr tuple& operator=(const tuple<UTypes...>& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)} and
\item \tcode{is_assignable_v<$\tcode{T}_i$\&, const $\tcode{U}_i$\&>} is \tcode{true} for all $i$.
\end{itemize}

\pnum
\effects
Assigns each element of \tcode{u} to the corresponding element
of \tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
template<class... UTypes> constexpr const tuple& operator=(const tuple<UTypes...>& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)} and
\item
\tcode{(is_assignable_v<const Types\&, const UTypes\&> \&\& ...)} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns each element of \tcode{u} to the corresponding element of \tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
template<class... UTypes> constexpr tuple& operator=(tuple<UTypes...>&& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)} and
\item \tcode{is_assignable_v<$\tcode{T}_i$\&, $\tcode{U}_i$>} is \tcode{true} for all $i$.
\end{itemize}

\pnum
\effects
For all $i$, assigns \tcode{std::forward<$\tcode{U}_i$>(get<$i$>(u))} to
\tcode{get<$i$>(*this)}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
template<class... UTypes> constexpr const tuple& operator=(tuple<UTypes...>&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)} and
\item
\tcode{(is_assignable_v<const Types\&, UTypes> \&\& ...)} is \tcode{true}.
\end{itemize}

\pnum
\effects
For all $i$,
assigns \tcode{std::forward<U$_i$>(get<$i$>(u))} to \tcode{get<$i$>(*this)}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\indexlibraryglobal{pair}%
\begin{itemdecl}
template<class U1, class U2> constexpr tuple& operator=(const pair<U1, U2>& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{sizeof...(Types)} is 2 and
\item \tcode{is_assignable_v<$\tcode{T}_0$\&, const U1\&>} is \tcode{true}, and
\item \tcode{is_assignable_v<$\tcode{T}_1$\&, const U2\&>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{u.first} to the first element of \tcode{*this}
and \tcode{u.second} to the second element of \tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
template<class U1, class U2> constexpr const tuple& operator=(const pair<U1, U2>& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} is 2,
\item
\tcode{is_assignable_v<const $\tcode{T}_0$\&, const U1\&>} is \tcode{true}, and
\item
\tcode{is_assignable_v<const $\tcode{T}_1$\&, const U2\&>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{u.first} to the first element and
\tcode{u.second} to the second element.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\indexlibraryglobal{pair}%
\begin{itemdecl}
template<class U1, class U2> constexpr tuple& operator=(pair<U1, U2>&& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{sizeof...(Types)} is 2 and
\item \tcode{is_assignable_v<$\tcode{T}_0$\&, U1>} is \tcode{true}, and
\item \tcode{is_assignable_v<$\tcode{T}_1$\&, U2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{std::forward<U1>(u.first)} to the first
element of \tcode{*this} and\\ \tcode{std::forward<U2>(u.second)} to the
second element of \tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
template<class U1, class U2> constexpr const tuple& operator=(pair<U1, U2>&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} is 2,
\item
\tcode{is_assignable_v<const $\tcode{T}_0$\&, U1>} is \tcode{true}, and
\item
\tcode{is_assignable_v<const $\tcode{T}_1$\&, U2>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Assigns \tcode{std::forward<U1>(u.first)} to the first element and\\
\tcode{std::forward<U2>(u.second)} to the second element.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
template<@\exposconcept{tuple-like}@ UTuple>
  constexpr tuple& operator=(UTuple&& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{\exposconcept{different-from}<UTuple, tuple>}\iref{range.utility.helpers}
is \tcode{true},

\item
\tcode{remove_cvref_t<UTuple>}
is not a specialization of \tcode{ranges::subrange},

\item
\tcode{sizeof...(Types)}
equals \tcode{tuple_size_v<remove_cvref_t<UTuple>>}, and

\item
\tcode{is_assignable_v<$\tcode{T}_i$\&, decltype(get<$i$>(std::forward<UTuple>(u)))>}
is \tcode{true} for all $i$.
\end{itemize}

\pnum
\effects
For all $i$, assigns \tcode{get<$i$>(std::forward<UTuple>(u))}
to \tcode{get<$i$>(*this)}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{tuple}%
\begin{itemdecl}
template<@\exposconcept{tuple-like}@ UTuple>
  constexpr const tuple& operator=(UTuple&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{\exposconcept{different-from}<UTuple, tuple>}\iref{range.utility.helpers}
is \tcode{true},

\item
\tcode{remove_cvref_t<UTuple>}
is not a specialization of \tcode{ranges::subrange},

\item
\tcode{sizeof...(Types)}
equals \tcode{tuple_size_v<remove_cvref_t<UTuple>>}, and

\item
\tcode{is_assignable_v<const $\tcode{T}_i$\&, decltype(get<$i$>(std::forward<UTuple>(u)))>}
is \tcode{true} for all $i$.
\end{itemize}

\pnum
\effects
For all $i$, assigns
\tcode{get<$i$>(std::forward<UTuple>(u))} to \tcode{get<$i$>(*this)}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\rSec3[tuple.swap]{\tcode{swap}}

\indexlibrarymember{swap}{tuple}%
\begin{itemdecl}
constexpr void swap(tuple& rhs) noexcept(@\seebelow@);
constexpr void swap(const tuple& rhs) const noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let $i$ be in the range \range{0}{sizeof...(Types)} in order.

\pnum
\mandates
\begin{itemize}
\item
For the first overload,
\tcode{(is_swappable_v<Types> \&\& ...)} is \tcode{true}.
\item
For the second overload,
\tcode{(is_swappable_v<const Types> \&\& ...)} is \tcode{true}.
\end{itemize}

\pnum
\expects
For all $i$, \tcode{get<$i$>(*this)} is swappable with\iref{swappable.requirements} \tcode{get<$i$>(rhs)}.

\pnum
\effects
For each $i$, calls \tcode{swap} for \tcode{get<$i$>(*this)} and \tcode{get<$i$>(rhs)}.

\pnum
\throws
Nothing unless one of the element-wise \tcode{swap} calls throws an exception.

\pnum
\remarks
The exception specification is equivalent to
\begin{itemize}
\item
\tcode{(is_nothrow_swappable_v<Types> \&\& ...)} for the first overload and
\item
\tcode{(is_nothrow_swappable_v<const Types> \&\& ...)} for the second overload.
\end{itemize}
\end{itemdescr}

\rSec2[tuple.creation]{Tuple creation functions}

\indexlibraryglobal{make_tuple}%
\indexlibrarymember{tuple}{make_tuple}%
\begin{itemdecl}
template<class... TTypes>
  constexpr tuple<unwrap_ref_decay_t<TTypes>...> make_tuple(TTypes&&... t);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{tuple<unwrap_ref_decay_t<TTypes>...>(std::forward<TTypes>(t)...)}.

\pnum
\begin{example}
\begin{codeblock}
int i; float j;
make_tuple(1, ref(i), cref(j));
\end{codeblock}
creates a tuple of type \tcode{tuple<int, int\&, const float\&>}.
\end{example}
\end{itemdescr}

\indexlibraryglobal{forward_as_tuple}%
\indexlibrarymember{tuple}{forward_as_tuple}%
\begin{itemdecl}
template<class... TTypes>
  constexpr tuple<TTypes&&...> forward_as_tuple(TTypes&&... t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a tuple of references to the arguments in \tcode{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).

\pnum
\returns
\tcode{tuple<TTypes\&\&...>(std::forward<TTypes>(t)...)}.
\end{itemdescr}

\indexlibraryglobal{tie}%
\indexlibraryglobal{ignore}%
\indexlibrarymember{tuple}{tie}%
\begin{itemdecl}
template<class... TTypes>
  constexpr tuple<TTypes&...> tie(TTypes&... t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{tuple<TTypes\&...>(t...)}.

\pnum
\begin{example}
\tcode{tie} functions allow one to create tuples that unpack
tuples into variables. \tcode{ignore} can be used for elements that
are not needed:
\begin{codeblock}
int i; std::string s;
tie(i, ignore, s) = make_tuple(42, 3.14, "C++");
// \tcode{i == 42}, \tcode{s == "C++"}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{tuple_cat}
\begin{itemdecl}
template<@\exposconcept{tuple-like}@... Tuples>
  constexpr tuple<CTypes...> tuple_cat(Tuples&&... tpls);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let $n$ be \tcode{sizeof...(Tuples)}.
For every integer $0 \leq i < n$:
\begin{itemize}
\item
Let $\tcode{T}_i$ be the $i^\text{th}$ type in \tcode{Tuples}.
\item
Let $\tcode{U}_i$ be \tcode{remove_cvref_t<$\tcode{T}_i$>}.
\item
Let $\tcode{tp}_i$ be the $i^\text{th}$ element
in the function parameter pack \tcode{tpls}.
\item
Let $S_i$ be \tcode{tuple_size_v<$\tcode{U}_i$>}.
\item
Let $E_i^k$ be \tcode{tuple_element_t<$k$, $\tcode{U}_i$>}.
\item
Let $e_i^k$ be \tcode{get<$k$>(std::forward<$\tcode{T}_i$>($\tcode{tp}_i$))}.
\item
Let $Elems_i$ be a pack of the types $E_i^0, \dotsc, E_i^{S_{i-1}}$.
\item
Let $elems_i$ be a pack of the expressions $e_i^0, \dotsc, e_i^{S_{i-1}}$.
\end{itemize}
The types in \tcode{CTypes} are equal to the ordered sequence of
the expanded packs of types
\tcode{$Elems_0$...}, \tcode{$Elems_1$...}, \ldots, \tcode{$Elems_{n-1}$...}.
Let \tcode{celems} be the ordered sequence of
the expanded packs of expressions
\tcode{$elems_0$...}, \ldots, \tcode{$elems_{n-1}$...}.

\pnum
\mandates
\tcode{(is_constructible_v<CTypes, decltype(celems)> \&\& ...)} is \tcode{true}.

\pnum
\returns
\tcode{tuple<CTypes...>(celems...)}.
\end{itemdescr}

\rSec2[tuple.apply]{Calling a function with a \tcode{tuple} of arguments}

\indexlibraryglobal{apply}%
\begin{itemdecl}
template<class F, @\exposconcept{tuple-like}@ Tuple>
  constexpr decltype(auto) apply(F&& f, Tuple&& t) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Given the exposition-only function template:
\begin{codeblock}
namespace std {
  template<class F, @\exposconcept{tuple-like}@ Tuple, size_t... I>
  constexpr decltype(auto) @\placeholdernc{apply-impl}@(F&& f, Tuple&& t, index_sequence<I...>) {
                                                                        // \expos
    return @\placeholdernc{INVOKE}@(std::forward<F>(f), get<I>(std::forward<Tuple>(t))...);     // see \ref{func.require}
  }
}
\end{codeblock}
Equivalent to:
\begin{codeblock}
return @\placeholdernc{apply-impl}@(std::forward<F>(f), std::forward<Tuple>(t),
                  make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
\end{codeblock}

\pnum
\remarks
Let \tcode{I} be the pack
\tcode{0, 1, ..., (tuple_size_v<remove_reference_t<Tuple>> - 1)}.
The exception specification is equivalent to:
\begin{codeblock}
noexcept(invoke(std::forward<F>(f), get<I>(std::forward<Tuple>(t))...))
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{make_from_tuple}%
\begin{itemdecl}
template<class T, @\exposconcept{tuple-like}@ Tuple>
  constexpr T make_from_tuple(Tuple&& t);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
If \tcode{tuple_size_v<remove_reference_t<Tuple>>} is 1,
then
\tcode{reference_constructs_from_temporary_v<T, decltype(get<0>(declval<Tuple>()))>}
is \tcode{false}.

\pnum
\effects
Given the exposition-only function template:
\begin{codeblock}
namespace std {
  template<class T, @\exposconcept{tuple-like}@ Tuple, size_t... I>
    requires is_constructible_v<T, decltype(get<I>(declval<Tuple>()))...>
  constexpr T @\placeholdernc{make-from-tuple-impl}@(Tuple&& t, index_sequence<I...>) {   // \expos
    return T(get<I>(std::forward<Tuple>(t))...);
  }
}
\end{codeblock}
Equivalent to:
\begin{codeblock}
return @\placeholdernc{make-from-tuple-impl}@<T>(
           std::forward<Tuple>(t),
           make_index_sequence<tuple_size_v<remove_reference_t<Tuple>>>{});
\end{codeblock}
\begin{note}
The type of \tcode{T} must be supplied
as an explicit template parameter,
as it cannot be deduced from the argument list.
\end{note}
\end{itemdescr}

\rSec2[tuple.helper]{Tuple helper classes}

\indexlibrary{\idxcode{tuple_size}!in general}%
\begin{itemdecl}
template<class T> struct tuple_size;
\end{itemdecl}

\begin{itemdescr}
\pnum
Except where specified otherwise,
all specializations of \tcode{tuple_size} meet the
\oldconcept{UnaryTypeTrait} requirements\iref{meta.rqmts} with a
base characteristic of \tcode{integral_constant<size_t, N>}
for some \tcode{N}.
\end{itemdescr}

\indexlibraryglobal{tuple_size}%
\begin{itemdecl}
template<class... Types>
  struct tuple_size<tuple<Types...>> : integral_constant<size_t, sizeof...(Types)> { };
\end{itemdecl}

\indexlibraryglobal{tuple_element}%
\begin{itemdecl}
template<size_t I, class... Types>
  struct tuple_element<I, tuple<Types...>> {
    using type = TI;
  };
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
$\tcode{I} < \tcode{sizeof...(Types)}$.

\pnum
\ctype
\tcode{TI} is the
type of the $\tcode{I}^\text{th}$ element of \tcode{Types},
where indexing is zero-based.
\end{itemdescr}

\indexlibraryglobal{tuple_size}%
\begin{itemdecl}
template<class T> struct tuple_size<const T>;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{TS} denote \tcode{tuple_size<T>} of the cv-unqualified type \tcode{T}.
If the expression \tcode{TS::value} is well-formed
when treated as an unevaluated operand\iref{term.unevaluated.operand}, then
each specialization of the template meets the \oldconcept{Unary\-Type\-Trait} requirements\iref{meta.rqmts}
with a base characteristic of
\begin{codeblock}
integral_constant<size_t, TS::value>
\end{codeblock}
Otherwise, it has no member \tcode{value}.

\pnum
Access checking is performed as if in a context
unrelated to \tcode{TS} and \tcode{T}.
Only the validity of the immediate context of the expression is considered.
\begin{note}
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}

\pnum
In addition to being available via inclusion of the \libheader{tuple} header,
the template is available
when any of the headers
\libheaderref{array},
\libheaderref{ranges}, or
\libheaderref{utility}
are included.
\end{itemdescr}

\indexlibraryglobal{tuple_element}%
\begin{itemdecl}
template<size_t I, class T> struct tuple_element<I, const T>;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{TE} denote \tcode{tuple_element_t<I, T>} of the cv-unqualified type \tcode{T}. Then
each specialization of the template meets the \oldconcept{TransformationTrait} requirements\iref{meta.rqmts}
with a member typedef \tcode{type} that names the type \tcode{add_const_t<TE>}.

\pnum
In addition to being available via inclusion of the \libheader{tuple} header,
the template is available
when any of the headers
\libheaderref{array},
\libheaderref{ranges}, or
\libheaderref{utility}
are included.
\end{itemdescr}

\rSec2[tuple.elem]{Element access}

\indexlibrarymember{get}{tuple}%
\begin{itemdecl}
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;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
$\tcode{I} < \tcode{sizeof...(Types)}$.

\pnum
\returns
A reference to the $\tcode{I}^\text{th}$ element of \tcode{t}, where
indexing is zero-based.

\pnum
\begin{note}
For the overload marked \#1,
if a type \tcode{T} in \tcode{Types} is some reference type \tcode{X\&},
the return type is \tcode{X\&}, not \tcode{X\&\&}.
However, if the element type is a non-reference type \tcode{T},
the return type is \tcode{T\&\&}.
\end{note}

\pnum
\begin{note}
Constness is shallow.
For the overload marked \#2,
if a type \tcode{T} in \tcode{Types} is some reference type \tcode{X\&},
the return type is \tcode{X\&}, not \tcode{const X\&}.
However, if the element type is a non-reference type \tcode{T},
the return type is \tcode{const T\&}.
This is consistent with how constness is defined to work
for non-static data members of reference type.
\end{note}
\end{itemdescr}

\indexlibrarymember{get}{tuple}%
\begin{itemdecl}
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;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The type \tcode{T} occurs exactly once in \tcode{Types}.

\pnum
\returns
A reference to the element of \tcode{t} corresponding to the type
\tcode{T} in \tcode{Types}.

\pnum
\begin{example}
\begin{codeblock}
const tuple<int, const int, double, double> t(1, 2, 3.4, 5.6);
const int& i1 = get<int>(t);                    // OK, \tcode{i1} has value \tcode{1}
const int& i2 = get<const int>(t);              // OK, \tcode{i2} has value \tcode{2}
const double& d = get<double>(t);               // error: type \tcode{double} is not unique within \tcode{t}
\end{codeblock}
\end{example}
\end{itemdescr}

\pnum
\begin{note}
The reason \tcode{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 \keyword{template} keyword.
\end{note}

\rSec2[tuple.rel]{Relational operators}

\indexlibrarymember{operator==}{tuple}%
\begin{itemdecl}
template<class... TTypes, class... UTypes>
  constexpr bool operator==(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
template<class... TTypes, @\exposconcept{tuple-like}@ UTuple>
  constexpr bool operator==(const tuple<TTypes...>& t, const UTuple& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
For the first overload let \tcode{UTuple} be \tcode{tuple<UTypes...>}.

\pnum
\constraints
For all \tcode{i},
where $0 \leq \tcode{i} < \tcode{sizeof...(TTypes)}$,
\tcode{get<i>(t) == get<i>(u)} is a valid expression and
\tcode{decltype(get<i>(t) == get<i>(u))} models \exposconcept{boolean-testable}.
\tcode{sizeof...(TTypes)} equals
\tcode{tuple_size_v<UTuple>}.

\pnum
\returns
\tcode{true} if \tcode{get<i>(t) == get<i>(u)} for all
\tcode{i}, otherwise \tcode{false}.
\begin{note}
If \tcode{sizeof...(TTypes)} equals zero, returns \tcode{true}.
\end{note}

\pnum
\remarks
\begin{itemize}
\item
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
\tcode{false}.
\item
The second overload is to be found via argument-dependent lookup\iref{basic.lookup.argdep} only.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{operator<=>}{tuple}%
\begin{itemdecl}
template<class... TTypes, class... UTypes>
  constexpr common_comparison_category_t<@\placeholder{synth-three-way-result}@<TTypes, UTypes>...>
    operator<=>(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
template<class... TTypes, @\exposconcept{tuple-like}@ UTuple>
  constexpr common_comparison_category_t<@\placeholder{synth-three-way-result}@<TTypes, Elems>...>
    operator<=>(const tuple<TTypes...>& t, const UTuple& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
For the second overload, \tcode{Elems} denotes the pack of types
\tcode{tuple_element_t<0, UTuple>},
\tcode{tuple_element_t<1, UTuple>}, \ldots,
\tcode{tuple_element_t<tuple_size_v<UTuple> - 1, UTuple>}.

\pnum
\effects
Performs a lexicographical comparison between \tcode{t} and \tcode{u}.
If \tcode{sizeof...(TTypes)} equals zero,
returns \tcode{strong_ordering::equal}.
Otherwise, equivalent to:
\begin{codeblock}
if (auto c = @\placeholder{synth-three-way}@(get<0>(t), get<0>(u)); c != 0) return c;
return @$\tcode{t}_\mathrm{tail}$@ <=> @$\tcode{u}_\mathrm{tail}$@;
\end{codeblock}
where $\tcode{r}_\mathrm{tail}$ for some \tcode{r}
is a tuple containing all but the first element of \tcode{r}.

\pnum
\remarks
The second overload is to be found via argument-dependent lookup\iref{basic.lookup.argdep} only.
\end{itemdescr}

\pnum
\begin{note}
The above definition does not require \tcode{t$_{\mathrm{tail}}$}
(or \tcode{u$_{\mathrm{tail}}$}) to be constructed. It might not
even be possible, as \tcode{t} and \tcode{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}

\rSec2[tuple.common.ref]{\tcode{common_reference} related specializations}

\pnum
In the descriptions that follow:
\begin{itemize}
\item
Let \tcode{TTypes} be a pack formed by
the sequence of \tcode{tuple_element_t<$i$, TTuple>}
for every integer $0 \leq i < \tcode{tuple_size_v<TTuple>}$.

\item
Let \tcode{UTypes} be a pack formed by
the sequence of \tcode{tuple_element_t<$i$, UTuple>}
for every integer $0 \leq i < \tcode{tuple_size_v<UTuple>}$.
\end{itemize}

\indexlibrarymember{basic_common_reference}{tuple}%
\begin{itemdecl}
template<@\exposconcept{tuple-like}@ TTuple, @\exposconcept{tuple-like}@ UTuple,
         template<class> class TQual, template<class> class UQual>
struct basic_common_reference<TTuple, UTuple, TQual, UQual> {
  using type = @\seebelow@;
};
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{TTuple} is a specialization of \tcode{tuple} or
\tcode{UTuple} is a specialization of \tcode{tuple}.
\item
\tcode{is_same_v<TTuple, decay_t<TTuple>>} is \tcode{true}.
\item
\tcode{is_same_v<UTuple, decay_t<UTuple>>} is \tcode{true}.
\item
\tcode{tuple_size_v<TTuple>} equals \tcode{tuple_size_v<UTuple>}.
\item
\tcode{tuple<common_reference_t<TQual<TTypes>, UQual<UTypes>>...>}
denotes a type.
\end{itemize}
The member \grammarterm{typedef-name} \tcode{type} denotes the type
\tcode{tuple<common_reference_t<TQual<TTypes>, \linebreak{}UQual<UTypes>>...>}.
\end{itemdescr}

\indexlibrarymember{common_type}{tuple}%
\begin{itemdecl}
template<@\exposconcept{tuple-like}@ TTuple, @\exposconcept{tuple-like}@ UTuple>
struct common_type<TTuple, UTuple> {
  using type = @\seebelow@;
};
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{TTuple} is a specialization of \tcode{tuple} or
\tcode{UTuple} is a specialization of \tcode{tuple}.
\item
\tcode{is_same_v<TTuple, decay_t<TTuple>>} is \tcode{true}.
\item
\tcode{is_same_v<UTuple, decay_t<UTuple>>} is \tcode{true}.
\item
\tcode{tuple_size_v<TTuple>} equals \tcode{tuple_size_v<UTuple>}.
\item
\tcode{tuple<common_type_t<TTypes, UTypes>...>} denotes a type.
\end{itemize}
The member \grammarterm{typedef-name} \tcode{type} denotes the type
\tcode{tuple<common_type_t<TTypes, UTypes>...>}.
\end{itemdescr}

\rSec2[tuple.traits]{Tuple traits}

\indexlibraryglobal{uses_allocator<tuple>}%
\begin{itemdecl}
template<class... Types, class Alloc>
  struct uses_allocator<tuple<Types...>, Alloc> : true_type { };
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{Alloc} meets
the \oldconcept{Allocator} requirements\iref{allocator.requirements.general}.

\pnum
\begin{note}
Specialization of this trait informs other library components that
\tcode{tuple} can be constructed with an allocator, even though it does not have
a nested \tcode{allocator_type}.
\end{note}
\end{itemdescr}

\rSec2[tuple.special]{Tuple specialized algorithms}

\indexlibrarymember{swap}{tuple}%
\begin{itemdecl}
template<class... Types>
  constexpr void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(@\seebelow@);
template<class... Types>
  constexpr void swap(const tuple<Types...>& x, const tuple<Types...>& y) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
For the first overload,
\tcode{(is_swappable_v<Types> \&\& ...)} is \tcode{true}.
\item
For the second overload,
\tcode{(is_swappable_v<const Types> \&\& ...)} is \tcode{true}.
\end{itemize}

\pnum
\effects
As if by \tcode{x.swap(y)}.

\pnum
\remarks
The exception specification is equivalent to:

\begin{codeblock}
noexcept(x.swap(y))
\end{codeblock}
\end{itemdescr}

\rSec1[optional]{Optional objects}

\rSec2[optional.general]{General}

\pnum
Subclause~\ref{optional} describes class template \tcode{optional} that represents
optional objects.
An \defn{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.

\rSec2[optional.syn]{Header \tcode{<optional>} synopsis}

\indexheader{optional}%
\begin{codeblock}
// mostly freestanding
#include <compare>              // see \ref{compare.syn}

namespace std {
  // \ref{optional.optional}, class template \tcode{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 @\defexposconcept{is-derived-from-optional}@ = requires(const T& t) {       // \expos
      []<class U>(const optional<U>&){ }(t);
    };

  // \ref{optional.nullopt}, no-value state indicator
  struct nullopt_t{@\seebelow@};
  inline constexpr nullopt_t nullopt(@\unspec@);

  // \ref{optional.bad.access}, class \tcode{bad_optional_access}
  class bad_optional_access;

  // \ref{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, @\libconcept{three_way_comparable_with}@<T> U>
    constexpr compare_three_way_result_t<T, U>
      operator<=>(const optional<T>&, const optional<U>&);

  // \ref{optional.nullops}, comparison with \tcode{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;

  // \ref{optional.comp.with.t}, comparison with \tcode{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 (!@\exposconcept{is-derived-from-optional}@<U>) && @\libconcept{three_way_comparable_with}@<T, U>
    constexpr compare_three_way_result_t<T, U>
      operator<=>(const optional<T>&, const U&);

  // \ref{optional.specalg}, specialized algorithms
  template<class T>
    constexpr void swap(optional<T>&, optional<T>&) noexcept(@\seebelow@);

  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);

  // \ref{optional.hash}, hash support
  template<class T> struct hash;
  template<class T> struct hash<optional<T>>;
}
\end{codeblock}

\rSec2[optional.optional]{Class template \tcode{optional}}

\rSec3[optional.optional.general]{General}

\indexlibraryglobal{optional}%
\indexlibrarymember{value_type}{optional}%
\begin{codeblock}
namespace std {
  template<class T>
  class optional {
  public:
    using value_type     = T;
    using iterator       = @\impdefnc@;              // see~\ref{optional.iterators}
    using const_iterator = @\impdefnc@;              // see~\ref{optional.iterators}

    // \ref{optional.ctor}, constructors
    constexpr optional() noexcept;
    constexpr optional(nullopt_t) noexcept;
    constexpr optional(const optional&);
    constexpr optional(optional&&) noexcept(@\seebelow@);
    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 = remove_cv_t<T>>
      constexpr explicit(@\seebelow@) optional(U&&);
    template<class U>
      constexpr explicit(@\seebelow@) optional(const optional<U>&);
    template<class U>
      constexpr explicit(@\seebelow@) optional(optional<U>&&);

    // \ref{optional.dtor}, destructor
    constexpr ~optional();

    // \ref{optional.assign}, assignment
    constexpr optional& operator=(nullopt_t) noexcept;
    constexpr optional& operator=(const optional&);
    constexpr optional& operator=(optional&&) noexcept(@\seebelow@);
    template<class U = remove_cv_t<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&&...);

    // \ref{optional.swap}, swap
    constexpr void swap(optional&) noexcept(@\seebelow@);

    // \ref{optional.iterators}, iterator support
    constexpr iterator begin() noexcept;
    constexpr const_iterator begin() const noexcept;
    constexpr iterator end() noexcept;
    constexpr const_iterator end() const noexcept;

    // \ref{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 = remove_cv_t<T>> constexpr T value_or(U&&) const &;
    template<class U = remove_cv_t<T>> constexpr T value_or(U&&) &&;

    // \ref{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 &;

    // \ref{optional.mod}, modifiers
    constexpr void reset() noexcept;

  private:
    T* val;         // \expos
  };

  template<class T>
    optional(T) -> optional<T>;
}
\end{codeblock}

\pnum
Any instance of \tcode{optional<T>} at any given time either contains a value or does not contain a value.
When an instance of \tcode{optional<T>} \defnx{contains a value}{contains a value!\idxcode{optional}},
it means that an object of type \tcode{T}, referred to as the optional object's \defnx{contained value}{contained value!\idxcode{optional}},
is nested within\iref{intro.object} the optional object.
When an object of type \tcode{optional<T>} is contextually converted to \tcode{bool},
the conversion returns \tcode{true} if the object contains a value;
otherwise the conversion returns \tcode{false}.

\pnum
When an \tcode{optional<T>} object contains a value,
member \tcode{val} points to the contained value.

\pnum
\tcode{T} shall be a type
other than \cv{} \tcode{in_place_t} or \cv{} \tcode{nullopt_t}
that meets the \oldconcept{Destructible} requirements (\tref{cpp17.destructible}).

\rSec3[optional.ctor]{Constructors}

\pnum
The exposition-only variable template \exposid{converts-from-any-cvref}
is used by some constructors for \tcode{optional}.
\begin{codeblock}
template<class T, class W>
constexpr bool @\exposid{converts-from-any-cvref}@ =  // \expos
  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>>;
\end{codeblock}

\indexlibraryctor{optional}%
\begin{itemdecl}
constexpr optional() noexcept;
constexpr optional(nullopt_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{*this} does not contain a value.

\pnum
\remarks
No contained value is initialized.
For every object type \tcode{T} these constructors are constexpr constructors\iref{dcl.constexpr}.
\end{itemdescr}

\indexlibraryctor{optional}%
\begin{itemdecl}
constexpr optional(const optional& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{rhs} contains a value, direct-non-list-initializes the contained value
with \tcode{*rhs}.

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
This constructor is defined as deleted unless
\tcode{is_copy_constructible_v<T>} is \tcode{true}.
If \tcode{is_trivially_copy_constructible_v<T>} is \tcode{true},
this constructor is trivial.
\end{itemdescr}

\indexlibraryctor{optional}%
\begin{itemdecl}
constexpr optional(optional&& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<T>} is \tcode{true}.

\pnum
\effects
If \tcode{rhs} contains a value, direct-non-list-initializes the contained value
with \tcode{std::move(*rhs)}.
\tcode{rhs.has_value()} is unchanged.

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
The exception specification is equivalent to
\tcode{is_nothrow_move_constructible_v<T>}.
If \tcode{is_trivially_move_constructible_v<T>} is \tcode{true},
this constructor is trivial.
\end{itemdescr}

\indexlibraryctor{optional}%
\begin{itemdecl}
template<class... Args> constexpr explicit optional(in_place_t, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<T, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes the contained value with \tcode{std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
If \tcode{T}'s constructor selected for the initialization is a constexpr constructor, this constructor is a constexpr constructor.
\end{itemdescr}

\indexlibraryctor{optional}%
\begin{itemdecl}
template<class U, class... Args>
  constexpr explicit optional(in_place_t, initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<T, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes the contained value with \tcode{il, std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
If \tcode{T}'s constructor selected for the initialization is a constexpr constructor, this constructor is a constexpr constructor.
\end{itemdescr}

\indexlibraryctor{optional}%
\begin{itemdecl}
template<class U = remove_cv_t<T>> constexpr explicit(@\seebelow@) optional(U&& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<T, U>} is \tcode{true},
\item \tcode{is_same_v<remove_cvref_t<U>, in_place_t>} is \tcode{false},
\item \tcode{is_same_v<remove_cvref_t<U>, optional>} is \tcode{false}, and
\item if \tcode{T} is \cv{} \tcode{bool},
\tcode{remove_cvref_t<U>} is not a specialization of \tcode{optional}.
\end{itemize}

\pnum
\effects
Direct-non-list-initializes the contained value with \tcode{std::forward<U>(v)}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
If \tcode{T}'s selected constructor is a constexpr constructor,
this constructor is a constexpr constructor.
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<U, T>
\end{codeblock}
\end{itemdescr}

\indexlibraryctor{optional}%
\begin{itemdecl}
template<class U> constexpr explicit(@\seebelow@) optional(const optional<U>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<T, const U\&>} is \tcode{true}, and
\item if \tcode{T} is not \cv{} \tcode{bool},
\tcode{\exposid{converts-from-any-cvref}<T, optional<U>>} is \tcode{false}.
\end{itemize}

\pnum
\effects
If \tcode{rhs} contains a value,
direct-non-list-initializes the contained value with \tcode{*rhs}.

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<const U&, T>
\end{codeblock}
\end{itemdescr}

\indexlibraryctor{optional}%
\begin{itemdecl}
template<class U> constexpr explicit(@\seebelow@) optional(optional<U>&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<T, U>} is \tcode{true}, and
\item if \tcode{T} is not \cv{} \tcode{bool},
\tcode{\exposid{converts-from-any-cvref}<T, optional<U>>} is \tcode{false}.
\end{itemize}

\pnum
\effects
If \tcode{rhs} contains a value,
direct-non-list-initializes the contained value with \tcode{std::move(*rhs)}.
\tcode{rhs.has_value()} is unchanged.

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
The expression inside \keyword{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<U, T>
\end{codeblock}
\end{itemdescr}

\rSec3[optional.dtor]{Destructor}

\indexlibrarydtor{optional}%
\begin{itemdecl}
constexpr ~optional();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{is_trivially_destructible_v<T> != true} and \tcode{*this} contains a value, calls
\begin{codeblock}
val->T::~T()
\end{codeblock}

\pnum
\remarks
If \tcode{is_trivially_destructible_v<T>} is \tcode{true}, then this destructor is trivial.
\end{itemdescr}

\rSec3[optional.assign]{Assignment}

\indexlibrarymember{operator=}{optional}%
\begin{itemdecl}
constexpr optional<T>& operator=(nullopt_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{*this} contains a value, calls \tcode{val->T::\~T()} to destroy the contained value; otherwise no effect.

\pnum
\ensures
\tcode{*this} does not contain a value.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{optional}%
\begin{itemdecl}
constexpr optional<T>& operator=(const optional& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
See \tref{optional.assign.copy}.
\begin{lib2dtab2}{\tcode{optional::operator=(const optional\&)} effects}{optional.assign.copy}
{\tcode{*this} contains a value}
{\tcode{*this} does not contain a value}

\rowhdr{\tcode{rhs} contains a value} &
assigns \tcode{*rhs} to the contained value &
direct-non-list-initializes the contained value with \tcode{*rhs} \\
\rowsep

\rowhdr{\tcode{rhs} does not contain a value} &
destroys the contained value by calling \tcode{val->T::\~T()} &
no effect \\
\end{lib2dtab2}

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
If any exception is thrown, the result of the expression \tcode{this->has_value()} remains unchanged.
If an exception is thrown during the call to \tcode{T}'s copy constructor, no effect.
If an exception is thrown during the call to \tcode{T}'s copy assignment,
the state of its contained value is as defined by the exception safety guarantee of \tcode{T}'s copy assignment.
This operator is defined as deleted unless
\tcode{is_copy_constructible_v<T>} is \tcode{true} and
\tcode{is_copy_assignable_v<T>} is \tcode{true}.
If \tcode{is_trivially_copy_constructible_v<T> \&\&}
\tcode{is_trivially_copy_assignable_v<T> \&\&}
\tcode{is_trivially_destructible_v<T>} is \tcode{true},
this assignment operator is trivial.
\end{itemdescr}

\indexlibrarymember{operator=}{optional}%
\begin{itemdecl}
constexpr optional& operator=(optional&& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<T>} is \tcode{true} and
\tcode{is_move_assignable_v<T>} is \tcode{true}.

\pnum
\effects
See \tref{optional.assign.move}.
The result of the expression \tcode{rhs.has_value()} remains unchanged.
\begin{lib2dtab2}{\tcode{optional::operator=(optional\&\&)} effects}{optional.assign.move}
{\tcode{*this} contains a value}
{\tcode{*this} does not contain a value}

\rowhdr{\tcode{rhs} contains a value} &
assigns \tcode{std::move(*rhs)} to the contained value &
direct-non-list-initializes the contained value with \tcode{std::move(*rhs)} \\
\rowsep

\rowhdr{\tcode{rhs} does not contain a value} &
destroys the contained value by calling \tcode{val->T::\~T()} &
no effect \\
\end{lib2dtab2}

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The exception specification is equivalent to:
\begin{codeblock}
is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T>
\end{codeblock}

\pnum
If any exception is thrown, the result of the expression \tcode{this->has_value()} remains unchanged.
If an exception is thrown during the call to \tcode{T}'s move constructor,
the state of \tcode{*rhs.val} is determined by the exception safety guarantee of \tcode{T}'s move constructor.
If an exception is thrown during the call to \tcode{T}'s move assignment,
the state of \tcode{*val} and \tcode{*rhs.val} is determined by the exception safety guarantee of \tcode{T}'s move assignment.
If \tcode{is_trivially_move_constructible_v<T> \&\&}
\tcode{is_trivially_move_assignable_v<T> \&\&}
\tcode{is_trivially_destructible_v<T>} is \tcode{true},
this assignment operator is trivial.
\end{itemdescr}

\indexlibrarymember{operator=}{optional}%
\begin{itemdecl}
template<class U = remove_cv_t<T>> constexpr optional& operator=(U&& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_same_v<remove_cvref_t<U>, optional>} is \tcode{false},
\item \tcode{conjunction_v<is_scalar<T>, is_same<T, decay_t<U>>>} is \tcode{false},
\item \tcode{is_constructible_v<T, U>} is \tcode{true}, and
\item \tcode{is_assignable_v<T\&, U>} is \tcode{true}.
\end{itemize}

\pnum
\effects
If \tcode{*this} contains a value, assigns \tcode{std::forward<U>(v)} to the contained value; otherwise direct-non-list-initializes the contained value with \tcode{std::forward<U>(v)}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
If any exception is thrown, the result of the expression \tcode{this->has_value()} remains unchanged. If an exception is thrown during the call to \tcode{T}'s constructor, the state of \tcode{v} is determined by the exception safety guarantee of \tcode{T}'s constructor. If an exception is thrown during the call to \tcode{T}'s assignment, the state of \tcode{*val} and \tcode{v} is determined by the exception safety guarantee of \tcode{T}'s assignment.
\end{itemdescr}

\indexlibrarymember{operator=}{optional}%
\begin{itemdecl}
template<class U> constexpr optional<T>& operator=(const optional<U>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<T, const U\&>} is \tcode{true},
\item \tcode{is_assignable_v<T\&, const U\&>} is \tcode{true},
\item \tcode{\exposid{converts-from-any-cvref}<T, optional<U>>} is \tcode{false},
\item \tcode{is_assignable_v<T\&, optional<U>\&>} is \tcode{false},
\item \tcode{is_assignable_v<T\&, optional<U>\&\&>} is \tcode{false},
\item \tcode{is_assignable_v<T\&, const optional<U>\&>} is \tcode{false}, and
\item \tcode{is_assignable_v<T\&, const optional<U>\&\&>} is \tcode{false}.
\end{itemize}

\pnum
\effects
See \tref{optional.assign.copy.templ}.
\begin{lib2dtab2}{\tcode{optional::operator=(const optional<U>\&)} effects}{optional.assign.copy.templ}
{\tcode{*this} contains a value}
{\tcode{*this} does not contain a value}

\rowhdr{\tcode{rhs} contains a value} &
assigns \tcode{*rhs} to the contained value &
direct-non-list-initializes the contained value with \tcode{*rhs} \\
\rowsep

\rowhdr{\tcode{rhs} does not contain a value} &
destroys the contained value by calling \tcode{val->T::\~T()} &
no effect \\
\end{lib2dtab2}

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
If any exception is thrown,
the result of the expression \tcode{this->has_value()} remains unchanged.
If an exception is thrown during the call to \tcode{T}'s constructor,
the state of \tcode{*rhs.val} is determined by
the exception safety guarantee of \tcode{T}'s constructor.
If an exception is thrown during the call to \tcode{T}'s assignment,
the state of \tcode{*val} and \tcode{*rhs.val} is determined by
the exception safety guarantee of \tcode{T}'s assignment.
\end{itemdescr}

\indexlibrarymember{operator=}{optional}%
\begin{itemdecl}
template<class U> constexpr optional<T>& operator=(optional<U>&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<T, U>} is \tcode{true},
\item \tcode{is_assignable_v<T\&, U>} is \tcode{true},
\item \tcode{\exposid{converts-from-any-cvref}<T, optional<U>>} is \tcode{false},
\item \tcode{is_assignable_v<T\&, optional<U>\&>} is \tcode{false},
\item \tcode{is_assignable_v<T\&, optional<U>\&\&>} is \tcode{false},
\item \tcode{is_assignable_v<T\&, const optional<U>\&>} is \tcode{false}, and
\item \tcode{is_assignable_v<T\&, const optional<U>\&\&>} is \tcode{false}.
\end{itemize}

\pnum
\effects
See \tref{optional.assign.move.templ}.
The result of the expression \tcode{rhs.has_value()} remains unchanged.
\begin{lib2dtab2}{\tcode{optional::operator=(optional<U>\&\&)} effects}{optional.assign.move.templ}
{\tcode{*this} contains a value}
{\tcode{*this} does not contain a value}

\rowhdr{\tcode{rhs} contains a value} &
assigns \tcode{std::move(*rhs)} to the contained value &
direct-non-list-initializes the contained value with \tcode{std::move(*rhs)} \\
\rowsep

\rowhdr{\tcode{rhs} does not contain a value} &
destroys the contained value by calling \tcode{val->T::\~T()} &
no effect \\
\end{lib2dtab2}

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
If any exception is thrown,
the result of the expression \tcode{this->has_value()} remains unchanged.
If an exception is thrown during the call to \tcode{T}'s constructor,
the state of \tcode{*rhs.val} is determined by
the exception safety guarantee of \tcode{T}'s constructor.
If an exception is thrown during the call to \tcode{T}'s assignment,
the state of \tcode{*val} and \tcode{*rhs.val} is determined by
the exception safety guarantee of \tcode{T}'s assignment.
\end{itemdescr}

\indexlibrarymember{emplace}{optional}%
\begin{itemdecl}
template<class... Args> constexpr T& emplace(Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_constructible_v<T, Args...>} is \tcode{true}.

\pnum
\effects
Calls \tcode{*this = nullopt}. Then direct-non-list-initializes the contained value
with \tcode{std::forward\brk{}<Args>(args)...}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\returns
A reference to the new contained value.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
If an exception is thrown during the call to \tcode{T}'s constructor, \tcode{*this} does not contain a value, and the previous \tcode{*val} (if any) has been destroyed.
\end{itemdescr}

\indexlibrarymember{emplace}{optional}%
\begin{itemdecl}
template<class U, class... Args> constexpr T& emplace(initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<T, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\effects
Calls \tcode{*this = nullopt}. Then direct-non-list-initializes the contained value with
\tcode{il, std::\brk{}forward<Args>(args)...}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\returns
A reference to the new contained value.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{T}.

\pnum
\remarks
If an exception is thrown during the call to \tcode{T}'s constructor, \tcode{*this} does not contain a value, and the previous \tcode{*val} (if any) has been destroyed.
\end{itemdescr}

\rSec3[optional.swap]{Swap}

\indexlibrarymember{swap}{optional}%
\begin{itemdecl}
constexpr void swap(optional& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_move_constructible_v<T>} is \tcode{true}.

\pnum
\expects
\tcode{T} meets the \oldconcept{Swappable} requirements\iref{swappable.requirements}.

\pnum
\effects
See \tref{optional.swap}.
\begin{lib2dtab2}{\tcode{optional::swap(optional\&)} effects}{optional.swap}
{\tcode{*this} contains a value}
{\tcode{*this} does not contain a value}

\rowhdr{\tcode{rhs} contains a value} &
calls \tcode{swap(*(*this), *rhs)} &
direct-non-list-initializes the contained value of \tcode{*this}
with \tcode{std::move(*rhs)},
followed by \tcode{rhs.val->T::\~T()};
postcondition is that \tcode{*this} contains a value and \tcode{rhs} does not contain a value \\
\rowsep

\rowhdr{\tcode{rhs} does not contain a value} &
direct-non-list-initializes the contained value of \tcode{rhs}
with \tcode{std::move(*(*this))},
followed by \tcode{val->T::\~T()};
postcondition is that \tcode{*this} does not contain a value and \tcode{rhs} contains a value &
no effect \\
\end{lib2dtab2}

\pnum
\throws
Any exceptions thrown by the operations in the relevant part of \tref{optional.swap}.

\pnum
\remarks
The exception specification is equivalent to:
\begin{codeblock}
is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T>
\end{codeblock}

\pnum
If any exception is thrown, the results of the expressions \tcode{this->has_value()} and \tcode{rhs.has_value()} remain unchanged.
If an exception is thrown during the call to function \tcode{swap},
the state of \tcode{*val} and \tcode{*rhs.val} is determined by the exception safety guarantee of \tcode{swap} for lvalues of \tcode{T}.
If an exception is thrown during the call to \tcode{T}'s move constructor,
the state of \tcode{*val} and \tcode{*rhs.val} is determined by the exception safety guarantee of \tcode{T}'s move constructor.
\end{itemdescr}

\rSec3[optional.iterators]{Iterator support}

\indexlibrarymember{iterator}{optional}%
\indexlibrarymember{const_iterator}{optional}%
\begin{itemdecl}
using iterator       = @\impdef@;
using const_iterator = @\impdef@;
\end{itemdecl}

\begin{itemdescr}
\pnum
These types
model \libconcept{contiguous_iterator}\iref{iterator.concept.contiguous},
meet the \oldconcept{RandomAccessIterator} requirements\iref{random.access.iterators}, and
meet the requirements for constexpr iterators\iref{iterator.requirements.general},
with value type \tcode{remove_cv_t<T>}.
The reference type is \tcode{T\&} for \tcode{iterator} and
\tcode{const T\&} for \tcode{const_iterator}.

\pnum
All requirements on container iterators\iref{container.reqmts} apply to
\tcode{optional::iterator} and \tcode{optional::\linebreak{}const_iterator} as well.

\pnum
Any operation that initializes or destroys the contained value of an optional object invalidates all iterators into that object.
\end{itemdescr}

\indexlibrarymember{begin}{optional}%
\begin{itemdecl}
constexpr iterator begin() noexcept;
constexpr const_iterator begin() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If \tcode{has_value()} is \tcode{true},
an iterator referring to the contained value.
Otherwise, a past-the-end iterator value.
\end{itemdescr}

\indexlibrarymember{end}{optional}%
\begin{itemdecl}
constexpr iterator end() noexcept;
constexpr const_iterator end() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{begin() + has_value()}.
\end{itemdescr}

\rSec3[optional.observe]{Observers}

\indexlibrarymember{operator->}{optional}%
\begin{itemdecl}
constexpr const T* operator->() const noexcept;
constexpr T* operator->() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{true}.

\pnum
\returns
\tcode{val}.

\pnum
\remarks
These functions are constexpr functions.
\end{itemdescr}

\indexlibrarymember{operator*}{optional}%
\begin{itemdecl}
constexpr const T& operator*() const & noexcept;
constexpr T& operator*() & noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{true}.

\pnum
\returns
\tcode{*val}.

\pnum
\remarks
These functions are constexpr functions.
\end{itemdescr}

\indexlibrarymember{operator*}{optional}%
\begin{itemdecl}
constexpr T&& operator*() && noexcept;
constexpr const T&& operator*() const && noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{true}.

\pnum
\effects
Equivalent to: \tcode{return std::move(*val);}
\end{itemdescr}

\indexlibrarymember{operator bool}{optional}%
\begin{itemdecl}
constexpr explicit operator bool() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if and only if \tcode{*this} contains a value.

\pnum
\remarks
This function is a constexpr function.
\end{itemdescr}

\indexlibrarymember{has_value}{optional}%
\begin{itemdecl}
constexpr bool has_value() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if and only if \tcode{*this} contains a value.

\pnum
\remarks
This function is a constexpr function.
\end{itemdescr}

\indexlibrarymember{value}{optional}%
\begin{itemdecl}
constexpr const T& value() const &;
constexpr T& value() &;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return has_value() ? *val : throw bad_optional_access();
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{value}{optional}%
\begin{itemdecl}
constexpr T&& value() &&;
constexpr const T&& value() const &&;
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
Equivalent to:
\begin{codeblock}
return has_value() ? std::move(*val) : throw bad_optional_access();
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{value_or}{optional}%
\begin{itemdecl}
template<class U = remove_cv_t<T>> constexpr T value_or(U&& v) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<T> \&\& is_convertible_v<U\&\&, T>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return has_value() ? **this : static_cast<T>(std::forward<U>(v));
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{value_or}{optional}%
\begin{itemdecl}
template<class U = remove_cv_t<T>> constexpr T value_or(U&& v) &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_move_constructible_v<T> \&\& is_convertible_v<U\&\&, T>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return has_value() ? std::move(**this) : static_cast<T>(std::forward<U>(v));
\end{codeblock}
\end{itemdescr}

\rSec3[optional.monadic]{Monadic operations}

\indexlibrarymember{and_then}{optional}
\begin{itemdecl}
template<class F> constexpr auto and_then(F&& f) &;
template<class F> constexpr auto and_then(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be \tcode{invoke_result_t<F, decltype(*val)>}.

\pnum
\mandates
\tcode{remove_cvref_t<U>} is a specialization of \tcode{optional}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (*this) {
  return invoke(std::forward<F>(f), *val);
} else {
  return remove_cvref_t<U>();
}
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{and_then}{optional}
\begin{itemdecl}
template<class F> constexpr auto and_then(F&& f) &&;
template<class F> constexpr auto and_then(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be \tcode{invoke_result_t<F, decltype(std::move(*val))>}.

\pnum
\mandates
\tcode{remove_cvref_t<U>} is a specialization of \tcode{optional}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (*this) {
  return invoke(std::forward<F>(f), std::move(*val));
} else {
  return remove_cvref_t<U>();
}
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{transform}{optional}
\begin{itemdecl}
template<class F> constexpr auto transform(F&& f) &;
template<class F> constexpr auto transform(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be \tcode{remove_cv_t<invoke_result_t<F, decltype(*val)>>}.

\pnum
\mandates
\tcode{U} is a non-array object type
other than \tcode{in_place_t} or \tcode{nullopt_t}.
The declaration
\begin{codeblock}
U u(invoke(std::forward<F>(f), *val));
\end{codeblock}
is well-formed for some invented variable \tcode{u}.
\begin{note}
There is no requirement that \tcode{U} is movable\iref{dcl.init.general}.
\end{note}

\pnum
\returns
If \tcode{*this} contains a value, an \tcode{optional<U>} object
whose contained value is direct-non-list-initialized with
\tcode{invoke(std::forward<F>(f), *val)};
otherwise, \tcode{optional<U>()}.
\end{itemdescr}

\indexlibrarymember{transform}{optional}
\begin{itemdecl}
template<class F> constexpr auto transform(F&& f) &&;
template<class F> constexpr auto transform(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be
\tcode{remove_cv_t<invoke_result_t<F, decltype(std::move(*val))>>}.

\pnum
\mandates
\tcode{U} is a non-array object type
other than \tcode{in_place_t} or \tcode{nullopt_t}.
The declaration
\begin{codeblock}
U u(invoke(std::forward<F>(f), std::move(*val)));
\end{codeblock}
is well-formed for some invented variable \tcode{u}.
\begin{note}
There is no requirement that \tcode{U} is movable\iref{dcl.init.general}.
\end{note}

\pnum
\returns
If \tcode{*this} contains a value, an \tcode{optional<U>} object
whose contained value is direct-non-list-initialized with
\tcode{invoke(std::forward<F>(f), std::move(*val))};
otherwise, \tcode{optional<U>()}.
\end{itemdescr}

\indexlibrarymember{or_else}{optional}
\begin{itemdecl}
template<class F> constexpr optional or_else(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{F} models \tcode{\libconcept{invocable}<>} and
\tcode{T} models \libconcept{copy_constructible}.

\pnum
\mandates
\tcode{is_same_v<remove_cvref_t<invoke_result_t<F>>, optional>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (*this) {
  return *this;
} else {
  return std::forward<F>(f)();
}
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{or_else}{optional}
\begin{itemdecl}
template<class F> constexpr optional or_else(F&& f) &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{F} models \tcode{\libconcept{invocable}<>} and
\tcode{T} models \libconcept{move_constructible}.

\pnum
\mandates
\tcode{is_same_v<remove_cvref_t<invoke_result_t<F>>, optional>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (*this) {
  return std::move(*this);
} else {
  return std::forward<F>(f)();
}
\end{codeblock}
\end{itemdescr}

\rSec3[optional.mod]{Modifiers}

\indexlibrarymember{reset}{optional}%
\begin{itemdecl}
constexpr void reset() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{*this} contains a value, calls \tcode{val->T::\~T()} to destroy the contained value;
otherwise no effect.

\pnum
\ensures
\tcode{*this} does not contain a value.
\end{itemdescr}

\rSec2[optional.nullopt]{No-value state indicator}

\indexlibraryglobal{nullopt_t}%
\indexlibraryglobal{nullopt}%
\begin{itemdecl}
struct nullopt_t{@\seebelow@};
inline constexpr nullopt_t nullopt(@\unspec@);
\end{itemdecl}

\pnum
The struct \tcode{nullopt_t} is an empty class type used as a unique type to indicate the state of not containing a value for \tcode{optional} objects.
In particular, \tcode{optional<T>} has a constructor with \tcode{nullopt_t} as a single argument;
this indicates that an optional object not containing a value shall be constructed.

\pnum
Type \tcode{nullopt_t} shall not have a default constructor or an initializer-list constructor, and shall not be an aggregate.

\rSec2[optional.bad.access]{Class \tcode{bad_optional_access}}

\begin{codeblock}
namespace std {
  class bad_optional_access : public exception {
  public:
    // see \ref{exception} for the specification of the special member functions
    constexpr const char* what() const noexcept override;
  };
}
\end{codeblock}

\pnum
The class \tcode{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.

\indexlibrarymember{what}{bad_optional_access}%
\begin{itemdecl}
constexpr const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An \impldef{return value of \tcode{bad_optional_access::what}} \ntbs{},
which during constant evaluation is encoded with
the ordinary literal encoding\iref{lex.ccon}.
\end{itemdescr}

\rSec2[optional.relops]{Relational operators}

\indexlibrarymember{operator==}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator==(const optional<T>& x, const optional<U>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{*x == *y} is well-formed and
its result is convertible to \tcode{bool}.
\begin{note}
\tcode{T} need not be \oldconcept{EqualityComparable}.
\end{note}

\pnum
\returns
If \tcode{x.has_value() != y.has_value()}, \tcode{false}; otherwise if \tcode{x.has_value() == false}, \tcode{true}; otherwise \tcode{*x == *y}.

\pnum
\remarks
Specializations of this function template
for which \tcode{*x == *y} is a core constant expression
are constexpr functions.
\end{itemdescr}

\indexlibrarymember{operator"!=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator!=(const optional<T>& x, const optional<U>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{*x != *y} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
If \tcode{x.has_value() != y.has_value()}, \tcode{true};
otherwise, if \tcode{x.has_value() == false}, \tcode{false};
otherwise \tcode{*x != *y}.

\pnum
\remarks
Specializations of this function template
for which \tcode{*x != *y} is a core constant expression
are constexpr functions.
\end{itemdescr}

\indexlibrarymember{operator<}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator<(const optional<T>& x, const optional<U>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{*x < *y} is well-formed
and its result is convertible to \tcode{bool}.

\pnum
\returns
If \tcode{!y}, \tcode{false};
otherwise, if \tcode{!x}, \tcode{true};
otherwise \tcode{*x < *y}.

\pnum
\remarks
Specializations of this function template
for which \tcode{*x < *y} is a core constant expression
are constexpr functions.
\end{itemdescr}

\indexlibrarymember{operator>}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator>(const optional<T>& x, const optional<U>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{*x > *y} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
If \tcode{!x}, \tcode{false};
otherwise, if \tcode{!y}, \tcode{true};
otherwise \tcode{*x > *y}.

\pnum
\remarks
Specializations of this function template
for which \tcode{*x > *y} is a core constant expression
are constexpr functions.
\end{itemdescr}

\indexlibrarymember{operator<=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator<=(const optional<T>& x, const optional<U>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{*x <= *y} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
If \tcode{!x}, \tcode{true};
otherwise, if \tcode{!y}, \tcode{false};
otherwise \tcode{*x <= *y}.

\pnum
\remarks
Specializations of this function template
for which \tcode{*x <= *y} is a core constant expression
are constexpr functions.
\end{itemdescr}

\indexlibrarymember{operator>=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator>=(const optional<T>& x, const optional<U>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{*x >= *y} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
If \tcode{!y}, \tcode{true};
otherwise, if \tcode{!x}, \tcode{false};
otherwise \tcode{*x >= *y}.

\pnum
\remarks
Specializations of this function template
for which \tcode{*x >= *y} is a core constant expression
are constexpr functions.
\end{itemdescr}

\indexlibrarymember{operator<=>}{optional}%
\begin{itemdecl}
template<class T, @\libconcept{three_way_comparable_with}@<T> U>
  constexpr compare_three_way_result_t<T, U>
    operator<=>(const optional<T>& x, const optional<U>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If \tcode{x \&\& y}, \tcode{*x <=> *y}; otherwise \tcode{x.has_value() <=> y.has_value()}.

\pnum
\remarks
Specializations of this function template
for which \tcode{*x <=> *y} is a core constant expression
are constexpr functions.
\end{itemdescr}

\rSec2[optional.nullops]{Comparison with \tcode{nullopt}}

\indexlibrarymember{operator==}{optional}%
\begin{itemdecl}
template<class T> constexpr bool operator==(const optional<T>& x, nullopt_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{!x}.
\end{itemdescr}

\indexlibrarymember{operator<=>}{optional}%
\begin{itemdecl}
template<class T> constexpr strong_ordering operator<=>(const optional<T>& x, nullopt_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.has_value() <=> false}.
\end{itemdescr}

\rSec2[optional.comp.with.t]{Comparison with \tcode{T}}

\indexlibrarymember{operator==}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator==(const optional<T>& x, const U& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{U} is not a specialization of \tcode{optional}.
The expression \tcode{*x == v} is well-formed and
its result is convertible to \tcode{bool}.
\begin{note}
\tcode{T} need not be \oldconcept{EqualityComparable}.
\end{note}

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? *x == v : false;}
\end{itemdescr}

\indexlibrarymember{operator==}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator==(const T& v, const optional<U>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not a specialization of \tcode{optional}.
The expression \tcode{v == *x} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? v == *x : false;}
\end{itemdescr}

\indexlibrarymember{operator"!=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator!=(const optional<T>& x, const U& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{U} is not a specialization of \tcode{optional}.
The expression \tcode{*x != v} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? *x != v : true;}
\end{itemdescr}

\indexlibrarymember{operator"!=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator!=(const T& v, const optional<U>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not a specialization of \tcode{optional}.
The expression \tcode{v != *x} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? v != *x : true;}
\end{itemdescr}

\indexlibrarymember{operator<}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator<(const optional<T>& x, const U& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{U} is not a specialization of \tcode{optional}.
The expression \tcode{*x < v} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? *x < v : true;}
\end{itemdescr}

\indexlibrarymember{operator<}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator<(const T& v, const optional<U>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not a specialization of \tcode{optional}.
The expression \tcode{v < *x} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? v < *x : false;}
\end{itemdescr}

\indexlibrarymember{operator>}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator>(const optional<T>& x, const U& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{U} is not a specialization of \tcode{optional}.
The expression \tcode{*x > v} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? *x > v : false;}
\end{itemdescr}

\indexlibrarymember{operator>}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator>(const T& v, const optional<U>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not a specialization of \tcode{optional}.
The expression \tcode{v > *x} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? v > *x : true;}
\end{itemdescr}

\indexlibrarymember{operator<=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator<=(const optional<T>& x, const U& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{U} is not a specialization of \tcode{optional}.
The expression \tcode{*x <= v} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? *x <= v : true;}
\end{itemdescr}

\indexlibrarymember{operator<=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator<=(const T& v, const optional<U>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not a specialization of \tcode{optional}.
The expression \tcode{v <= *x} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? v <= *x : false;}
\end{itemdescr}

\indexlibrarymember{operator>=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator>=(const optional<T>& x, const U& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{U} is not a specialization of \tcode{optional}.
The expression \tcode{*x >= v} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? *x >= v : false;}
\end{itemdescr}

\indexlibrarymember{operator>=}{optional}%
\begin{itemdecl}
template<class T, class U> constexpr bool operator>=(const T& v, const optional<U>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not a specialization of \tcode{optional}.
The expression \tcode{v >= *x} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? v >= *x : true;}
\end{itemdescr}

\indexlibrarymember{operator<=>}{optional}%
\begin{itemdecl}
template<class T, class U>
    requires (!@\exposconcept{is-derived-from-optional}@<U>) && @\libconcept{three_way_comparable_with}@<T, U>
  constexpr compare_three_way_result_t<T, U>
    operator<=>(const optional<T>& x, const U& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return x.has_value() ? *x <=> v : strong_ordering::less;}
\end{itemdescr}

\rSec2[optional.specalg]{Specialized algorithms}

\indexlibrarymember{swap}{optional}%
\begin{itemdecl}
template<class T>
  constexpr void swap(optional<T>& x, optional<T>& y) noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<T>} is \tcode{true} and
\tcode{is_swappable_v<T>} is \tcode{true}.

\pnum
\effects
Calls \tcode{x.swap(y)}.
\end{itemdescr}

\indexlibraryglobal{make_optional}%
\begin{itemdecl}
template<class T> constexpr optional<decay_t<T>> make_optional(T&& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{optional<decay_t<T>>(std::forward<T>(v))}.
\end{itemdescr}

\indexlibraryglobal{make_optional}%
\begin{itemdecl}
template<class T, class...Args>
  constexpr optional<T> make_optional(Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return optional<T>(in_place, std::forward<Args>(args)...);}
\end{itemdescr}

\indexlibraryglobal{make_optional}%
\begin{itemdecl}
template<class T, class U, class... Args>
  constexpr optional<T> make_optional(initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return optional<T>(in_place, il, std::forward<Args>(args)...);}
\end{itemdescr}

\rSec2[optional.hash]{Hash support}

\indexlibrarymember{hash}{optional}%
\begin{itemdecl}
template<class T> struct hash<optional<T>>;
\end{itemdecl}

\begin{itemdescr}
\pnum
The specialization \tcode{hash<optional<T>>} is enabled\iref{unord.hash}
if and only if \tcode{hash<remove_const_t<T>>} is enabled.
When enabled, for an object \tcode{o} of type \tcode{optional<T>},
if \tcode{o.has_value() == true}, then \tcode{hash<optional<T>>()(o)}
evaluates to the same value as \tcode{hash<remove_const_t<T>>()(*o)};
otherwise it evaluates to an unspecified value.
The member functions are not guaranteed to be \keyword{noexcept}.
\end{itemdescr}


\rSec1[variant]{Variants}

\rSec2[variant.general]{General}

\pnum
A variant object holds and manages the lifetime of a value.
If the \tcode{variant} holds a value, that value's type has to be one
of the template argument types given to \tcode{variant}.
These template arguments are called alternatives.

\pnum
In \ref{variant},
\exposid{GET} denotes
a set of exposition-only function templates\iref{variant.get}.

\rSec2[variant.syn]{Header \tcode{<variant>} synopsis}
\indexheader{variant}%

\begin{codeblock}
// mostly freestanding
#include <compare>              // see \ref{compare.syn}

namespace std {
  // \ref{variant.variant}, class template \tcode{variant}
  template<class... Types>
    class variant;

  // \ref{variant.helper}, variant helper classes
  template<class T> struct variant_size;                        // \notdef
  template<class T> struct variant_size<const T>;
  template<class T>
    constexpr size_t @\libglobal{variant_size_v}@ = variant_size<T>::value;

  template<class... Types>
    struct variant_size<variant<Types...>>;

  template<size_t I, class T> struct variant_alternative;       // \notdef
  template<size_t I, class T> struct variant_alternative<I, const T>;
  template<size_t I, class T>
    using @\libglobal{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;

  // \ref{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;

  // \ref{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 (@\libconcept{three_way_comparable}@<Types> && ...)
    constexpr common_comparison_category_t<compare_three_way_result_t<Types>...>
      operator<=>(const variant<Types...>&, const variant<Types...>&);

  // \ref{variant.visit}, visitation
  template<class Visitor, class... Variants>
    constexpr @\seebelow@ visit(Visitor&&, Variants&&...);
  template<class R, class Visitor, class... Variants>
    constexpr R visit(Visitor&&, Variants&&...);

  // \ref{variant.monostate}, class \tcode{monostate}
  struct monostate;

  // \ref{variant.monostate.relops}, \tcode{monostate} relational operators
  constexpr bool operator==(monostate, monostate) noexcept;
  constexpr strong_ordering operator<=>(monostate, monostate) noexcept;

  // \ref{variant.specalg}, specialized algorithms
  template<class... Types>
    constexpr void swap(variant<Types...>&, variant<Types...>&) noexcept(@\seebelow@);

  // \ref{variant.bad.access}, class \tcode{bad_variant_access}
  class bad_variant_access;

  // \ref{variant.hash}, hash support
  template<class T> struct hash;
  template<class... Types> struct hash<variant<Types...>>;
  template<> struct hash<monostate>;
}
\end{codeblock}

\rSec2[variant.variant]{Class template \tcode{variant}}%
\indexlibraryglobal{variant}%

\rSec3[variant.variant.general]{General}

\begin{codeblock}
namespace std {
  template<class... Types>
  class variant {
  public:
    // \ref{variant.ctor}, constructors
    constexpr variant() noexcept(@\seebelow@);
    constexpr variant(const variant&);
    constexpr variant(variant&&) noexcept(@\seebelow@);

    template<class T>
      constexpr variant(T&&) noexcept(@\seebelow@);

    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&&...);

    // \ref{variant.dtor}, destructor
    constexpr ~variant();

    // \ref{variant.assign}, assignment
    constexpr variant& operator=(const variant&);
    constexpr variant& operator=(variant&&) noexcept(@\seebelow@);

    template<class T> constexpr variant& operator=(T&&) noexcept(@\seebelow@);

    // \ref{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&&...);

    // \ref{variant.status}, value status
    constexpr bool valueless_by_exception() const noexcept;
    constexpr size_t index() const noexcept;

    // \ref{variant.swap}, swap
    constexpr void swap(variant&) noexcept(@\seebelow@);

    // \ref{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&&);
  };
}
\end{codeblock}

\pnum
Any instance of \tcode{variant} at any given time either holds a value
of one of its alternative types or holds no value.
When an instance of \tcode{variant} holds a value of alternative type \tcode{T},
it means that a value of type \tcode{T}, referred to as the \tcode{variant}
object's \defnx{contained value}{contained value!\idxcode{variant}},
is nested within\iref{intro.object} the
\tcode{variant} object.

\pnum
All types in \tcode{Types} shall meet
the \oldconcept{Destructible} requirements (\tref{cpp17.destructible}).

\pnum
A program that instantiates the definition of \tcode{variant} with
no template arguments is ill-formed.

\pnum
If a program declares an explicit or partial specialization of \tcode{variant},
the program is ill-formed, no diagnostic required.

\rSec3[variant.ctor]{Constructors}

\pnum
In the descriptions that follow, let $i$ be in the range \range{0}{sizeof...(Types)},
and $\tcode{T}_i$ be the $i^\text{th}$ type in \tcode{Types}.

\indexlibraryctor{variant}%
\begin{itemdecl}
constexpr variant() noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_default_constructible_v<$\tcode{T}_0$>} is \tcode{true}.

\pnum
\effects
Constructs a \tcode{variant} holding a value-initialized value of type $\tcode{T}_0$.

\pnum
\ensures
\tcode{valueless_by_exception()} is \tcode{false} and \tcode{index()} is \tcode{0}.

\pnum
\throws
Any exception thrown by the value-initialization of $\tcode{T}_0$.

\pnum
\remarks
This function is \keyword{constexpr} if and only if the
value-initialization of the alternative type $\tcode{T}_0$
would be constexpr-suitable\iref{dcl.constexpr}.
The exception specification is equivalent to
\tcode{is_nothrow_default_constructible_v<$\tcode{T}_0$>}.
\begin{note}
See also class \tcode{monostate}.
\end{note}
\end{itemdescr}

\indexlibraryctor{variant}%
\begin{itemdecl}
constexpr variant(const variant& w);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{w} holds a value, initializes the \tcode{variant} to hold the same
alternative as \tcode{w} and direct-initializes the contained value
with \tcode{\exposid{GET}<j>(w)}, where \tcode{j} is \tcode{w.index()}.
Otherwise, initializes the \tcode{variant} to not hold a value.

\pnum
\throws
Any exception thrown by direct-initializing any $\tcode{T}_i$ for all $i$.

\pnum
\remarks
This constructor is defined as deleted unless
\tcode{is_copy_constructible_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.
If \tcode{is_trivially_copy_constructible_v<$\tcode{T}_i$>}
is \tcode{true} for all $i$, this constructor is trivial.
\end{itemdescr}

\indexlibraryctor{variant}%
\begin{itemdecl}
constexpr variant(variant&& w) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.

\pnum
\effects
If \tcode{w} holds a value, initializes the \tcode{variant} to hold the same
alternative as \tcode{w} and direct-initializes the contained value with
\tcode{\exposid{GET}<j>(std::move(w))}, where \tcode{j} is \tcode{w.index()}.
Otherwise, initializes the \tcode{variant} to not hold a value.

\pnum
\throws
Any exception thrown by move-constructing any $\tcode{T}_i$ for all $i$.

\pnum
\remarks
The exception specification is equivalent to the logical \logop{and} of
\tcode{is_nothrow_move_con\-structible_v<$\tcode{T}_i$>} for all $i$.
If \tcode{is_trivially_move_constructible_v<$\tcode{T}_i$>}
is \tcode{true} for all $i$, this constructor is trivial.
\end{itemdescr}

\indexlibraryctor{variant}%
\begin{itemdecl}
template<class T> constexpr variant(T&& t) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let $\tcode{T}_j$ be a type that is determined as follows:
build an imaginary function \tcode{\placeholdernc{FUN}($\tcode{T}_i$)}
for each alternative type $\tcode{T}_i$
for which \tcode{$\tcode{T}_i$ x[] =} \tcode{\{std::forward<T>(t)\};}
is well-formed for some invented variable \tcode{x}.
The overload \tcode{\placeholdernc{FUN}($\tcode{T}_j$)} selected by overload
resolution for the expression \tcode{\placeholdernc{FUN}(std::forward<T>(\brk{}t))} defines
the alternative $\tcode{T}_j$ which is the type of the contained value after
construction.

\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} is nonzero,

\item
\tcode{is_same_v<remove_cvref_t<T>, variant>} is \tcode{false},

\item
\tcode{remove_cvref_t<T>} is neither
a specialization of \tcode{in_place_type_t} nor
a specialization of \tcode{in_place_index_t},

\item
\tcode{is_constructible_v<$\tcode{T}_j$, T>} is \tcode{true}, and

\item
the expression \tcode{\placeholdernc{FUN}(}\brk\tcode{std::forward<T>(t))}
(with \tcode{\placeholdernc{FUN}} being the above-mentioned set of
imaginary functions) is well-formed.
\begin{note}
\begin{codeblock}
variant<string, string> v("abc");
\end{codeblock}
is ill-formed, as both alternative types have an equally viable constructor
for the argument.
\end{note}
\end{itemize}

\pnum
\effects
Initializes \tcode{*this} to hold the alternative type $\tcode{T}_j$ and
direct-non-list-initializes the contained value with \tcode{std::forward<T>(t)}.

\pnum
\ensures
\tcode{holds_alternative<$\tcode{T}_j$>(*this)} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of the selected alternative $\tcode{T}_j$.

\pnum
\remarks
The exception specification is equivalent to
\tcode{is_nothrow_constructible_v<$\tcode{T}_j$, T>}.
If $\tcode{T}_j$'s selected constructor is a constexpr constructor,
this constructor is a constexpr constructor.
\end{itemdescr}

\indexlibraryctor{variant}%
\begin{itemdecl}
template<class T, class... Args> constexpr explicit variant(in_place_type_t<T>, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item There is exactly one occurrence of \tcode{T} in \tcode{Types...} and
\item \tcode{is_constructible_v<T, Args...>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Direct-non-list-initializes the contained value of type \tcode{T}
with \tcode{std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{holds_alternative<T>(*this)} is \tcode{true}.

\pnum
\throws
Any exception thrown by calling the selected constructor of \tcode{T}.

\pnum
\remarks
If \tcode{T}'s selected constructor is a constexpr constructor, this
constructor is a constexpr constructor.
\end{itemdescr}

\indexlibraryctor{variant}%
\begin{itemdecl}
template<class T, class U, class... Args>
  constexpr explicit variant(in_place_type_t<T>, initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item There is exactly one occurrence of \tcode{T} in \tcode{Types...} and
\item \tcode{is_constructible_v<T, initializer_list<U>\&, Args...>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Direct-non-list-initializes the contained value of type \tcode{T}
with \tcode{il, std::forward<Args>(\brk{}args)...}.

\pnum
\ensures
\tcode{holds_alternative<T>(*this)} is \tcode{true}.

\pnum
\throws
Any exception thrown by calling the selected constructor of \tcode{T}.

\pnum
\remarks
If \tcode{T}'s selected constructor is a constexpr constructor, this
constructor is a constexpr constructor.
\end{itemdescr}

\indexlibraryctor{variant}%
\begin{itemdecl}
template<size_t I, class... Args> constexpr explicit variant(in_place_index_t<I>, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{I} is less than \tcode{sizeof...(Types)} and
\item
\tcode{is_constructible_v<$\tcode{T}_I$, Args...>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Direct-non-list-initializes the contained value of type $\tcode{T}_I$
with \tcode{std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{index()} is \tcode{I}.

\pnum
\throws
Any exception thrown by calling the selected constructor of $\tcode{T}_I$.

\pnum
\remarks
If $\tcode{T}_I$'s selected constructor is a constexpr constructor, this
constructor is a constexpr constructor.
\end{itemdescr}

\indexlibraryctor{variant}%
\begin{itemdecl}
template<size_t I, class U, class... Args>
  constexpr explicit variant(in_place_index_t<I>, initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{I} is less than \tcode{sizeof...(Types)} and
\item
\tcode{is_constructible_v<$\tcode{T}_I$, initializer_list<U>\&, Args...>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Direct-non-list-initializes the contained value of type $\tcode{T}_I$
with \tcode{il, std::forward<Args>(\brk{}args)...}.

\pnum
\ensures
\tcode{index()} is \tcode{I}.

\pnum
\throws
Any exception thrown by calling the selected constructor of $\tcode{T}_I$.

\pnum
\remarks
If $\tcode{T}_I$'s selected constructor is a constexpr constructor, this
constructor is a constexpr constructor.
\end{itemdescr}

\rSec3[variant.dtor]{Destructor}

\indexlibrarydtor{variant}%
\begin{itemdecl}
constexpr ~variant();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{valueless_by_exception()} is \tcode{false},
destroys the currently contained value.

\pnum
\remarks
If \tcode{is_trivially_destructible_v<$\tcode{T}_i$>} is \tcode{true} for all $\tcode{T}_i$,
then this destructor is trivial.
\end{itemdescr}

\rSec3[variant.assign]{Assignment}

\indexlibrarymember{operator=}{variant}%
\begin{itemdecl}
constexpr variant& operator=(const variant& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let $j$ be \tcode{rhs.index()}.

\pnum
\effects
\begin{itemize}
\item
If neither \tcode{*this} nor \tcode{rhs} holds a value, there is no effect.
\item
Otherwise, if \tcode{*this} holds a value but \tcode{rhs} does not, destroys the value
contained in \tcode{*this} and sets \tcode{*this} to not hold a value.
\item
Otherwise, if \tcode{index() == $j$}, assigns the value contained in \tcode{rhs}
to the value contained in \tcode{*this}.
\item
Otherwise, if either \tcode{is_nothrow_copy_constructible_v<$\tcode{T}_j$>}
is \tcode{true} or
\tcode{is_nothrow_move_con\-structible_v<$\tcode{T}_j$>} is \tcode{false},
equivalent to \tcode{emplace<$j$>(\exposid{GET}<$j$>(rhs))}.
\item
Otherwise, equivalent to \tcode{operator=(variant(rhs))}.
\end{itemize}

\pnum
\ensures
\tcode{index() == rhs.index()}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
This operator is defined as deleted unless
\tcode{is_copy_constructible_v<$\tcode{T}_i$> \&\&}
\tcode{is_copy_assignable_v<$\tcode{T}_i$>}
is \tcode{true} for all $i$.
If \tcode{is_trivially_copy_constructible_v<$\tcode{T}_i$> \&\&}
\tcode{is_trivially_copy_assignable_v<$\tcode{T}_i$> \&\&}
\tcode{is_trivially_destructible_v<$\tcode{T}_i$>}
is \tcode{true} for all $i$, this assignment operator is trivial.
\end{itemdescr}

\indexlibrarymember{operator=}{variant}%
\begin{itemdecl}
constexpr variant& operator=(variant&& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let $j$ be \tcode{rhs.index()}.

\pnum
\constraints
\tcode{is_move_constructible_v<$\tcode{T}_i$> \&\&}
\tcode{is_move_assignable_v<$\tcode{T}_i$>} is
\tcode{true} for all $i$.

\pnum
\effects
\begin{itemize}
\item
If neither \tcode{*this} nor \tcode{rhs} holds a value, there is no effect.
\item
Otherwise, if \tcode{*this} holds a value but \tcode{rhs} does not, destroys the value
contained in \tcode{*this} and sets \tcode{*this} to not hold a value.
\item
Otherwise, if \tcode{index() == $j$}, assigns \tcode{\exposid{GET}<$j$>(std::move(rhs))} to
the value contained in \tcode{*this}.
\item
Otherwise, equivalent to \tcode{emplace<$j$>(\exposid{GET}<$j$>(std::move(rhs)))}.
\end{itemize}

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
If \tcode{is_trivially_move_constructible_v<$\tcode{T}_i$> \&\&}
\tcode{is_trivially_move_assignable_v<$\tcode{T}_i$> \&\&}
\tcode{is_trivially_destructible_v<$\tcode{T}_i$>}
is \tcode{true} for all $i$, this assignment operator is trivial.
The exception specification is equivalent to
\tcode{is_nothrow_move_constructible_v<$\tcode{T}_i$> \&\& is_nothrow_move_assignable_v<$\tcode{T}_i$>} for all $i$.
\begin{itemize}
\item If an exception is thrown during the call to $\tcode{T}_j$'s move construction
(with $j$ being \tcode{rhs.index()}), the \tcode{variant} will hold no value.
\item If an exception is thrown during the call to $\tcode{T}_j$'s move assignment,
the state of the contained value is as defined by the exception safety
guarantee of $\tcode{T}_j$'s move assignment; \tcode{index()} will be $j$.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{operator=}{variant}%
\begin{itemdecl}
template<class T> constexpr variant& operator=(T&& t) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let $\tcode{T}_j$ be a type that is determined as follows:
build an imaginary function \tcode{\placeholdernc{FUN}($\tcode{T}_i$)}
for each alternative type $\tcode{T}_i$
for which \tcode{$\tcode{T}_i$ x[] =} \tcode{\{std::forward<T>(t)\};}
is well-formed for some invented variable \tcode{x}.
The overload \tcode{\placeholdernc{FUN}($\tcode{T}_j$)} selected by overload
resolution for the expression \tcode{\placeholdernc{FUN}(std::forward<T>(\brk{}t))} defines
the alternative $\tcode{T}_j$ which is the type of the contained value after
assignment.

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_same_v<remove_cvref_t<T>, variant>} is \tcode{false},

\item
\tcode{is_assignable_v<$\tcode{T}_j$\&, T> \&\& is_constructible_v<$\tcode{T}_j$, T>}
is \tcode{true}, and

\item
the expression \tcode{\placeholdernc{FUN}(std::forward<T>(t))}
(with \tcode{\placeholdernc{FUN}} being the above-mentioned set
of imaginary functions) is well-formed.
\begin{note}
\begin{codeblock}
variant<string, string> v;
v = "abc";
\end{codeblock}
is ill-formed, as both alternative types have an equally viable constructor
for the argument.
\end{note}
\end{itemize}

\pnum
\effects
\begin{itemize}
\item
If \tcode{*this} holds a $\tcode{T}_j$, assigns \tcode{std::forward<T>(t)} to
the value contained in \tcode{*this}.
\item
Otherwise, if \tcode{is_nothrow_constructible_v<$\tcode{T}_j$, T> ||}
\tcode{!is_nothrow_move_constructible_v<$\tcode{T}_j$>} is \tcode{true},
equivalent to \tcode{emplace<$j$>(std::forward<T>(t))}.
\item
Otherwise, equivalent to \tcode{emplace<$j$>($\tcode{T}_j$(std::forward<T>(t)))}.
\end{itemize}

\pnum
\ensures
\tcode{holds_alternative<$\tcode{T}_j$>(*this)} is \tcode{true}, with $\tcode{T}_j$
selected by the imaginary function overload resolution described above.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The exception specification is equivalent to:
\begin{codeblock}
is_nothrow_assignable_v<T@$_j$@&, T> && is_nothrow_constructible_v<T@$_j$@, T>
\end{codeblock}
\begin{itemize}
\item If an exception is thrown during the assignment of \tcode{std::forward<T>(t)}
to the value contained in \tcode{*this}, the state of the contained value and
\tcode{t} are as defined by the exception safety guarantee of the assignment
expression; \tcode{valueless_by_exception()} will be \tcode{false}.
\item If an exception is thrown during the initialization of the contained value,
the \tcode{variant} object is permitted to not hold a value.
\end{itemize}
\end{itemdescr}

\rSec3[variant.mod]{Modifiers}

\indexlibrarymember{emplace}{variant}%
\begin{itemdecl}
template<class T, class... Args> constexpr T& emplace(Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<T, Args...>} is \tcode{true}, and
\tcode{T} occurs exactly once in \tcode{Types}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return emplace<@$I$@>(std::forward<Args>(args)...);
\end{codeblock}
where $I$ is the zero-based index of \tcode{T} in \tcode{Types}.
\end{itemdescr}

\indexlibrarymember{emplace}{variant}%
\begin{itemdecl}
template<class T, class U, class... Args>
  constexpr T& emplace(initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<T, initializer_list<U>\&, Args...>} is \tcode{true},
and \tcode{T} occurs exactly once in \tcode{Types}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return emplace<@$I$@>(il, std::forward<Args>(args)...);
\end{codeblock}
where $I$ is the zero-based index of \tcode{T} in \tcode{Types}.
\end{itemdescr}

\indexlibrarymember{emplace}{variant}%
\begin{itemdecl}
template<size_t I, class... Args>
  constexpr variant_alternative_t<I, variant<Types...>>& emplace(Args&&... args);
\end{itemdecl}

\begin{itemdescr}  % NOCHECK: order
\pnum
\mandates
$\tcode{I} < \tcode{sizeof...(Types)}$.

\pnum
\constraints
\tcode{is_constructible_v<$\tcode{T}_I$, Args...>} is \tcode{true}.

\pnum
\effects
Destroys the currently contained value if \tcode{valueless_by_exception()}
is \tcode{false}.
Then direct-non-list-initializes the contained value of type $\tcode{T}_I$
with the arguments \tcode{std::forward<Ar\-gs>(args)...}.

\pnum
\ensures
\tcode{index()} is \tcode{I}.

\pnum
\returns
A reference to the new contained value.

\pnum
\throws
Any exception thrown during the initialization of the contained value.

\pnum
\remarks
If an exception is thrown during the initialization of the contained value,
the \tcode{variant} is permitted to not hold a value.
\end{itemdescr}

\indexlibrarymember{emplace}{variant}%
\begin{itemdecl}
template<size_t I, class U, class... Args>
  constexpr variant_alternative_t<I, variant<Types...>>&
    emplace(initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}  % NOCHECK: order
\pnum
\mandates
$\tcode{I} < \tcode{sizeof...(Types)}$.

\pnum
\constraints
\tcode{is_constructible_v<$\tcode{T}_I$, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\effects
Destroys the currently contained value if \tcode{valueless_by_exception()}
is \tcode{false}.
Then direct-non-list-initializes the contained value of type $\tcode{T}_I$
with \tcode{il, std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{index()} is \tcode{I}.

\pnum
\returns
A reference to the new contained value.

\pnum
\throws
Any exception thrown during the initialization of the contained value.

\pnum
\remarks
If an exception is thrown during the initialization of the contained value,
the \tcode{variant} is permitted to not hold a value.
\end{itemdescr}

\rSec3[variant.status]{Value status}

\indexlibrarymember{valueless_by_exception}{variant}%
\begin{itemdecl}
constexpr bool valueless_by_exception() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Returns \tcode{false} if and only if the \tcode{variant} holds a value.

\pnum
\begin{note}
It is possible for a \tcode{variant} to hold no value
if an exception is thrown during a
type-changing assignment or emplacement. The latter means that even a
\tcode{variant<float, int>} can become \tcode{valueless_by_exception()}, for
instance by
\begin{codeblock}
struct S { operator int() { throw 42; }};
variant<float, int> v{12.f};
v.emplace<1>(S());
\end{codeblock}
\end{note}
\end{itemdescr}

\indexlibrarymember{index}{variant}%
\begin{itemdecl}
constexpr size_t index() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{valueless_by_exception()} is \tcode{true}, returns \tcode{variant_npos}.
Otherwise, returns the zero-based index of the alternative of the contained value.
\end{itemdescr}

\rSec3[variant.swap]{Swap}

\indexlibrarymember{swap}{variant}%
\begin{itemdecl}
constexpr void swap(variant& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_move_constructible_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.

\pnum
\expects
Each $\tcode{T}_i$ meets the \oldconcept{Swappable} requirements\iref{swappable.requirements}.

\pnum
\effects
\begin{itemize}
\item
If \tcode{valueless_by_exception() \&\& rhs.valueless_by_exception()} no effect.
\item
Otherwise, if \tcode{index() == rhs.index()}, calls \tcode{swap(\exposid{GET}<$i$>(*this), \exposid{GET}<$i$>(rhs))} where $i$ is \tcode{index()}.
\item
Otherwise, exchanges values of \tcode{rhs} and \tcode{*this}.
\end{itemize}

\pnum
\throws
If \tcode{index() == rhs.index()},
any exception thrown by \tcode{swap(\exposid{GET}<$i$>(*this), \exposid{GET}<$i$>(rhs))}
with $i$ being \tcode{index()}.
Otherwise, any exception thrown by the move constructor
of $\tcode{T}_i$ or $\tcode{T}_j$
with $i$ being \tcode{index()} and $j$ being \tcode{rhs.index()}.

\pnum
\remarks
If an exception is thrown during the call to function \tcode{swap(\exposid{GET}<$i$>(*this), \exposid{GET}<$i$>(rhs))},
the states of the contained values of \tcode{*this} and of \tcode{rhs} are
determined by the exception safety guarantee of \tcode{swap} for lvalues of
$\tcode{T}_i$ with $i$ being \tcode{index()}.
If an exception is thrown during the exchange of the values of \tcode{*this}
and \tcode{rhs}, the states of the values of \tcode{*this} and of \tcode{rhs}
are determined by the exception safety guarantee of \tcode{variant}'s move constructor.
The exception specification is equivalent to the logical \logop{and} of
\tcode{is_nothrow_move_constructible_v<$\tcode{T}_i$> \&\& is_nothrow_swappable_v<$\tcode{T}_i$>} for all $i$.
\end{itemdescr}

\rSec2[variant.helper]{\tcode{variant} helper classes}

\indexlibraryglobal{variant_size}%
\begin{itemdecl}
template<class T> struct variant_size;
\end{itemdecl}

\begin{itemdescr}
\pnum
All specializations of \tcode{variant_size} meet the
\oldconcept{UnaryTypeTrait} requirements\iref{meta.rqmts}
with a base characteristic of \tcode{integral_constant<size_t, N>} for some \tcode{N}.
\end{itemdescr}

\indexlibraryglobal{variant_size}%
\begin{itemdecl}
template<class T> struct variant_size<const T>;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VS} denote \tcode{variant_size<T>} of the cv-unqualified
type \tcode{T}. Then each specialization of the template meets the
\oldconcept{UnaryTypeTrait} requirements\iref{meta.rqmts} with a
base characteristic of \tcode{integral_constant<size_t, VS::value>}.
\end{itemdescr}

\indexlibraryglobal{variant_size}%
\begin{itemdecl}
template<class... Types>
  struct variant_size<variant<Types...>> : integral_constant<size_t, sizeof...(Types)> { };
\end{itemdecl}
% No itemdescr needed for variant_size<variant<Types...>>

\indexlibraryglobal{variant_alternative}%
\begin{itemdecl}
template<size_t I, class T> struct variant_alternative<I, const T>;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VA} denote \tcode{variant_alternative<I, T>} of the
cv-unqualified type \tcode{T}. Then each specialization of the template
meets the \oldconcept{TransformationTrait} requirements\iref{meta.rqmts} with a
member typedef \tcode{type} that names the type \tcode{add_const_t<VA::type>}.
\end{itemdescr}

\indexlibraryglobal{variant_alternative}%
\begin{itemdecl}
variant_alternative<I, variant<Types...>>::type
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
$\tcode{I} < \tcode{sizeof...(Types)}$.

\pnum
\ctype
The type $\tcode{T}_I$.
\end{itemdescr}

\rSec2[variant.get]{Value access}

\indexlibraryglobal{holds_alternative}
\indexlibrarymember{variant}{holds_alternative}
\begin{itemdecl}
template<class T, class... Types>
  constexpr bool holds_alternative(const variant<Types...>& v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The type \tcode{T} occurs exactly once in \tcode{Types}.

\pnum
\returns
\tcode{true} if \tcode{index()} is equal to the zero-based index of \tcode{T} in \tcode{Types}.
\end{itemdescr}

\begin{itemdecl}
template<size_t I, class... Types>
  constexpr variant_alternative_t<I, variant<Types...>>&
    @\exposid{GET}@(variant<Types...>& v);                                  // \expos
template<size_t I, class... Types>
  constexpr variant_alternative_t<I, variant<Types...>>&&
    @\exposid{GET}@(variant<Types...>&& v);                                 // \expos
template<size_t I, class... Types>
  constexpr const variant_alternative_t<I, variant<Types...>>&
    @\exposid{GET}@(const variant<Types...>& v);                            // \expos
template<size_t I, class... Types>
  constexpr const variant_alternative_t<I, variant<Types...>>&&
    @\exposid{GET}@(const variant<Types...>&& v);                           // \expos
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
$\tcode{I} < \tcode{sizeof...(Types)}$.

\pnum
\expects
\tcode{v.index()} is \tcode{I}.

\pnum
\returns
A reference to the object stored in the \tcode{variant}.
\end{itemdescr}

\indexlibrarymember{get}{variant}%
\begin{itemdecl}
template<size_t I, class... Types>
  constexpr variant_alternative_t<I, variant<Types...>>& get(variant<Types...>& v);
template<size_t I, class... Types>
  constexpr variant_alternative_t<I, variant<Types...>>&& get(variant<Types...>&& v);
template<size_t I, class... Types>
  constexpr const variant_alternative_t<I, variant<Types...>>& get(const variant<Types...>& v);
template<size_t I, class... Types>
  constexpr const variant_alternative_t<I, variant<Types...>>&& get(const variant<Types...>&& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
$\tcode{I} < \tcode{sizeof...(Types)}$.

\pnum
\effects
If \tcode{v.index()} is \tcode{I}, returns a reference to the object stored in
the \tcode{variant}. Otherwise, throws an exception of type \tcode{bad_variant_access}.
\end{itemdescr}

\indexlibrarymember{get}{variant}%
\begin{itemdecl}
template<class T, class... Types> constexpr T& get(variant<Types...>& v);
template<class T, class... Types> constexpr T&& get(variant<Types...>&& v);
template<class T, class... Types> constexpr const T& get(const variant<Types...>& v);
template<class T, class... Types> constexpr const T&& get(const variant<Types...>&& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The type \tcode{T} occurs exactly once in \tcode{Types}.

\pnum
\effects
If \tcode{v} holds a value of type \tcode{T}, returns a reference to that value.
Otherwise, throws an exception of type \tcode{bad_variant_access}.
\end{itemdescr}

\indexlibraryglobal{get_if}%
\indexlibrarymember{variant}{get_if}%
\begin{itemdecl}
template<size_t I, class... Types>
  constexpr add_pointer_t<variant_alternative_t<I, variant<Types...>>>
    get_if(variant<Types...>* v) noexcept;
template<size_t I, class... Types>
  constexpr add_pointer_t<const variant_alternative_t<I, variant<Types...>>>
    get_if(const variant<Types...>* v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
$\tcode{I} < \tcode{sizeof...(Types)}$.

\pnum
\returns
A pointer to the value stored in the \tcode{variant}, if \tcode{v != nullptr}
and \tcode{v->index() == I}. Otherwise, returns \keyword{nullptr}.
\end{itemdescr}

\indexlibraryglobal{get_if}%
\indexlibrarymember{variant}{get_if}%
\begin{itemdecl}
template<class T, class... Types>
  constexpr add_pointer_t<T>
    get_if(variant<Types...>* v) noexcept;
template<class T, class... Types>
  constexpr add_pointer_t<const T>
    get_if(const variant<Types...>* v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The type \tcode{T} occurs exactly once in \tcode{Types}.

\pnum
\effects
Equivalent to: \tcode{return get_if<$i$>(v);} with $i$ being the zero-based
index of \tcode{T} in \tcode{Types}.
\end{itemdescr}

\rSec2[variant.relops]{Relational operators}

\indexlibrarymember{operator==}{variant}%
\begin{itemdecl}
template<class... Types>
  constexpr bool operator==(const variant<Types...>& v, const variant<Types...>& w);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{\exposid{GET}<$i$>(v) == \exposid{GET}<$i$>(w)} is a valid expression that is
convertible to \tcode{bool}, for all $i$.

\pnum
\returns
If \tcode{v.index() != w.index()}, \tcode{false};
otherwise if \tcode{v.valueless_by_exception()}, \tcode{true};
otherwise \tcode{\exposid{GET}<$i$>(v) == \exposid{GET}<$i$>(w)} with $i$ being \tcode{v.index()}.
\end{itemdescr}

\indexlibrarymember{operator"!=}{variant}%
\begin{itemdecl}
template<class... Types>
  constexpr bool operator!=(const variant<Types...>& v, const variant<Types...>& w);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{\exposid{GET}<$i$>(v) != \exposid{GET}<$i$>(w)} is a valid expression that is
convertible to \tcode{bool}, for all $i$.

\pnum
\returns
If \tcode{v.index() != w.index()}, \tcode{true};
otherwise if \tcode{v.valueless_by_exception()}, \tcode{false};
otherwise \tcode{\exposid{GET}<$i$>(v) != \exposid{GET}<$i$>(w)} with $i$ being \tcode{v.index()}.
\end{itemdescr}

\indexlibrarymember{operator<}{variant}%
\begin{itemdecl}
template<class... Types>
  constexpr bool operator<(const variant<Types...>& v, const variant<Types...>& w);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{\exposid{GET}<$i$>(v) < \exposid{GET}<$i$>(w)} is a valid expression that is
convertible to \tcode{bool}, for all $i$.

\pnum
\returns
If \tcode{w.valueless_by_exception()}, \tcode{false};
otherwise if \tcode{v.valueless_by_exception()}, \tcode{true};
otherwise, if \tcode{v.index() < w.index()}, \tcode{true};
otherwise if \tcode{v.index() > w.index()}, \tcode{false};
otherwise \tcode{\exposid{GET}<$i$>(v) < \exposid{GET}<$i$>(w)} with $i$ being \tcode{v.index()}.
\end{itemdescr}

\indexlibrarymember{operator>}{variant}%
\begin{itemdecl}
template<class... Types>
  constexpr bool operator>(const variant<Types...>& v, const variant<Types...>& w);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{\exposid{GET}<$i$>(v) > \exposid{GET}<$i$>(w)} is a valid expression that is
convertible to \tcode{bool}, for all $i$.

\pnum
\returns
If \tcode{v.valueless_by_exception()}, \tcode{false};
otherwise if \tcode{w.valueless_by_exception()}, \tcode{true};
otherwise, if \tcode{v.index() > w.index()}, \tcode{true};
otherwise if \tcode{v.index() < w.index()}, \tcode{false};
otherwise \tcode{\exposid{GET}<$i$>(v) > \exposid{GET}<$i$>(w)} with $i$ being \tcode{v.index()}.
\end{itemdescr}

\indexlibrarymember{operator<=}{variant}%
\begin{itemdecl}
template<class... Types>
  constexpr bool operator<=(const variant<Types...>& v, const variant<Types...>& w);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{\exposid{GET}<$i$>(v) <= \exposid{GET}<$i$>(w)} is a valid expression that is
convertible to \tcode{bool}, for all $i$.

\pnum
\returns
If \tcode{v.valueless_by_exception()}, \tcode{true};
otherwise if \tcode{w.valueless_by_exception()}, \tcode{false};
otherwise, if \tcode{v.index() < w.index()}, \tcode{true};
otherwise if \tcode{v.index() > w.index()}, \tcode{false};
otherwise \tcode{\exposid{GET}<$i$>(v) <= \exposid{GET}<$i$>(w)} with $i$ being \tcode{v.index()}.
\end{itemdescr}

\indexlibrarymember{operator>=}{variant}%
\begin{itemdecl}
template<class... Types>
  constexpr bool operator>=(const variant<Types...>& v, const variant<Types...>& w);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{\exposid{GET}<$i$>(v) >= \exposid{GET}<$i$>(w)} is a valid expression that is
convertible to \tcode{bool}, for all $i$.

\pnum
\returns
If \tcode{w.valueless_by_exception()}, \tcode{true};
otherwise if \tcode{v.valueless_by_exception()}, \tcode{false};
otherwise, if \tcode{v.index() > w.index()}, \tcode{true};
otherwise if \tcode{v.index() < w.index()}, \tcode{false};
otherwise \tcode{\exposid{GET}<$i$>(v) >= \exposid{GET}<$i$>(w)} with $i$ being \tcode{v.index()}.
\end{itemdescr}

\indexlibrarymember{operator<=>}{variant}%
\begin{itemdecl}
template<class... Types> requires (@\libconcept{three_way_comparable}@<Types> && ...)
  constexpr common_comparison_category_t<compare_three_way_result_t<Types>...>
    operator<=>(const variant<Types...>& v, const variant<Types...>& w);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
if (v.valueless_by_exception() && w.valueless_by_exception())
  return strong_ordering::equal;
if (v.valueless_by_exception()) return strong_ordering::less;
if (w.valueless_by_exception()) return strong_ordering::greater;
if (auto c = v.index() <=> w.index(); c != 0) return c;
return @\exposid{GET}@<@$i$@>(v) <=> @\exposid{GET}@<@$i$@>(w);
\end{codeblock}
with $i$ being \tcode{v.index()}.
\end{itemdescr}

\rSec2[variant.visit]{Visitation}

\indexlibraryglobal{visit}%
\indexlibrarymember{variant}{visit}%
\begin{itemdecl}
template<class Visitor, class... Variants>
  constexpr @\seebelow@ visit(Visitor&& vis, Variants&&... vars);
template<class R, class Visitor, class... Variants>
  constexpr R visit(Visitor&& vis, Variants&&... vars);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \exposid{as-variant} denote the following exposition-only function templates:
\begin{codeblock}
template<class... Ts>
  constexpr auto&& @\exposid{as-variant}@(variant<Ts...>& var) { return var; }
template<class... Ts>
  constexpr auto&& @\exposid{as-variant}@(const variant<Ts...>& var) { return var; }
template<class... Ts>
  constexpr auto&& @\exposid{as-variant}@(variant<Ts...>&& var) { return std::move(var); }
template<class... Ts>
  constexpr auto&& @\exposid{as-variant}@(const variant<Ts...>&& var) { return std::move(var); }
\end{codeblock}
Let $n$ be \tcode{sizeof...(Variants)}.
For each $0 \leq i < n$, let
$\tcode{V}_i$ denote the type\newline
\tcode{decltype(\exposid{as-variant}(\tcode{std::forward<$\tcode{Variants}_i$>($\tcode{vars}_i$)}))}.

\pnum
\constraints
$\tcode{V}_i$ is a valid type for all $0 \leq i < n$.

\pnum
Let \tcode{V} denote the pack of types $\tcode{V}_i$.

\pnum
Let $m$ be a pack of $n$ values of type \tcode{size_t}.
Such a pack is valid if\newline
$0 \leq m_i < \tcode{variant_size_v<remove_reference_t<V}_i\tcode{>>}$
for all $0 \leq i < n$.
For each valid pack $m$, let $e(m)$ denote the expression:
\begin{codeblock}
@\placeholder{INVOKE}@(std::forward<Visitor>(vis), @\exposid{GET}@<@$m$@>(std::forward<V>(vars))...)  // see \ref{func.require}
\end{codeblock}
for the first form and
\begin{codeblock}
@\placeholder{INVOKE}@<R>(std::forward<Visitor>(vis), @\exposid{GET}@<@$m$@>(std::forward<V>(vars))...)  // see \ref{func.require}
\end{codeblock}
for the second form.

\pnum
\mandates
For each valid pack $m$, $e(m)$ is a valid expression.
All such expressions are of the same type and value category.

\pnum
\returns
$e(m)$, where $m$ is the pack for which
$m_i$ is \tcode{\exposid{as-variant}(vars$_i$).index()} for all $0 \leq i < n$.
The return type is $\tcode{decltype(}e(m)\tcode{)}$
for the first form.

\pnum
\throws
\tcode{bad_variant_access} if
\tcode{(\exposid{as-variant}(vars).valueless_by_exception() || ...)}
is \tcode{true}.

\pnum
\complexity
For $n \leq 1$, the invocation of the callable object is
implemented in constant time, i.e., for $n = 1$, it does not depend on
the number of alternative types of $\tcode{V}_0$.
For $n > 1$, the invocation of the callable object has
no complexity requirements.
\end{itemdescr}

\indexlibrarymember{visit}{variant}%
\begin{itemdecl}
template<class Self, class Visitor>
  constexpr decltype(auto) visit(this Self&& self, Visitor&& vis);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{V} be
\tcode{\exposid{OVERRIDE_REF}(Self\&\&, \exposid{COPY_CONST}(remove_reference_t<Self>, variant))}\iref{forward}.

\pnum
\constraints
The call to \tcode{visit} does not use
an explicit \grammarterm{template-argument-list} that
begins with a type \grammarterm{template-argument}.

\pnum
\effects
Equivalent to: \tcode{return std::visit(std::forward<Visitor>(vis), (V)self);}
\end{itemdescr}

\indexlibrarymember{visit}{variant}%
\begin{itemdecl}
template<class R, class Self, class Visitor>
  constexpr R visit(this Self&& self, Visitor&& vis);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{V} be
\tcode{\exposid{OVERRIDE_REF}(Self\&\&, \exposid{COPY_CONST}(remove_reference_t<Self>, variant))}\iref{forward}.

\pnum
\effects
Equivalent to: \tcode{return std::visit<R>(std::forward<Visitor>(vis), (V)self);}
\end{itemdescr}

\rSec2[variant.monostate]{Class \tcode{monostate}}%
\indexlibraryglobal{monostate}%

\begin{itemdecl}
struct monostate{};
\end{itemdecl}

\begin{itemdescr}
\pnum
The class \tcode{monostate} can serve as a first alternative type for
a \tcode{variant} to make the \tcode{variant} type default constructible.
\end{itemdescr}


\rSec2[variant.monostate.relops]{\tcode{monostate} relational operators}

\indexlibrarymember{operator==}{monostate}%
\indexlibrarymember{operator<=>}{monostate}%
\begin{itemdecl}
constexpr bool operator==(monostate, monostate) noexcept { return true; }
constexpr strong_ordering operator<=>(monostate, monostate) noexcept
{ return strong_ordering::equal; }
\end{itemdecl}

\begin{itemdescr}
\pnum
\begin{note}
\tcode{monostate} objects have only a single state; they thus always compare equal.
\end{note}
\end{itemdescr}

\rSec2[variant.specalg]{Specialized algorithms}

\indexlibrarymember{swap}{variant}%
\begin{itemdecl}
template<class... Types>
  constexpr void swap(variant<Types...>& v, variant<Types...>& w) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<$\tcode{T}_i$> \&\& is_swappable_v<$\tcode{T}_i$>}
is \tcode{true} for all $i$.

\pnum
\effects
Equivalent to \tcode{v.swap(w)}.

\pnum
\remarks
The exception specification is equivalent to \tcode{noexcept(v.swap(w))}.
\end{itemdescr}

\rSec2[variant.bad.access]{Class \tcode{bad_variant_access}}%
\indexlibraryglobal{bad_variant_access}%

\begin{codeblock}
namespace std {
  class bad_variant_access : public exception {
  public:
    // see \ref{exception} for the specification of the special member functions
    constexpr const char* what() const noexcept override;
  };
}
\end{codeblock}

\pnum
Objects of type \tcode{bad_variant_access} are thrown to report invalid
accesses to the value of a \tcode{variant} object.

\indexlibrarymember{what}{bad_variant_access}%
\begin{itemdecl}
constexpr const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An \impldef{return value of \tcode{bad_variant_access::what}} \ntbs{},
which during constant evaluation is encoded with
the ordinary literal encoding\iref{lex.ccon}.
\end{itemdescr}

\rSec2[variant.hash]{Hash support}

\indexlibrarymember{hash}{variant}%
\begin{itemdecl}
template<class... Types> struct hash<variant<Types...>>;
\end{itemdecl}

\begin{itemdescr}
\pnum
The specialization \tcode{hash<variant<Types...>>} is enabled\iref{unord.hash}
if and only if every specialization in \tcode{hash<remove_const_t<Types>>...} is enabled.
The member functions are not guaranteed to be \keyword{noexcept}.
\end{itemdescr}

\indexlibrarymember{hash}{monostate}%
\begin{itemdecl}
template<> struct hash<monostate>;
\end{itemdecl}

\begin{itemdescr}
\pnum
The specialization is enabled\iref{unord.hash}.
\end{itemdescr}


\rSec1[any]{Storage for any type}

\rSec2[any.general]{General}

\pnum
Subclause \ref{any} describes components that \Cpp{} programs may use to perform operations on objects of a discriminated type.

\pnum
\begin{note}
The discriminated type can contain values of different types but does not attempt conversion between them,
i.e., \tcode{5} is held strictly as an \tcode{int} and is not implicitly convertible either to \tcode{"5"} or to \tcode{5.0}.
This indifference to interpretation but awareness of type effectively allows safe, generic containers of single values, with no scope for surprises from ambiguous conversions.
\end{note}

\rSec2[any.synop]{Header \tcode{<any>} synopsis}

\indexheader{any}%

\begin{codeblock}
namespace std {
  // \ref{any.bad.any.cast}, class \tcode{bad_any_cast}
  class bad_any_cast;

  // \ref{any.class}, class \tcode{any}
  class any;

  // \ref{any.nonmembers}, non-member functions
  void swap(any& x, any& y) noexcept;

  template<class T, class... Args>
    any make_any(Args&&... args);
  template<class T, class U, class... Args>
    any make_any(initializer_list<U> il, Args&&... args);

  template<class T>
    T any_cast(const any& operand);
  template<class T>
    T any_cast(any& operand);
  template<class T>
    T any_cast(any&& operand);

  template<class T>
    const T* any_cast(const any* operand) noexcept;
  template<class T>
    T* any_cast(any* operand) noexcept;
}
\end{codeblock}

\rSec2[any.bad.any.cast]{Class \tcode{bad_any_cast}}

\indexlibraryglobal{bad_any_cast}%
\begin{codeblock}
namespace std {
  class bad_any_cast : public bad_cast {
  public:
    // see \ref{exception} for the specification of the special member functions
    const char* what() const noexcept override;
  };
}
\end{codeblock}

\pnum
Objects of type \tcode{bad_any_cast} are thrown by a failed \tcode{any_cast}\iref{any.nonmembers}.

\indexlibrarymember{what}{bad_any_cast}%
\begin{itemdecl}
const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An \impldef{return value of \tcode{bad_any_cast::what}} \ntbs{}.
\end{itemdescr}

\rSec2[any.class]{Class \tcode{any}}

\rSec3[any.class.general]{General}

\begin{codeblock}
namespace std {
  class any {
  public:
    // \ref{any.cons}, construction and destruction
    constexpr any() noexcept;

    any(const any& other);
    any(any&& other) noexcept;

    template<class T>
      any(T&& value);

    template<class T, class... Args>
      explicit any(in_place_type_t<T>, Args&&...);
    template<class T, class U, class... Args>
      explicit any(in_place_type_t<T>, initializer_list<U>, Args&&...);

    ~any();

    // \ref{any.assign}, assignments
    any& operator=(const any& rhs);
    any& operator=(any&& rhs) noexcept;

    template<class T>
      any& operator=(T&& rhs);

    // \ref{any.modifiers}, modifiers
    template<class T, class... Args>
      decay_t<T>& emplace(Args&&...);
    template<class T, class U, class... Args>
      decay_t<T>& emplace(initializer_list<U>, Args&&...);
    void reset() noexcept;
    void swap(any& rhs) noexcept;

    // \ref{any.observers}, observers
    bool has_value() const noexcept;
    const type_info& type() const noexcept;
  };
}
\end{codeblock}

\pnum
An object of class \tcode{any} stores an instance of any type that meets the constructor requirements or it has no value,
and this is referred to as the \defn{state} of the class \tcode{any} object.
The stored instance is called the \defnx{contained value}{contained value!\idxcode{any}}.
Two states are equivalent if either they both have no value, or they both have a value and the contained values are equivalent.

\pnum
The non-member \tcode{any_cast} functions provide type-safe access to the contained value.

\pnum
Implementations should avoid the use of dynamically allocated memory for a small contained value.
However, any such small-object optimization shall only be applied to types \tcode{T} for which
\tcode{is_nothrow_move_constructible_v<T>} is \tcode{true}.
\begin{example}
A contained value of type \tcode{int} could be stored in an internal buffer,
not in separately-allocated memory.
\end{example}

\rSec3[any.cons]{Construction and destruction}

\indexlibraryctor{any}%
\begin{itemdecl}
constexpr any() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{has_value()} is \tcode{false}.
\end{itemdescr}

\indexlibraryctor{any}%
\begin{itemdecl}
any(const any& other);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{other.has_value()} is \tcode{false}, constructs an object that has no value.
Otherwise, equivalent to \tcode{any(in_place_type<T>, any_cast<const T\&>(other))}
where \tcode{T} is the type of the contained value.

\pnum
\throws
Any exceptions arising from calling the selected constructor for the contained value.
\end{itemdescr}

\indexlibraryctor{any}%
\begin{itemdecl}
any(any&& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{other.has_value()} is \tcode{false}, constructs an object that has no value.
Otherwise, constructs an object of type \tcode{any} that
contains either the contained value of \tcode{other}, or
contains an object of the same type constructed from
the contained value of \tcode{other} considering that contained value as an rvalue.
\end{itemdescr}

\indexlibraryctor{any}%
\begin{itemdecl}
template<class T>
  any(T&& value);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\tcode{VT} is not the same type as \tcode{any},
\tcode{VT} is not a specialization of \tcode{in_place_type_t},
and \tcode{is_copy_constructible_v<VT>} is \tcode{true}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{CopyConstructible} requirements.

\pnum
\effects
Constructs an object of type \tcode{any} that contains an object of type \tcode{VT} direct-initialized with \tcode{std::forward<T>(value)}.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{VT}.
\end{itemdescr}

\indexlibraryctor{any}%
\begin{itemdecl}
template<class T, class... Args>
  explicit any(in_place_type_t<T>, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\tcode{is_copy_constructible_v<VT>} is \tcode{true} and
\tcode{is_constructible_v<VT, Args...>} is \tcode{true}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{CopyConstructible} requirements.

\pnum
\effects
Direct-non-list-initializes the contained value of type \tcode{VT}
with \tcode{std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{*this} contains a value of type \tcode{VT}.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{VT}.
\end{itemdescr}

\indexlibraryctor{any}%
\begin{itemdecl}
template<class T, class U, class... Args>
  explicit any(in_place_type_t<T>, initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\tcode{is_copy_constructible_v<VT>} is \tcode{true} and
\tcode{is_constructible_v<VT, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{CopyConstructible} requirements.

\pnum
\effects
Direct-non-list-initializes the contained value of type \tcode{VT}
with \tcode{il, std::forward<Args>(\brk{}args)...}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{VT}.
\end{itemdescr}

\indexlibrarydtor{any}
\begin{itemdecl}
~any();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by \tcode{reset()}.
\end{itemdescr}

\rSec3[any.assign]{Assignment}

\indexlibrarymember{operator=}{any}%
\begin{itemdecl}
any& operator=(const any& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by \tcode{any(rhs).swap(*this)}.
No effects if an exception is thrown.

\pnum
\returns
\tcode{*this}.

\pnum
\throws
Any exceptions arising from the copy constructor for the contained value.
\end{itemdescr}

\indexlibrarymember{operator=}{any}%
\begin{itemdecl}
any& operator=(any&& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by \tcode{any(std::move(rhs)).swap(*this)}.

\pnum
\ensures
The state of \tcode{*this} is equivalent to the original state of \tcode{rhs}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{any}%
\begin{itemdecl}
template<class T>
  any& operator=(T&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\tcode{VT} is not the same type as \tcode{any} and
\tcode{is_copy_constructible_v<VT>} is \tcode{true}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{CopyConstructible} requirements.

\pnum
\effects
Constructs an object \tcode{tmp} of type \tcode{any} that contains an object of type \tcode{VT} direct-initialized with \tcode{std::forward<T>(rhs)}, and \tcode{tmp.swap(*this)}.
No effects if an exception is thrown.

\pnum
\returns
\tcode{*this}.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{VT}.
\end{itemdescr}

\rSec3[any.modifiers]{Modifiers}

\indexlibrarymember{emplace}{any}%
\begin{itemdecl}
template<class T, class... Args>
  decay_t<T>& emplace(Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\tcode{is_copy_constructible_v<VT>} is \tcode{true} and
\tcode{is_constructible_v<VT, Args...>} is \tcode{true}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{CopyConstructible} requirements.

\pnum
\effects
Calls \tcode{reset()}.
Then direct-non-list-initializes the contained value of type \tcode{VT}
with \tcode{std::for\-ward<Args>(args)...}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\returns
A reference to the new contained value.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{VT}.

\pnum
\remarks
If an exception is thrown during the call to \tcode{VT}'s constructor,
\tcode{*this} does not contain a value, and any previously contained value
has been destroyed.
\end{itemdescr}

\indexlibrarymember{emplace}{any}%
\begin{itemdecl}
template<class T, class U, class... Args>
  decay_t<T>& emplace(initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\tcode{is_copy_constructible_v<VT>} is \tcode{true} and
\tcode{is_constructible_v<VT, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{CopyConstructible} requirements.

\pnum
\effects
Calls \tcode{reset()}. Then direct-non-list-initializes the contained value
of type \tcode{VT} with \tcode{il, std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{*this} contains a value.

\pnum
\returns
A reference to the new contained value.

\pnum
\throws
Any exception thrown by the selected constructor of \tcode{VT}.

\pnum
\remarks
If an exception is thrown during the call to \tcode{VT}'s constructor,
\tcode{*this} does not contain a value, and any previously contained value
has been destroyed.
\end{itemdescr}

\indexlibrarymember{reset}{any}%
\begin{itemdecl}
void reset() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{has_value()} is \tcode{true}, destroys the contained value.

\pnum
\ensures
\tcode{has_value()} is \tcode{false}.
\end{itemdescr}

\indexlibrarymember{swap}{any}%
\begin{itemdecl}
void swap(any& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
Exchanges the states of \tcode{*this} and \tcode{rhs}.
\end{itemdescr}

\rSec3[any.observers]{Observers}

\indexlibrarymember{has_value}{any}%
\begin{itemdecl}
bool has_value() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if \tcode{*this} contains an object, otherwise \tcode{false}.
\end{itemdescr}

\indexlibrarymember{type}{any}%
\begin{itemdecl}
const type_info& type() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{typeid(T)} if \tcode{*this} has a contained value of type \tcode{T},
otherwise \tcode{typeid(void)}.

\pnum
\begin{note}
Useful for querying against types known either at compile time or only at runtime.
\end{note}
\end{itemdescr}

\rSec2[any.nonmembers]{Non-member functions}

\indexlibrarymember{swap}{any}%
\begin{itemdecl}
void swap(any& x, any& y) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{x.swap(y)}.
\end{itemdescr}

\indexlibraryglobal{make_any}%
\begin{itemdecl}
template<class T, class... Args>
  any make_any(Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return any(in_place_type<T>, std::forward<Args>(args)...);}
\end{itemdescr}

\indexlibraryglobal{make_any}%
\begin{itemdecl}
template<class T, class U, class... Args>
  any make_any(initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return any(in_place_type<T>, il, std::forward<Args>(args)...);}
\end{itemdescr}

\indexlibraryglobal{any_cast}%
\begin{itemdecl}
template<class T>
  T any_cast(const any& operand);
template<class T>
  T any_cast(any& operand);
template<class T>
  T any_cast(any&& operand);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be the type \tcode{remove_cvref_t<T>}.

\pnum
\mandates
For the first overload, \tcode{is_constructible_v<T, const U\&>} is \tcode{true}.
For the second overload, \tcode{is_constructible_v<T, U\&>} is \tcode{true}.
For the third overload, \tcode{is_constructible_v<T, U>} is \tcode{true}.

\pnum
\returns
For the first and second overload, \tcode{static_cast<T>(*any_cast<U>(\&operand))}.
For the third overload, \tcode{static_cast<T>(std::move(*any_cast<U>(\&operand)))}.

\pnum
\throws
\tcode{bad_any_cast} if \tcode{operand.type() != typeid(remove_reference_t<T>)}.

\pnum
\begin{example}
\begin{codeblock}
any x(5);                                   // \tcode{x} holds \tcode{int}
assert(any_cast<int>(x) == 5);              // cast to value
any_cast<int&>(x) = 10;                     // cast to reference
assert(any_cast<int>(x) == 10);

x = "Meow";                                 // \tcode{x} holds \tcode{const char*}
assert(strcmp(any_cast<const char*>(x), "Meow") == 0);
any_cast<const char*&>(x) = "Harry";
assert(strcmp(any_cast<const char*>(x), "Harry") == 0);

x = string("Meow");                         // \tcode{x} holds \tcode{string}
string s, s2("Jane");
s = move(any_cast<string&>(x));             // move from \tcode{any}
assert(s == "Meow");
any_cast<string&>(x) = move(s2);            // move to \tcode{any}
assert(any_cast<const string&>(x) == "Jane");

string cat("Meow");
const any y(cat);                           // \tcode{const y} holds \tcode{string}
assert(any_cast<const string&>(y) == cat);

any_cast<string&>(y);                       // error: cannot \tcode{any_cast} away const
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{any_cast}%
\begin{itemdecl}
template<class T>
  const T* any_cast(const any* operand) noexcept;
template<class T>
  T* any_cast(any* operand) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_void_v<T>} is \tcode{false}.

\pnum
\returns
If \tcode{operand != nullptr \&\& operand->type() == typeid(T)} is \tcode{true},
a pointer to the object contained by \tcode{operand};
otherwise, \keyword{nullptr}.

\pnum
\begin{example}
\begin{codeblock}
bool is_string(const any& operand) {
  return any_cast<string>(&operand) != nullptr;
}
\end{codeblock}
\end{example}
\end{itemdescr}

\rSec1[expected]{Expected objects}
\indexlibraryglobal{expected}%

\rSec2[expected.general]{General}

\pnum
Subclause \ref{expected} describes the class template \tcode{expected}
that represents expected objects.
An \tcode{expected<T, E>} object holds
an object of type \tcode{T} or an object of type \tcode{E} and
manages the lifetime of the contained objects.

\rSec2[expected.syn]{Header \tcode{<expected>} synopsis}

\indexheader{expected}%
\indexlibraryglobal{unexpect_t}%
\indexlibraryglobal{unexpect}%
\begin{codeblock}
// mostly freestanding
namespace std {
  // \ref{expected.unexpected}, class template \tcode{unexpected}
  template<class E> class unexpected;

  // \ref{expected.bad}, class template \tcode{bad_expected_access}
  template<class E> class bad_expected_access;

  // \ref{expected.bad.void}, specialization for \tcode{void}
  template<> class bad_expected_access<void>;

  // in-place construction of unexpected values
  struct unexpect_t {
    explicit unexpect_t() = default;
  };
  inline constexpr unexpect_t unexpect{};

  // \ref{expected.expected}, class template \tcode{expected}
  template<class T, class E> class expected;                                // partially freestanding

  // \ref{expected.void}, partial specialization of \tcode{expected} for \tcode{void} types
  template<class T, class E> requires is_void_v<T> class expected<T, E>;    // partially freestanding
}
\end{codeblock}

\rSec2[expected.unexpected]{Class template \tcode{unexpected}}

\rSec3[expected.un.general]{General}

\pnum
Subclause \ref{expected.unexpected} describes the class template \tcode{unexpected}
that represents unexpected objects stored in \tcode{expected} objects.

\indexlibraryglobal{unexpected}%
\begin{codeblock}
namespace std {
  template<class E>
  class unexpected {
  public:
    // \ref{expected.un.cons}, constructors
    constexpr unexpected(const unexpected&) = default;
    constexpr unexpected(unexpected&&) = default;
    template<class Err = E>
      constexpr explicit unexpected(Err&&);
    template<class... Args>
      constexpr explicit unexpected(in_place_t, Args&&...);
    template<class U, class... Args>
      constexpr explicit unexpected(in_place_t, initializer_list<U>, Args&&...);

    constexpr unexpected& operator=(const unexpected&) = default;
    constexpr unexpected& operator=(unexpected&&) = default;

    constexpr const E& error() const & noexcept;
    constexpr E& error() & noexcept;
    constexpr const E&& error() const && noexcept;
    constexpr E&& error() && noexcept;

    constexpr void swap(unexpected& other) noexcept(@\seebelow@);

    template<class E2>
      friend constexpr bool operator==(const unexpected&, const unexpected<E2>&);

    friend constexpr void swap(unexpected& x, unexpected& y) noexcept(noexcept(x.swap(y)));

  private:
    E @\exposidnc{unex}@;             // \expos
  };

  template<class E> unexpected(E) -> unexpected<E>;
}
\end{codeblock}

\pnum
A program that instantiates the definition of \tcode{unexpected} for
a non-object type,
an array type,
a specialization of \tcode{unexpected}, or
a cv-qualified type
is ill-formed.

\rSec3[expected.un.cons]{Constructors}

\indexlibraryctor{unexpected}%
\begin{itemdecl}
template<class Err = E>
  constexpr explicit unexpected(Err&& e);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_same_v<remove_cvref_t<Err>, unexpected>} is \tcode{false}; and
\item
\tcode{is_same_v<remove_cvref_t<Err>, in_place_t>} is \tcode{false}; and
\item
\tcode{is_constructible_v<E, Err>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Direct-non-list-initializes \exposid{unex} with \tcode{std::forward<Err>(e)}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\indexlibraryctor{unexpected}%
\begin{itemdecl}
template<class... Args>
  constexpr explicit unexpected(in_place_t, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<E, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes
\exposid{unex} with \tcode{std::forward<Args>(args)...}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\indexlibraryctor{unexpected}%
\begin{itemdecl}
template<class U, class... Args>
  constexpr explicit unexpected(in_place_t, initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<E, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes
\exposid{unex} with \tcode{il, std::forward<Args>(args)...}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\rSec3[expected.un.obs]{Observers}

\indexlibrarymember{error}{unexpected}%
\begin{itemdecl}
constexpr const E& error() const & noexcept;
constexpr E& error() & noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\exposid{unex}.
\end{itemdescr}

\indexlibrarymember{error}{unexpected}%
\begin{itemdecl}
constexpr E&& error() && noexcept;
constexpr const E&& error() const && noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(\exposid{unex})}.
\end{itemdescr}

\rSec3[expected.un.swap]{Swap}

\indexlibrarymember{swap}{unexpected}%
\begin{itemdecl}
constexpr void swap(unexpected& other) noexcept(is_nothrow_swappable_v<E>);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_swappable_v<E>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\tcode{using std::swap; swap(\exposid{unex}, other.\exposid{unex});}
\end{itemdescr}

\begin{itemdecl}
friend constexpr void swap(unexpected& x, unexpected& y) noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_swappable_v<E>} is \tcode{true}.

\pnum
\effects
Equivalent to \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[expected.un.eq]{Equality operator}

\indexlibrarymember{operator==}{unexpected}%
\begin{itemdecl}
template<class E2>
  friend constexpr bool operator==(const unexpected& x, const unexpected<E2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The expression \tcode{x.error() == y.error()} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
\tcode{x.error() == y.error()}.
\end{itemdescr}

\rSec2[expected.bad]{Class template \tcode{bad_expected_access}}

\indexlibraryglobal{bad_expected_access}%
\begin{codeblock}
namespace std {
  template<class E>
  class bad_expected_access : public bad_expected_access<void> {
  public:
    constexpr explicit bad_expected_access(E);
    constexpr const char* what() const noexcept override;
    constexpr E& error() & noexcept;
    constexpr const E& error() const & noexcept;
    constexpr E&& error() && noexcept;
    constexpr const E&& error() const && noexcept;

  private:
    E @\exposidnc{unex}@;             // \expos
  };
}
\end{codeblock}

\pnum
The class template \tcode{bad_expected_access}
defines the type of objects thrown as exceptions to report the situation
where an attempt is made to access the value of an \tcode{expected<T, E>} object
for which \tcode{has_value()} is \tcode{false}.

\indexlibraryctor{bad_expected_access}%
\begin{itemdecl}
constexpr explicit bad_expected_access(E e);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes \exposid{unex} with \tcode{std::move(e)}.
\end{itemdescr}

\indexlibrarymember{error}{bad_expected_access}%
\begin{itemdecl}
constexpr const E& error() const & noexcept;
constexpr E& error() & noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\exposid{unex}.
\end{itemdescr}

\indexlibrarymember{error}{bad_expected_access}%
\begin{itemdecl}
constexpr E&& error() && noexcept;
constexpr const E&& error() const && noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(\exposid{unex})}.
\end{itemdescr}

\indexlibrarymember{what}{bad_expected_access}%
\begin{itemdecl}
constexpr const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An \impldef{return value of \tcode{bad_expected_access<E>::what}} \ntbs,
which during constant evaluation is encoded with
the ordinary literal encoding\iref{lex.ccon}.
\end{itemdescr}

\rSec2[expected.bad.void]{Class template specialization \tcode{bad_expected_access<void>}}

\begin{codeblock}
namespace std {
  template<>
  class bad_expected_access<void> : public exception {
  protected:
    constexpr bad_expected_access() noexcept;
    constexpr bad_expected_access(const bad_expected_access&) noexcept;
    constexpr bad_expected_access(bad_expected_access&&) noexcept;
    constexpr bad_expected_access& operator=(const bad_expected_access&) noexcept;
    constexpr bad_expected_access& operator=(bad_expected_access&&) noexcept;
    constexpr ~bad_expected_access();

  public:
    constexpr const char* what() const noexcept override;
  };
}
\end{codeblock}

\indexlibrarymember{what}{bad_expected_access}%
\begin{itemdecl}
constexpr const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An \impldef{return value of \tcode{bad_expected_access<void>::what}} \ntbs,
which during constant evaluation is encoded with
the ordinary literal encoding\iref{lex.ccon}.
\end{itemdescr}

\rSec2[expected.expected]{Class template \tcode{expected}}

\rSec3[expected.object.general]{General}

\begin{codeblock}
namespace std {
  template<class T, class E>
  class expected {
  public:
    using @\libmember{value_type}{expected}@ = T;
    using @\libmember{error_type}{expected}@ = E;
    using @\libmember{unexpected_type}{expected}@ = unexpected<E>;

    template<class U>
    using @\libmember{rebind}{expected}@ = expected<U, error_type>;

    // \ref{expected.object.cons}, constructors
    constexpr expected();
    constexpr expected(const expected&);
    constexpr expected(expected&&) noexcept(@\seebelow@);
    template<class U, class G>
      constexpr explicit(@\seebelow@) expected(const expected<U, G>&);
    template<class U, class G>
      constexpr explicit(@\seebelow@) expected(expected<U, G>&&);

    template<class U = remove_cv_t<T>>
      constexpr explicit(@\seebelow@) expected(U&& v);

    template<class G>
      constexpr explicit(@\seebelow@) expected(const unexpected<G>&);
    template<class G>
      constexpr explicit(@\seebelow@) expected(unexpected<G>&&);

    template<class... Args>
      constexpr explicit expected(in_place_t, Args&&...);
    template<class U, class... Args>
      constexpr explicit expected(in_place_t, initializer_list<U>, Args&&...);
    template<class... Args>
      constexpr explicit expected(unexpect_t, Args&&...);
    template<class U, class... Args>
      constexpr explicit expected(unexpect_t, initializer_list<U>, Args&&...);

    // \ref{expected.object.dtor}, destructor
    constexpr ~expected();

    // \ref{expected.object.assign}, assignment
    constexpr expected& operator=(const expected&);
    constexpr expected& operator=(expected&&) noexcept(@\seebelow@);
    template<class U = remove_cv_t<T>> constexpr expected& operator=(U&&);
    template<class G>
      constexpr expected& operator=(const unexpected<G>&);
    template<class G>
      constexpr expected& operator=(unexpected<G>&&);

    template<class... Args>
      constexpr T& emplace(Args&&...) noexcept;
    template<class U, class... Args>
      constexpr T& emplace(initializer_list<U>, Args&&...) noexcept;

    // \ref{expected.object.swap}, swap
    constexpr void swap(expected&) noexcept(@\seebelow@);
    friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));

    // \ref{expected.object.obs}, observers
    constexpr const T* operator->() const noexcept;
    constexpr T* operator->() noexcept;
    constexpr const T& operator*() const & noexcept;
    constexpr T& operator*() & noexcept;
    constexpr const T&& operator*() const && noexcept;
    constexpr T&& operator*() && 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 const T&& value() const &&;                                   // freestanding-deleted
    constexpr T&& value() &&;                                               // freestanding-deleted
    constexpr const E& error() const & noexcept;
    constexpr E& error() & noexcept;
    constexpr const E&& error() const && noexcept;
    constexpr E&& error() && noexcept;
    template<class U = remove_cv_t<T>> constexpr T value_or(U&&) const &;
    template<class U = remove_cv_t<T>> constexpr T value_or(U&&) &&;
    template<class G = E> constexpr E error_or(G&&) const &;
    template<class G = E> constexpr E error_or(G&&) &&;

    // \ref{expected.object.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 or_else(F&& f) &;
    template<class F> constexpr auto or_else(F&& f) &&;
    template<class F> constexpr auto or_else(F&& f) const &;
    template<class F> constexpr auto or_else(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 auto transform_error(F&& f) &;
    template<class F> constexpr auto transform_error(F&& f) &&;
    template<class F> constexpr auto transform_error(F&& f) const &;
    template<class F> constexpr auto transform_error(F&& f) const &&;

    // \ref{expected.object.eq}, equality operators
    template<class T2, class E2> requires (!is_void_v<T2>)
      friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
    template<class T2>
      friend constexpr bool operator==(const expected&, const T2&);
    template<class E2>
      friend constexpr bool operator==(const expected&, const unexpected<E2>&);

  private:
    bool @\exposid{has_val}@;       // \expos
    union {
      T @\exposid{val}@;            // \expos
      E @\exposid{unex}@;           // \expos
    };
  };
}
\end{codeblock}

\pnum
Any object of type \tcode{expected<T, E>} either
contains a value of type \tcode{T} or
a value of type \tcode{E}
nested within\iref{intro.object} it.
Member \exposid{has_val} indicates whether the \tcode{expected<T, E>} object
contains an object of type \tcode{T}.

\pnum
A type \tcode{T} is a \term{valid value type for \tcode{expected}},
if \tcode{remove_cv_t<T>} is \tcode{void}
or a complete non-array object type that is not \tcode{in_place_t},
\tcode{unexpect_t},
or a specialization of \tcode{unexpected}.
A program which instantiates class template \tcode{expected<T, E>}
with an argument \tcode{T} that is not a valid value
type for \tcode{expected} is ill-formed.
A program that instantiates
the definition of the template \tcode{expected<T, E>}
with a type for the \tcode{E} parameter
that is not a valid template argument for \tcode{unexpected} is ill-formed.

\pnum
When \tcode{T} is not \cv{} \tcode{void}, it shall meet
the \oldconcept{Destructible} requirements (\tref{cpp17.destructible}).
\tcode{E} shall meet
the \oldconcept{Destructible} requirements.

\rSec3[expected.object.cons]{Constructors}

\pnum
The exposition-only variable template \exposid{converts-from-any-cvref}
defined in \ref{optional.ctor}
is used by some constructors for \tcode{expected}.

\indexlibraryctor{expected}%
\begin{itemdecl}
constexpr expected();
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_default_constructible_v<T>} is \tcode{true}.

\pnum
\effects
Value-initializes \exposid{val}.

\pnum
\ensures
\tcode{has_value()} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{val}.
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
constexpr expected(const expected& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{rhs.has_value()} is \tcode{true},
direct-non-list-initializes \exposid{val} with \tcode{*rhs}.
Otherwise, direct-non-list-initializes \exposid{unex} with \tcode{rhs.error()}.

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{val} or \exposid{unex}.

\pnum
\remarks
This constructor is defined as deleted unless
\begin{itemize}
\item
\tcode{is_copy_constructible_v<T>} is \tcode{true} and
\item
\tcode{is_copy_constructible_v<E>} is \tcode{true}.
\end{itemize}

\pnum
This constructor is trivial if
\begin{itemize}
\item
\tcode{is_trivially_copy_constructible_v<T>} is \tcode{true} and
\item
\tcode{is_trivially_copy_constructible_v<E>} is \tcode{true}.
\end{itemize}
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
constexpr expected(expected&& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_move_constructible_v<T>} is \tcode{true} and
\item
\tcode{is_move_constructible_v<E>} is \tcode{true}.
\end{itemize}

\pnum
\effects
If \tcode{rhs.has_value()} is \tcode{true},
direct-non-list-initializes \exposid{val} with \tcode{std::move(*rhs)}.
Otherwise,
direct-non-list-initializes \exposid{unex} with \tcode{std::move(rhs.error())}.

\pnum
\ensures
\tcode{rhs.has_value()} is unchanged;
\tcode{rhs.has_value() == this->has_value()} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{val} or \exposid{unex}.

\pnum
\remarks
The exception specification is equivalent to
\tcode{is_nothrow_move_constructible_v<T> \&\&
is_nothrow_move_constructible_v<E>}.

\pnum
This constructor is trivial if
\begin{itemize}
\item
\tcode{is_trivially_move_constructible_v<T>} is \tcode{true} and
\item
\tcode{is_trivially_move_constructible_v<E>} is \tcode{true}.
\end{itemize}
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
template<class U, class G>
  constexpr explicit(@\seebelow@) expected(const expected<U, G>& rhs);
template<class U, class G>
  constexpr explicit(@\seebelow@) expected(expected<U, G>&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let:
\begin{itemize}
\item
\tcode{UF} be \tcode{const U\&} for the first overload and
\tcode{U} for the second overload.
\item
\tcode{GF} be \tcode{const G\&} for the first overload and
\tcode{G} for the second overload.
\end{itemize}

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_constructible_v<T, UF>} is \tcode{true}; and
\item
\tcode{is_constructible_v<E, GF>} is \tcode{true}; and
\item
if \tcode{T} is not \cv{} \tcode{bool},
\tcode{\exposid{converts-from-any-cvref}<T, expected<U, G>>} is \tcode{false}; and
\item
\tcode{is_constructible_v<unexpected<E>, expected<U, G>\&>} is \tcode{false}; and
\item
\tcode{is_constructible_v<unexpected<E>, expected<U, G>>} is \tcode{false}; and
\item
\tcode{is_constructible_v<unexpected<E>, const expected<U, G>\&>} is \tcode{false}; and
\item
\tcode{is_constructible_v<unexpected<E>, const expected<U, G>>} is \tcode{false}.
\end{itemize}

\pnum
\effects
If \tcode{rhs.has_value()},
direct-non-list-initializes \exposid{val} with \tcode{std::forward<UF>(*rhs)}.
Otherwise,
direct-non-list-initializes \exposid{unex} with \tcode{std::forward<GF>(rhs.error())}.

\pnum
\ensures
\tcode{rhs.has_value()} is unchanged;
\tcode{rhs.has_value() == this->has_value()} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{val} or \exposid{unex}.

\pnum
\remarks
The expression inside \tcode{explicit} is equivalent to
\tcode{!is_convertible_v<UF, T> || !is_convertible_v<GF, E>}.
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
template<class U = remove_cv_t<T>>
  constexpr explicit(!is_convertible_v<U, T>) expected(U&& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_same_v<remove_cvref_t<U>, in_place_t>} is \tcode{false}; and
\item
\tcode{is_same_v<expected, remove_cvref_t<U>>} is \tcode{false}; and
\item
\tcode{remove_cvref_t<U>} is not a specialization of \tcode{unexpected}; and
\item
\tcode{is_constructible_v<T, U>} is \tcode{true}; and
\item
if \tcode{T} is \cv{} \tcode{bool},
\tcode{remove_cvref_t<U>} is not a specialization of \tcode{expected}.
\end{itemize}

\pnum
\effects
Direct-non-list-initializes \exposid{val} with \tcode{std::forward<U>(v)}.

\pnum
\ensures
\tcode{has_value()} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{val}.
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
template<class G>
  constexpr explicit(!is_convertible_v<const G&, E>) expected(const unexpected<G>& e);
template<class G>
  constexpr explicit(!is_convertible_v<G, E>) expected(unexpected<G>&& e);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{GF} be \tcode{const G\&} for the first overload and
\tcode{G} for the second overload.

\pnum
\constraints
\tcode{is_constructible_v<E, GF>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes \exposid{unex} with \tcode{std::forward<GF>(e.error())}.

\pnum
\ensures
\tcode{has_value()} is \tcode{false}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
template<class... Args>
  constexpr explicit expected(in_place_t, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<T, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes \exposid{val} with \tcode{std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{has_value()} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{val}.
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
template<class U, class... Args>
  constexpr explicit expected(in_place_t, initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<T, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes \exposid{val} with
\tcode{il, std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{has_value()} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{val}.
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
template<class... Args>
  constexpr explicit expected(unexpect_t, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<E, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes \exposid{unex} with
\tcode{std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{has_value()} is \tcode{false}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\indexlibraryctor{expected}%
\begin{itemdecl}
template<class U, class... Args>
  constexpr explicit expected(unexpect_t, initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<E, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes \exposid{unex} with
\tcode{il, std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{has_value()} is \tcode{false}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\rSec3[expected.object.dtor]{Destructor}

\indexlibrarydtor{expected}%
\begin{itemdecl}
constexpr ~expected();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{has_value()} is \tcode{true}, destroys \exposid{val},
otherwise destroys \exposid{unex}.

\pnum
\remarks
If \tcode{is_trivially_destructible_v<T>} is \tcode{true}, and
\tcode{is_trivially_destructible_v<E>} is \tcode{true},
then this destructor is a trivial destructor.
\end{itemdescr}

\rSec3[expected.object.assign]{Assignment}

\pnum
This subclause makes use of the following exposition-only function template:
\begin{codeblock}
template<class T, class U, class... Args>
constexpr void @\exposid{reinit-expected}@(T& newval, U& oldval, Args&&... args) {  // \expos
  if constexpr (is_nothrow_constructible_v<T, Args...>) {
    destroy_at(addressof(oldval));
    construct_at(addressof(newval), std::forward<Args>(args)...);
  } else if constexpr (is_nothrow_move_constructible_v<T>) {
    T tmp(std::forward<Args>(args)...);
    destroy_at(addressof(oldval));
    construct_at(addressof(newval), std::move(tmp));
  } else {
    U tmp(std::move(oldval));
    destroy_at(addressof(oldval));
    try {
      construct_at(addressof(newval), std::forward<Args>(args)...);
    } catch (...) {
      construct_at(addressof(oldval), std::move(tmp));
      throw;
    }
  }
}
\end{codeblock}

\indexlibrarymember{operator=}{expected}%
\begin{itemdecl}
constexpr expected& operator=(const expected& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{itemize}
\item
If \tcode{this->has_value() \&\& rhs.has_value()} is \tcode{true},
equivalent to \tcode{\exposid{val} = *rhs}.
\item
Otherwise, if \tcode{this->has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
@\exposid{reinit-expected}@(@\exposid{unex}@, @\exposid{val}@, rhs.error())
\end{codeblock}
\item
Otherwise, if \tcode{rhs.has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
@\exposid{reinit-expected}@(@\exposid{val}@, @\exposid{unex}@, *rhs)
\end{codeblock}
\item
Otherwise, equivalent to \tcode{\exposid{unex} = rhs.error()}.
\end{itemize}
Then, if no exception was thrown,
equivalent to: \tcode{\exposid{has_val} = rhs.has_value(); return *this;}

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
This operator is defined as deleted unless:
\begin{itemize}
\item
\tcode{is_copy_assignable_v<T>} is \tcode{true} and
\item
\tcode{is_copy_constructible_v<T>} is \tcode{true} and
\item
\tcode{is_copy_assignable_v<E>} is \tcode{true} and
\item
\tcode{is_copy_constructible_v<E>} is \tcode{true} and
\item
\tcode{is_nothrow_move_constructible_v<T> || is_nothrow_move_constructible_v<E>}
is \tcode{true}.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{operator=}{expected}%
\begin{itemdecl}
constexpr expected& operator=(expected&& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_move_constructible_v<T>} is \tcode{true} and
\item
\tcode{is_move_assignable_v<T>} is \tcode{true} and
\item
\tcode{is_move_constructible_v<E>} is \tcode{true} and
\item
\tcode{is_move_assignable_v<E>} is \tcode{true} and
\item
\tcode{is_nothrow_move_constructible_v<T> || is_nothrow_move_constructible_v<E>}
is \tcode{true}.
\end{itemize}

\pnum
\effects
\begin{itemize}
\item
If \tcode{this->has_value() \&\& rhs.has_value()} is \tcode{true},
equivalent to \tcode{\exposid{val} = std::move(*rhs)}.
\item
Otherwise, if \tcode{this->has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
@\exposid{reinit-expected}@(@\exposid{unex}@, @\exposid{val}@, std::move(rhs.error()))
\end{codeblock}
\item
Otherwise, if \tcode{rhs.has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
@\exposid{reinit-expected}@(@\exposid{val}@, @\exposid{unex}@, std::move(*rhs))
\end{codeblock}
\item
Otherwise, equivalent to \tcode{\exposid{unex} = std::move(rhs.error())}.
\end{itemize}
Then, if no exception was thrown,
equivalent to: \tcode{has_val = rhs.has_value(); return *this;}

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The exception specification is equivalent to:
\begin{codeblock}
is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T> &&
is_nothrow_move_assignable_v<E> && is_nothrow_move_constructible_v<E>
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{operator=}{expected}%
\begin{itemdecl}
template<class U = remove_cv_t<T>>
  constexpr expected& operator=(U&& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_same_v<expected, remove_cvref_t<U>>} is \tcode{false}; and
\item
\tcode{remove_cvref_t<U>} is not a specialization of \tcode{unexpected}; and
\item
\tcode{is_constructible_v<T, U>} is \tcode{true}; and
\item
\tcode{is_assignable_v<T\&, U>} is \tcode{true}; and
\item
\tcode{is_nothrow_constructible_v<T, U> || is_nothrow_move_constructible_v<T> ||\newline
is_nothrow_move_constructible_v<E>}
is \tcode{true}.
\end{itemize}

\pnum
\effects
\begin{itemize}
\item
If \tcode{has_value()} is \tcode{true},
equivalent to: \tcode{\exposid{val} = std::forward<U>(v);}
\item
Otherwise, equivalent to:
\begin{codeblock}
@\exposid{reinit-expected}@(@\exposid{val}@, @\exposid{unex}@, std::forward<U>(v));
@\exposid{has_val}@ = true;
\end{codeblock}
\end{itemize}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{expected}%
\begin{itemdecl}
template<class G>
  constexpr expected& operator=(const unexpected<G>& e);
template<class G>
  constexpr expected& operator=(unexpected<G>&& e);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{GF} be \tcode{const G\&} for the first overload and
\tcode{G} for the second overload.

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_constructible_v<E, GF>} is \tcode{true}; and
\item
\tcode{is_assignable_v<E\&, GF>} is \tcode{true}; and
\item
\tcode{is_nothrow_constructible_v<E, GF> || is_nothrow_move_constructible_v<T> ||\newline
is_nothrow_move_constructible_v<E>} is \tcode{true}.
\end{itemize}

\pnum
\effects
\begin{itemize}
\item
If \tcode{has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
@\exposid{reinit-expected}@(@\exposid{unex}@, @\exposid{val}@, std::forward<GF>(e.error()));
@\exposid{has_val}@ = false;
\end{codeblock}
\item
Otherwise, equivalent to:
\tcode{\exposid{unex} = std::forward<GF>(e.error());}
\end{itemize}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{emplace}{expected}%
\begin{itemdecl}
template<class... Args>
  constexpr T& emplace(Args&&... args) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_nothrow_constructible_v<T, Args...>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value()) {
  destroy_at(addressof(@\exposid{val}@));
} else {
  destroy_at(addressof(@\exposid{unex}@));
  @\exposid{has_val}@ = true;
}
return *construct_at(addressof(@\exposid{val}@), std::forward<Args>(args)...);
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{emplace}{expected}%
\begin{itemdecl}
template<class U, class... Args>
  constexpr T& emplace(initializer_list<U> il, Args&&... args) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_nothrow_constructible_v<T, initializer_list<U>\&, Args...>}
is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value()) {
  destroy_at(addressof(@\exposid{val}@));
} else {
  destroy_at(addressof(@\exposid{unex}@));
  @\exposid{has_val}@ = true;
}
return *construct_at(addressof(@\exposid{val}@), il, std::forward<Args>(args)...);
\end{codeblock}
\end{itemdescr}

\rSec3[expected.object.swap]{Swap}

\indexlibrarymember{swap}{expected}%
\begin{itemdecl}
constexpr void swap(expected& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{is_swappable_v<T>} is \tcode{true} and
\item
\tcode{is_swappable_v<E>} is \tcode{true} and
\item
\tcode{is_move_constructible_v<T> \&\& is_move_constructible_v<E>}
is \tcode{true}, and
\item
\tcode{is_nothrow_move_constructible_v<T> || is_nothrow_move_constructible_v<E>}
is \tcode{true}.
\end{itemize}

\pnum
\effects
See \tref{expected.object.swap}.

\begin{floattable}{\tcode{swap(expected\&)} effects}{expected.object.swap}
{lx{0.35\hsize}x{0.35\hsize}}
\topline
& \chdr{\tcode{this->has_value()}} & \rhdr{\tcode{!this->has_value()}} \\ \capsep
\lhdr{\tcode{rhs.has_value()}} &
  equivalent to: \tcode{using std::swap; swap(\exposid{val}, rhs.\exposid{val});} &
  calls \tcode{rhs.swap(*this)} \\
\lhdr{\tcode{!rhs.has_value()}} &
  \seebelow &
  equivalent to: \tcode{using std::swap; swap(\exposid{unex}, rhs.\exposid{unex});} \\
\end{floattable}

For the case where \tcode{rhs.has_value()} is \tcode{false} and
\tcode{this->has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
if constexpr (is_nothrow_move_constructible_v<E>) {
  E tmp(std::move(rhs.@\exposid{unex}@));
  destroy_at(addressof(rhs.@\exposid{unex}@));
  try {
    construct_at(addressof(rhs.@\exposid{val}@), std::move(@\exposid{val}@));
    destroy_at(addressof(@\exposid{val}@));
    construct_at(addressof(@\exposid{unex}@), std::move(tmp));
  } catch(...) {
    construct_at(addressof(rhs.@\exposid{unex}@), std::move(tmp));
    throw;
  }
} else {
  T tmp(std::move(@\exposid{val}@));
  destroy_at(addressof(@\exposid{val}@));
  try {
    construct_at(addressof(@\exposid{unex}@), std::move(rhs.@\exposid{unex}@));
    destroy_at(addressof(rhs.@\exposid{unex}@));
    construct_at(addressof(rhs.@\exposid{val}@), std::move(tmp));
  } catch (...) {
    construct_at(addressof(@\exposid{val}@), std::move(tmp));
    throw;
  }
}
@\exposid{has_val}@ = false;
rhs.@\exposid{has_val}@ = true;
\end{codeblock}

\pnum
\throws
Any exception thrown by the expressions in the \Fundescx{Effects}.

\pnum
\remarks
The exception specification is equivalent to:
\begin{codeblock}
is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T> &&
is_nothrow_move_constructible_v<E> && is_nothrow_swappable_v<E>
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{swap}{expected}%
\begin{itemdecl}
friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[expected.object.obs]{Observers}

\indexlibrarymember{operator->}{expected}%
\begin{itemdecl}
constexpr const T* operator->() const noexcept;
constexpr T* operator->() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{true}.

\pnum
\returns
\tcode{addressof(\exposid{val})}.
\end{itemdescr}

\indexlibrarymember{operator*}{expected}%
\begin{itemdecl}
constexpr const T& operator*() const & noexcept;
constexpr T& operator*() & noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{true}.

\pnum
\returns
\exposid{val}.
\end{itemdescr}

\indexlibrarymember{operator*}{expected}%
\begin{itemdecl}
constexpr T&& operator*() && noexcept;
constexpr const T&& operator*() const && noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{true}.

\pnum
\returns
\tcode{std::move(\exposid{val})}.
\end{itemdescr}

\indexlibrarymember{operator bool}{expected}%
\indexlibrarymember{has_value}{expected}%
\begin{itemdecl}
constexpr explicit operator bool() const noexcept;
constexpr bool has_value() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\exposid{has_val}.
\end{itemdescr}

\indexlibrarymember{value}{expected}%
\begin{itemdecl}
constexpr const T& value() const &;
constexpr T& value() &;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<E>} is \tcode{true}.

\pnum
\returns
\exposid{val}, if \tcode{has_value()} is \tcode{true}.

\pnum
\throws
\tcode{bad_expected_access(as_const(error()))} if \tcode{has_value()} is \tcode{false}.
\end{itemdescr}

\indexlibrarymember{value}{expected}%
\begin{itemdecl}
constexpr T&& value() &&;
constexpr const T&& value() const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<E>} is \tcode{true} and
\tcode{is_constructible_v<E, decltype(std::\linebreak{}move(error()))>} is \tcode{true}.

\pnum
\returns
\tcode{std::move(\exposid{val})}, if \tcode{has_value()} is \tcode{true}.

\pnum
\throws
\tcode{bad_expected_access(std::move(error()))}
if \tcode{has_value()} is \tcode{false}.
\end{itemdescr}

\indexlibrarymember{error}{expected}%
\begin{itemdecl}
constexpr const E& error() const & noexcept;
constexpr E& error() & noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{false}.

\pnum
\returns
\exposid{unex}.
\end{itemdescr}

\indexlibrarymember{error}{expected}%
\begin{itemdecl}
constexpr E&& error() && noexcept;
constexpr const E&& error() const && noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{false}.

\pnum
\returns
\tcode{std::move(\exposid{unex})}.
\end{itemdescr}

\indexlibrarymember{value_or}{expected}%
\begin{itemdecl}
template<class U = remove_cv_t<T>> constexpr T value_or(U&& v) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<T>} is \tcode{true} and
\tcode{is_convertible_v<U, T>} is \tcode{true}.

\pnum
\returns
\tcode{has_value() ? **this : static_cast<T>(std::forward<U>(v))}.
\end{itemdescr}

\indexlibrarymember{value_or}{expected}%
\begin{itemdecl}
template<class U = remove_cv_t<T>> constexpr T value_or(U&& v) &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_move_constructible_v<T>} is \tcode{true} and
\tcode{is_convertible_v<U, T>} is \tcode{true}.

\pnum
\returns
\tcode{has_value() ? std::move(**this) : static_cast<T>(std::forward<U>(v))}.
\end{itemdescr}

\indexlibrarymember{error_or}{expected}%
\begin{itemdecl}
template<class G = E> constexpr E error_or(G&& e) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<E>} is \tcode{true} and
\tcode{is_convertible_v<G, E>} is \tcode{true}.

\pnum
\returns
\tcode{std::forward<G>(e)} if \tcode{has_value()} is \tcode{true},
\tcode{error()} otherwise.
\end{itemdescr}

\indexlibrarymember{error_or}{expected}%
\begin{itemdecl}
template<class G = E> constexpr E error_or(G&& e) &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_move_constructible_v<E>} is \tcode{true} and
\tcode{is_convertible_v<G, E>} is \tcode{true}.

\pnum
\returns
\tcode{std::forward<G>(e)} if \tcode{has_value()} is \tcode{true},
\tcode{std::move(error())} otherwise.
\end{itemdescr}

\rSec3[expected.object.monadic]{Monadic operations}

\indexlibrarymember{and_then}{expected}%
\begin{itemdecl}
template<class F> constexpr auto and_then(F&& f) &;
template<class F> constexpr auto and_then(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be \tcode{remove_cvref_t<invoke_result_t<F, decltype((\exposid{val}))>>}.

\pnum
\constraints
\tcode{is_constructible_v<E, decltype(error())>} is \tcode{true}.

\pnum
\mandates
\tcode{U} is a specialization of \tcode{expected} and
\tcode{is_same_v<U::error_type, E>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value())
  return invoke(std::forward<F>(f), @\exposid{val}@);
else
  return U(unexpect, error());
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{and_then}{expected}%
\begin{itemdecl}
template<class F> constexpr auto and_then(F&& f) &&;
template<class F> constexpr auto and_then(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be
\tcode{remove_cvref_t<invoke_result_t<F, decltype(std::move(\exposid{val}))>>}.

\pnum
\constraints
\tcode{is_constructible_v<E, decltype(std::move(error()))>} is \tcode{true}.

\pnum
\mandates
\tcode{U} is a specialization of \tcode{expected} and
\tcode{is_same_v<U::error_type, E>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value())
  return invoke(std::forward<F>(f), std::move(@\exposid{val}@));
else
  return U(unexpect, std::move(error()));
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{or_else}{expected}%
\begin{itemdecl}
template<class F> constexpr auto or_else(F&& f) &;
template<class F> constexpr auto or_else(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{G} be \tcode{remove_cvref_t<invoke_result_t<F, decltype(error())>>}.

\pnum
\constraints
\tcode{is_constructible_v<T, decltype((\exposid{val}))>} is \tcode{true}.

\pnum
\mandates
\tcode{G} is a specialization of \tcode{expected} and
\tcode{is_same_v<G::value_type, T>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value())
  return G(in_place, @\exposid{val}@);
else
  return invoke(std::forward<F>(f), error());
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{or_else}{expected}%
\begin{itemdecl}
template<class F> constexpr auto or_else(F&& f) &&;
template<class F> constexpr auto or_else(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{G} be
\tcode{remove_cvref_t<invoke_result_t<F, decltype(std::move(error()))>>}.

\pnum
\constraints
\tcode{is_constructible_v<T, decltype(std::move(\exposid{val}))>} is \tcode{true}.

\pnum
\mandates
\tcode{G} is a specialization of \tcode{expected} and
\tcode{is_same_v<G::value_type, T>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value())
  return G(in_place, std::move(@\exposid{val}@));
else
  return invoke(std::forward<F>(f), std::move(error()));
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{transform}{expected}%
\begin{itemdecl}
template<class F> constexpr auto transform(F&& f) &;
template<class F> constexpr auto transform(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be
\tcode{remove_cv_t<invoke_result_t<F, decltype((\exposid{val}))>>}.

\pnum
\constraints
\tcode{is_constructible_v<E, decltype(error())>} is \tcode{true}.

\pnum
\mandates
\tcode{U} is a valid value type for \tcode{expected}.
If \tcode{is_void_v<U>} is \tcode{false},
the declaration
\begin{codeblock}
U u(invoke(std::forward<F>(f), @\exposid{val}@));
\end{codeblock}
is well-formed.

\pnum
\effects
\begin{itemize}
\item
If \tcode{has_value()} is \tcode{false}, returns
\tcode{expected<U, E>(unexpect, error())}.
\item
Otherwise, if \tcode{is_void_v<U>} is \tcode{false}, returns an
\tcode{expected<U, E>} object whose \exposid{has_val} member is \tcode{true}
and \exposid{val} member is direct-non-list-initialized with
\tcode{invoke(std::forward<F>(f), \exposid{val})}.
\item
Otherwise, evaluates \tcode{invoke(std::forward<F>(f), \exposid{val})} and then
returns \tcode{expected<U, E>()}.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{transform}{expected}%
\begin{itemdecl}
template<class F> constexpr auto transform(F&& f) &&;
template<class F> constexpr auto transform(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be
\tcode{remove_cv_t<invoke_result_t<F, decltype(std::move(\exposid{val}))>>}.

\pnum
\constraints
\tcode{is_constructible_v<E, decltype(std::move(error()))>} is \tcode{true}.

\pnum
\mandates
\tcode{U} is a valid value type for \tcode{expected}. If \tcode{is_void_v<U>} is
\tcode{false}, the declaration
\begin{codeblock}
U u(invoke(std::forward<F>(f), std::move(@\exposid{val}@)));
\end{codeblock}
is well-formed.

\pnum
\effects
\begin{itemize}
\item
If \tcode{has_value()} is \tcode{false}, returns
\tcode{expected<U, E>(unexpect, std::move(error()))}.
\item
Otherwise, if \tcode{is_void_v<U>} is \tcode{false}, returns an
\tcode{expected<U, E>} object whose \exposid{has_val} member is \tcode{true}
and \exposid{val} member is direct-non-list-initialized with
\tcode{invoke(std::forward<F>(f), std::move(\exposid{val}))}.
\item
Otherwise, evaluates \tcode{invoke(std::forward<F>(f), std::move(\exposid{val}))} and
then returns \tcode{ex\-pected<U, E>()}.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{transform_error}{expected}%
\begin{itemdecl}
template<class F> constexpr auto transform_error(F&& f) &;
template<class F> constexpr auto transform_error(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{G} be \tcode{remove_cv_t<invoke_result_t<F, decltype(error())>>}.

\pnum
\constraints
\tcode{is_constructible_v<T, decltype((\exposid{val}))>} is \tcode{true}.

\pnum
\mandates
\tcode{G} is a valid template argument
for \tcode{unexpected}\iref{expected.un.general} and the declaration
\begin{codeblock}
G g(invoke(std::forward<F>(f), error()));
\end{codeblock}
is well-formed.

\pnum
\returns
If \tcode{has_value()} is \tcode{true},
\tcode{expected<T, G>(in_place, \exposid{val})}; otherwise, an \tcode{expected<T, G>}
object whose \exposid{has_val} member is \tcode{false} and \exposid{unex} member
is direct-non-list-initialized with \tcode{invoke(std::forward<F>(f), error())}.
\end{itemdescr}

\indexlibrarymember{transform_error}{expected}%
\begin{itemdecl}
template<class F> constexpr auto transform_error(F&& f) &&;
template<class F> constexpr auto transform_error(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{G} be
\tcode{remove_cv_t<invoke_result_t<F, decltype(std::move(error()))>>}.

\pnum
\constraints
\tcode{is_constructible_v<T, decltype(std::move(\exposid{val}))>} is \tcode{true}.

\pnum
\mandates
\tcode{G} is a valid template argument
for \tcode{unexpected}\iref{expected.un.general} and the declaration
\begin{codeblock}
G g(invoke(std::forward<F>(f), std::move(error())));
\end{codeblock}
is well-formed.

\pnum
\returns
If \tcode{has_value()} is \tcode{true},
\tcode{expected<T, G>(in_place, std::move(\exposid{val}))}; otherwise, an
\tcode{expected<T, G>} object whose \exposid{has_val} member is \tcode{false}
and \exposid{unex} member is direct-non-list-initialized with
\tcode{invoke(std::forward<F>(f), std::move(error()))}.
\end{itemdescr}

\rSec3[expected.object.eq]{Equality operators}

\indexlibrarymember{operator==}{expected}%
\begin{itemdecl}
template<class T2, class E2> requires (!is_void_v<T2>)
  friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expressions \tcode{*x == *y} and \tcode{x.error() == y.error()}
are well-formed and their results are convertible to \tcode{bool}.

\pnum
\returns
If \tcode{x.has_value()} does not equal \tcode{y.has_value()}, \tcode{false};
otherwise if \tcode{x.has_value()} is \tcode{true}, \tcode{*x == *y};
otherwise \tcode{x.error() == y.error()}.
\end{itemdescr}

\indexlibrarymember{operator==}{expected}%
\begin{itemdecl}
template<class T2> friend constexpr bool operator==(const expected& x, const T2& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T2} is not a specialization of \tcode{expected}.
The expression \tcode{*x == v} is well-formed and
its result is convertible to \tcode{bool}.
\begin{note}
\tcode{T} need not be \oldconcept{EqualityComparable}.
\end{note}

\pnum
\returns
\tcode{x.has_value() \&\& static_cast<bool>(*x == v)}.
\end{itemdescr}

\indexlibrarymember{operator==}{expected}%
\begin{itemdecl}
template<class E2> friend constexpr bool operator==(const expected& x, const unexpected<E2>& e);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{x.error() == e.error()} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
\tcode{!x.has_value() \&\& static_cast<bool>(x.error() == e.error())}.
\end{itemdescr}

\rSec2[expected.void]{Partial specialization of \tcode{expected} for \tcode{void} types}

\rSec3[expected.void.general]{General}

\begin{codeblock}
template<class T, class E> requires is_void_v<T>
class expected<T, E> {
public:
  using @\libmember{value_type}{expected<void>}@ = T;
  using @\libmember{error_type}{expected<void>}@ = E;
  using @\libmember{unexpected_type}{expected<void>}@ = unexpected<E>;

  template<class U>
  using @\libmember{rebind}{expected<void>}@ = expected<U, error_type>;

  // \ref{expected.void.cons}, constructors
  constexpr expected() noexcept;
  constexpr expected(const expected&);
  constexpr expected(expected&&) noexcept(@\seebelow@);
  template<class U, class G>
    constexpr explicit(@\seebelow@) expected(const expected<U, G>&);
  template<class U, class G>
    constexpr explicit(@\seebelow@) expected(expected<U, G>&&);

  template<class G>
    constexpr explicit(@\seebelow@) expected(const unexpected<G>&);
  template<class G>
    constexpr explicit(@\seebelow@) expected(unexpected<G>&&);

  constexpr explicit expected(in_place_t) noexcept;
  template<class... Args>
    constexpr explicit expected(unexpect_t, Args&&...);
  template<class U, class... Args>
    constexpr explicit expected(unexpect_t, initializer_list<U>, Args&&...);


  // \ref{expected.void.dtor}, destructor
  constexpr ~expected();

  // \ref{expected.void.assign}, assignment
  constexpr expected& operator=(const expected&);
  constexpr expected& operator=(expected&&) noexcept(@\seebelow@);
  template<class G>
    constexpr expected& operator=(const unexpected<G>&);
  template<class G>
    constexpr expected& operator=(unexpected<G>&&);
  constexpr void emplace() noexcept;

  // \ref{expected.void.swap}, swap
  constexpr void swap(expected&) noexcept(@\seebelow@);
  friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));

  // \ref{expected.void.obs}, observers
  constexpr explicit operator bool() const noexcept;
  constexpr bool has_value() const noexcept;
  constexpr void operator*() const noexcept;
  constexpr void value() const &;                                           // freestanding-deleted
  constexpr void value() &&;                                                // freestanding-deleted
  constexpr const E& error() const & noexcept;
  constexpr E& error() & noexcept;
  constexpr const E&& error() const && noexcept;
  constexpr E&& error() && noexcept;
  template<class G = E> constexpr E error_or(G&&) const &;
  template<class G = E> constexpr E error_or(G&&) &&;

  // \ref{expected.void.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 or_else(F&& f) &;
  template<class F> constexpr auto or_else(F&& f) &&;
  template<class F> constexpr auto or_else(F&& f) const &;
  template<class F> constexpr auto or_else(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 auto transform_error(F&& f) &;
  template<class F> constexpr auto transform_error(F&& f) &&;
  template<class F> constexpr auto transform_error(F&& f) const &;
  template<class F> constexpr auto transform_error(F&& f) const &&;

  // \ref{expected.void.eq}, equality operators
  template<class T2, class E2> requires is_void_v<T2>
    friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
  template<class E2>
    friend constexpr bool operator==(const expected&, const unexpected<E2>&);

private:
  bool @\exposid{has_val}@;         // \expos
  union {
    E @\exposid{unex}@;             // \expos
  };
};
\end{codeblock}

\pnum
Any object of type \tcode{expected<T, E>} either
represents a value of type \tcode{T}, or
contains a value of type \tcode{E}
nested within\iref{intro.object} it.
Member \exposid{has_val} indicates whether the \tcode{expected<T, E>} object
represents a value of type \tcode{T}.

\pnum
A program that instantiates
the definition of the template \tcode{expected<T, E>} with
a type for the \tcode{E} parameter that
is not a valid template argument for \tcode{unexpected} is ill-formed.

\pnum
\tcode{E} shall meet the requirements of
\oldconcept{Destructible} (\tref{cpp17.destructible}).

\rSec3[expected.void.cons]{Constructors}

\indexlibraryctor{expected<void>}%
\begin{itemdecl}
constexpr expected() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{has_value()} is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{expected<void>}%
\begin{itemdecl}
constexpr expected(const expected& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{rhs.has_value()} is \tcode{false},
direct-non-list-initializes \exposid{unex} with \tcode{rhs.error()}.

\pnum
\ensures
\tcode{rhs.has_value() == this->has_value()}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.

\pnum
\remarks
This constructor is defined as deleted
unless \tcode{is_copy_constructible_v<E>} is \tcode{true}.

\pnum
This constructor is trivial
if \tcode{is_trivially_copy_constructible_v<E>} is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{expected<void>}%
\begin{itemdecl}
constexpr expected(expected&& rhs) noexcept(is_nothrow_move_constructible_v<E>);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<E>} is \tcode{true}.

\pnum
\effects
If \tcode{rhs.has_value()} is \tcode{false},
direct-non-list-initializes \exposid{unex} with \tcode{std::move(rhs.error())}.

\pnum
\ensures
\tcode{rhs.has_value()} is unchanged;
\tcode{rhs.has_value() == this->has_value()} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.

\pnum
\remarks
This constructor is trivial
if \tcode{is_trivially_move_constructible_v<E>} is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{expected<void>}%
\begin{itemdecl}
template<class U, class G>
  constexpr explicit(!is_convertible_v<const G&, E>) expected(const expected<U, G>& rhs);
template<class U, class G>
  constexpr explicit(!is_convertible_v<G, E>) expected(expected<U, G>&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{GF} be \tcode{const G\&} for the first overload and
\tcode{G} for the second overload.

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_void_v<U>} is \tcode{true}; and
\item
\tcode{is_constructible_v<E, GF>} is \tcode{true}; and
\item
\tcode{is_constructible_v<unexpected<E>, expected<U, G>\&>}
is \tcode{false}; and
\item
\tcode{is_constructible_v<unexpected<E>, expected<U, G>>}
is \tcode{false}; and
\item
\tcode{is_constructible_v<unexpected<E>, const expected<U, G>\&>}
is \tcode{false}; and
\item
\tcode{is_constructible_v<unexpected<E>, const expected<U, G>>}
is \tcode{false}.
\end{itemize}

\pnum
\effects
If \tcode{rhs.has_value()} is \tcode{false},
direct-non-list-initializes \exposid{unex}
with \tcode{std::forward<GF>(rhs.er\-ror())}.

\pnum
\ensures
\tcode{rhs.has_value()} is unchanged;
\tcode{rhs.has_value() == this->has_value()} is \tcode{true}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\indexlibraryctor{expected<void>}%
\begin{itemdecl}
template<class G>
  constexpr explicit(!is_convertible_v<const G&, E>) expected(const unexpected<G>& e);
template<class G>
  constexpr explicit(!is_convertible_v<G, E>) expected(unexpected<G>&& e);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{GF} be \tcode{const G\&} for the first overload and
\tcode{G} for the second overload.

\pnum
\constraints
\tcode{is_constructible_v<E, GF>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes \exposid{unex}
with \tcode{std::forward<GF>(e.error())}.

\pnum
\ensures
\tcode{has_value()} is \tcode{false}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\indexlibraryctor{expected<void>}%
\begin{itemdecl}
constexpr explicit expected(in_place_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{has_value()} is \tcode{true}.
\end{itemdescr}

\indexlibraryctor{expected<void>}%
\begin{itemdecl}
template<class... Args>
  constexpr explicit expected(unexpect_t, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<E, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes \exposid{unex}
with \tcode{std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{has_value()} is \tcode{false}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\indexlibraryctor{expected<void>}%
\begin{itemdecl}
template<class U, class... Args>
    constexpr explicit expected(unexpect_t, initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<E, initializer_list<U>\&, Args...>} is \tcode{true}.

\pnum
\effects
Direct-non-list-initializes \exposid{unex}
with \tcode{il, std::forward<Args>(args)...}.

\pnum
\ensures
\tcode{has_value()} is \tcode{false}.

\pnum
\throws
Any exception thrown by the initialization of \exposid{unex}.
\end{itemdescr}

\rSec3[expected.void.dtor]{Destructor}

\indexlibrarydtor{expected<void>}%
\begin{itemdecl}
constexpr ~expected();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{has_value()} is \tcode{false}, destroys \exposid{unex}.

\pnum
\remarks
If \tcode{is_trivially_destructible_v<E>} is \tcode{true},
then this destructor is a trivial destructor.
\end{itemdescr}

\rSec3[expected.void.assign]{Assignment}

\indexlibrarymember{operator=}{expected<void>}%
\begin{itemdecl}
constexpr expected& operator=(const expected& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{itemize}
\item
If \tcode{this->has_value() \&\& rhs.has_value()} is \tcode{true}, no effects.
\item
Otherwise, if \tcode{this->has_value()} is \tcode{true},
equivalent to: \tcode{construct_at(addressof(\exposid{unex}), rhs.\exposid{unex}); \exposid{has_val} = false;}
\item
Otherwise, if \tcode{rhs.has_value()} is \tcode{true},
destroys \exposid{unex} and sets \exposid{has_val} to \tcode{true}.
\item
Otherwise, equivalent to \tcode{\exposid{unex} = rhs.error()}.
\end{itemize}

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
This operator is defined as deleted unless
\tcode{is_copy_assignable_v<E>} is \tcode{true} and
\tcode{is_copy_constructible_v<E>} is \tcode{true}.
\end{itemdescr}

\indexlibrarymember{operator=}{expected<void>}%
\begin{itemdecl}
constexpr expected& operator=(expected&& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<E>} is \tcode{true} and
\tcode{is_move_assignable_v<E>} is \tcode{true}.

\pnum
\effects
\begin{itemize}
\item
If \tcode{this->has_value() \&\& rhs.has_value()} is \tcode{true}, no effects.
\item
Otherwise, if \tcode{this->has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
construct_at(addressof(@\exposid{unex}@), std::move(rhs.@\exposid{unex}@));
@\exposid{has_val}@ = false;
\end{codeblock}
\item
Otherwise, if \tcode{rhs.has_value()} is \tcode{true},
destroys \exposid{unex} and sets \exposid{has_val} to \tcode{true}.
\item
Otherwise, equivalent to \tcode{\exposid{unex} = std::move(rhs.error())}.
\end{itemize}

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The exception specification is equivalent to
\tcode{is_nothrow_move_constructible_v<E> \&\& is_nothrow_move_assignable_v<E>}.
\end{itemdescr}

\indexlibrarymember{operator=}{expected<void>}%
\begin{itemdecl}
template<class G>
  constexpr expected& operator=(const unexpected<G>& e);
template<class G>
  constexpr expected& operator=(unexpected<G>&& e);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{GF} be \tcode{const G\&} for the first overload and
\tcode{G} for the second overload.

\pnum
\constraints
\tcode{is_constructible_v<E, GF>} is \tcode{true} and
\tcode{is_assignable_v<E\&, GF>} is \tcode{true}.

\pnum
\effects
\begin{itemize}
\item
If \tcode{has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
construct_at(addressof(@\exposid{unex}@), std::forward<GF>(e.error()));
@\exposid{has_val}@ = false;
\end{codeblock}
\item
Otherwise, equivalent to:
\tcode{\exposid{unex} = std::forward<GF>(e.error());}
\end{itemize}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{emplace}{expected<void>}%
\begin{itemdecl}
constexpr void emplace() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{has_value()} is \tcode{false},
destroys \exposid{unex} and sets \exposid{has_val} to \tcode{true}.
\end{itemdescr}

\rSec3[expected.void.swap]{Swap}

\indexlibrarymember{swap}{expected<void>}%
\begin{itemdecl}
constexpr void swap(expected& rhs) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_swappable_v<E>} is \tcode{true} and
\tcode{is_move_constructible_v<E>} is \tcode{true}.

\pnum
\effects
See \tref{expected.void.swap}.

\begin{floattable}{\tcode{swap(expected\&)} effects}{expected.void.swap}
{lx{0.35\hsize}x{0.35\hsize}}
\topline
& \chdr{\tcode{this->has_value()}} & \rhdr{\tcode{!this->has_value()}} \\ \capsep
\lhdr{\tcode{rhs.has_value()}} &
  no effects &
  calls \tcode{rhs.swap(*this)} \\
\lhdr{\tcode{!rhs.has_value()}} &
  \seebelow &
  equivalent to: \tcode{using std::swap; swap(\exposid{unex}, rhs.\exposid{unex});} \\
\end{floattable}

For the case where \tcode{rhs.has_value()} is \tcode{false} and
\tcode{this->has_value()} is \tcode{true}, equivalent to:
\begin{codeblock}
construct_at(addressof(@\exposid{unex}@), std::move(rhs.@\exposid{unex}@));
destroy_at(addressof(rhs.@\exposid{unex}@));
@\exposid{has_val}@ = false;
rhs.@\exposid{has_val}@ = true;
\end{codeblock}

\pnum
\throws
Any exception thrown by the expressions in the \Fundescx{Effects}.

\pnum
\remarks
The exception specification is equivalent to
\tcode{is_nothrow_move_constructible_v<E> \&\& is_nothrow_swappable_v<E>}.
\end{itemdescr}

\indexlibrarymember{swap}{expected<void>}%
\begin{itemdecl}
friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[expected.void.obs]{Observers}

\indexlibrarymember{operator bool}{expected<void>}%
\indexlibrarymember{has_value}{expected<void>}%
\begin{itemdecl}
constexpr explicit operator bool() const noexcept;
constexpr bool has_value() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\exposid{has_val}.
\end{itemdescr}

\indexlibrarymember{operator*}{expected<void>}%
\begin{itemdecl}
constexpr void operator*() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{true}.
\end{itemdescr}

\indexlibrarymember{value}{expected<void>}%
\begin{itemdecl}
constexpr void value() const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<E>} is \tcode{true}.

\pnum
\throws
\tcode{bad_expected_access(error())} if \tcode{has_value()} is \tcode{false}.
\end{itemdescr}

\indexlibrarymember{value}{expected<void>}%
\begin{itemdecl}
constexpr void value() &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<E>} is \tcode{true} and
\tcode{is_move_constructible_v<E>} is \tcode{true}.

\pnum
\throws
\tcode{bad_expected_access(std::move(error()))}
if \tcode{has_value()} is \tcode{false}.
\end{itemdescr}

\indexlibrarymember{error}{expected<void>}%
\begin{itemdecl}
constexpr const E& error() const & noexcept;
constexpr E& error() & noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{false}.

\pnum
\returns
\exposid{unex}.
\end{itemdescr}

\indexlibrarymember{error}{expected<void>}%
\begin{itemdecl}
constexpr E&& error() && noexcept;
constexpr const E&& error() const && noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{has_value()} is \tcode{false}.

\pnum
\returns
\tcode{std::move(\exposid{unex})}.
\end{itemdescr}

\indexlibrarymember{error_or}{expected<void>}%
\begin{itemdecl}
template<class G = E> constexpr E error_or(G&& e) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_copy_constructible_v<E>} is \tcode{true} and
\tcode{is_convertible_v<G, E>} is \tcode{true}.

\pnum
\returns
\tcode{std::forward<G>(e)} if \tcode{has_value()} is \tcode{true},
\tcode{error()} otherwise.
\end{itemdescr}

\indexlibrarymember{error_or}{expected<void>}%
\begin{itemdecl}
template<class G = E> constexpr E error_or(G&& e) &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_move_constructible_v<E>} is \tcode{true} and
\tcode{is_convertible_v<G, E>} is \tcode{true}.

\pnum
\returns
\tcode{std::forward<G>(e)} if \tcode{has_value()} is \tcode{true},
\tcode{std::move(error())} otherwise.
\end{itemdescr}

\rSec3[expected.void.monadic]{Monadic operations}

\indexlibrarymember{and_then}{expected<void>}%
\begin{itemdecl}
template<class F> constexpr auto and_then(F&& f) &;
template<class F> constexpr auto and_then(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be \tcode{remove_cvref_t<invoke_result_t<F>>}.

\pnum
\constraints
\tcode{is_constructible_v<E, decltype(error())>>} is \tcode{true}.

\pnum
\mandates
\tcode{U} is a specialization of \tcode{expected} and
\tcode{is_same_v<U::error_type, E>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value())
  return invoke(std::forward<F>(f));
else
  return U(unexpect, error());
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{and_then}{expected<void>}%
\begin{itemdecl}
template<class F> constexpr auto and_then(F&& f) &&;
template<class F> constexpr auto and_then(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be \tcode{remove_cvref_t<invoke_result_t<F>>}.

\pnum
\constraints
\tcode{is_constructible_v<E, decltype(std::move(error()))>} is \tcode{true}.

\pnum
\mandates
\tcode{U} is a specialization of \tcode{expected} and
\tcode{is_same_v<U::error_type, E>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value())
  return invoke(std::forward<F>(f));
else
  return U(unexpect, std::move(error()));
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{or_else}{expected<void>}%
\begin{itemdecl}
template<class F> constexpr auto or_else(F&& f) &;
template<class F> constexpr auto or_else(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{G} be \tcode{remove_cvref_t<invoke_result_t<F, decltype(error())>>}.

\pnum
\mandates
\tcode{G} is a specialization of \tcode{expected} and
\tcode{is_same_v<G::value_type, T>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value())
  return G();
else
  return invoke(std::forward<F>(f), error());
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{or_else}{expected<void>}%
\begin{itemdecl}
template<class F> constexpr auto or_else(F&& f) &&;
template<class F> constexpr auto or_else(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{G} be
\tcode{remove_cvref_t<invoke_result_t<F, decltype(std::move(error()))>>}.

\pnum
\mandates
\tcode{G} is a specialization of \tcode{expected} and
\tcode{is_same_v<G::value_type, T>} is \tcode{true}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (has_value())
  return G();
else
  return invoke(std::forward<F>(f), std::move(error()));
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{transform}{expected<void>}%
\begin{itemdecl}
template<class F> constexpr auto transform(F&& f) &;
template<class F> constexpr auto transform(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be \tcode{remove_cv_t<invoke_result_t<F>>}.

\pnum
\constraints
\tcode{is_constructible_v<E, decltype(error())>} is \tcode{true}.

\pnum
\mandates
\tcode{U} is a valid value type for \tcode{expected}. If \tcode{is_void_v<U>} is
\tcode{false}, the declaration
\begin{codeblock}
U u(invoke(std::forward<F>(f)));
\end{codeblock}
is well-formed.

\pnum
\effects
\begin{itemize}
\item
If \tcode{has_value()} is \tcode{false}, returns
\tcode{expected<U, E>(unexpect, error())}.
\item
Otherwise, if \tcode{is_void_v<U>} is \tcode{false}, returns an
\tcode{expected<U, E>} object whose \exposid{has_val} member is \tcode{true} and
\exposid{val} member is direct-non-list-initialized with
\tcode{invoke(std::forward<F>(f))}.
\item
Otherwise, evaluates \tcode{invoke(std::forward<F>(f))} and then returns
\tcode{expected<U, E>()}.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{transform}{expected<void>}%
\begin{itemdecl}
template<class F> constexpr auto transform(F&& f) &&;
template<class F> constexpr auto transform(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{U} be \tcode{remove_cv_t<invoke_result_t<F>>}.

\pnum
\constraints
\tcode{is_constructible_v<E, decltype(std::move(error()))>} is \tcode{true}.

\pnum
\mandates
\tcode{U} is a valid value type for \tcode{expected}. If \tcode{is_void_v<U>} is
\tcode{false}, the declaration
\begin{codeblock}
U u(invoke(std::forward<F>(f)));
\end{codeblock}
is well-formed.

\pnum
\effects
\begin{itemize}
\item
If \tcode{has_value()} is \tcode{false}, returns
\tcode{expected<U, E>(unexpect, std::move(error()))}.
\item
Otherwise, if \tcode{is_void_v<U>} is \tcode{false}, returns an
\tcode{expected<U, E>} object whose \exposid{has_val} member is \tcode{true} and
\exposid{val} member is direct-non-list-initialized with
\tcode{invoke(std::forward<F>(f))}.
\item
Otherwise, evaluates \tcode{invoke(std::forward<F>(f))} and then returns
\tcode{expected<U, E>()}.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{transform_error}{expected<void>}%
\begin{itemdecl}
template<class F> constexpr auto transform_error(F&& f) &;
template<class F> constexpr auto transform_error(F&& f) const &;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{G} be \tcode{remove_cv_t<invoke_result_t<F, decltype(error())>>}.

\pnum
\mandates
\tcode{G} is a valid template argument
for \tcode{unexpected}\iref{expected.un.general} and the declaration
\begin{codeblock}
G g(invoke(std::forward<F>(f), error()));
\end{codeblock}
is well-formed.

\pnum
\returns
If \tcode{has_value()} is \tcode{true}, \tcode{expected<T, G>()}; otherwise, an
\tcode{expected<T, G>} object whose \exposid{has_val} member is \tcode{false}
and \exposid{unex} member is direct-non-list-initialized with
\tcode{invoke(std::for\-ward<F>(f), error())}.
\end{itemdescr}

\indexlibrarymember{transform_error}{expected<void>}%
\begin{itemdecl}
template<class F> constexpr auto transform_error(F&& f) &&;
template<class F> constexpr auto transform_error(F&& f) const &&;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{G} be
\tcode{remove_cv_t<invoke_result_t<F, decltype(std::move(error()))>>}.

\pnum
\mandates
\tcode{G} is a valid template argument
for \tcode{unexpected}\iref{expected.un.general} and the declaration
\begin{codeblock}
G g(invoke(std::forward<F>(f), std::move(error())));
\end{codeblock}
is well-formed.

\pnum
\returns
If \tcode{has_value()} is \tcode{true}, \tcode{expected<T, G>()}; otherwise, an
\tcode{expected<T, G>} object whose \exposid{has_val} member is \tcode{false}
and \exposid{unex} member is direct-non-list-initialized with
\tcode{invoke(std::for\-ward<F>(f), std::move(error()))}.
\end{itemdescr}

\rSec3[expected.void.eq]{Equality operators}

\indexlibrarymember{operator==}{expected<void>}%
\begin{itemdecl}
template<class T2, class E2> requires is_void_v<T2>
  friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{x.error() == y.error()} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
If \tcode{x.has_value()} does not equal \tcode{y.has_value()}, \tcode{false};
otherwise \tcode{x.has_value() || static_cast<bool>(x.error() == y.error())}.
\end{itemdescr}

\indexlibrarymember{operator==}{expected<void>}%
\begin{itemdecl}
template<class E2>
  friend constexpr bool operator==(const expected& x, const unexpected<E2>& e);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{x.error() == e.error()} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
\tcode{!x.has_value() \&\& static_cast<bool>(x.error() == e.error())}.
\end{itemdescr}

\rSec1[bitset]{Bitsets}
\indexlibraryglobal{bitset}%

\rSec2[bitset.syn]{Header \tcode{<bitset>} synopsis}%

\pnum
The header \libheaderdef{bitset} defines a class template
and several related functions for representing
and manipulating fixed-size sequences of bits.

\begin{codeblock}
#include <string>   // see \ref{string.syn}
#include <iosfwd>   // for \tcode{istream}\iref{istream.syn}, \tcode{ostream}\iref{ostream.syn}, see \ref{iosfwd.syn}

namespace std {
  template<size_t N> class bitset;

  // \ref{bitset.operators}, bitset operators
  template<size_t N>
    constexpr bitset<N> operator&(const bitset<N>&, const bitset<N>&) noexcept;
  template<size_t N>
    constexpr bitset<N> operator|(const bitset<N>&, const bitset<N>&) noexcept;
  template<size_t N>
    constexpr bitset<N> operator^(const bitset<N>&, const bitset<N>&) noexcept;
  template<class charT, class traits, size_t N>
    basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>& is, bitset<N>& x);
  template<class charT, class traits, size_t N>
    basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, const bitset<N>& x);
}
\end{codeblock}

\rSec2[template.bitset]{Class template \tcode{bitset}}%

\rSec3[template.bitset.general]{General}%
\indexlibraryglobal{bitset}%
\begin{codeblock}
namespace std {
  template<size_t N> class bitset {
  public:
    // bit reference
    class reference {
    public:
      constexpr reference(const reference&) = default;
      constexpr ~reference();
      constexpr reference& operator=(bool x) noexcept;              // for \tcode{b[i] = x;}
      constexpr reference& operator=(const reference&) noexcept;    // for \tcode{b[i] = b[j];}
      constexpr bool operator~() const noexcept;                    // flips the bit
      constexpr operator bool() const noexcept;                     // for \tcode{x = b[i];}
      constexpr reference& flip() noexcept;                         // for \tcode{b[i].flip();}
    };

    // \ref{bitset.cons}, constructors
    constexpr bitset() noexcept;
    constexpr bitset(unsigned long long val) noexcept;
    template<class charT, class traits, class Allocator>
      constexpr explicit bitset(
        const basic_string<charT, traits, Allocator>& str,
        typename basic_string<charT, traits, Allocator>::size_type pos = 0,
        typename basic_string<charT, traits, Allocator>::size_type n
          = basic_string<charT, traits, Allocator>::npos,
        charT zero = charT('0'),
        charT one = charT('1'));
    template<class charT, class traits>
      constexpr explicit bitset(
        basic_string_view<charT, traits> str,
        typename basic_string_view<charT, traits>::size_type pos = 0,
        typename basic_string_view<charT, traits>::size_type n
          = basic_string_view<charT, traits>::npos,
        charT zero = charT('0'),
        charT one = charT('1'));
    template<class charT>
      constexpr explicit bitset(
        const charT* str,
        typename basic_string_view<charT>::size_type n = basic_string_view<charT>::npos,
        charT zero = charT('0'),
        charT one = charT('1'));

    // \ref{bitset.members}, bitset operations
    constexpr bitset& operator&=(const bitset& rhs) noexcept;
    constexpr bitset& operator|=(const bitset& rhs) noexcept;
    constexpr bitset& operator^=(const bitset& rhs) noexcept;
    constexpr bitset& operator<<=(size_t pos) noexcept;
    constexpr bitset& operator>>=(size_t pos) noexcept;
    constexpr bitset  operator<<(size_t pos) const noexcept;
    constexpr bitset  operator>>(size_t pos) const noexcept;
    constexpr bitset& set() noexcept;
    constexpr bitset& set(size_t pos, bool val = true);
    constexpr bitset& reset() noexcept;
    constexpr bitset& reset(size_t pos);
    constexpr bitset  operator~() const noexcept;
    constexpr bitset& flip() noexcept;
    constexpr bitset& flip(size_t pos);

    // element access
    constexpr bool operator[](size_t pos) const;
    constexpr reference operator[](size_t pos);

    constexpr unsigned long to_ulong() const;
    constexpr unsigned long long to_ullong() const;
    template<class charT = char,
             class traits = char_traits<charT>,
             class Allocator = allocator<charT>>
      constexpr basic_string<charT, traits, Allocator>
        to_string(charT zero = charT('0'), charT one = charT('1')) const;

    // observers
    constexpr size_t count() const noexcept;
    constexpr size_t size() const noexcept;
    constexpr bool operator==(const bitset& rhs) const noexcept;
    constexpr bool test(size_t pos) const;
    constexpr bool all() const noexcept;
    constexpr bool any() const noexcept;
    constexpr bool none() const noexcept;
  };

  // \ref{bitset.hash}, hash support
  template<class T> struct hash;
  template<size_t N> struct hash<bitset<N>>;
}
\end{codeblock}

\pnum
The class template
\tcode{bitset<N>}
describes an object that can store a sequence consisting of a fixed number of
bits, \tcode{N}.

\pnum
Each bit represents either the value zero (reset) or one (set).
To
\term{toggle}
a bit is to change the value zero to one, or the value one to
zero.
Each bit has a non-negative position \tcode{pos}.
When converting
between an object of class
\tcode{bitset<N>}
and a value of some
integral type, bit position \tcode{pos} corresponds to the
\term{bit value}
\tcode{1 << pos}.
The integral value corresponding to two
or more bits is the sum of their bit values.

\pnum
The functions described in \ref{template.bitset} can report three kinds of
errors, each associated with a distinct exception:
\begin{itemize}
\item
an
\term{invalid-argument}
error is associated with exceptions of type
\tcode{invalid_argument}\iref{invalid.argument};
\indexlibraryglobal{invalid_argument}%
\item
an
\term{out-of-range}
error is associated with exceptions of type
\tcode{out_of_range}\iref{out.of.range};
\indexlibraryglobal{out_of_range}%
\item
an
\term{overflow}
error is associated with exceptions of type
\tcode{overflow_error}\iref{overflow.error}.
\indexlibraryglobal{overflow_error}%
\end{itemize}

\rSec3[bitset.cons]{Constructors}

\indexlibraryctor{bitset}%
\begin{itemdecl}
constexpr bitset() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes all bits in \tcode{*this} to zero.
\end{itemdescr}

\indexlibraryctor{bitset}%
\begin{itemdecl}
constexpr bitset(unsigned long long val) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes the first \tcode{M} bit positions to the corresponding bit
values in \tcode{val}.
\tcode{M} is the smaller of \tcode{N} and the number of bits in the value
representation\iref{term.object.representation} of \tcode{unsigned long long}.
If \tcode{M < N}, the remaining bit positions are initialized to zero.
\end{itemdescr}

\indexlibraryctor{bitset}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  constexpr explicit bitset(
    const basic_string<charT, traits, Allocator>& str,
    typename basic_string<charT, traits, Allocator>::size_type pos = 0,
    typename basic_string<charT, traits, Allocator>::size_type n
      = basic_string<charT, traits, Allocator>::npos,
    charT zero = charT('0'),
    charT one = charT('1'));
template<class charT, class traits>
  constexpr explicit bitset(
    basic_string_view<charT, traits> str,
    typename basic_string_view<charT, traits>::size_type pos = 0,
    typename basic_string_view<charT, traits>::size_type n
      = basic_string_view<charT, traits>::npos,
    charT zero = charT('0'),
    charT one = charT('1'));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Determines the effective length
\tcode{rlen} of the initializing string as the smaller of
\tcode{n} and
\tcode{str.size() - pos}.
Initializes the first \tcode{M} bit
positions to values determined from the corresponding characters in the string
\tcode{str}.
\tcode{M} is the smaller of \tcode{N} and \tcode{rlen}.

\pnum
An element of the constructed object has value zero if the
corresponding character in \tcode{str}, beginning at position
\tcode{pos}, is
\tcode{zero}.
Otherwise, the element has the value one.
Character position \tcode{pos + M - 1} corresponds to bit position zero.
Subsequent decreasing character positions correspond to increasing bit positions.

\pnum
If \tcode{M < N}, remaining bit positions are initialized to zero.

\pnum
The function uses \tcode{traits::eq}
to compare the character values.

\pnum
\throws
\indexlibraryglobal{out_of_range}%
\tcode{out_of_range} if \tcode{pos > str.size()} or
\indexlibraryglobal{invalid_argument}%
\tcode{invalid_argument} if any of
the \tcode{rlen} characters in \tcode{str}
beginning at position \tcode{pos}
is other than \tcode{zero} or \tcode{one}.
\end{itemdescr}

\indexlibraryctor{bitset}%
\begin{itemdecl}
template<class charT>
  constexpr explicit bitset(
    const charT* str,
    typename basic_string_view<charT>::size_type n = basic_string_view<charT>::npos,
    charT zero = charT('0'),
    charT one = charT('1'));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by:
\begin{codeblock}
bitset(n == basic_string_view<charT>::npos
          ? basic_string_view<charT>(str)
          : basic_string_view<charT>(str, n),
       0, n, zero, one)
\end{codeblock}
\end{itemdescr}


\rSec3[bitset.members]{Members}

\indexlibrarymember{operator\&=}{bitset}%
\begin{itemdecl}
constexpr bitset& operator&=(const bitset& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Clears each bit in
\tcode{*this}
for which the corresponding bit in \tcode{rhs} is clear, and leaves all other bits unchanged.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator"|=}{bitset}%
\begin{itemdecl}
constexpr bitset& operator|=(const bitset& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Sets each bit in
\tcode{*this}
for which the corresponding bit in \tcode{rhs} is set, and leaves all other bits unchanged.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator\caret=}{bitset}%
\begin{itemdecl}
constexpr bitset& operator^=(const bitset& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Toggles each bit in
\tcode{*this}
for which the corresponding bit in \tcode{rhs} is set, and leaves all other bits unchanged.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator<<=}{bitset}%
\begin{itemdecl}
constexpr bitset& operator<<=(size_t pos) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Replaces each bit at position \tcode{I} in
\tcode{*this}
with a value determined as follows:

\begin{itemize}
\item
If \tcode{I < pos}, the new value is zero;
\item
If \tcode{I >= pos}, the new value is the previous
value of the bit at position \tcode{I - pos}.
\end{itemize}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator>>=}{bitset}%
\begin{itemdecl}
constexpr bitset& operator>>=(size_t pos) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Replaces each bit at position \tcode{I} in
\tcode{*this}
with a value determined as follows:

\begin{itemize}
\item
If \tcode{pos >= N - I}, the new value is zero;
\item
If \tcode{pos < N - I}, the new value is the previous value of the bit at position \tcode{I + pos}.
\end{itemize}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator<<}{bitset}%
\begin{itemdecl}
constexpr bitset operator<<(size_t pos) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{bitset(*this) <<= pos}.
\end{itemdescr}

\indexlibrarymember{operator>>}{bitset}%
\begin{itemdecl}
constexpr bitset operator>>(size_t pos) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{bitset(*this) >>= pos}.
\end{itemdescr}

% Do not use \indexlibrarymember.
\indexlibrary{\idxcode{set} (member)!\idxcode{bitset}}%
\indexlibrary{\idxcode{bitset}!\idxcode{set}}%
\begin{itemdecl}
constexpr bitset& set() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Sets all bits in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

% Do not use \indexlibrarymember.
\indexlibrary{\idxcode{set} (member)!\idxcode{bitset}}%
\indexlibrary{\idxcode{bitset}!\idxcode{set}}%
\begin{itemdecl}
constexpr bitset& set(size_t pos, bool val = true);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Stores a new value in the bit at position \tcode{pos} in
\tcode{*this}.
If \tcode{val} is \tcode{true}, the stored value is one, otherwise it is zero.

\pnum
\returns
\tcode{*this}.

\pnum
\throws
\indexlibraryglobal{out_of_range}%
\tcode{out_of_range} if \tcode{pos} does not correspond to a valid bit position.
\end{itemdescr}

\indexlibrarymember{reset}{bitset}%
\begin{itemdecl}
constexpr bitset& reset() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Resets all bits in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{reset}{bitset}%
\begin{itemdecl}
constexpr bitset& reset(size_t pos);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Resets the bit at position \tcode{pos} in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.

\pnum
\throws
\indexlibraryglobal{out_of_range}%
\tcode{out_of_range} if \tcode{pos} does not correspond to a valid bit position.
\end{itemdescr}

\indexlibrarymember{operator\~{}}{bitset}%
\begin{itemdecl}
constexpr bitset operator~() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object \tcode{x} of class
\tcode{bitset}
and initializes it with
\tcode{*this}.

\pnum
\returns
\tcode{x.flip()}.
\end{itemdescr}

\indexlibrarymember{flip}{bitset}%
\begin{itemdecl}
constexpr bitset& flip() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Toggles all bits in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{flip}{bitset}%
\begin{itemdecl}
constexpr bitset& flip(size_t pos);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Toggles the bit at position \tcode{pos} in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.

\pnum
\throws
\indexlibraryglobal{out_of_range}%
\tcode{out_of_range} if \tcode{pos} does not correspond to a valid bit position.
\end{itemdescr}

\indexlibrarymember{operator[]}{bitset}%
\begin{itemdecl}
constexpr bool operator[](size_t pos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{pos < size()} is \tcode{true}.

\pnum
\returns
\tcode{true} if the bit at position \tcode{pos} in \tcode{*this} has the value
one, otherwise \tcode{false}.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibrarymember{operator[]}{bitset}%
\begin{itemdecl}
constexpr bitset::reference operator[](size_t pos);
\end{itemdecl}

\begin{itemdescr}
\pnum
\hardexpects
\tcode{pos < size()} is \tcode{true}.

\pnum
\returns
An object of type
\tcode{bitset::reference}
such that
\tcode{(*this)[pos] == this->test(pos)},
and such that
\tcode{(*this)[pos] = val}
is equivalent to
\tcode{this->set(pos, val)}.

\pnum
\throws
Nothing.

\pnum
\remarks
For the purpose of determining the presence of a data
race\iref{intro.multithread}, any access or update through the resulting
reference potentially accesses or modifies, respectively, the entire
underlying bitset.
\end{itemdescr}

\indexlibrarymember{to_ulong}{bitset}%
\begin{itemdecl}
constexpr unsigned long to_ulong() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x}.

\pnum
\throws
\indexlibraryglobal{overflow_error}%
\tcode{overflow_error} if the integral value \tcode{x}
corresponding to the bits in \tcode{*this}
cannot be represented as type \tcode{unsigned long}.
\end{itemdescr}

\indexlibrarymember{to_ullong}{bitset}%
\begin{itemdecl}
constexpr unsigned long long to_ullong() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x}.

\pnum
\throws
\indexlibraryglobal{overflow_error}%
\tcode{overflow_error} if the integral value \tcode{x}
corresponding to the bits in \tcode{*this}
cannot be represented as type \tcode{unsigned long long}.
\end{itemdescr}

\indexlibrarymember{to_string}{bitset}%
\begin{itemdecl}
template<class charT = char,
         class traits = char_traits<charT>,
         class Allocator = allocator<charT>>
  constexpr basic_string<charT, traits, Allocator>
    to_string(charT zero = charT('0'), charT one = charT('1')) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a string object of the appropriate type
and initializes it to a string of length \tcode{N} characters.
Each character is determined by the value of its corresponding bit position in
\tcode{*this}.
Character position \tcode{N - 1} corresponds to bit position zero.
Subsequent decreasing character positions correspond to increasing bit
positions.
Bit value zero becomes the character \tcode{zero},
bit value one becomes the character
\tcode{one}.

\pnum
\returns
The created object.
\end{itemdescr}

\indexlibrarymember{count}{bitset}%
\begin{itemdecl}
constexpr size_t count() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A count of the number of bits set in
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{size}{bitset}%
\begin{itemdecl}
constexpr size_t size() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{N}.
\end{itemdescr}

\indexlibrarymember{operator==}{bitset}%
\begin{itemdecl}
constexpr bool operator==(const bitset& rhs) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if the value of each bit in
\tcode{*this}
equals the value of the corresponding bit in \tcode{rhs}.
\end{itemdescr}

\indexlibrarymember{test}{bitset}%
\begin{itemdecl}
constexpr bool test(size_t pos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true}
if the bit at position \tcode{pos}
in
\tcode{*this}
has the value one.

\pnum
\throws
\indexlibraryglobal{out_of_range}%
\tcode{out_of_range} if \tcode{pos} does not correspond to a valid bit position.
\end{itemdescr}

\indexlibrarymember{all}{bitset}%
\begin{itemdecl}
constexpr bool all() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{count() == size()}.
\end{itemdescr}

% Do not use \indexlibrarymember.
\indexlibrary{\idxcode{any} (member)!\idxcode{bitset}}%
\indexlibrary{\idxcode{bitset}!\idxcode{any}}%
\begin{itemdecl}
constexpr bool any() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{count() != 0}.
\end{itemdescr}

\indexlibrarymember{none}{bitset}%
\begin{itemdecl}
constexpr bool none() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{count() == 0}.
\end{itemdescr}

\rSec2[bitset.hash]{\tcode{bitset} hash support}

\indexlibraryglobal{hash_code}%
\begin{itemdecl}
template<size_t N> struct hash<bitset<N>>;
\end{itemdecl}

\begin{itemdescr}
\pnum
The specialization is enabled\iref{unord.hash}.
\end{itemdescr}


\rSec2[bitset.operators]{\tcode{bitset} operators}

\indexlibrarymember{operator\&}{bitset}%
\begin{itemdecl}
template<size_t N>
  constexpr bitset<N> operator&(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{bitset<N>(lhs) \&= rhs}.
\end{itemdescr}

\indexlibrarymember{operator"|}{bitset}%
\begin{itemdecl}
template<size_t N>
  constexpr bitset<N> operator|(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{bitset<N>(lhs) |= rhs}.
\end{itemdescr}

\indexlibrarymember{operator\caret}{bitset}%
\begin{itemdecl}
template<size_t N>
  constexpr bitset<N> operator^(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{bitset<N>(lhs) \caret= rhs}.
\end{itemdescr}

\indexlibrarymember{operator>>}{bitset}%
\begin{itemdecl}
template<class charT, class traits, size_t N>
  basic_istream<charT, traits>&
    operator>>(basic_istream<charT, traits>& is, bitset<N>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
A formatted input function\iref{istream.formatted}.

\pnum
\effects
Extracts up to \tcode{N} characters from \tcode{is}.
Stores these characters in a temporary object \tcode{str} of type
\tcode{basic_string<charT, traits>},
then evaluates the expression
\tcode{x = bitset<N>(str)}.
Characters are extracted and stored until any of the following occurs:
\begin{itemize}
\item
\tcode{N} characters have been extracted and stored;
\item
\indextext{end-of-file}%
end-of-file occurs on the input sequence;
\item
the next input character is neither
\tcode{is.widen('0')}
nor
\tcode{is.widen('1')}
(in which case the input character is not extracted).
\end{itemize}

\pnum
If \tcode{N > 0} and no characters are stored in \tcode{str},
\tcode{ios_base::failbit} is set in the input function's local error state
before \tcode{setstate} is called.

\pnum
\returns
\tcode{is}.
\end{itemdescr}

\indexlibrarymember{operator<<}{bitset}%
\begin{itemdecl}
template<class charT, class traits, size_t N>
  basic_ostream<charT, traits>&
    operator<<(basic_ostream<charT, traits>& os, const bitset<N>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\begin{codeblock}
os << x.template to_string<charT, traits, allocator<charT>>(
  use_facet<ctype<charT>>(os.getloc()).widen('0'),
  use_facet<ctype<charT>>(os.getloc()).widen('1'))
\end{codeblock}
(see~\ref{ostream.formatted}).
\end{itemdescr}

\rSec1[function.objects]{Function objects}

\rSec2[function.objects.general]{General}

\pnum
A \defnx{function object type}{function object!type} is an object
type\iref{term.object.type} that can be the type of the
\grammarterm{postfix-expression}
in a function call\iref{expr.call,over.match.call}.
\begin{footnote}
Such a type is a function
pointer or a class type which has a member \tcode{operator()} or a class type
which has a conversion to a pointer to function.
\end{footnote}
A \defn{function object} is an
object of a function object type. In the places where one would expect to pass a
pointer to a function to an algorithmic template\iref{algorithms}, the
interface is specified to accept a function object. This not only makes
algorithmic templates work with pointers to functions, but also enables them to
work with arbitrary function objects.

\rSec2[functional.syn]{Header \tcode{<functional>} synopsis}

\indexheader{functional}%
\indexlibraryglobal{unwrap_ref_decay}%
\indexlibraryglobal{unwrap_ref_decay_t}%
\begin{codeblock}
namespace std {
  // \ref{func.invoke}, invoke
  template<class F, class... Args>
    constexpr invoke_result_t<F, Args...> invoke(F&& f, Args&&... args)             // freestanding
      noexcept(is_nothrow_invocable_v<F, Args...>);

  template<class R, class F, class... Args>
    constexpr R invoke_r(F&& f, Args&&... args)                                     // freestanding
      noexcept(is_nothrow_invocable_r_v<R, F, Args...>);

  // \ref{refwrap}, \tcode{reference_wrapper}
  template<class T> class reference_wrapper;                                        // freestanding

  template<class T> constexpr reference_wrapper<T> ref(T&) noexcept;                // freestanding
  template<class T> constexpr reference_wrapper<const T> cref(const T&) noexcept;   // freestanding
  template<class T> void ref(const T&&) = delete;                                   // freestanding
  template<class T> void cref(const T&&) = delete;                                  // freestanding

  template<class T>
    constexpr reference_wrapper<T> ref(reference_wrapper<T>) noexcept;              // freestanding
  template<class T>
    constexpr reference_wrapper<const T> cref(reference_wrapper<T>) noexcept;       // freestanding

  // \ref{refwrap.common.ref}, \tcode{common_reference} related specializations
  template<class R, class T, template<class> class RQual, template<class> class TQual>
    requires @\seebelow@
  struct basic_common_reference<R, T, RQual, TQual>;

  template<class T, class R, template<class> class TQual, template<class> class RQual>
    requires @\seebelow@
  struct basic_common_reference<T, R, TQual, RQual>;

  // \ref{arithmetic.operations}, arithmetic operations
  template<class T = void> struct plus;                                             // freestanding
  template<class T = void> struct minus;                                            // freestanding
  template<class T = void> struct multiplies;                                       // freestanding
  template<class T = void> struct divides;                                          // freestanding
  template<class T = void> struct modulus;                                          // freestanding
  template<class T = void> struct negate;                                           // freestanding
  template<> struct plus<void>;                                                     // freestanding
  template<> struct minus<void>;                                                    // freestanding
  template<> struct multiplies<void>;                                               // freestanding
  template<> struct divides<void>;                                                  // freestanding
  template<> struct modulus<void>;                                                  // freestanding
  template<> struct negate<void>;                                                   // freestanding

  // \ref{comparisons}, comparisons
  template<class T = void> struct equal_to;                                         // freestanding
  template<class T = void> struct not_equal_to;                                     // freestanding
  template<class T = void> struct greater;                                          // freestanding
  template<class T = void> struct less;                                             // freestanding
  template<class T = void> struct greater_equal;                                    // freestanding
  template<class T = void> struct less_equal;                                       // freestanding
  template<> struct equal_to<void>;                                                 // freestanding
  template<> struct not_equal_to<void>;                                             // freestanding
  template<> struct greater<void>;                                                  // freestanding
  template<> struct less<void>;                                                     // freestanding
  template<> struct greater_equal<void>;                                            // freestanding
  template<> struct less_equal<void>;                                               // freestanding

  // \ref{comparisons.three.way}, class \tcode{compare_three_way}
  struct compare_three_way;                                                         // freestanding

  // \ref{logical.operations}, logical operations
  template<class T = void> struct logical_and;                                      // freestanding
  template<class T = void> struct logical_or;                                       // freestanding
  template<class T = void> struct logical_not;                                      // freestanding
  template<> struct logical_and<void>;                                              // freestanding
  template<> struct logical_or<void>;                                               // freestanding
  template<> struct logical_not<void>;                                              // freestanding

  // \ref{bitwise.operations}, bitwise operations
  template<class T = void> struct bit_and;                                          // freestanding
  template<class T = void> struct bit_or;                                           // freestanding
  template<class T = void> struct bit_xor;                                          // freestanding
  template<class T = void> struct bit_not;                                          // freestanding
  template<> struct bit_and<void>;                                                  // freestanding
  template<> struct bit_or<void>;                                                   // freestanding
  template<> struct bit_xor<void>;                                                  // freestanding
  template<> struct bit_not<void>;                                                  // freestanding

  // \ref{func.identity}, identity
  struct identity;                                                                  // freestanding

  // \ref{func.not.fn}, function template \tcode{not_fn}
  template<class F> constexpr @\unspec@ not_fn(F&& f);                            // freestanding
  template<auto f> constexpr @\unspec@ not_fn() noexcept;                         // freestanding

  // \ref{func.bind.partial}, function templates \tcode{bind_front} and \tcode{bind_back}
  template<class F, class... Args>
    constexpr @\unspec@ bind_front(F&&, Args&&...);                               // freestanding
  template<auto f, class... Args>
    constexpr @\unspec@ bind_front(Args&&...);                                    // freestanding
  template<class F, class... Args>
    constexpr @\unspec@ bind_back(F&&, Args&&...);                                // freestanding
  template<auto f, class... Args>
    constexpr @\unspec@ bind_back(Args&&...);                                     // freestanding

  // \ref{func.bind}, bind
  template<class T> struct is_bind_expression;                                      // freestanding
  template<class T>
    constexpr bool @\libglobal{is_bind_expression_v}@ =                                           // freestanding
      is_bind_expression<T>::value;
  template<class T> struct is_placeholder;                                          // freestanding
  template<class T>
    constexpr int @\libglobal{is_placeholder_v}@ =                                                // freestanding
      is_placeholder<T>::value;

  template<class F, class... BoundArgs>
    constexpr @\unspec@ bind(F&&, BoundArgs&&...);                                // freestanding
  template<class R, class F, class... BoundArgs>
    constexpr @\unspec@ bind(F&&, BoundArgs&&...);                                // freestanding

  namespace placeholders {
    // \tcode{\placeholder{M}} is the \impldef{number of placeholders for bind expressions} number of placeholders
    @\seebelownc@ _1;                                                                   // freestanding
    @\seebelownc@ _2;                                                                   // freestanding
               @\vdots@
    @\seebelownc@ _@\placeholdernc{M}@;                                                                   // freestanding
  }

  // \ref{func.memfn}, member function adaptors
  template<class R, class T>
    constexpr @\unspec@ mem_fn(R T::*) noexcept;                                  // freestanding

  // \ref{func.wrap}, polymorphic function wrappers
  // \ref{func.wrap.badcall}, class \tcode{bad_function_call}
  class bad_function_call;

  // \ref{func.wrap.func}, class template \tcode{function}
  template<class> class function;       // \notdef
  template<class R, class... ArgTypes> class function<R(ArgTypes...)>;

  // \ref{func.wrap.func.alg}, \tcode{function} specialized algorithms
  template<class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;

  // \ref{func.wrap.func.nullptr}, \tcode{function} null pointer comparison operator functions
  template<class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;

  // \ref{func.wrap.move}, move-only wrapper
  template<class... S> class move_only_function;                        // \notdef
  template<class R, class... ArgTypes>
    class move_only_function<R(ArgTypes...) @\cv{}\itcorr[-1]@ @\placeholdernc{ref}@ noexcept(@\placeholdernc{noex}@)>;     // \seebelow

  // \ref{func.wrap.copy}, copyable wrapper
  template<class... S> class copyable_function;                         // \notdef
  template<class R, class... ArgTypes>
    class copyable_function<R(ArgTypes...) @\cv{}\itcorr[-1]@ @\placeholdernc{ref}@ noexcept(@\placeholdernc{noex}@)>;      // \seebelow

  // \ref{func.wrap.ref}, non-owning wrapper
  template<class... S> class function_ref;                              // freestanding, \notdef
  template<class R, class... ArgTypes>
    class function_ref<R(ArgTypes...) @\cv{}\itcorr[-1]@ noexcept(@\placeholdernc{noex}@)>;               // freestanding, \seebelow

  // \ref{func.search}, searchers
  template<class ForwardIterator1, class BinaryPredicate = equal_to<>>
    class default_searcher;                                                         // freestanding

  template<class RandomAccessIterator,
           class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
           class BinaryPredicate = equal_to<>>
    class boyer_moore_searcher;

  template<class RandomAccessIterator,
           class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
           class BinaryPredicate = equal_to<>>
    class boyer_moore_horspool_searcher;

  // \ref{unord.hash}, class template \tcode{hash}
  template<class T>
    struct hash;                                                                    // freestanding

  namespace ranges {
    // \ref{range.cmp}, concept-constrained comparisons
    struct equal_to;                                                                // freestanding
    struct not_equal_to;                                                            // freestanding
    struct greater;                                                                 // freestanding
    struct less;                                                                    // freestanding
    struct greater_equal;                                                           // freestanding
    struct less_equal;                                                              // freestanding
  }

  template<class Fn, class... Args>
    concept @\defexposconceptnc{callable}@ =                                                  // \expos
      requires (Fn&& fn, Args&&... args) {
        std::forward<Fn>(fn)(std::forward<Args>(args)...);
      };

  template<class Fn, class... Args>
    concept @\defexposconceptnc{nothrow-callable}@ =                                          // \expos
      @\exposconcept{callable}@<Fn, Args...> &&
      requires (Fn&& fn, Args&&... args) {
        { std::forward<Fn>(fn)(std::forward<Args>(args)...) } noexcept;
      };

  template<class Fn, class... Args>
    using @\exposidnc{call-result-t}@ = decltype(declval<Fn>()(declval<Args>()...));  // \expos

  template<const auto& T>
    using @\exposidnc{decayed-typeof}@ = decltype(auto(T));                           // \expos
}
\end{codeblock}

\pnum
\begin{example}
If a \Cpp{} program wants to have a by-element addition of two vectors \tcode{a}
and \tcode{b} containing \tcode{double} and put the result into \tcode{a},
it can do:

\begin{codeblock}
transform(a.begin(), a.end(), b.begin(), a.begin(), plus<double>());
\end{codeblock}
\end{example}

\pnum
\begin{example}
To negate every element of \tcode{a}:

\begin{codeblock}
transform(a.begin(), a.end(), a.begin(), negate<double>());
\end{codeblock}

\end{example}

\rSec2[func.def]{Definitions}

\pnum
The following definitions apply to this Clause:

\pnum
A \defn{call signature} is the name of a return type followed by a
parenthesized comma-separated list of zero or more argument types.

\pnum
A \defnadj{callable}{type} is a function object type\iref{function.objects} or a pointer to member.

\pnum
A \defnadj{callable}{object} is an object of a callable type.

\pnum
A \defnx{call wrapper type}{call wrapper!type} is a type that holds a callable object
and supports a call operation that forwards to that object.

\pnum
A \defn{call wrapper} is an object of a call wrapper type.

\pnum
A \defn{target object} is the callable object held by a call wrapper.

\pnum
A call wrapper type may additionally hold
a sequence of objects and references
that may be passed as arguments to the target object.
These entities are collectively referred to
as \defnx{bound argument entities}{bound argument entity}.

\pnum
The target object and bound argument entities of the call wrapper are
collectively referred to as \defnx{state entities}{state entity}.

\rSec2[func.require]{Requirements}

\pnum
\indextext{invoke@\tcode{\placeholder{INVOKE}}}%
\indexlibrary{invoke@\tcode{\placeholder{INVOKE}}}%
Define \tcode{\placeholdernc{INVOKE}(f, t$_1$, t$_2$, $\dotsc$, t$_N$)} as follows:
\begin{itemize}
\item \tcode{(t$_1$.*f)(t$_2$, $\dotsc$, t$_N$)} when \tcode{f} is a pointer to a
member function of a class \tcode{T}
and
\tcode{is_same_v<T, remove_cvref_t<decltype(t$_1$)>> ||}
\tcode{is_base_of_v<T, remove_cvref_t<decltype(t$_1$)>>} is \tcode{true};

\item \tcode{(t$_1$.get().*f)(t$_2$, $\dotsc$, t$_N$)} when \tcode{f} is a pointer to a
member function of a class \tcode{T}
and \tcode{remove_cvref_t<decltype(t$_1$)>} is a specialization of \tcode{reference_wrapper};

\item \tcode{((*t$_1$).*f)(t$_2$, $\dotsc$, t$_N$)} when \tcode{f} is a pointer to a
member function of a class \tcode{T}
and \tcode{t$_1$} does not satisfy the previous two items;

\item \tcode{t$_1$.*f} when $N = 1$ and \tcode{f} is a pointer to
data member of a class \tcode{T}
and
\tcode{is_same_v<T, remove_cvref_t<decltype(t$_1$)>> ||}
\tcode{is_base_of_v<T, remove_cvref_t<decltype(t$_1$)>>} is \tcode{true};

\item \tcode{t$_1$.get().*f} when $N = 1$ and \tcode{f} is a pointer to
data member of a class \tcode{T}
and \tcode{remove_cvref_t<decltype(t$_1$)>} is a specialization of \tcode{reference_wrapper};

\item \tcode{(*t$_1$).*f} when $N = 1$ and \tcode{f} is a pointer to
data member of a class \tcode{T}
and \tcode{t$_1$} does not satisfy the previous two items;

\item \tcode{f(t$_1$, t$_2$, $\dotsc$, t$_N$)} in all other cases.
\end{itemize}

\pnum
\indexlibrary{invoke@\tcode{\placeholder{INVOKE}}}%
Define \tcode{\placeholdernc{INVOKE}<R>(f, t$_1$, t$_2$, $\dotsc$, t$_N$)} as
\tcode{static_cast<void>(\placeholdernc{INVOKE}(f, t$_1$, t$_2$, $\dotsc$, t$_N$))}
if \tcode{R} is \cv{}~\keyword{void}, otherwise
\tcode{\placeholdernc{INVOKE}(f, t$_1$, t$_2$, $\dotsc$, t$_N$)} implicitly converted
to \tcode{R}.
If
\tcode{reference_converts_from_temporary_v<R, decltype(\placeholdernc{INVOKE}(f, t$_1$, t$_2$, $\dotsc$, t$_N$))>}
is \tcode{true},
\tcode{\placeholdernc{INVOKE}<R>(f, t$_1$, t$_2$, $\dotsc$, t$_N$)}
is ill-formed.

\pnum
\indextext{call wrapper}%
\indextext{call wrapper!simple}%
\indextext{call wrapper!forwarding}%
Every call wrapper\iref{func.def} meets the \oldconcept{MoveConstructible}
and \oldconcept{Destructible} requirements.
An \defn{argument forwarding call wrapper} is a
call wrapper that can be called with an arbitrary argument list
and delivers the arguments to the target object as references.
This forwarding step delivers rvalue arguments as rvalue references
and lvalue arguments as lvalue references.
\begin{note}
In a typical implementation, argument forwarding call wrappers have
an overloaded function call operator of the form
\begin{codeblock}
template<class... UnBoundArgs>
  constexpr R operator()(UnBoundArgs&&... unbound_args) @\textit{cv-qual}@;
\end{codeblock}
\end{note}

\pnum
\label{term.perfect.forwarding.call.wrapper}%
A \defnadj{perfect forwarding}{call wrapper} is
an argument forwarding call wrapper
that forwards its state entities to the underlying call expression.
This forwarding step delivers a state entity of type \tcode{T}
as \cv{} \tcode{T\&}
when the call is performed on an lvalue of the call wrapper type and
as \cv{} \tcode{T\&\&} otherwise,
where \cv{} represents the cv-qualifiers of the call wrapper and
where \cv{} shall be neither \tcode{volatile} nor \tcode{const volatile}.

\pnum
A \defn{call pattern} defines the semantics of invoking
a perfect forwarding call wrapper.
A postfix call performed on a perfect forwarding call wrapper is
expression-equivalent\iref{defns.expression.equivalent} to
an expression \tcode{e} determined from its call pattern \tcode{cp}
by replacing all occurrences
of the arguments of the call wrapper and its state entities
with references as described in the corresponding forwarding steps.

\pnum
\label{term.simple.call.wrapper}%
A \defn{simple call wrapper} is a perfect forwarding call wrapper that meets
the \oldconcept{CopyConstructible} and \oldconcept{CopyAssignable} requirements
and whose copy constructor, move constructor, and assignment operators
are constexpr functions that do not throw exceptions.

\pnum
The copy/move constructor of an argument forwarding call wrapper has
the same apparent semantics
as if memberwise copy/move of its state entities
were performed\iref{class.copy.ctor}.
\begin{note}
This implies that each of the copy/move constructors has
the same exception-specification as
the corresponding implicit definition and is declared as \keyword{constexpr}
if the corresponding implicit definition would be considered to be constexpr.
\end{note}

\pnum
Argument forwarding call wrappers returned by
a given standard library function template have the same type
if the types of their corresponding state entities are the same.

\rSec2[func.invoke]{\tcode{invoke} functions}
\indexlibraryglobal{invoke}%
\indexlibrary{invoke@\tcode{\placeholder{INVOKE}}}%
\begin{itemdecl}
template<class F, class... Args>
  constexpr invoke_result_t<F, Args...> invoke(F&& f, Args&&... args)
    noexcept(is_nothrow_invocable_v<F, Args...>);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_invocable_v<F, Args...>} is \tcode{true}.

\pnum
\returns
\tcode{\placeholdernc{INVOKE}(std::forward<F>(f), std::forward<Args>(args)...)}\iref{func.require}.
\end{itemdescr}

\indexlibraryglobal{invoke_r}%
\begin{itemdecl}
template<class R, class F, class... Args>
  constexpr R invoke_r(F&& f, Args&&... args)
    noexcept(is_nothrow_invocable_r_v<R, F, Args...>);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_invocable_r_v<R, F, Args...>} is \tcode{true}.

\pnum
\returns
\tcode{\placeholdernc{INVOKE}<R>(std::forward<F>(f), std::forward<Args>(args)...)}\iref{func.require}.
\end{itemdescr}

\rSec2[refwrap]{Class template \tcode{reference_wrapper}}

\rSec3[refwrap.general]{General}

\indexlibraryglobal{reference_wrapper}%
\indextext{function object!\idxcode{reference_wrapper}}%
\begin{codeblock}
namespace std {
  template<class T> class reference_wrapper {
  public:
    // types
    using type = T;

    // \ref{refwrap.const}, constructors
    template<class U>
      constexpr reference_wrapper(U&&) noexcept(@\seebelow@);
    constexpr reference_wrapper(const reference_wrapper& x) noexcept;

    // \ref{refwrap.assign}, assignment
    constexpr reference_wrapper& operator=(const reference_wrapper& x) noexcept;

    // \ref{refwrap.access}, access
    constexpr operator T& () const noexcept;
    constexpr T& get() const noexcept;

    // \ref{refwrap.invoke}, invocation
    template<class... ArgTypes>
      constexpr invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&...) const
        noexcept(is_nothrow_invocable_v<T&, ArgTypes...>);

    // \ref{refwrap.comparisons}, comparisons
    friend constexpr bool operator==(reference_wrapper, reference_wrapper);
    friend constexpr bool operator==(reference_wrapper, const T&);
    friend constexpr bool operator==(reference_wrapper, reference_wrapper<const T>);

    friend constexpr auto operator<=>(reference_wrapper, reference_wrapper);
    friend constexpr auto operator<=>(reference_wrapper, const T&);
    friend constexpr auto operator<=>(reference_wrapper, reference_wrapper<const T>);
  };

  template<class T>
    reference_wrapper(T&) -> reference_wrapper<T>;
}
\end{codeblock}

\pnum
\tcode{reference_wrapper<T>} is a \oldconcept{CopyConstructible} and \oldconcept{CopyAssignable} wrapper
around a reference to an object or function of type \tcode{T}.

\pnum
\tcode{reference_wrapper<T>} is
a trivially copyable type\iref{term.trivially.copyable.type}.

\pnum
The template parameter \tcode{T} of \tcode{reference_wrapper}
may be an incomplete type.
\begin{note}
Using the comparison operators described in \ref{refwrap.comparisons}
with \tcode{T} being an incomplete type
can lead to an ill-formed program
with no diagnostic required\iref{temp.point,temp.constr.atomic}.
\end{note}

\rSec3[refwrap.const]{Constructors}

\indexlibraryctor{reference_wrapper}%
\begin{itemdecl}
template<class U>
  constexpr reference_wrapper(U&& u) noexcept(@\seebelow@);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{\placeholdernc{FUN}} denote the exposition-only functions
\begin{codeblock}
void @\placeholdernc{FUN}@(T&) noexcept;
void @\placeholdernc{FUN}@(T&&) = delete;
\end{codeblock}

\pnum
\constraints
The expression \tcode{\placeholdernc{FUN}(declval<U>())} is well-formed and
\tcode{is_same_v<remove_cvref_t<U>, reference_wrapper>} is \tcode{false}.

\pnum
\effects
Creates a variable \tcode{r}
as if by \tcode{T\& r = std::forward<U>(u)},
then constructs a \tcode{reference_wrapper} object
that stores a reference to \tcode{r}.

\pnum
\remarks
The exception specification is equivalent to
\tcode{noexcept(\placeholdernc{FUN}(declval<U>()))}.
\end{itemdescr}

\indexlibraryctor{reference_wrapper}%
\begin{itemdecl}
constexpr reference_wrapper(const reference_wrapper& x) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a \tcode{reference_wrapper} object that
stores a reference to \tcode{x.get()}.
\end{itemdescr}

\rSec3[refwrap.assign]{Assignment}

\indexlibrarymember{operator=}{reference_wrapper}%
\begin{itemdecl}
constexpr reference_wrapper& operator=(const reference_wrapper& x) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{*this} stores a reference to  \tcode{x.get()}.
\end{itemdescr}

\rSec3[refwrap.access]{Access}

\indexlibrarymember{operator T\&}{reference_wrapper}%
\begin{itemdecl}
constexpr operator T& () const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The stored reference.
\end{itemdescr}

\indexlibrarymember{get}{reference_wrapper}%
\begin{itemdecl}
constexpr T& get() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The stored reference.
\end{itemdescr}

\rSec3[refwrap.invoke]{Invocation}

\indexlibrarymember{operator()}{reference_wrapper}%
\begin{itemdecl}
template<class... ArgTypes>
  constexpr invoke_result_t<T&, ArgTypes...>
    operator()(ArgTypes&&... args) const noexcept(is_nothrow_invocable_v<T&, ArgTypes...>);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{T} is a complete type.

\pnum
\returns
\tcode{\placeholdernc{INVOKE}(get(), std::forward<ArgTypes>(args)...)}\iref{func.require}.
\end{itemdescr}

\rSec3[refwrap.comparisons]{Comparisons}

\begin{itemdecl}
friend constexpr bool operator==(reference_wrapper x, reference_wrapper y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{x.get() == y.get()} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
\tcode{x.get() == y.get()}.
\end{itemdescr}

\begin{itemdecl}
friend constexpr bool operator==(reference_wrapper x, const T& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{x.get() == y} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
\tcode{x.get() == y}.
\end{itemdescr}

\begin{itemdecl}
friend constexpr bool operator==(reference_wrapper x, reference_wrapper<const T> y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_const_v<T>} is \tcode{false} and
the expression \tcode{x.get() == y.get()} is well-formed and
its result is convertible to \tcode{bool}.

\pnum
\returns
\tcode{x.get() == y.get()}.
\end{itemdescr}

\begin{itemdecl}
friend constexpr auto operator<=>(reference_wrapper x, reference_wrapper y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{\exposid{synth-three-way}(x.get(), y.get())}
is well-formed.

\pnum
\returns
\tcode{\exposid{synth-three-way}(x.get(), y.get())}.
\end{itemdescr}

\begin{itemdecl}
friend constexpr auto operator<=>(reference_wrapper x, const T& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The expression \tcode{\exposid{synth-three-way}(x.get(), y)}
is well-formed.

\pnum
\returns
\tcode{\exposid{synth-three-way}(x.get(), y)}.
\end{itemdescr}

\begin{itemdecl}
friend constexpr auto operator<=>(reference_wrapper x, reference_wrapper<const T> y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_const_v<T>} is \tcode{false}.
The expression \tcode{\exposid{synth-three-way}(x.get(), y.get())}
is well-formed.

\pnum
\returns
\tcode{\exposid{synth-three-way}(x.get(), y.get())}.
\end{itemdescr}

\rSec3[refwrap.helpers]{Helper functions}

\pnum
The template parameter \tcode{T} of
the following \tcode{ref} and \tcode{cref} function templates
may be an incomplete type.

\indexlibrarymember{ref}{reference_wrapper}%
\begin{itemdecl}
template<class T> constexpr reference_wrapper<T> ref(T& t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{reference_wrapper<T>(t)}.
\end{itemdescr}

\indexlibrarymember{ref}{reference_wrapper}%
\begin{itemdecl}
template<class T> constexpr reference_wrapper<T> ref(reference_wrapper<T> t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{t}.
\end{itemdescr}

\indexlibrarymember{cref}{reference_wrapper}%
\begin{itemdecl}
template<class T> constexpr reference_wrapper<const T> cref(const T& t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{reference_wrapper<const T>(t)}.
\end{itemdescr}

\indexlibrarymember{cref}{reference_wrapper}%
\begin{itemdecl}
template<class T> constexpr reference_wrapper<const T> cref(reference_wrapper<T> t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{t}.
\end{itemdescr}

\rSec3[refwrap.common.ref]{\tcode{common_reference} related specializations}

\indexlibraryglobal{basic_common_reference}%
\begin{codeblock}
namespace std {
  template<class T>
    constexpr bool @\exposid{is-ref-wrapper}@ = false;                              // \expos

  template<class T>
    constexpr bool @\exposid{is-ref-wrapper}@<reference_wrapper<T>> = true;

  template<class R, class T, class RQ, class TQ>
    concept @\defexposconcept{ref-wrap-common-reference-exists-with}@ =                     // \expos
      @\exposid{is-ref-wrapper}@<R> &&
      requires { typename common_reference_t<typename R::type&, TQ>; } &&
      @\libconcept{convertible_to}@<RQ, common_reference_t<typename R::type&, TQ>>;

  template<class R, class T, template<class> class RQual, template<class> class TQual>
    requires (@\exposconcept{ref-wrap-common-reference-exists-with}@<R, T, RQual<R>, TQual<T>> &&
              !@\exposconcept{ref-wrap-common-reference-exists-with}@<T, R, TQual<T>, RQual<R>>)
  struct basic_common_reference<R, T, RQual, TQual> {
    using type = common_reference_t<typename R::type&, TQual<T>>;
  };

  template<class T, class R, template<class> class TQual, template<class> class RQual>
    requires (@\exposconcept{ref-wrap-common-reference-exists-with}@<R, T, RQual<R>, TQual<T>> &&
              !@\exposconcept{ref-wrap-common-reference-exists-with}@<T, R, TQual<T>, RQual<R>>)
  struct basic_common_reference<T, R, TQual, RQual> {
    using type = common_reference_t<typename R::type&, TQual<T>>;
  };
}
\end{codeblock}

\rSec2[arithmetic.operations]{Arithmetic operations}

\rSec3[arithmetic.operations.general]{General}

\pnum
The library provides basic function object classes for all of the arithmetic
operators in the language\iref{expr.mul,expr.add}.

\rSec3[arithmetic.operations.plus]{Class template \tcode{plus}}

\indexlibraryglobal{plus}%
\begin{itemdecl}
template<class T = void> struct plus {
  constexpr T operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{plus}%
\begin{itemdecl}
constexpr T operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x + y}.
\end{itemdescr}

\indexlibraryglobal{plus<>}%
\begin{itemdecl}
template<> struct plus<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) + std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{plus<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) + std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) + std::forward<U>(u)}.
\end{itemdescr}

\rSec3[arithmetic.operations.minus]{Class template \tcode{minus}}

\indexlibraryglobal{minus}%
\begin{itemdecl}
template<class T = void> struct minus {
  constexpr T operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{minus}%
\begin{itemdecl}
constexpr T operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x - y}.
\end{itemdescr}

\indexlibraryglobal{minus<>}%
\begin{itemdecl}
template<> struct minus<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) - std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{minus<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) - std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) - std::forward<U>(u)}.
\end{itemdescr}

\rSec3[arithmetic.operations.multiplies]{Class template \tcode{multiplies}}

\indexlibraryglobal{multiplies}%
\begin{itemdecl}
template<class T = void> struct multiplies {
  constexpr T operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{multiplies}%
\begin{itemdecl}
constexpr T operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x * y}.
\end{itemdescr}

\indexlibraryglobal{multiplies<>}%
\begin{itemdecl}
template<> struct multiplies<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) * std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{multiplies<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) * std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) * std::forward<U>(u)}.
\end{itemdescr}

\rSec3[arithmetic.operations.divides]{Class template \tcode{divides}}

\indexlibraryglobal{divides}%
\begin{itemdecl}
template<class T = void> struct divides {
  constexpr T operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{divides}%
\begin{itemdecl}
constexpr T operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x / y}.
\end{itemdescr}

\indexlibraryglobal{divides<>}%
\begin{itemdecl}
template<> struct divides<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) / std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{divides<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) / std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) / std::forward<U>(u)}.
\end{itemdescr}

\rSec3[arithmetic.operations.modulus]{Class template \tcode{modulus}}

\indexlibraryglobal{modulus}%
\begin{itemdecl}
template<class T = void> struct modulus {
  constexpr T operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{modulus}%
\begin{itemdecl}
constexpr T operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x \% y}.
\end{itemdescr}

\indexlibraryglobal{modulus<>}%
\begin{itemdecl}
template<> struct modulus<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) % std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{modulus<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) % std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) \% std::forward<U>(u)}.
\end{itemdescr}

\rSec3[arithmetic.operations.negate]{Class template \tcode{negate}}

\indexlibraryglobal{negate}%
\begin{itemdecl}
template<class T = void> struct negate {
  constexpr T operator()(const T& x) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{negate}%
\begin{itemdecl}
constexpr T operator()(const T& x) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{-x}.
\end{itemdescr}

\indexlibraryglobal{negate<>}%
\begin{itemdecl}
template<> struct negate<void> {
  template<class T> constexpr auto operator()(T&& t) const
    -> decltype(-std::forward<T>(t));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{negate<>}%
\begin{itemdecl}
template<class T> constexpr auto operator()(T&& t) const
    -> decltype(-std::forward<T>(t));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{-std::forward<T>(t)}.
\end{itemdescr}


\rSec2[comparisons]{Comparisons}

\rSec3[comparisons.general]{General}

\pnum
The library provides basic function object classes for all of the comparison
operators in the language\iref{expr.rel,expr.eq}.

\pnum
For templates \tcode{less}, \tcode{greater}, \tcode{less_equal}, and
\tcode{greater_equal}, the specializations for any pointer type
yield a result consistent with the
implementation-defined strict total order over pointers\iref{defns.order.ptr}.
\begin{note}
If \tcode{a < b} is well-defined
for pointers \tcode{a} and \tcode{b} of type \tcode{P},
then \tcode{(a < b) == less<P>()(a, b)},
\tcode{(a > b) == greater<P>()(a, b)}, and so forth.
\end{note}
For template specializations \tcode{less<void>}, \tcode{greater<void>},
\tcode{less_equal<void>}, and \tcode{greater_equal<void>},
if the call operator calls a built-in operator comparing pointers,
the call operator yields a result consistent
with the implementation-defined strict total order over pointers.

\rSec3[comparisons.equal.to]{Class template \tcode{equal_to}}

\indexlibraryglobal{equal_to}%
\begin{itemdecl}
template<class T = void> struct equal_to {
  constexpr bool operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{equal_to}%
\begin{itemdecl}
constexpr bool operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x == y}.
\end{itemdescr}

\indexlibraryglobal{equal_to<>}%
\begin{itemdecl}
template<> struct equal_to<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) == std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{equal_to<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) == std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) == std::forward<U>(u)}.
\end{itemdescr}

\rSec3[comparisons.not.equal.to]{Class template \tcode{not_equal_to}}

\indexlibraryglobal{not_equal_to}%
\begin{itemdecl}
template<class T = void> struct not_equal_to {
  constexpr bool operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{not_equal_to}%
\begin{itemdecl}
constexpr bool operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x != y}.
\end{itemdescr}

\indexlibraryglobal{not_equal_to<>}%
\begin{itemdecl}
template<> struct not_equal_to<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) != std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{not_equal_to<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) != std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) != std::forward<U>(u)}.
\end{itemdescr}

\rSec3[comparisons.greater]{Class template \tcode{greater}}

\indexlibraryglobal{greater}%
\begin{itemdecl}
template<class T = void> struct greater {
  constexpr bool operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{greater}%
\begin{itemdecl}
constexpr bool operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x > y}.
\end{itemdescr}

\indexlibraryglobal{greater<>}%
\begin{itemdecl}
template<> struct greater<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) > std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{greater<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) > std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) > std::forward<U>(u)}.
\end{itemdescr}

\rSec3[comparisons.less]{Class template \tcode{less}}

\indexlibraryglobal{less}%
\begin{itemdecl}
template<class T = void> struct less {
  constexpr bool operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{less}%
\begin{itemdecl}
constexpr bool operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x < y}.
\end{itemdescr}

\indexlibraryglobal{less<>}%
\begin{itemdecl}
template<> struct less<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) < std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{less<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) < std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) < std::forward<U>(u)}.
\end{itemdescr}

\rSec3[comparisons.greater.equal]{Class template \tcode{greater_equal}}

\indexlibraryglobal{greater_equal}%
\begin{itemdecl}
template<class T = void> struct greater_equal {
  constexpr bool operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{greater_equal}%
\begin{itemdecl}
constexpr bool operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x >= y}.
\end{itemdescr}

\indexlibraryglobal{greater_equal<>}%
\begin{itemdecl}
template<> struct greater_equal<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) >= std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{greater_equal<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) >= std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) >= std::forward<U>(u)}.
\end{itemdescr}

\rSec3[comparisons.less.equal]{Class template \tcode{less_equal}}

\indexlibraryglobal{less_equal}%
\begin{itemdecl}
template<class T = void> struct less_equal {
  constexpr bool operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{less_equal}%
\begin{itemdecl}
constexpr bool operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x <= y}.
\end{itemdescr}

\indexlibraryglobal{less_equal<>}%
\begin{itemdecl}
template<> struct less_equal<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) <= std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{less_equal<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) <= std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) <= std::forward<U>(u)}.
\end{itemdescr}

\rSec3[comparisons.three.way]{Class \tcode{compare_three_way}}

\indexlibraryglobal{compare_three_way}%
\begin{codeblock}
namespace std {
  struct compare_three_way {
    template<class T, class U>
      constexpr auto operator()(T&& t, U&& u) const;

    using is_transparent = @\unspec@;
  };
}
\end{codeblock}

\begin{itemdecl}
template<class T, class U>
  constexpr auto operator()(T&& t, U&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} and \tcode{U} satisfy \libconcept{three_way_comparable_with}.

\pnum
\expects
If the expression \tcode{std::forward<T>(t) <=> std::forward<U>(u)} results in
a call to a built-in operator \tcode{<=>} comparing pointers of type \tcode{P},
the conversion sequences from both \tcode{T} and \tcode{U} to \tcode{P}
are equality-preserving\iref{concepts.equality};
otherwise, \tcode{T} and \tcode{U} model \libconcept{three_way_comparable_with}.

\pnum
\effects
\begin{itemize}
\item
  If the expression \tcode{std::forward<T>(t) <=> std::forward<U>(u)} results in
  a call to a built-in operator \tcode{<=>} comparing pointers of type \tcode{P},
  returns \tcode{strong_ordering::less}
  if (the converted value of) \tcode{t} precedes \tcode{u}
  in the implementation-defined strict total order
  over pointers\iref{defns.order.ptr},
  \tcode{strong_ordering::greater}
  if \tcode{u} precedes \tcode{t}, and
  otherwise \tcode{strong_ordering::equal}.
\item
  Otherwise, equivalent to: \tcode{return std::forward<T>(t) <=> std::forward<U>(u);}
\end{itemize}
\end{itemdescr}

\rSec2[range.cmp]{Concept-constrained comparisons}

\indexlibraryglobal{equal_to}%
\begin{codeblock}
struct ranges::equal_to {
  template<class T, class U>
    constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{codeblock}

\begin{itemdecl}
template<class T, class U>
  constexpr bool operator()(T&& t, U&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} and \tcode{U} satisfy \libconcept{equality_comparable_with}.

\pnum
\expects
If the expression \tcode{std::forward<T>(t) == std::forward<U>(u)}
results in a call to a built-in operator \tcode{==} comparing pointers of type
\tcode{P}, the conversion sequences from both \tcode{T} and \tcode{U} to \tcode{P}
are equality-preserving\iref{concepts.equality};
otherwise, \tcode{T} and \tcode{U} model \libconcept{equality_comparable_with}.

\pnum
\effects
\begin{itemize}
\item
  If the expression \tcode{std::forward<T>(t) == std::forward<U>(u)} results in
  a call to a built-in operator \tcode{==} comparing pointers:
  returns \tcode{false} if either (the converted value of) \tcode{t} precedes
  \tcode{u} or \tcode{u} precedes \tcode{t} in the implementation-defined strict
  total order over pointers\iref{defns.order.ptr} and otherwise \tcode{true}.

\item
  Otherwise, equivalent to:
  \tcode{return std::forward<T>(t) == std::forward<U>(u);}
\end{itemize}
\end{itemdescr}

\indexlibraryglobal{not_equal_to}%
\begin{codeblock}
struct ranges::not_equal_to {
  template<class T, class U>
    constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{codeblock}

\begin{itemdecl}
template<class T, class U>
  constexpr bool operator()(T&& t, U&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} and \tcode{U} satisfy \libconcept{equality_comparable_with}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return !ranges::equal_to{}(std::forward<T>(t), std::forward<U>(u));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{greater}%
\begin{codeblock}
struct ranges::greater {
  template<class T, class U>
  constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{codeblock}

\begin{itemdecl}
template<class T, class U>
  constexpr bool operator()(T&& t, U&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} and \tcode{U} satisfy \libconcept{totally_ordered_with}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return ranges::less{}(std::forward<U>(u), std::forward<T>(t));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{less}%
\begin{codeblock}
struct ranges::less {
  template<class T, class U>
    constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{codeblock}

\begin{itemdecl}
template<class T, class U>
  constexpr bool operator()(T&& t, U&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} and \tcode{U} satisfy \libconcept{totally_ordered_with}.

\pnum
\expects
If the expression \tcode{std::forward<T>(t) < std::forward<U>(u)} results in a
call to a built-in operator \tcode{<} comparing pointers of type \tcode{P}, the
conversion sequences from both \tcode{T} and \tcode{U} to \tcode{P} are
equality-preserving\iref{concepts.equality};
otherwise, \tcode{T} and \tcode{U} model \libconcept{totally_ordered_with}.
For any expressions
\tcode{ET} and \tcode{EU} such that \tcode{decltype((ET))} is \tcode{T} and
\tcode{decltype((EU))} is \tcode{U}, exactly one of
\tcode{ranges::less\{\}(ET, EU)},
\tcode{ranges::less\{\}(EU, ET)}, or
\tcode{ranges::equal_to\{\}(ET, EU)}
is \tcode{true}.

\pnum
\effects
\begin{itemize}
\item
If the expression \tcode{std::forward<T>(t) < std::forward<U>(u)} results in a
call to a built-in operator \tcode{<} comparing pointers:
returns \tcode{true} if (the converted value of) \tcode{t} precedes \tcode{u} in
the implementation-defined strict total order over pointers\iref{defns.order.ptr}
and otherwise \tcode{false}.

\item
Otherwise, equivalent to:
\tcode{return std::forward<T>(t) < std::forward<U>(u);}
\end{itemize}
\end{itemdescr}

\indexlibraryglobal{greater_equal}%
\begin{codeblock}
struct ranges::greater_equal {
  template<class T, class U>
    constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{codeblock}

\begin{itemdecl}
template<class T, class U>
  constexpr bool operator()(T&& t, U&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} and \tcode{U} satisfy \libconcept{totally_ordered_with}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return !ranges::less{}(std::forward<T>(t), std::forward<U>(u));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{less_equal}%
\begin{itemdecl}
struct ranges::less_equal {
  template<class T, class U>
    constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{itemdecl}

\begin{itemdecl}
template<class T, class U>
  constexpr bool operator()(T&& t, U&& u) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} and \tcode{U} satisfy \libconcept{totally_ordered_with}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return !ranges::less{}(std::forward<U>(u), std::forward<T>(t));
\end{codeblock}
\end{itemdescr}

\rSec2[logical.operations]{Logical operations}

\rSec3[logical.operations.general]{General}

\pnum
The library provides basic function object classes for all of the logical
operators in the language\iref{expr.log.and,expr.log.or,expr.unary.op}.

\rSec3[logical.operations.and]{Class template \tcode{logical_and}}

\indexlibraryglobal{logical_and}%
\begin{itemdecl}
template<class T = void> struct logical_and {
  constexpr bool operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{logical_and}%
\begin{itemdecl}
constexpr bool operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x \&\& y}.
\end{itemdescr}

\indexlibraryglobal{logical_and<>}%
\begin{itemdecl}
template<> struct logical_and<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) && std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{logical_and<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) && std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) \&\& std::forward<U>(u)}.
\end{itemdescr}

\rSec3[logical.operations.or]{Class template \tcode{logical_or}}

\indexlibraryglobal{logical_or}%
\begin{itemdecl}
template<class T = void> struct logical_or {
  constexpr bool operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{logical_or}%
\begin{itemdecl}
constexpr bool operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x || y}.
\end{itemdescr}

\indexlibraryglobal{logical_or<>}%
\begin{itemdecl}
template<> struct logical_or<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) || std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{logical_or<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) || std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) || std::forward<U>(u)}.
\end{itemdescr}

\rSec3[logical.operations.not]{Class template \tcode{logical_not}}

\indexlibraryglobal{logical_not}%
\begin{itemdecl}
template<class T = void> struct logical_not {
  constexpr bool operator()(const T& x) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{logical_not}%
\begin{itemdecl}
constexpr bool operator()(const T& x) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{!x}.
\end{itemdescr}

\indexlibraryglobal{logical_not<>}%
\begin{itemdecl}
template<> struct logical_not<void> {
  template<class T> constexpr auto operator()(T&& t) const
    -> decltype(!std::forward<T>(t));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{logical_not<>}%
\begin{itemdecl}
template<class T> constexpr auto operator()(T&& t) const
    -> decltype(!std::forward<T>(t));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{!std::forward<T>(t)}.
\end{itemdescr}


\rSec2[bitwise.operations]{Bitwise operations}

\rSec3[bitwise.operations.general]{General}

\pnum
The library provides basic function object classes for all of the bitwise
operators in the language\iref{expr.bit.and,expr.or,expr.xor,expr.unary.op}.

\rSec3[bitwise.operations.and]{Class template \tcode{bit_and}}

\indexlibraryglobal{bit_and}%
\begin{itemdecl}
template<class T = void> struct bit_and {
  constexpr T operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{bit_and}%
\begin{itemdecl}
constexpr T operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x \& y}.
\end{itemdescr}

\indexlibraryglobal{bit_and<>}%
\begin{itemdecl}
template<> struct bit_and<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) & std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{bit_and<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) & std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) \& std::forward<U>(u)}.
\end{itemdescr}

\rSec3[bitwise.operations.or]{Class template \tcode{bit_or}}

\indexlibraryglobal{bit_or}%
\begin{itemdecl}
template<class T = void> struct bit_or {
  constexpr T operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{bit_or}%
\begin{itemdecl}
constexpr T operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x | y}.
\end{itemdescr}

\indexlibraryglobal{bit_or<>}%
\begin{itemdecl}
template<> struct bit_or<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) | std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{bit_or<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) | std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) | std::forward<U>(u)}.
\end{itemdescr}

\rSec3[bitwise.operations.xor]{Class template \tcode{bit_xor}}

\indexlibraryglobal{bit_xor}%
\begin{itemdecl}
template<class T = void> struct bit_xor {
  constexpr T operator()(const T& x, const T& y) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{bit_xor}%
\begin{itemdecl}
constexpr T operator()(const T& x, const T& y) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x \caret{} y}.
\end{itemdescr}

\indexlibraryglobal{bit_xor<>}%
\begin{itemdecl}
template<> struct bit_xor<void> {
  template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) ^ std::forward<U>(u));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{bit_xor<>}%
\begin{itemdecl}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const
    -> decltype(std::forward<T>(t) ^ std::forward<U>(u));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::forward<T>(t) \caret{} std::forward<U>(u)}.
\end{itemdescr}

\rSec3[bitwise.operations.not]{Class template \tcode{bit_not}}

\begin{itemdecl}
template<class T = void> struct bit_not {
  constexpr T operator()(const T& x) const;
};
\end{itemdecl}

\indexlibrarymember{operator()}{bit_not}%
\begin{itemdecl}
constexpr T operator()(const T& x) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{\~{}x}.
\end{itemdescr}

\indexlibraryglobal{bit_not<>}%
\begin{itemdecl}
template<> struct bit_not<void> {
  template<class T> constexpr auto operator()(T&& t) const
    -> decltype(~std::forward<T>(t));

  using is_transparent = @\unspec@;
};
\end{itemdecl}

\indexlibrarymember{operator()}{bit_not<>}%
\begin{itemdecl}
template<class T> constexpr auto operator()(T&& t) const
    -> decltype(~std::forward<T>(t));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{\~{}std::forward<T>(t)}.
\end{itemdescr}


\rSec2[func.identity]{Class \tcode{identity}}

\indexlibraryglobal{identity}%
\begin{itemdecl}
struct identity {
  template<class T>
    constexpr T&& operator()(T&& t) const noexcept;

  using is_transparent = @\unspec@;
};

template<class T>
  constexpr T&& operator()(T&& t) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return std::forward<T>(t);}
\end{itemdescr}


\rSec2[func.not.fn]{Function template \tcode{not_fn}}

\indexlibraryglobal{not_fn}%
\begin{itemdecl}
template<class F> constexpr @\unspec@ not_fn(F&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
In the text that follows:
\begin{itemize}
\item \tcode{g} is a value of the result of a \tcode{not_fn} invocation,
\item \tcode{FD} is the type \tcode{decay_t<F>},
\item \tcode{fd} is the target object of \tcode{g}\iref{func.def}
  of type \tcode{FD},
  direct-non-list-initialized with \tcode{std::forward<F\brk{}>(f)},
\item \tcode{call_args} is an argument pack
  used in a function call expression\iref{expr.call} of \tcode{g}.
\end{itemize}

\pnum
\mandates
\tcode{is_constructible_v<FD, F> \&\& is_move_constructible_v<FD>}
is \tcode{true}.

\pnum
\expects
\tcode{FD} meets the \oldconcept{MoveConstructible} requirements.

\pnum
\returns
A perfect forwarding call wrapper\iref{term.perfect.forwarding.call.wrapper} \tcode{g}
with call pattern \tcode{!invoke(fd, call_args...)}.

\pnum
\throws
Any exception thrown by the initialization of \tcode{fd}.
\end{itemdescr}

\indexlibraryglobal{not_fn}%
\begin{itemdecl}
template<auto f> constexpr @\unspec@ not_fn() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
In the text that follows:
\begin{itemize}
\item
\tcode{F} is the type of \tcode{f},
\item
\tcode{g} is a value of the result of a \tcode{not_fn} invocation,
\item
\tcode{call_args} is an argument pack
used in a function call expression\iref{expr.call} of \tcode{g}.
\end{itemize}

\pnum
\mandates
If \tcode{is_pointer_v<F> || is_member_pointer_v<F>} is \tcode{true},
then \tcode{f != nullptr} is \tcode{true}.

\pnum
\returns
A perfect forwarding call wrapper\iref{func.require} \tcode{g} that
does not have state entities, and
has the call pattern \tcode{!invoke(f, call_args...)}.
\end{itemdescr}

\rSec2[func.bind.partial]{Function templates \tcode{bind_front} and \tcode{bind_back}}

\indexlibraryglobal{bind_front}%
\indexlibraryglobal{bind_back}%
\begin{itemdecl}
template<class F, class... Args>
  constexpr @\unspec@ bind_front(F&& f, Args&&... args);
template<class F, class... Args>
  constexpr @\unspec@ bind_back(F&& f, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Within this subclause:
\begin{itemize}
\item \tcode{g} is a value of
the result of a \tcode{bind_front} or \tcode{bind_back} invocation,
\item \tcode{FD} is the type \tcode{decay_t<F>},
\item \tcode{fd} is the target object of \tcode{g}\iref{func.def}
  of type \tcode{FD},
  direct-non-list-initialized with \tcode{std::forward<F\brk{}>(f)},
\item \tcode{BoundArgs} is a pack
  that denotes \tcode{decay_t<Args>...},
\item \tcode{bound_args} is
  a pack of bound argument entities of \tcode{g}\iref{func.def}
  of types \tcode{BoundArgs...},
  direct-non-list-initialized with \tcode{std::forward<Args>(args)...},
  respectively, and
\item \tcode{call_args} is an argument pack used in
  a function call expression\iref{expr.call} of \tcode{g}.
\end{itemize}

\pnum
\mandates
\begin{codeblock}
is_constructible_v<FD, F> &&
is_move_constructible_v<FD> &&
(is_constructible_v<BoundArgs, Args> && ...) &&
(is_move_constructible_v<BoundArgs> && ...)
\end{codeblock}
is \tcode{true}.

\pnum
\expects
\tcode{FD} meets the \oldconcept{MoveConstructible} requirements.
For each $\tcode{T}_i$ in \tcode{BoundArgs},
if $\tcode{T}_i$ is an object type,
$\tcode{T}_i$ meets the \oldconcept{MoveConstructible} requirements.

\pnum
\returns
A perfect forwarding call wrapper\iref{term.perfect.forwarding.call.wrapper} \tcode{g}
with call pattern:
\begin{itemize}
\item
\tcode{invoke(fd, bound_args..., call_args...)}
for a \tcode{bind_front} invocation, or
\item
\tcode{invoke(fd, call_args..., bound_args...)}
for a \tcode{bind_back} invocation.
\end{itemize}

\pnum
\throws
Any exception thrown by
the initialization of the state entities of \tcode{g}\iref{func.def}.
\end{itemdescr}

\indexlibraryglobal{bind_front}%
\indexlibraryglobal{bind_back}%
\begin{itemdecl}
template<auto f, class... Args>
  constexpr @\unspec@ bind_front(Args&&... args);
template<auto f, class... Args>
  constexpr @\unspec@ bind_back(Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Within this subclause:
\begin{itemize}
\item
\tcode{F} is the type of \tcode{f},
\item
\tcode{g} is a value of the result of
a \tcode{bind_front} or \tcode{bind_back} invocation,
\item
\tcode{BoundArgs} is a pack that denotes \tcode{decay_t<Args>...},
\item
\tcode{bound_args} is a pack of bound argument entities of
\tcode{g}\iref{func.def} of types \tcode{BoundArgs...},
direct-non-list-initialized with \tcode{std::forward<Args>(args)...},
respectively, and
\item
\tcode{call_args} is an argument pack used in
a function call expression\iref{expr.call} of \tcode{g}.
\end{itemize}

\pnum
\mandates
\begin{itemize}
\item
\tcode{(is_constructible_v<BoundArgs, Args> \&\& ...)} is \tcode{true}, and
\item
\tcode{(is_move_constructible_v<BoundArgs> \&\& ...)} is \tcode{true}, and
\item
if \tcode{is_pointer_v<F> || is_member_pointer_v<F>} is \tcode{true},
then \tcode{f != nullptr} is \tcode{true}.
\end{itemize}

\pnum
\expects
For each $\tcode{T}_i$ in \tcode{BoundArgs},
$\tcode{T}_i$ meets the \oldconcept{MoveConstructible} requirements.

\pnum
\returns
A perfect forwarding call wrapper\iref{func.require} \tcode{g} that
does not have a target object, and has the call pattern:
\begin{itemize}
\item
\tcode{invoke(f, bound_args..., call_args...)}
for a \tcode{bind_front} invocation, or
\item
\tcode{invoke(f, call_args..., bound_args...)}
for a \tcode{bind_back} invocation.
\end{itemize}

\pnum
throws
Any exception thrown by the initialization of \tcode{bound_args}.
\end{itemdescr}

\rSec2[func.bind]{Function object binders}%

\rSec3[func.bind.general]{General}%
\indextext{function object!binders|(}

\pnum
Subclause \ref{func.bind} describes a uniform mechanism for binding
arguments of callable objects.

\rSec3[func.bind.isbind]{Class template \tcode{is_bind_expression}}

\indexlibraryglobal{is_bind_expression}%
\begin{codeblock}
namespace std {
  template<class T> struct is_bind_expression;  // see below
}
\end{codeblock}

\pnum
The class template \tcode{is_bind_expression} can be used to detect function objects
generated by \tcode{bind}. The function template \tcode{bind}
uses \tcode{is_bind_expression} to detect subexpressions.

\pnum
Specializations of the \tcode{is_bind_expression} template shall meet
the \oldconcept{UnaryTypeTrait} requirements\iref{meta.rqmts}. The implementation
provides a definition that has a base characteristic of
\tcode{true_type} if \tcode{T} is a type returned from \tcode{bind},
otherwise it has a base characteristic of \tcode{false_type}.
A program may specialize this template for a program-defined type \tcode{T}
to have a base characteristic of \tcode{true_type} to indicate that
\tcode{T} should be treated as a subexpression in a \tcode{bind} call.

\rSec3[func.bind.isplace]{Class template \tcode{is_placeholder}}

\indexlibraryglobal{is_placeholder}%
\begin{codeblock}
namespace std {
  template<class T> struct is_placeholder;      // see below
}
\end{codeblock}

\pnum
\indexlibraryglobal{placeholders}%
\indexlibrary{1@\tcode{_1}}%
\indexlibrary{2@\tcode{_2}}%
\indexlibrary{3@\tcode{_3}}%
\indexlibrary{4@\tcode{_4}}%
\indexlibrary{5@\tcode{_5}}%
\indexlibrary{6@\tcode{_6}}%
\indexlibrary{7@\tcode{_7}}%
\indexlibrary{8@\tcode{_8}}%
\indexlibrary{9@\tcode{_9}}%
\indexlibrary{10@\tcode{_10}}%
The class template \tcode{is_placeholder} can be used to detect the standard placeholders
\tcode{_1}, \tcode{_2}, and so on\iref{func.bind.place}.
The function template \tcode{bind} uses
\tcode{is_placeholder} to detect placeholders.

\pnum
Specializations of the \tcode{is_placeholder} template shall meet
the \oldconcept{UnaryTypeTrait} requirements\iref{meta.rqmts}. The implementation
provides a definition that has the base characteristic of
\tcode{integral_constant<int, \placeholder{J}>} if \tcode{T} is the type of
\tcode{std::placeholders::_\placeholder{J}}, otherwise it has a
base characteristic of \tcode{integral_constant<int, 0>}. A program
may specialize this template for a program-defined type \tcode{T} to
have a base characteristic of \tcode{integral_constant<int, N>}
with \tcode{N > 0} to indicate that \tcode{T} should be
treated as a placeholder type.

\rSec3[func.bind.bind]{Function template \tcode{bind}}
\indexlibrary{\idxcode{bind}|(}

\pnum
In the text that follows:
\begin{itemize}
\item \tcode{g} is a value of the result of a \tcode{bind} invocation,
\item \tcode{FD} is the type \tcode{decay_t<F>},
\item \tcode{fd} is an lvalue that
  is a target object of \tcode{g}\iref{func.def} of type \tcode{FD}
  direct-non-list-initialized with \tcode{std::forward<F>(f)},
\item $\tcode{T}_i$ is the $i^\text{th}$ type in the template parameter pack \tcode{BoundArgs},
\item $\tcode{TD}_i$ is the type \tcode{decay_t<$\tcode{T}_i$>},
\item $\tcode{t}_i$ is the $i^\text{th}$ argument in the function parameter pack \tcode{bound_args},
\item $\tcode{td}_i$ is a bound argument entity
  of \tcode{g}\iref{func.def} of type $\tcode{TD}_i$
  direct-non-list-initialized with
  \tcode{std::forward<\brk{}$\tcode{T}_i$>($\tcode{t}_i$)},
\item $\tcode{U}_j$ is the $j^\text{th}$ deduced type of the \tcode{UnBoundArgs\&\&...} parameter
  of the argument forwarding call wrapper, and
\item $\tcode{u}_j$ is the $j^\text{th}$ argument associated with $\tcode{U}_j$.
\end{itemize}

\indexlibraryglobal{bind}%
\begin{itemdecl}
template<class F, class... BoundArgs>
  constexpr @\unspec@ bind(F&& f, BoundArgs&&... bound_args);
template<class R, class F, class... BoundArgs>
  constexpr @\unspec@ bind(F&& f, BoundArgs&&... bound_args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_constructible_v<FD, F>} is \tcode{true}. For each $\tcode{T}_i$
in \tcode{BoundArgs}, \tcode{is_cons\-tructible_v<$\tcode{TD}_i$, $\tcode{T}_i$>} is \tcode{true}.

\pnum
\expects
\tcode{FD} and each $\tcode{TD}_i$ meet
the \oldconcept{MoveConstructible} and \oldconcept{Destructible} requirements.
\tcode{\placeholdernc{INVOKE}(fd, $\tcode{w}_1$, $\tcode{w}_2$, $\dotsc$,
$\tcode{w}_N$)}\iref{func.require} is a valid expression for some
values $\tcode{w}_1$, $\tcode{w}_2$, $\dotsc{}$, $\tcode{w}_N$, where
$N$ has the value \tcode{sizeof...(bound_args)}.

\pnum
\returns
An argument forwarding call wrapper \tcode{g}\iref{func.require}.
A program that attempts to invoke a volatile-qualified \tcode{g}
is ill-formed.
When \tcode{g} is not volatile-qualified, invocation of
\tcode{g($\tcode{u}_1$, $\tcode{u}_2$, $\dotsc$, $\tcode{u}_M$)}
is expression-equivalent\iref{defns.expression.equivalent} to
\begin{codeblock}
@\placeholdernc{INVOKE}@(static_cast<@$\tcode{V}_\tcode{fd}$@>(@$\tcode{v}_\tcode{fd}$@),
       static_cast<@$\tcode{V}_1$@>(@$\tcode{v}_1$@), static_cast<@$\tcode{V}_2$@>(@$\tcode{v}_2$@), @$\dotsc$@, static_cast<@$\tcode{V}_N$@>(@$\tcode{v}_N$@))
\end{codeblock}
for the first overload, and
\begin{codeblock}
@\placeholdernc{INVOKE}@<R>(static_cast<@$\tcode{V}_\tcode{fd}$@>(@$\tcode{v}_\tcode{fd}$@),
          static_cast<@$\tcode{V}_1$@>(@$\tcode{v}_1$@), static_cast<@$\tcode{V}_2$@>(@$\tcode{v}_2$@), @$\dotsc$@, static_cast<@$\tcode{V}_N$@>(@$\tcode{v}_N$@))
\end{codeblock}
for the second overload,
where the values and types of the target argument $\tcode{v}_\tcode{fd}$ and
of the bound arguments
$\tcode{v}_1$, $\tcode{v}_2$, $\dotsc$, $\tcode{v}_N$ are determined as specified below.

\pnum
\throws
Any exception thrown by the initialization of
the state entities of \tcode{g}.

\pnum
\begin{note}
If all of \tcode{FD} and $\tcode{TD}_i$ meet
the requirements of \oldconcept{CopyConstructible}, then
the return type meets the requirements of \oldconcept{CopyConstructible}.
\end{note}
\end{itemdescr}

\pnum
\indextext{bound arguments}%
The values of the \term{bound arguments} $\tcode{v}_1$, $\tcode{v}_2$, $\dotsc$, $\tcode{v}_N$ and their
corresponding types $\tcode{V}_1$, $\tcode{V}_2$, $\dotsc$, $\tcode{V}_N$ depend on the
types $\tcode{TD}_i$ derived from
the call to \tcode{bind} and the
cv-qualifiers \cv{} of the call wrapper \tcode{g} as follows:
\begin{itemize}
\item if $\tcode{TD}_i$ is \tcode{reference_wrapper<T>}, the
argument is \tcode{$\tcode{td}_i$.get()} and its type $\tcode{V}_i$ is \tcode{T\&};

\item if the value of \tcode{is_bind_expression_v<$\tcode{TD}_i$>}
is \tcode{true}, the argument is
\begin{codeblock}
static_cast<@\cv{} $\tcode{TD}_i$@&>(@$\tcode{td}_i$@)(std::forward<@$\tcode{U}_j$@>(@$\tcode{u}_j$@)...)
\end{codeblock}
and its type $\tcode{V}_i$ is
\tcode{invoke_result_t<\cv{} $\tcode{TD}_i$\&, $\tcode{U}_j$...>\&\&};

\item if the value \tcode{j} of \tcode{is_placeholder_v<$\tcode{TD}_i$>}
is not zero, the  argument is \tcode{std::forward<$\tcode{U}_j$>($\tcode{u}_j$)}
and its type $\tcode{V}_i$
is \tcode{$\tcode{U}_j$\&\&};

\item otherwise, the value is $\tcode{td}_i$ and its type $\tcode{V}_i$
is \tcode{\cv{} $\tcode{TD}_i$\&}.
\end{itemize}

\pnum
The value of the target argument $\tcode{v}_\tcode{fd}$ is \tcode{fd} and
its corresponding type $\tcode{V}_\tcode{fd}$ is \tcode{\cv{} FD\&}.
\indexlibrary{\idxcode{bind}|)}%

\rSec3[func.bind.place]{Placeholders}

\indexlibraryglobal{placeholders}%
\indexlibrary{1@\tcode{_1}}%
\indexlibrary{2@\tcode{_2}}%
\indexlibrary{3@\tcode{_3}}%
\indexlibrary{4@\tcode{_4}}%
\indexlibrary{5@\tcode{_5}}%
\indexlibrary{6@\tcode{_6}}%
\indexlibrary{7@\tcode{_7}}%
\indexlibrary{8@\tcode{_8}}%
\indexlibrary{9@\tcode{_9}}%
\indexlibrary{10@\tcode{_10}}%
% FIXME: Fomatting for M and the members _1, _2, _M below,
% as well as their usages elsewhere is inconsistent.
% Should they all follow the formatting used in delcaration of
% "namespace placeholders" in [functional.syn]?
\begin{codeblock}
namespace std::placeholders {
  // \tcode{\placeholder{M}} is the number of placeholders
  @\seebelow@ _1;
  @\seebelow@ _2;
             @\itcorr\vdots@
  @\seebelow@ _@\placeholdernc{M}@;
}
\end{codeblock}

\pnum
The number \tcode{\placeholder{M}} of placeholders is
\impldef{number of placeholders for bind expressions}.

\pnum
All placeholder types meet the \oldconcept{DefaultConstructible} and
\oldconcept{CopyConstructible} requirements, and
their default constructors and copy/move
constructors are constexpr functions that
do not throw exceptions. It is \impldef{assignability of placeholder
objects} whether
placeholder types meet the \oldconcept{CopyAssignable} requirements,
but if so, their copy assignment operators are
constexpr functions that do not throw exceptions.

\pnum
Placeholders should be defined as:
\begin{codeblock}
inline constexpr @\unspec@ _1{};
\end{codeblock}
If they are not, they are declared as:
\begin{codeblock}
extern @\unspec@ _1;
\end{codeblock}%
\indextext{function object!binders|)}

\pnum
\indextext{placeholders!freestanding item}%
Placeholders are freestanding items\iref{freestanding.item}.

\rSec2[func.memfn]{Function template \tcode{mem_fn}}%
\indextext{function object!\idxcode{mem_fn}|(}

\indexlibraryglobal{mem_fn}%
\begin{itemdecl}
template<class R, class T> constexpr @\unspec@ mem_fn(R T::* pm) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A simple call wrapper\iref{term.simple.call.wrapper} \tcode{fn}
with call pattern \tcode{invoke(pmd, call_args...)}, where
\tcode{pmd} is the target object of \tcode{fn} of type \tcode{R T::*}
direct-non-list-initialized with \tcode{pm}, and
\tcode{call_args} is an argument pack
used in a function call expression\iref{expr.call} of \tcode{fn}.
\end{itemdescr}
\indextext{function object!\idxcode{mem_fn}|)}

\rSec2[func.wrap]{Polymorphic function wrappers}%

\rSec3[func.wrap.general]{General}%
\indextext{function object!wrapper|(}

\pnum
Subclause \ref{func.wrap} describes polymorphic wrapper classes that
encapsulate arbitrary callable objects.

\pnum
Let \tcode{t} be an object of a type that is a specialization of
\tcode{function}, \tcode{copyable_function}, or \tcode{move_only_function},
such that the target object \tcode{x} of \tcode{t} has a type that
is a specialization of
\tcode{function}, \tcode{copyable_function}, or \tcode{move_only_function}.
Each argument of the
invocation of \tcode{x} evaluated as part of the invocation of \tcode{t}
may alias an argument in the same position in the invocation of \tcode{t} that
has the same type, even if the corresponding parameter is not of reference type.
\begin{example}
\begin{codeblock}
move_only_function<void(T)>
  f{copyable_function<void(T)>{[](T) {}}};
T t;
f(t);                               // it is unspecified how many copies of \tcode{T} are made
\end{codeblock}
\end{example}

\pnum
\recommended
Implementations should avoid double wrapping when
constructing polymorphic wrappers from one another.

\rSec3[func.wrap.badcall]{Class \tcode{bad_function_call}}%
\indexlibraryglobal{bad_function_call}%

\pnum
An exception of type \tcode{bad_function_call} is thrown by
\tcode{function::operator()}\iref{func.wrap.func.inv}
when the function wrapper object has no target.

\begin{codeblock}
namespace std {
  class bad_function_call : public exception {
  public:
    // see \ref{exception} for the specification of the special member functions
    const char* what() const noexcept override;
  };
}
\end{codeblock}

\indexlibrarymember{what}{bad_function_call}%
\begin{itemdecl}
const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An
\impldef{return value of \tcode{bad_function_call::what}} \ntbs{}.
\end{itemdescr}

\rSec3[func.wrap.func]{Class template \tcode{function}}

\rSec4[func.wrap.func.general]{General}
\indexlibraryglobal{function}%

\indexlibrarymember{result_type}{function}%
\begin{codeblock}
namespace std {
  template<class R, class... ArgTypes>
  class function<R(ArgTypes...)> {
  public:
    using result_type = R;

    // \ref{func.wrap.func.con}, construct/copy/destroy
    function() noexcept;
    function(nullptr_t) noexcept;
    function(const function&);
    function(function&&) noexcept;
    template<class F> function(F&&);

    function& operator=(const function&);
    function& operator=(function&&);
    function& operator=(nullptr_t) noexcept;
    template<class F> function& operator=(F&&);
    template<class F> function& operator=(reference_wrapper<F>) noexcept;

    ~function();

    // \ref{func.wrap.func.mod}, function modifiers
    void swap(function&) noexcept;

    // \ref{func.wrap.func.cap}, function capacity
    explicit operator bool() const noexcept;

    // \ref{func.wrap.func.inv}, function invocation
    R operator()(ArgTypes...) const;

    // \ref{func.wrap.func.targ}, function target access
    const type_info& target_type() const noexcept;
    template<class T>       T* target() noexcept;
    template<class T> const T* target() const noexcept;
  };

  template<class R, class... ArgTypes>
    function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>;

  template<class F> function(F) -> function<@\seebelow@>;
}
\end{codeblock}

\pnum
The \tcode{function} class template provides polymorphic wrappers that
generalize the notion of a function pointer. Wrappers can store, copy,
and call arbitrary callable objects\iref{func.def}, given a call
signature\iref{func.def}.

\pnum
The \tcode{function} class template is a call
wrapper\iref{func.def} whose call signature\iref{func.def}
is \tcode{R(ArgTypes...)}.

\pnum
\begin{note}
The types deduced by the deduction guides for \tcode{function}
might change in future revisions of \Cpp{}.
\end{note}

\rSec4[func.wrap.func.con]{Constructors and destructor}

\indexlibraryctor{function}%
\begin{itemdecl}
function() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{!*this}.
\end{itemdescr}

\indexlibraryctor{function}%
\begin{itemdecl}
function(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{!*this}.
\end{itemdescr}

\indexlibraryctor{function}%
\begin{itemdecl}
function(const function& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{!*this} if \tcode{!f}; otherwise,
the target object of \tcode{*this} is a copy of the target object of \tcode{f}.

\pnum
\throws
Nothing if \tcode{f}'s target is
a specialization of \tcode{reference_wrapper} or
a function pointer. Otherwise, may throw \tcode{bad_alloc}
or any exception thrown by the copy constructor of the stored callable object.

\pnum
\recommended
Implementations should avoid the use of
dynamically allocated memory for small callable objects, for example, where
\tcode{f}'s target is an object holding only a pointer or reference
to an object and a member function pointer.
\end{itemdescr}

\indexlibraryctor{function}%
\begin{itemdecl}
function(function&& f) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
If \tcode{!f}, \tcode{*this} has no target;
otherwise, the target of \tcode{*this} is equivalent to
the target of \tcode{f} before the construction, and
\tcode{f} is in a valid state with an unspecified value.

\pnum
\recommended
Implementations should avoid the use of
dynamically allocated memory for small callable objects, for example,
where \tcode{f}'s target is an object holding only a pointer or reference
to an object and a member function pointer.
\end{itemdescr}

\indexlibraryctor{function}%
\begin{itemdecl}
template<class F> function(F&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{FD} be \tcode{decay_t<F>}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_same_v<remove_cvref_t<F>, function>} is \tcode{false}, and
\item
\tcode{is_invocable_r_v<R, FD\&, ArgTypes...>} is \tcode{true}.
\end{itemize}

\pnum
\mandates
\begin{itemize}
\item
\tcode{is_copy_constructible_v<FD>} is \tcode{true}, and
\item
\tcode{is_constructible_v<FD, F>} is \tcode{true}.
\end{itemize}

\pnum
\expects
\tcode{FD} meets the \oldconcept{CopyConstructible} requirements.

\pnum
\ensures
\tcode{!*this} is \tcode{true} if any of the following hold:
\begin{itemize}
\item \tcode{f} is a null function pointer value.
\item \tcode{f} is a null member pointer value.
\item \tcode{remove_cvref_t<F>} is
a specialization of the \tcode{function} class template, and
\tcode{!f} is \tcode{true}.
\end{itemize}

\pnum
Otherwise, \tcode{*this} has a target object of type \tcode{FD}
direct-non-list-initialized with \tcode{std::forward<F>(f)}.

\pnum
\throws
Nothing if \tcode{FD} is
a specialization of \tcode{reference_wrapper} or
a function pointer type.
Otherwise, may throw \tcode{bad_alloc} or
any exception thrown by the initialization of the target object.

\pnum
\recommended
Implementations should avoid the use of
dynamically allocated memory for small callable objects, for example,
where \tcode{f} refers to an object holding only a pointer or
reference to an object and a member function pointer.
\end{itemdescr}


\begin{itemdecl}
template<class F> function(F) -> function<@\seebelow@>;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{\&F::operator()} is well-formed when treated as an unevaluated operand and either
\begin{itemize}
\item
\tcode{F::operator()} is a non-static member function and
\tcode{decltype(\brk{}\&F::operator())} is either of the form
\tcode{R(G::*)(A...)}~\cv{}~\tcode{\opt{\&}~\opt{noexcept}}
or of the form
\tcode{R(*)(G, A...)~\opt{noexcept}}
for a type \tcode{G}, or
\item
\tcode{F::operator()} is a static member function and
\tcode{decltype(\&F::operator())} is of the form
\tcode{R(*)(A...) \opt{noexcept}}.
\end{itemize}

\pnum
\remarks
The deduced type is \tcode{function<R(A...)>}.

\pnum
\begin{example}
\begin{codeblock}
void f() {
  int i{5};
  function g = [&](double) { return i; };       // deduces \tcode{function<int(double)>}
}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibrarymember{operator=}{function}%
\begin{itemdecl}
function& operator=(const function& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by \tcode{function(f).swap(*this);}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{function}%
\begin{itemdecl}
function& operator=(function&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Replaces the target of \tcode{*this}
with the target of \tcode{f}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{function}%
\begin{itemdecl}
function& operator=(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{*this != nullptr}, destroys the target of \keyword{this}.

\pnum
\ensures
\tcode{!(*this)}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{function}%
\begin{itemdecl}
template<class F> function& operator=(F&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_invocable_r_v<R, decay_t<F>\&, ArgTypes...>} is \tcode{true}.

\pnum
\effects
As if by: \tcode{function(std::forward<F>(f)).swap(*this);}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{function}%
\begin{itemdecl}
template<class F> function& operator=(reference_wrapper<F> f) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by: \tcode{function(f).swap(*this);}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarydtor{function}%
\begin{itemdecl}
~function();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{*this != nullptr}, destroys the target of \keyword{this}.
\end{itemdescr}

\rSec4[func.wrap.func.mod]{Modifiers}

\indexlibrarymember{swap}{function}%
\begin{itemdecl}
void swap(function& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Interchanges the target objects of \tcode{*this} and \tcode{other}.
\end{itemdescr}

\rSec4[func.wrap.func.cap]{Capacity}

\indexlibrarymember{operator bool}{function}%
\begin{itemdecl}
explicit operator bool() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if \tcode{*this} has a target, otherwise \tcode{false}.
\end{itemdescr}

\rSec4[func.wrap.func.inv]{Invocation}

\indexlibrary{\idxcode{function}!invocation}%
\indexlibrarymember{operator()}{function}%
\begin{itemdecl}
R operator()(ArgTypes... args) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{\placeholdernc{INVOKE}<R>(f, std::forward<ArgTypes>(args)...)}\iref{func.require},
where \tcode{f} is the target object\iref{func.def} of \tcode{*this}.

\pnum
\throws
\tcode{bad_function_call} if \tcode{!*this}; otherwise, any
exception thrown by the target object.
\end{itemdescr}

\rSec4[func.wrap.func.targ]{Target access}

\indexlibrarymember{target_type}{function}%
\begin{itemdecl}
const type_info& target_type() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If \tcode{*this} has a target of type \tcode{T},
  \tcode{typeid(T)}; otherwise, \tcode{typeid(void)}.
\end{itemdescr}

\indexlibrarymember{target}{function}%
\begin{itemdecl}
template<class T>       T* target() noexcept;
template<class T> const T* target() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If \tcode{target_type() == typeid(T)}
a pointer to the stored function target; otherwise a null pointer.
\end{itemdescr}

\rSec4[func.wrap.func.nullptr]{Null pointer comparison operator functions}

\indexlibrarymember{operator==}{function}%
\begin{itemdecl}
template<class R, class... ArgTypes>
  bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{!f}.
\end{itemdescr}

\rSec4[func.wrap.func.alg]{Specialized algorithms}

\indexlibrarymember{swap}{function}%
\begin{itemdecl}
template<class R, class... ArgTypes>
  void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by: \tcode{f1.swap(f2);}
\end{itemdescr}%

\rSec3[func.wrap.move]{Move-only wrapper}

\rSec4[func.wrap.move.general]{General}

\pnum
The header provides partial specializations of \tcode{move_only_function}
for each combination of the possible replacements
of the placeholders \cv{}, \placeholder{ref}, and \placeholder{noex} where
\begin{itemize}
\item
\cv{} is either const or empty,
\item
\placeholder{ref} is either \tcode{\&}, \tcode{\&\&}, or empty, and
\item
\placeholder{noex} is either \tcode{true} or \tcode{false}.
\end{itemize}

\pnum
For each of the possible combinations of the placeholders mentioned above,
there is a placeholder \placeholder{inv-quals} defined as follows:
\begin{itemize}
\item
If \placeholder{ref} is empty, let \placeholder{inv-quals} be \cv{}\tcode{\&},
\item
otherwise, let \placeholder{inv-quals} be \cv{} \placeholder{ref}.
\end{itemize}

\rSec4[func.wrap.move.class]{Class template \tcode{move_only_function}}

\indexlibraryglobal{move_only_function}%
\begin{codeblock}
namespace std {
  template<class R, class... ArgTypes>
  class move_only_function<R(ArgTypes...) @\cv{}@ @\placeholder{ref}@ noexcept(@\placeholder{noex}@)> {
  public:
    using result_type = R;

    // \ref{func.wrap.move.ctor}, constructors, assignment, and destructor
    move_only_function() noexcept;
    move_only_function(nullptr_t) noexcept;
    move_only_function(move_only_function&&) noexcept;
    template<class F> move_only_function(F&&);
    template<class T, class... Args>
      explicit move_only_function(in_place_type_t<T>, Args&&...);
    template<class T, class U, class... Args>
      explicit move_only_function(in_place_type_t<T>, initializer_list<U>, Args&&...);

    move_only_function& operator=(move_only_function&&);
    move_only_function& operator=(nullptr_t) noexcept;
    template<class F> move_only_function& operator=(F&&);

    ~move_only_function();

    // \ref{func.wrap.move.inv}, invocation
    explicit operator bool() const noexcept;
    R operator()(ArgTypes...) @\cv{}@ @\placeholder{ref}@ noexcept(@\placeholder{noex}@);

    // \ref{func.wrap.move.util}, utility
    void swap(move_only_function&) noexcept;
    friend void swap(move_only_function&, move_only_function&) noexcept;
    friend bool operator==(const move_only_function&, nullptr_t) noexcept;

  private:
    template<class VT>
      static constexpr bool @\exposid{is-callable-from}@ = @\seebelow@;       // \expos
  };
}
\end{codeblock}

\pnum
The \tcode{move_only_function} class template provides polymorphic wrappers
that generalize the notion of a callable object\iref{func.def}.
These wrappers can store, move, and call arbitrary callable objects,
given a call signature.

\pnum
\recommended
Implementations should avoid the use of dynamically allocated memory
for a small contained value.
\begin{note}
Such small-object optimization can only be applied to a type \tcode{T}
for which \tcode{is_nothrow_move_constructible_v<T>} is \tcode{true}.
\end{note}

\rSec4[func.wrap.move.ctor]{Constructors, assignment, and destructor}

\indextext{move_only_function::is-callable-from@\tcode{move_only_function::\exposid{is-callable-from}}}%
\begin{itemdecl}
template<class VT>
  static constexpr bool @\exposid{is-callable-from}@ = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
If \placeholder{noex} is \tcode{true},
\tcode{\exposid{is-callable-from}<VT>} is equal to:
\begin{codeblock}
is_nothrow_invocable_r_v<R, VT @\cv{}@ @\placeholder{ref}@, ArgTypes...> &&
is_nothrow_invocable_r_v<R, VT @\placeholder{inv-quals}@, ArgTypes...>
\end{codeblock}
Otherwise, \tcode{\exposid{is-callable-from}<VT>} is equal to:
\begin{codeblock}
is_invocable_r_v<R, VT @\cv{}@ @\placeholder{ref}@, ArgTypes...> &&
is_invocable_r_v<R, VT @\placeholder{inv-quals}@, ArgTypes...>
\end{codeblock}
\end{itemdescr}

\indexlibraryctor{move_only_function}%
\begin{itemdecl}
move_only_function() noexcept;
move_only_function(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{*this} has no target object.
\end{itemdescr}

\indexlibraryctor{move_only_function}%
\begin{itemdecl}
move_only_function(move_only_function&& f) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
The target object of \tcode{*this} is
the target object \tcode{f} had before construction, and
\tcode{f} is in a valid state with an unspecified value.
\end{itemdescr}

\indexlibraryctor{move_only_function}%
\begin{itemdecl}
template<class F> move_only_function(F&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<F>}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{remove_cvref_t<F>} is not the same type as \tcode{move_only_function}, and
\item
\tcode{remove_cvref_t<F>} is not a specialization of \tcode{in_place_type_t}, and
\item
\tcode{\exposid{is-callable-from}<VT>} is \tcode{true}.
\end{itemize}

\pnum
\mandates
\tcode{is_constructible_v<VT, F>} is \tcode{true}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{Destructible} requirements, and
if \tcode{is_move_constructible_v<VT>} is \tcode{true},
\tcode{VT} meets the \oldconcept{MoveConstructible} requirements.

\pnum
\ensures
\tcode{*this} has no target object if any of the following hold:
\begin{itemize}
\item
\tcode{f} is a null function pointer value, or
\item
\tcode{f} is a null member pointer value, or
\item
\tcode{remove_cvref_t<F>} is a specialization of
the \tcode{move_only_function} class template,
and \tcode{f} has no target object.
\end{itemize}
Otherwise, \tcode{*this} has a target object of type \tcode{VT}
direct-non-list-initialized with \tcode{std::forward<F>(f)}.

\pnum
\throws
Any exception thrown by the initialization of the target object.
May throw \tcode{bad_alloc} unless \tcode{VT} is
a function pointer or a specialization of \tcode{reference_wrapper}.
\end{itemdescr}

\indexlibraryctor{move_only_function}%
\begin{itemdecl}
template<class T, class... Args>
  explicit move_only_function(in_place_type_t<T>, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_constructible_v<VT, Args...>} is \tcode{true}, and
\item
\tcode{\exposid{is-callable-from}<VT>} is \tcode{true}.
\end{itemize}

\pnum
\mandates
\tcode{VT} is the same type as \tcode{T}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{Destructible} requirements, and
if \tcode{is_move_constructible_v<VT>} is \tcode{true},
\tcode{VT} meets the \oldconcept{MoveConstructible} requirements.

\pnum
\ensures
\tcode{*this} has a target object of type \tcode{VT}
direct-non-list-initialized with \tcode{std::forward<Args>\brk{}(args)...}.

\pnum
\throws
Any exception thrown by the initialization of the target object.
May throw \tcode{bad_alloc} unless \tcode{VT} is
a function pointer or a specialization of \tcode{reference_wrapper}.
\end{itemdescr}

\indexlibraryctor{move_only_function}%
\begin{itemdecl}
template<class T, class U, class... Args>
  explicit move_only_function(in_place_type_t<T>, initializer_list<U> ilist, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_constructible_v<VT, initializer_list<U>\&, Args...>} is
\tcode{true}, and
\item
\tcode{\exposid{is-callable-from}<VT>} is \tcode{true}.
\end{itemize}

\pnum
\mandates
\tcode{VT} is the same type as \tcode{T}.

\pnum
\expects
\tcode{VT} meets the \oldconcept{Destructible} requirements, and
if \tcode{is_move_constructible_v<VT>} is \tcode{true},
\tcode{VT} meets the \oldconcept{MoveConstructible} requirements.

\pnum
\ensures
\tcode{*this} has a target object of type \tcode{VT}
direct-non-list-initialized with
\tcode{ilist, std::for\-ward<Args>(args)...}.

\pnum
\throws
Any exception thrown by the initialization of the target object.
May throw \tcode{bad_alloc} unless \tcode{VT} is
a function pointer or a specialization of \tcode{reference_wrapper}.
\end{itemdescr}

\indexlibrarymember{operator=}{move_only_function}%
\begin{itemdecl}
move_only_function& operator=(move_only_function&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{move_only_function(std::move(f)).swap(*this);}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{move_only_function}%
\begin{itemdecl}
move_only_function& operator=(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys the target object of \tcode{*this}, if any.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{move_only_function}%
\begin{itemdecl}
template<class F> move_only_function& operator=(F&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{move_only_function(std::forward<F>(f)).swap(*this);}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarydtor{move_only_function}%
\begin{itemdecl}
~move_only_function();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys the target object of \tcode{*this}, if any.
\end{itemdescr}

\rSec4[func.wrap.move.inv]{Invocation}

\indexlibrarymember{operator bool}{move_only_function}%
\begin{itemdecl}
explicit operator bool() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if \tcode{*this} has a target object, otherwise \tcode{false}.
\end{itemdescr}

\indexlibrarymember{operator()}{move_only_function}%
\begin{itemdecl}
R operator()(ArgTypes... args) @\cv{}@ @\placeholder{ref}@ noexcept(@\placeholder{noex}@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{*this} has a target object.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return @\placeholder{INVOKE}@<R>(static_cast<F @\placeholder{inv-quals}@>(f), std::forward<ArgTypes>(args)...);
\end{codeblock}
where \tcode{f} is an lvalue designating the target object of \tcode{*this} and
\tcode{F} is the type of \tcode{f}.
\end{itemdescr}

\rSec4[func.wrap.move.util]{Utility}

\indexlibrarymember{swap}{move_only_function}%
\begin{itemdecl}
void swap(move_only_function& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Exchanges the target objects of \tcode{*this} and \tcode{other}.
\end{itemdescr}

\indexlibrarymember{swap}{move_only_function}%
\begin{itemdecl}
friend void swap(move_only_function& f1, move_only_function& f2) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{f1.swap(f2)}.
\end{itemdescr}

\indexlibrarymember{operator==}{move_only_function}%
\begin{itemdecl}
friend bool operator==(const move_only_function& f, nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if \tcode{f} has no target object, otherwise \tcode{false}.
\end{itemdescr}

\rSec3[func.wrap.copy]{Copyable wrapper}

\rSec4[func.wrap.copy.general]{General}

\pnum
The header provides partial specializations of \tcode{copyable_function}
for each combination of the possible replacements
of the placeholders \cv{}, \placeholder{ref}, and \placeholder{noex} where
\begin{itemize}
\item
\cv{} is either const or empty,
\item
\placeholder{ref} is either \tcode{\&}, \tcode{\&\&}, or empty, and
\item
\placeholder{noex} is either \tcode{true} or \tcode{false}.
\end{itemize}

\pnum
For each of the possible combinations of the placeholders mentioned above,
there is a placeholder \placeholder{inv-quals} defined as follows:
\begin{itemize}
\item
If \placeholder{ref} is empty, let \placeholder{inv-quals} be \cv{}\tcode{\&},
\item
otherwise, let \placeholder{inv-quals} be \cv{} \placeholder{ref}.
\end{itemize}

\rSec4[func.wrap.copy.class]{Class template \tcode{copyable_function}}

\indexlibraryglobal{copyable_function}%
\begin{codeblock}
namespace std {
  template<class R, class... ArgTypes>
  class copyable_function<R(ArgTypes...) @\cv{}@ @\placeholder{ref}@ noexcept(@\placeholder{noex}@)> {
  public:
    using result_type = R;

    // \ref{func.wrap.copy.ctor}, constructors, assignments, and destructors
    copyable_function() noexcept;
    copyable_function(nullptr_t) noexcept;
    copyable_function(const copyable_function&);
    copyable_function(copyable_function&&) noexcept;
    template<class F> copyable_function(F&&);
    template<class T, class... Args>
      explicit copyable_function(in_place_type_t<T>, Args&&...);
    template<class T, class U, class... Args>
      explicit copyable_function(in_place_type_t<T>, initializer_list<U>, Args&&...);

    copyable_function& operator=(const copyable_function&);
    copyable_function& operator=(copyable_function&&);
    copyable_function& operator=(nullptr_t) noexcept;
    template<class F> copyable_function& operator=(F&&);

    ~copyable_function();

    // \ref{func.wrap.copy.inv}, invocation
    explicit operator bool() const noexcept;
    R operator()(ArgTypes...) @\cv{}@ @\placeholder{ref}@ noexcept(@\placeholder{noex}@);

    // \ref{func.wrap.copy.util}, utility
    void swap(copyable_function&) noexcept;
    friend void swap(copyable_function&, copyable_function&) noexcept;
    friend bool operator==(const copyable_function&, nullptr_t) noexcept;

  private:
    template<class VT>
      static constexpr bool @\exposid{is-callable-from}@ = @\seebelow@;       // \expos
  };
}
\end{codeblock}

\pnum
The \tcode{copyable_function} class template provides polymorphic wrappers
that generalize the notion of a callable object\iref{func.def}.
These wrappers can store, copy, move, and call arbitrary callable objects,
given a call signature.

\pnum
\recommended
Implementations should avoid the use of dynamically allocated memory
for a small contained value.
\begin{note}
Such small-object optimization can only be applied to a type \tcode{T}
for which \tcode{is_nothrow_move_constructible_v<T>} is \tcode{true}.
\end{note}

\rSec4[func.wrap.copy.ctor]{Constructors, assignments, and destructors}

\indextext{copyable_function::is-callable-from@\tcode{copyable_function::\exposid{is-callable-from}}}%
\begin{itemdecl}
template<class VT>
  static constexpr bool @\exposid{is-callable-from}@ = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
If \placeholder{noex} is \tcode{true},
\tcode{\exposid{is-callable-from}<VT>} is equal to:
\begin{codeblock}
is_nothrow_invocable_r_v<R, VT @\cv{}@ @\placeholder{ref}@, ArgTypes...> &&
is_nothrow_invocable_r_v<R, VT @\placeholder{inv-quals}@, ArgTypes...>
\end{codeblock}
Otherwise, \tcode{\exposid{is-callable-from}<VT>} is equal to:
\begin{codeblock}
is_invocable_r_v<R, VT @\cv{}@ @\placeholder{ref}@, ArgTypes...> &&
is_invocable_r_v<R, VT @\placeholder{inv-quals}@, ArgTypes...>
\end{codeblock}
\end{itemdescr}

\indexlibraryctor{copyable_function}%
\begin{itemdecl}
copyable_function() noexcept;
copyable_function(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{*this} has no target object.
\end{itemdescr}

\indexlibraryctor{copyable_function}%
\begin{itemdecl}
copyable_function(const copyable_function& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{*this} has no target object if \tcode{f} had no target object.
Otherwise, the target object of \tcode{*this}
is a copy of the target object of \tcode{f}.

\pnum
\throws
Any exception thrown by the initialization of the target object.
May throw \tcode{bad_alloc}.
\end{itemdescr}

\indexlibraryctor{copyable_function}%
\begin{itemdecl}
copyable_function(copyable_function&& f) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
The target object of \tcode{*this} is
the target object \tcode{f} had before construction, and
\tcode{f} is in a valid state with an unspecified value.
\end{itemdescr}

\indexlibraryctor{copyable_function}%
\begin{itemdecl}
template<class F> copyable_function(F&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<F>}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{remove_cvref_t<F>} is not the same type as \tcode{copyable_function}, and
\item
\tcode{remove_cvref_t<F>} is not a specialization of \tcode{in_place_type_t}, and
\item
\tcode{\exposid{is-callable-from}<VT>} is \tcode{true}.
\end{itemize}

\pnum
\mandates
\begin{itemize}
\item
\tcode{is_constructible_v<VT, F>} is \tcode{true}, and
\item
\tcode{is_copy_constructible_v<VT>} is \tcode{true}.
\end{itemize}

\pnum
\expects
\tcode{VT} meets the \oldconcept{Destructible} and
\oldconcept{CopyConstructible} requirements.

\pnum
\ensures
\tcode{*this} has no target object if any of the following hold:
\begin{itemize}
\item
\tcode{f} is a null function pointer value, or
\item
\tcode{f} is a null member pointer value, or
\item
\tcode{remove_cvref_t<F>} is a specialization of
the \tcode{copyable_function} class template,
and \tcode{f} has no target object.
\end{itemize}
Otherwise, \tcode{*this} has a target object of type \tcode{VT}
direct-non-list-initialized with \tcode{std::forward<F>(f)}.

\pnum
\throws
Any exception thrown by the initialization of the target object.
May throw \tcode{bad_alloc} unless \tcode{VT} is
a function pointer or a specialization of \tcode{reference_wrapper}.
\end{itemdescr}

\indexlibraryctor{copyable_function}%
\begin{itemdecl}
template<class T, class... Args>
  explicit copyable_function(in_place_type_t<T>, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_constructible_v<VT, Args...>} is \tcode{true}, and
\item
\tcode{\exposid{is-callable-from}<VT>} is \tcode{true}.
\end{itemize}

\pnum
\mandates
\begin{itemize}
\item
\tcode{VT} is the same type as \tcode{T}, and
\item
\tcode{is_copy_constructible_v<VT>} is \tcode{true}.
\end{itemize}

\pnum
\expects
\tcode{VT} meets the \oldconcept{Destructible} and
\oldconcept{CopyConstructible} requirements.

\pnum
\ensures
\tcode{*this} has a target object of type \tcode{VT}
direct-non-list-initialized with \tcode{std::forward<Args>\brk{}(args)...}.

\pnum
\throws
Any exception thrown by the initialization of the target object.
May throw \tcode{bad_alloc} unless \tcode{VT} is
a pointer or a specialization of \tcode{reference_wrapper}.
\end{itemdescr}

\indexlibraryctor{copyable_function}%
\begin{itemdecl}
template<class T, class U, class... Args>
  explicit copyable_function(in_place_type_t<T>, initializer_list<U> ilist, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{VT} be \tcode{decay_t<T>}.

\pnum
\constraints
\begin{itemize}
\item
\tcode{is_constructible_v<VT, initializer_list<U>\&, Args...>} is
\tcode{true}, and
\item
\tcode{\exposid{is-callable-from}<VT>} is \tcode{true}.
\end{itemize}

\pnum
\mandates
\begin{itemize}
\item
\tcode{VT} is the same type as \tcode{T}, and
\item
\tcode{is_copy_constructible_v<VT>} is \tcode{true}.
\end{itemize}

\pnum
\expects
\tcode{VT} meets the \oldconcept{Destructible} and
\oldconcept{CopyConstructible} requirements.

\pnum
\ensures
\tcode{*this} has a target object of type \tcode{VT}
direct-non-list-initialized with
\tcode{ilist, std::for\-ward<Args>(args)...}.

\pnum
\throws
Any exception thrown by the initialization of the target object.
May throw \tcode{bad_alloc} unless \tcode{VT} is
a pointer or a specialization of \tcode{reference_wrapper}.
\end{itemdescr}

\indexlibrarymember{operator=}{copyable_function}%
\begin{itemdecl}
copyable_function& operator=(const copyable_function& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{copyable_function(f).swap(*this);}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{copyable_function}%
\begin{itemdecl}
copyable_function& operator=(copyable_function&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{copyable_function(std::move(f)).swap(*this);}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{copyable_function}%
\begin{itemdecl}
copyable_function& operator=(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys the target object of \tcode{*this}, if any.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarymember{operator=}{copyable_function}%
\begin{itemdecl}
template<class F> copyable_function& operator=(F&& f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{copyable_function(std::forward<F>(f)).swap(*this);}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrarydtor{copyable_function}%
\begin{itemdecl}
~copyable_function();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys the target object of \tcode{*this}, if any.
\end{itemdescr}

\rSec4[func.wrap.copy.inv]{Invocation}

\indexlibrarymember{operator bool}{copyable_function}%
\begin{itemdecl}
explicit operator bool() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if \tcode{*this} has a target object, otherwise \tcode{false}.
\end{itemdescr}

\indexlibrarymember{operator()}{copyable_function}%
\begin{itemdecl}
R operator()(ArgTypes... args) @\cv{}@ @\placeholder{ref}@ noexcept(@\placeholder{noex}@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{*this} has a target object.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return @\placeholder{INVOKE}@<R>(static_cast<F @\placeholder{inv-quals}@>(f), std::forward<ArgTypes>(args)...);
\end{codeblock}
where \tcode{f} is an lvalue designating the target object of \tcode{*this} and
\tcode{F} is the type of \tcode{f}.
\end{itemdescr}

\rSec4[func.wrap.copy.util]{Utility}

\indexlibrarymember{swap}{copyable_function}%
\begin{itemdecl}
void swap(copyable_function& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Exchanges the target objects of \tcode{*this} and \tcode{other}.
\end{itemdescr}

\indexlibrarymember{swap}{copyable_function}%
\begin{itemdecl}
friend void swap(copyable_function& f1, copyable_function& f2) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{f1.swap(f2)}.
\end{itemdescr}

\indexlibrarymember{operator==}{copyable_function}%
\begin{itemdecl}
friend bool operator==(const copyable_function& f, nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if \tcode{f} has no target object, otherwise \tcode{false}.
\end{itemdescr}

\rSec3[func.wrap.ref]{Non-owning wrapper}

\rSec4[func.wrap.ref.general]{General}

\pnum
The header provides partial specializations of \tcode{function_ref}
for each combination of the possible replacements of
the placeholders \cv{} and \placeholder{noex} where:

\begin{itemize}
\item \cv{} is either const or empty, and
\item \placeholder{noex} is either \tcode{true} or \tcode{false}.
\end{itemize}

\rSec4[func.wrap.ref.class]{Class template \tcode{function_ref}}

\indexlibraryglobal{function_ref}%
\begin{codeblock}
namespace std {
  template<class R, class... ArgTypes>
  class function_ref<R(ArgTypes...) @\cv{}@ noexcept(@\placeholder{noex}@)> {
  public:
    // \ref{func.wrap.ref.ctor}, constructors and assignment operators
    template<class F> function_ref(F*) noexcept;
    template<class F> constexpr function_ref(F&&) noexcept;
    template<auto f> constexpr function_ref(nontype_t<f>) noexcept;
    template<auto f, class U> constexpr function_ref(nontype_t<f>, U&&) noexcept;
    template<auto f, class T> constexpr function_ref(nontype_t<f>, @\cv{}@ T*) noexcept;

    constexpr function_ref(const function_ref&) noexcept = default;
    constexpr function_ref& operator=(const function_ref&) noexcept = default;
    template<class T> function_ref& operator=(T) = delete;

    // \ref{func.wrap.ref.inv}, invocation
    R operator()(ArgTypes...) const noexcept(@\placeholder{noex}@);

  private:
    template<class... T>
      static constexpr bool @\exposidnc{is-invocable-using}@ = @\seebelownc@;     // \expos

    R (*@\exposidnc{thunk-ptr}@)(@\exposidnc{BoundEntityType}@, Args&&...) noexcept(@\placeholdernc{noex}@);  // \expos
    @\exposidnc{BoundEntityType}@ @\exposidnc{bound-entity}@;                               // \expos
  };

  // \ref{func.wrap.ref.deduct}, deduction guides
  template<class F>
    function_ref(F*) -> function_ref<F>;
  template<auto f>
    function_ref(nontype_t<f>) -> function_ref<@\seebelow@>;
  template<auto f, class T>
    function_ref(nontype_t<f>, T&&) -> function_ref<@\seebelow@>;
}
\end{codeblock}

\pnum
An object of class
\tcode{function_ref<R(Args...) \cv{} noexcept(\placeholder{noex})>}
stores a pointer to function \exposid{thunk-ptr} and
an object \exposid{bound-entity}.
\exposid{bound-entity} has
an unspecified trivially copyable type \exposid{BoundEntityType}, that
models \libconcept{copyable} and
is capable of storing a pointer to object value or a pointer to function value.
The type of \exposid{thunk-ptr} is
\tcode{R(*)(\exposidnc{BoundEntityType}, Args\&\&...) noexcept(\placeholder{noex})}.

\pnum
Each specialization of \tcode{function_ref} is
a trivially copyable type\iref{term.trivially.copyable.type}
that models \libconcept{copyable}.

\pnum
Within \ref{func.wrap.ref},
\tcode{\placeholder{call-args}} is an argument pack with elements such that
\tcode{decltype((\placeholder{call-args}\linebreak{}))...} denote
\tcode{Args\&\&...} respectively.

\rSec4[func.wrap.ref.ctor]{Constructors and assignment operators}

\indextext{function_ref::is-invocable-using@\tcode{function_ref::\exposid{is-invocable-using}}}%
\begin{itemdecl}
template<class... T>
  static constexpr bool @\exposid{is-invocable-using}@ = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
If \placeholder{noex} is \tcode{true},
\tcode{\exposid{is-invocable-using}<T...>} is equal to:
\begin{codeblock}
is_nothrow_invocable_r_v<R, T..., ArgTypes...>
\end{codeblock}
Otherwise, \tcode{\exposid{is-invocable-using}<T...>} is equal to:
\begin{codeblock}
is_invocable_r_v<R, T..., ArgTypes...>
\end{codeblock}
\end{itemdescr}

\indexlibraryctor{function_ref}%
\begin{itemdecl}
template<class F> function_ref(F* f) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_function_v<F>} is \tcode{true}, and
\item \tcode{\exposid{is-invocable-using}<F>} is \tcode{true}.
\end{itemize}

\pnum
\expects
\tcode{f} is not a null pointer.

\pnum
\effects
Initializes
\exposid{bound-entity} with \tcode{f}, and
\exposid{thunk-ptr} with the address of a function \tcode{\placeholder{thunk}}
such that
\tcode{\placeholder{thunk}(\exposid{bound-entity}, \placeholder{call-args}...)}
is expression-equivalent\iref{defns.expression.equivalent} to
\tcode{invoke_r<R>(f, \placeholder{call-args}...)}.
\end{itemdescr}

\indexlibraryctor{function_ref}%
\begin{itemdecl}
template<class F> constexpr function_ref(F&& f) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{T} be \tcode{remove_reference_t<F>}.

\pnum
\constraints
\begin{itemize}
\item \tcode{remove_cvref_t<F>} is not the same type as \tcode{function_ref},
\item \tcode{is_member_pointer_v<T>} is \tcode{false}, and
\item \tcode{\exposid{is-invocable-using}<\cv{} T\&>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Initializes
\exposid{bound-entity} with \tcode{addressof(f)}, and
\exposid{thunk-ptr} with the address of a function \tcode{\placeholder{thunk}}
such that
\tcode{\placeholder{thunk}(\exposid{bound-entity}, \placeholder{call-args}...)}
is expression-equivalent\iref{defns.expression.equivalent} to
\tcode{invoke_r<R>(static_cast<\cv{} T\&>(f), \placeholder{call-args}...)}.
\end{itemdescr}

\indexlibraryctor{function_ref}%
\begin{itemdecl}
template<auto f> constexpr function_ref(nontype_t<f>) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{F} be \tcode{decltype(f)}.

\pnum
\constraints
\tcode{\exposid{is-invocable-using}<F>} is \tcode{true}.

\pnum
\mandates
If \tcode{is_pointer_v<F> || is_member_pointer_v<F>} is \tcode{true},
then \tcode{f != nullptr} is \tcode{true}.

\pnum
\effects
Initializes
\exposid{bound-entity} with a pointer to an unspecified object or
null pointer value, and
\exposid{thunk-ptr} with the address of a function \tcode{\placeholder{thunk}}
such that
\tcode{\placeholder{thunk}(\exposid{bound-entity}, \placeholder{call-args}...)}
is expression-equivalent\iref{defns.expression.equivalent} to
\tcode{invoke_r<R>(f, \placeholder{call-args}...)}.
\end{itemdescr}

\indexlibraryctor{function_ref}%
\begin{itemdecl}
template<auto f, class U>
  constexpr function_ref(nontype_t<f>, U&& obj) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{T} be \tcode{remove_reference_t<U>} and
\tcode{F} be \tcode{decltype(f)}.

\pnum
\constraints
\begin{itemize}
\item \tcode{is_rvalue_reference_v<U\&\&>} is \tcode{false}, and
\item \tcode{\exposid{is-invocable-using}<F, \cv{} T\&>} is \tcode{true}.
\end{itemize}

\pnum
\mandates
If \tcode{is_pointer_v<F> || is_member_pointer_v<F>} is \tcode{true},
then \tcode{f != nullptr} is \tcode{true}.

\pnum
\effects
Initializes
\exposid{bound-entity} with \tcode{addressof(obj)}, and
\exposid{thunk-ptr} with the address of a function \tcode{\placeholder{thunk}}
such that
\tcode{\placeholder{thunk}(\exposid{bound-entity}, \placeholder{call-args}...)}
is expression-equivalent\iref{defns.expression.equivalent} to
\tcode{invoke_r<R>(f, static_cast<\cv{} T\&>(obj), \placeholder{call-args}...)}.
\end{itemdescr}

\indexlibraryctor{function_ref}%
\begin{itemdecl}
template<auto f, class T>
  constexpr function_ref(nontype_t<f>, @\cv{}@ T* obj) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{F} be \tcode{decltype(f)}.

\pnum
\constraints
\tcode{\exposid{is-invocable-using}<F, \cv{} T*>} is \tcode{true}.

\pnum
\mandates
If \tcode{is_pointer_v<F> || is_member_pointer_v<F>} is \tcode{true},
then \tcode{f != nullptr} is \tcode{true}.

\pnum
\expects
If \tcode{is_member_pointer_v<F>} is \tcode{true},
\tcode{obj} is not a null pointer.

\pnum
\effects
Initializes
\exposid{bound-entity} with \tcode{obj}, and
\exposid{thunk-ptr} with the address of a function \tcode{\placeholder{thunk}}
such that
\tcode{\placeholder{thunk}(\exposid{bound-entity}, \placeholder{call-args}...)}
is expression-equivalent\iref{defns.expression.equivalent} to
\tcode{invoke_r<R>(f, obj, \placeholder{call-args}...)}.
\end{itemdescr}

\indexlibrarymember{operator=}{function_ref}%
\begin{itemdecl}
template<class T> function_ref& operator=(T) = delete;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{T} is not the same type as \tcode{function_ref},
\item \tcode{is_pointer_v<T>} is \tcode{false}, and
\item \tcode{T} is not a specialization of \tcode{nontype_t}.
\end{itemize}
\end{itemdescr}

\rSec4[func.wrap.ref.inv]{Invocation}

\indexlibrarymember{operator()}{function_ref}%
\begin{itemdecl}
R operator()(ArgTypes... args) const noexcept(@\placeholder{noex}@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\tcode{return \exposid{thunk-ptr}(\exposid{bound-entity}, std::forward<ArgTypes>(args)...);}
\end{itemdescr}

\rSec4[func.wrap.ref.deduct]{Deduction guides}

\begin{itemdecl}
template<class F>
  function_ref(F*) -> function_ref<F>;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_function_v<F>} is \tcode{true}.
\end{itemdescr}

\begin{itemdecl}
template<auto f>
  function_ref(nontype_t<f>) -> function_ref<@\seebelow@>;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{F} be \tcode{remove_pointer_t<decltype(f)>}.

\pnum
\constraints
\tcode{is_function_v<F>} is \tcode{true}.

\pnum
\remarks
The deduced type is \tcode{function_ref<F>}.
\end{itemdescr}

\begin{itemdecl}
template<auto f, class T>
  function_ref(nontype_t<f>, T&&) -> function_ref<@\seebelow@>;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{F} be \tcode{decltype(f)}.

\pnum
\constraints
%FIXME: R and E should be defined outside of these constraints.
%FIXME: Define R and E via "let" in paragraph above, then use them here and below.
\begin{itemize}
\item
\tcode{F} is of the form
\tcode{R(G::*)(A...) \cv{} \opt{\&} noexcept(E)} for a type \tcode{G}, or
\item
\tcode{F} is of the form
\tcode{M G::*} for a type \tcode{G} and an object type \tcode{M},
in which case
let \tcode{R} be \tcode{invoke_result_t<F, T\&>},
\tcode{A...} be an empty pack, and
\tcode{E} be \tcode{false}, or
\item
\tcode{F} is of the form
\tcode{R(*)(G, A...) noexcept(E)} for a type \tcode{G}.
\end{itemize}

\pnum
\remarks
The deduced type is \tcode{function_ref<R(A...) noexcept(E)>}.
\end{itemdescr}
\indextext{function object!wrapper|)}

\rSec2[func.search]{Searchers}

\rSec3[func.search.general]{General}

\pnum
Subclause \ref{func.search} provides function object types\iref{function.objects} for
operations that search for a sequence \range{pat\textunderscore\nobreak first}{pat_last} in another
sequence \range{first}{last} that is provided to the object's function call
operator.  The first sequence (the pattern to be searched for) is provided to
the object's constructor, and the second (the sequence to be searched) is
provided to the function call operator.

\pnum
Each specialization of a class template specified in \ref{func.search}
shall meet the \oldconcept{CopyConst\-ruct\-ible} and \oldconcept{CopyAssignable} requirements.
Template parameters named
\begin{itemize}
\item \tcode{ForwardIterator},
\item \tcode{ForwardIterator1},
\item \tcode{ForwardIterator2},
\item \tcode{RandomAccessIterator},
\item \tcode{RandomAccessIterator1},
\item \tcode{RandomAccessIterator2}, and
\item \tcode{BinaryPredicate}
\end{itemize}
of templates specified in
\ref{func.search} shall meet the same requirements and semantics as
specified in \ref{algorithms.general}.
Template parameters named \tcode{Hash} shall meet the \oldconcept{Hash}
requirements (\tref{cpp17.hash}).

\pnum
The Boyer-Moore searcher implements the Boyer-Moore search algorithm.
The Boyer-Moore-Horspool searcher implements the Boyer-Moore-Horspool search algorithm.
In general, the Boyer-Moore searcher will use more memory and give better runtime performance than Boyer-Moore-Horspool.

\rSec3[func.search.default]{Class template \tcode{default_searcher}}

\indexlibraryglobal{default_searcher}%
\begin{codeblock}
namespace std {
  template<class ForwardIterator1, class BinaryPredicate = equal_to<>>
  class default_searcher {
  public:
    constexpr default_searcher(ForwardIterator1 pat_first, ForwardIterator1 pat_last,
                               BinaryPredicate pred = BinaryPredicate());

    template<class ForwardIterator2>
      constexpr pair<ForwardIterator2, ForwardIterator2>
        operator()(ForwardIterator2 first, ForwardIterator2 last) const;

  private:
    ForwardIterator1 pat_first_;        // \expos
    ForwardIterator1 pat_last_;         // \expos
    BinaryPredicate pred_;              // \expos
  };
}
\end{codeblock}

\indexlibraryctor{default_searcher}%
\begin{itemdecl}
constexpr default_searcher(ForwardIterator1 pat_first, ForwardIterator1 pat_last,
                           BinaryPredicate pred = BinaryPredicate());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
% FIXME: The mbox prevents TeX from adding a bizarre hyphen after pat_last_.
Constructs a \tcode{default_searcher} object, initializing \tcode{pat_first_}
with \tcode{pat_first}, \mbox{\tcode{pat_last_}} with \tcode{pat_last}, and
\tcode{pred_} with \tcode{pred}.

\pnum
\throws
Any exception thrown by the copy constructor of \tcode{BinaryPredicate} or
\tcode{ForwardIterator1}.
\end{itemdescr}

\indexlibrarymember{operator()}{default_searcher}%
\begin{itemdecl}
template<class ForwardIterator2>
  constexpr pair<ForwardIterator2, ForwardIterator2>
    operator()(ForwardIterator2 first, ForwardIterator2 last) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Returns a pair of iterators \tcode{i} and \tcode{j} such that
\begin{itemize}
\item \tcode{i == search(first, last, pat_first_, pat_last_, pred_)}, and
\item if \tcode{i == last}, then \tcode{j == last},
otherwise \tcode{j == next(i, distance(pat_first_, pat_last_))}.
\end{itemize}
\end{itemdescr}

\rSec3[func.search.bm]{Class template \tcode{boyer_moore_searcher}}

\indexlibraryglobal{boyer_moore_searcher}%
\begin{codeblock}
namespace std {
  template<class RandomAccessIterator1,
           class Hash = hash<typename iterator_traits<RandomAccessIterator1>::value_type>,
           class BinaryPredicate = equal_to<>>
  class boyer_moore_searcher {
  public:
    boyer_moore_searcher(RandomAccessIterator1 pat_first,
                         RandomAccessIterator1 pat_last,
                         Hash hf = Hash(),
                         BinaryPredicate pred = BinaryPredicate());

    template<class RandomAccessIterator2>
      pair<RandomAccessIterator2, RandomAccessIterator2>
        operator()(RandomAccessIterator2 first, RandomAccessIterator2 last) const;

  private:
    RandomAccessIterator1 pat_first_;   // \expos
    RandomAccessIterator1 pat_last_;    // \expos
    Hash hash_;                         // \expos
    BinaryPredicate pred_;              // \expos
  };
}
\end{codeblock}

\indexlibraryctor{boyer_moore_searcher}%
\begin{itemdecl}
boyer_moore_searcher(RandomAccessIterator1 pat_first,
                     RandomAccessIterator1 pat_last,
                     Hash hf = Hash(),
                     BinaryPredicate pred = BinaryPredicate());
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
The value type of \tcode{RandomAccessIterator1} meets
the \oldconcept{DefaultConstructible},
\oldconcept{CopyConstructible}, and
\oldconcept{CopyAssignable} requirements.

\pnum
Let \tcode{V} be \tcode{iterator_traits<RandomAccessIterator1>::val\-ue_type}.
For any two values \tcode{A} and \tcode{B} of type \tcode{V},
if \tcode{pred(A, B) == true}, then \tcode{hf(A) == hf(B)} is \tcode{true}.

\pnum
\effects
Initializes
\tcode{pat_first_} with \tcode{pat_first},
\tcode{pat_last_} with \tcode{pat_last},
\tcode{hash_} with \tcode{hf}, and
% FIXME: The mbox prevents TeX from adding a bizarre hyphen after pred_.
\mbox{\tcode{pred_}} with \tcode{pred}.

\pnum
\throws
Any exception thrown by the copy constructor of \tcode{RandomAccessIterator1},
or by the default constructor, copy constructor, or the copy assignment operator of the value type of \tcode{RandomAccess\-Iterator1},
or the copy constructor or \tcode{operator()} of \tcode{BinaryPredicate} or \tcode{Hash}.
May throw \tcode{bad_alloc} if additional memory needed for internal data structures cannot be allocated.
\end{itemdescr}

\indexlibrarymember{operator()}{boyer_moore_searcher}%
\begin{itemdecl}
template<class RandomAccessIterator2>
  pair<RandomAccessIterator2, RandomAccessIterator2>
    operator()(RandomAccessIterator2 first, RandomAccessIterator2 last) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{RandomAccessIterator1} and \tcode{RandomAccessIterator2}
have the same value type.

\pnum
\effects
Finds a subsequence of equal values in a sequence.

\pnum
\returns
A pair of iterators \tcode{i} and \tcode{j} such that
\begin{itemize}
\item \tcode{i} is the first iterator
in the range \range{first}{last - (pat_last_ - pat_first_)} such that
for every non-negative integer \tcode{n} less than \tcode{pat_last_ - pat_first_}
the following condition holds:
\tcode{pred(*(i + n), *(pat_first_ + n)) != false}, and
\item \tcode{j == next(i, distance(pat_first_, pat_last_))}.
\end{itemize}
Returns \tcode{make_pair(first, first)} if \range{pat_first_}{pat_last_} is empty,
otherwise returns \tcode{make_pair(last, last)} if no such iterator is found.

\pnum
\complexity
At most \tcode{(last - first) * (pat_last_ - pat_first_)} applications of the predicate.
\end{itemdescr}

\rSec3[func.search.bmh]{Class template \tcode{boyer_moore_horspool_searcher}}

\indexlibraryglobal{boyer_moore_horspool_searcher}%
\begin{codeblock}
namespace std {
  template<class RandomAccessIterator1,
           class Hash = hash<typename iterator_traits<RandomAccessIterator1>::value_type>,
           class BinaryPredicate = equal_to<>>
  class boyer_moore_horspool_searcher {
  public:
    boyer_moore_horspool_searcher(RandomAccessIterator1 pat_first,
                                  RandomAccessIterator1 pat_last,
                                  Hash hf = Hash(),
                                  BinaryPredicate pred = BinaryPredicate());

    template<class RandomAccessIterator2>
      pair<RandomAccessIterator2, RandomAccessIterator2>
        operator()(RandomAccessIterator2 first, RandomAccessIterator2 last) const;

  private:
    RandomAccessIterator1 pat_first_;   // \expos
    RandomAccessIterator1 pat_last_;    // \expos
    Hash hash_;                         // \expos
    BinaryPredicate pred_;              // \expos
  };
}
\end{codeblock}

\indexlibraryctor{boyer_moore_horspool_searcher}%
\begin{itemdecl}
boyer_moore_horspool_searcher(RandomAccessIterator1 pat_first,
                              RandomAccessIterator1 pat_last,
                              Hash hf = Hash(),
                              BinaryPredicate pred = BinaryPredicate());
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
The value type of \tcode{RandomAccessIterator1} meets the \oldconcept{DefaultConstructible},
\oldconcept{Copy\-Constructible}, and \oldconcept{CopyAssignable} requirements.

\pnum
Let \tcode{V} be \tcode{iterator_traits<RandomAccessIterator1>::val\-ue_type}.
For any two values \tcode{A} and \tcode{B} of type \tcode{V},
if \tcode{pred(A, B) == true}, then \tcode{hf(A) == hf(B)} is \tcode{true}.

\pnum
\effects
Initializes
\tcode{pat_first_} with \tcode{pat_first},
\tcode{pat_last_} with \tcode{pat_last},
\tcode{hash_} with \tcode{hf}, and
% FIXME: The mbox prevents TeX from adding a bizarre hyphen after pred_.
\mbox{\tcode{pred_}} with \tcode{pred}.

\pnum
\throws
Any exception thrown by the copy constructor of \tcode{RandomAccessIterator1},
or by the default constructor, copy constructor, or the copy assignment operator of the value type of \tcode{RandomAccess\-Iterator1},
or the copy constructor or \tcode{operator()} of \tcode{BinaryPredicate} or \tcode{Hash}.
May throw \tcode{bad_alloc} if additional memory needed for internal data structures cannot be allocated.
\end{itemdescr}

\indexlibrarymember{operator()}{boyer_moore_horspool_searcher}%
\begin{itemdecl}
template<class RandomAccessIterator2>
  pair<RandomAccessIterator2, RandomAccessIterator2>
    operator()(RandomAccessIterator2 first, RandomAccessIterator2 last) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{RandomAccessIterator1} and \tcode{RandomAccessIterator2}
have the same value type.

\pnum
\effects
Finds a subsequence of equal values in a sequence.

\pnum
\returns
A pair of iterators \tcode{i} and \tcode{j} such that
\begin{itemize}
\item \tcode{i} is the first iterator in the range
\range{first}{last - (pat_last_ - pat_first_)} such that
for every non-negative integer \tcode{n} less than \tcode{pat_last_ - pat_first_}
the following condition holds:
\tcode{pred(*(i + n), *(pat_first_ + n)) != false}, and
\item \tcode{j == next(i, distance(pat_first_, pat_last_))}.
\end{itemize}
Returns \tcode{make_pair(first, first)} if \range{pat_first_}{pat_last_} is empty,
otherwise returns \tcode{make_pair(last, last)} if no such iterator is found.

\pnum
\complexity
At most \tcode{(last - first) * (pat_last_ - pat_first_)} applications of the predicate.
\end{itemdescr}

\rSec2[unord.hash]{Class template \tcode{hash}}

\pnum
\indexlibraryglobal{hash}%
\indextext{\idxcode{hash}!instantiation restrictions}%
The unordered associative containers defined in \ref{unord} use
specializations of the class template \tcode{hash}\iref{functional.syn}
as the default hash function.

\pnum
Each specialization of \tcode{hash} is either enabled or disabled,
as described below.
\begin{note}
Enabled specializations meet the \oldconcept{Hash} requirements, and
disabled specializations do not.
\end{note}
Each header that declares the template \tcode{hash}
provides enabled specializations of \tcode{hash} for \tcode{nullptr_t} and
all cv-unqualified arithmetic, enumeration, and pointer types.
For any type \tcode{Key} for which neither the library nor the user provides
an explicit or partial specialization of the class template \tcode{hash},
\tcode{hash<Key>} is disabled.

\pnum
If the library provides an explicit or partial specialization of \tcode{hash<Key>},
that specialization is enabled except as noted otherwise,
and its member functions are \keyword{noexcept} except as noted otherwise.

\pnum
If \tcode{H} is a disabled specialization of \tcode{hash},
these values are \tcode{false}:
\tcode{is_default_constructible_v<H>},
\tcode{is_copy_constructible_v<H>},
\tcode{is_move_constructible_v<H>},
\tcode{is_copy_assignable_v<H>}, and
\tcode{is_move_assignable_v<H>}.
Disabled specializations of \tcode{hash}
are not function object types\iref{function.objects}.
\begin{note}
This means that the specialization of \tcode{hash} exists, but
any attempts to use it as a \oldconcept{Hash} will be ill-formed.
\end{note}

\pnum
An enabled specialization \tcode{hash<Key>} will:
\begin{itemize}
\item meet the \oldconcept{Hash} requirements (\tref{cpp17.hash}),
with \tcode{Key} as the function
call argument type, the \oldconcept{Default\-Constructible} requirements (\tref{cpp17.defaultconstructible}),
the \oldconcept{CopyAssignable} requirements (\tref{cpp17.copyassignable}),
the \oldconcept{Swappable} requirements\iref{swappable.requirements},
\item meet the requirement that if \tcode{k1 == k2} is \tcode{true}, \tcode{h(k1) == h(k2)} is
also \tcode{true}, where \tcode{h} is an object of type \tcode{hash<Key>} and \tcode{k1} and \tcode{k2}
are objects of type \tcode{Key};
\item meet the requirement that the expression \tcode{h(k)}, where \tcode{h}
is an object of type \tcode{hash<Key>} and \tcode{k} is an object of type
\tcode{Key}, shall not throw an exception unless \tcode{hash<Key>} is a
program-defined specialization.
\end{itemize}

\rSec1[bit]{Bit manipulation}

\rSec2[bit.general]{General}

\pnum
The header \libheaderdef{bit} provides components to access,
manipulate and process both individual bits and bit sequences.

\rSec2[bit.syn]{Header \tcode{<bit>} synopsis}

\begin{codeblock}
// all freestanding
namespace std {
  // \ref{bit.cast}, \tcode{bit_cast}
  template<class To, class From>
    constexpr To bit_cast(const From& from) noexcept;

  // \ref{bit.byteswap}, \tcode{byteswap}
  template<class T>
    constexpr T byteswap(T value) noexcept;

  // \ref{bit.pow.two}, integral powers of 2
  template<class T>
    constexpr bool has_single_bit(T x) noexcept;
  template<class T>
    constexpr T bit_ceil(T x);
  template<class T>
    constexpr T bit_floor(T x) noexcept;
  template<class T>
    constexpr int bit_width(T x) noexcept;

  // \ref{bit.rotate}, rotating
  template<class T>
    constexpr T rotl(T x, int s) noexcept;
  template<class T>
    constexpr T rotr(T x, int s) noexcept;

  // \ref{bit.count}, counting
  template<class T>
    constexpr int countl_zero(T x) noexcept;
  template<class T>
    constexpr int countl_one(T x) noexcept;
  template<class T>
    constexpr int countr_zero(T x) noexcept;
  template<class T>
    constexpr int countr_one(T x) noexcept;
  template<class T>
    constexpr int popcount(T x) noexcept;

  // \ref{bit.endian}, endian
  enum class endian {
    little = @\seebelow@,
    big    = @\seebelow@,
    native = @\seebelow@
  };
}
\end{codeblock}

\rSec2[bit.cast]{Function template \tcode{bit_cast}}

\indexlibraryglobal{bit_cast}%
\begin{itemdecl}
template<class To, class From>
  constexpr To bit_cast(const From& from) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{sizeof(To) == sizeof(From)} is \tcode{true};
\item \tcode{is_trivially_copyable_v<To>} is \tcode{true}; and
\item \tcode{is_trivially_copyable_v<From>} is \tcode{true}.
\end{itemize}

\pnum
\returns
An object of type \tcode{To}.
Implicitly creates objects nested within the result\iref{intro.object}.
Each bit of the value representation of the result
is equal to the corresponding bit in the object representation
of \tcode{from}. Padding bits of the result are unspecified.
For the result and each object created within it,
if there is no value of the object's type corresponding to the
value representation produced, the behavior is undefined.
If there are multiple such values, which value is produced is unspecified.
A bit in the value representation of the result is indeterminate if
it does not correspond to a bit in the value representation of \tcode{from} or
corresponds to a bit
for which the smallest enclosing object is not within its lifetime or
has an indeterminate value\iref{basic.indet}.
A bit in the value representation of the result is erroneous
if it corresponds to a bit
for which the smallest enclosing object has an erroneous value.
For each bit $b$ in the value representation of the result
that is indeterminate or erroneous,
let $u$ be the smallest object containing that bit enclosing $b$:
\begin{itemize}
\item
If $u$ is of unsigned ordinary character type or \tcode{std::byte} type,
$u$ has an indeterminate value
if any of the bits in its value representation are indeterminate, or
otherwise has an erroneous value.
\item
Otherwise, if $b$ is indeterminate, the behavior is undefined.
\item
Otherwise, the behavior is erroneous, and the result is as specified above.
\end{itemize}
The result does not otherwise contain any indeterminate or erroneous values.

\pnum
\remarks
This function is \keyword{constexpr} if and only if
\tcode{To}, \tcode{From}, and the types of all subobjects
of \tcode{To} and \tcode{From} are types \tcode{T} such that:
\begin{itemize}
\item \tcode{is_union_v<T>} is \tcode{false};
\item \tcode{is_pointer_v<T>} is \tcode{false};
\item \tcode{is_member_pointer_v<T>} is \tcode{false};
\item \tcode{is_volatile_v<T>} is \tcode{false}; and
\item \tcode{T} has no non-static data members of reference type.
\end{itemize}
\end{itemdescr}

\rSec2[bit.byteswap]{\tcode{byteswap}}

\indexlibraryglobal{byteswap}%
\begin{itemdecl}
template<class T>
  constexpr T byteswap(T value) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} models \libconcept{integral}.

\pnum
\mandates
\tcode{T} does not have padding bits\iref{basic.types.general}.

\pnum
Let the sequence $R$ comprise
the bytes of the object representation of \tcode{value} in reverse order.

\pnum
\returns
An object \tcode{v} of type \tcode{T}
such that each byte in the object representation of \tcode{v} is equal to
the byte in the corresponding position in $R$.
\end{itemdescr}

\rSec2[bit.pow.two]{Integral powers of 2}

\indexlibraryglobal{has_single_bit}%
\begin{itemdecl}
template<class T>
  constexpr bool has_single_bit(T x) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
\tcode{true} if \tcode{x} is an integral power of two;
\tcode{false} otherwise.

\end{itemdescr}

\indexlibraryglobal{bit_ceil}%
\begin{itemdecl}
template<class T>
  constexpr T bit_ceil(T x);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let $N$ be the smallest power of 2 greater than or equal to \tcode{x}.

\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\expects
$N$ is representable as a value of type \tcode{T}.

\pnum
\returns
$N$.

\pnum
\throws
Nothing.

\pnum
\remarks
A function call expression
that violates the precondition in the \expects element
is not a core constant expression\iref{expr.const}.
\end{itemdescr}

\indexlibraryglobal{bit_floor}%
\begin{itemdecl}
template<class T>
  constexpr T bit_floor(T x) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
If \tcode{x == 0}, \tcode{0};
otherwise the maximal value \tcode{y}
such that \tcode{has_single_bit(y)} is \tcode{true} and \tcode{y <= x}.

\end{itemdescr}

\indexlibraryglobal{bit_width}%
\begin{itemdecl}
template<class T>
  constexpr int bit_width(T x) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
If \tcode{x == 0}, \tcode{0};
otherwise one plus the base-2 logarithm of \tcode{x},
with any fractional part discarded.

\end{itemdescr}

\rSec2[bit.rotate]{Rotating}

\pnum
In the following descriptions,
let \tcode{N} denote \tcode{numeric_limits<T>::digits}.

\begin{itemdecl}
template<class T>
  constexpr T rotl(T x, int s) noexcept;
\end{itemdecl}

\indexlibraryglobal{rotl}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
Let \tcode{r} be \tcode{s \% N}.

\pnum
\returns
If \tcode{r} is \tcode{0}, \tcode{x};
if \tcode{r} is positive, \tcode{(x << r) | (x >> (N - r))};
if \tcode{r} is negative, \tcode{rotr(x, -r)}.
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr T rotr(T x, int s) noexcept;
\end{itemdecl}

\indexlibraryglobal{rotr}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
Let \tcode{r} be \tcode{s \% N}.

\pnum
\returns
If \tcode{r} is \tcode{0}, \tcode{x};
if \tcode{r} is positive, \tcode{(x >> r) | (x << (N - r))};
if \tcode{r} is negative, \tcode{rotl(x, -r)}.
\end{itemdescr}

\rSec2[bit.count]{Counting}

\pnum
In the following descriptions,
let \tcode{N} denote \tcode{numeric_limits<T>::digits}.

\begin{itemdecl}
template<class T>
  constexpr int countl_zero(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{countl_zero}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of consecutive \tcode{0} bits in the value of \tcode{x},
starting from the most significant bit.
\begin{note}
Returns \tcode{N} if \tcode{x == 0}.
\end{note}
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr int countl_one(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{countl_one}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of consecutive \tcode{1} bits in the value of \tcode{x},
starting from the most significant bit.
\begin{note}
Returns \tcode{N} if \tcode{x == numeric_limits<T>::max()}.
\end{note}
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr int countr_zero(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{countr_zero}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of consecutive \tcode{0} bits in the value of \tcode{x},
starting from the least significant bit.
\begin{note}
Returns \tcode{N} if \tcode{x == 0}.
\end{note}
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr int countr_one(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{countr_one}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of consecutive \tcode{1} bits in the value of \tcode{x},
starting from the least significant bit.
\begin{note}
Returns \tcode{N} if \tcode{x == numeric_limits<T>::max()}.
\end{note}
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr int popcount(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{popcount}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of \tcode{1} bits in the value of \tcode{x}.
\end{itemdescr}

\rSec2[bit.endian]{Endian}

\pnum
Two common methods of byte ordering in multibyte scalar types are big-endian
and little-endian in the execution environment. Big-endian is a format for
storage of binary data in which the most significant byte is placed first,
with the rest in descending order. Little-endian is a format for storage of
binary data in which the least significant byte is placed first, with the rest
in ascending order. This subclause describes the endianness of the scalar types
of the execution environment.

\indexlibraryglobal{endian}%
\indexlibrarymember{little}{endian}%
\indexlibrarymember{big}{endian}%
\indexlibrarymember{native}{endian}%
\begin{itemdecl}
enum class endian {
  little = @\seebelow@,
  big    = @\seebelow@,
  native = @\seebelow@
};
\end{itemdecl}

\begin{itemdescr}
\pnum
If all scalar types have size 1 byte, then all of \tcode{endian::little},
\tcode{endian::big}, and \tcode{endian::native} have the same value.
Otherwise, \tcode{endian::little} is not equal to \tcode{endian::big}.
If all scalar types are big-endian, \tcode{endian::native} is
equal to \tcode{endian::big}.
If all scalar types are little-endian, \tcode{endian::native} is
equal to \tcode{endian::little}.
Otherwise, \tcode{endian::native} is not equal
to either \tcode{endian::big} or \tcode{endian::little}.
\end{itemdescr}

\rSec1[stdbit.h.syn]{Header \tcode{<stdbit.h>} synopsis}

\indexheader{stdbit.h}%
\begin{codeblock}
#define @\libmacro{__STDC_VERSION_STDBIT_H__}@ 202311L

#define @\libmacro{__STDC_ENDIAN_BIG__}@     @\seebelow@
#define @\libmacro{__STDC_ENDIAN_LITTLE__}@  @\seebelow@
#define @\libmacro{__STDC_ENDIAN_NATIVE__}@  @\seebelow@

unsigned int @\libglobal{stdc_leading_zeros_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_leading_zeros_us}@(unsigned short value);
unsigned int @\libglobal{stdc_leading_zeros_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_leading_zeros_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_leading_zeros_ull}@(unsigned long long int value);
template<class T> @\seebelow@ @\libglobal{stdc_leading_zeros}@(T value);

unsigned int @\libglobal{stdc_leading_ones_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_leading_ones_us}@(unsigned short value);
unsigned int @\libglobal{stdc_leading_ones_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_leading_ones_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_leading_ones_ull}@(unsigned long long int value);
template<class T> @\seebelow@ @\libglobal{stdc_leading_ones}@(T value);

unsigned int @\libglobal{stdc_trailing_zeros_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_trailing_zeros_us}@(unsigned short value);
unsigned int @\libglobal{stdc_trailing_zeros_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_trailing_zeros_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_trailing_zeros_ull}@(unsigned long long int value);
template<class T> @\seebelow@ @\libglobal{stdc_trailing_zeros}@(T value);

unsigned int @\libglobal{stdc_trailing_ones_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_trailing_ones_us}@(unsigned short value);
unsigned int @\libglobal{stdc_trailing_ones_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_trailing_ones_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_trailing_ones_ull}@(unsigned long long int value);
template<class T> @\seebelow@ @\libglobal{stdc_trailing_ones}@(T value);

unsigned int @\libglobal{stdc_first_leading_zero_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_first_leading_zero_us}@(unsigned short value);
unsigned int @\libglobal{stdc_first_leading_zero_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_first_leading_zero_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_first_leading_zero_ull}@(unsigned long long int value);
template<class T> @\seebelow@ @\libglobal{stdc_first_leading_zero}@(T value);

unsigned int @\libglobal{stdc_first_leading_one_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_first_leading_one_us}@(unsigned short value);
unsigned int @\libglobal{stdc_first_leading_one_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_first_leading_one_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_first_leading_one_ull}@(unsigned long long int value);
template<class T> @\seebelow@ stdc_first_leading_one(T value);

unsigned int @\libglobal{stdc_first_trailing_zero_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_first_trailing_zero_us}@(unsigned short value);
unsigned int @\libglobal{stdc_first_trailing_zero_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_first_trailing_zero_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_first_trailing_zero_ull}@(unsigned long long int value);
template<class T> @\seebelow@ stdc_first_trailing_zero(T value);

unsigned int @\libglobal{stdc_first_trailing_one_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_first_trailing_one_us}@(unsigned short value);
unsigned int @\libglobal{stdc_first_trailing_one_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_first_trailing_one_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_first_trailing_one_ull}@(unsigned long long int value);
template<class T> @\seebelow@ stdc_first_trailing_one(T value);

unsigned int @\libglobal{stdc_count_zeros_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_count_zeros_us}@(unsigned short value);
unsigned int @\libglobal{stdc_count_zeros_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_count_zeros_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_count_zeros_ull}@(unsigned long long int value);
template<class T> @\seebelow@ @\libglobal{stdc_count_zeros}@(T value);

unsigned int @\libglobal{stdc_count_ones_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_count_ones_us}@(unsigned short value);
unsigned int @\libglobal{stdc_count_ones_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_count_ones_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_count_ones_ull}@(unsigned long long int value);
template<class T> @\seebelow@ stdc_count_ones(T value);

bool @\libglobal{stdc_has_single_bit_uc}@(unsigned char value);
bool @\libglobal{stdc_has_single_bit_us}@(unsigned short value);
bool @\libglobal{stdc_has_single_bit_ui}@(unsigned int value);
bool @\libglobal{stdc_has_single_bit_ul}@(unsigned long int value);
bool @\libglobal{stdc_has_single_bit_ull}@(unsigned long long int value);
template<class T> bool @\libglobal{stdc_has_single_bit}@(T value);

unsigned int @\libglobal{stdc_bit_width_uc}@(unsigned char value);
unsigned int @\libglobal{stdc_bit_width_us}@(unsigned short value);
unsigned int @\libglobal{stdc_bit_width_ui}@(unsigned int value);
unsigned int @\libglobal{stdc_bit_width_ul}@(unsigned long int value);
unsigned int @\libglobal{stdc_bit_width_ull}@(unsigned long long int value);
template<class T> @\seebelow@ @\libglobal{stdc_bit_width}@(T value);

unsigned char @\libglobal{stdc_bit_floor_uc}@(unsigned char value);
unsigned short @\libglobal{stdc_bit_floor_us}@(unsigned short value);
unsigned int @\libglobal{stdc_bit_floor_ui}@(unsigned int value);
unsigned long int @\libglobal{stdc_bit_floor_ul}@(unsigned long int value);
unsigned long long int @\libglobal{stdc_bit_floor_ull}@(unsigned long long int value);
template<class T> T @\libglobal{stdc_bit_floor}@(T value);

unsigned char @\libglobal{stdc_bit_ceil_uc}@(unsigned char value);
unsigned short @\libglobal{stdc_bit_ceil_us}@(unsigned short value);
unsigned int @\libglobal{stdc_bit_ceil_ui}@(unsigned int value);
unsigned long int @\libglobal{stdc_bit_ceil_ul}@(unsigned long int value);
unsigned long long int @\libglobal{stdc_bit_ceil_ull}@(unsigned long long int value);
template<class T> T @\libglobal{stdc_bit_ceil}@(T value);
\end{codeblock}

\pnum
For a function template whose return type is not specified above,
the return type is
an \impldef{return types for \tcode{<stdbit.h>} functions} unsigned integer type
large enough to represent all possible result values.
Each function template has the same semantics
as the corresponding type-generic function with the same name
specified in \IsoCUndated{}:2024, 7.18.  %% change to \xrefc{7.18}

\pnum
\mandates
\tcode{T} is an unsigned integer type.

\pnum
Otherwise,
the contents and meaning of the header \libheader{stdbit.h} are the same as
the C standard library header \tcode{<stdbit.h>}.

\xref{\IsoCUndated{}:2024, 7.18}   %% TODO: change to \xrefc{7.18}