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{type.index}            & Type indexes                      & \tcode{<typeindex>}   \\ \rowsep
\ref{execpol}               & Execution policies                & \tcode{<execution>}   \\ \rowsep
\ref{charconv}              & Primitive numeric conversions     & \tcode{<charconv>}    \\ \rowsep
\ref{format}                & Formatting                        & \tcode{<format>}      \\ \rowsep
\ref{bit}                   & Bit manipulation                  & \tcode{<bit>} \\ \rowsep
\ref{debugging}             & Debugging                         & \tcode{<debugging>} \\
\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>
    [[nodiscard]] 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.unreachable}, unreachable
  [[noreturn]] void unreachable();

  // \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{};
}
\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>
  [[nodiscard]] 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.unreachable]{Function \tcode{unreachable}}

\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}

\rSec1[pairs]{Pairs}

\rSec2[pairs.general]{In 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
\expects
Each of \tcode{decltype(x.first == y.first)} and
\tcode{decltype(x.second == y.second)} models \exposconcept{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]{In 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}.

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

  // \ref{tuple.creation}, tuple creation functions
  inline constexpr @\unspec@ ignore;

  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}
\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...)}.  When an
argument in \tcode{t} is \tcode{ignore}, assigning
any value to the corresponding tuple element has no effect.

\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...>> : public 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;        // Note A
template<size_t I, class... Types>
  constexpr const tuple_element_t<I, tuple<Types...>>&
    get(const tuple<Types...>& t) noexcept;   // Note B
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}
[Note A]
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}
[Note B]
Constness is shallow.
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
\mandates
For all \tcode{i},
where $0 \leq \tcode{i} < \tcode{sizeof...(TTypes)}$,
\tcode{get<i>(t) == get<i>(u)} is a valid expression.
\tcode{sizeof...(TTypes)} equals
\tcode{tuple_size_v<UTuple>}.

\pnum
\expects
For all \tcode{i}, \tcode{decltype(get<i>(t) == get<i>(u))} models
\exposconcept{boolean-testable}.

\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]{In 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>
    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<@\seebelow@> 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;

    // \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 = 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 = 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.observe}, observers
    constexpr const T* operator->() const noexcept;
    constexpr T* operator->() noexcept;
    constexpr const T& operator*() const & noexcept;
    constexpr T& operator*() & noexcept;
    constexpr T&& operator*() && noexcept;
    constexpr const T&& operator*() const && noexcept;
    constexpr explicit operator bool() const noexcept;
    constexpr bool has_value() const noexcept;
    constexpr const T& value() const &;                                 // freestanding-deleted
    constexpr T& value() &;                                             // freestanding-deleted
    constexpr T&& value() &&;                                           // freestanding-deleted
    constexpr const T&& value() const &&;                               // freestanding-deleted
    template<class U> constexpr T value_or(U&&) const &;
    template<class U> constexpr T value_or(U&&) &&;

    // \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 allocated within the storage of the optional object.
Implementations are not permitted to use additional storage, such as dynamic memory, to allocate its contained value.
When an object of type \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 = 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 = T> constexpr optional<T>& operator=(U&& v);
\end{itemdecl}

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

\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.observe]{Observers}

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

\begin{itemdescr}
\pnum
\expects
\tcode{*this} contains a value.

\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
\expects
\tcode{*this} contains a value.

\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
\expects
\tcode{*this} contains a value.

\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> 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> 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
    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}
const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An \impldef{return value of \tcode{bad_optional_access::what}} \ntbs{}.
\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
\mandates
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
\mandates
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
\mandates
\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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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
\mandates
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]{In 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 subclause \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 allocated within the storage of the
\tcode{variant} object.
Implementations are not permitted to use additional storage, such as dynamic
memory, to allocate the contained value.

\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
\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
\mandates
\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
\mandates
\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
\mandates
\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
\mandates
\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
\mandates
\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
\mandates
\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>
  auto&& @\exposid{as-variant}@(variant<Ts...>& var) { return var; }
template<class... Ts>
  auto&& @\exposid{as-variant}@(const variant<Ts...>& var) { return var; }
template<class... Ts>
  auto&& @\exposid{as-variant}@(variant<Ts...>&& var) { return std::move(var); }
template<class... Ts>
  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
    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}
const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An \impldef{return value of \tcode{bad_variant_access::what}} \ntbs{}.
\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]{In 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:
    explicit bad_expected_access(E);
    const char* what() const noexcept override;
    E& error() & noexcept;
    const E& error() const & noexcept;
    E&& error() && noexcept;
    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}
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}
const E& error() const & noexcept;
E& error() & noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\exposid{unex}.
\end{itemdescr}

\indexlibrarymember{error}{bad_expected_access}%
\begin{itemdecl}
E&& error() && noexcept;
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}
const char* what() const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An implementation-defined \ntbs.
\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:
    bad_expected_access() noexcept;
    bad_expected_access(const bad_expected_access&);
    bad_expected_access(bad_expected_access&&);
    bad_expected_access& operator=(const bad_expected_access&);
    bad_expected_access& operator=(bad_expected_access&&);
    ~bad_expected_access();

  public:
    const char* what() const noexcept override;
  };
}
\end{codeblock}

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

\begin{itemdescr}
\pnum
\returns
An implementation-defined \ntbs.
\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 = 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 = 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> constexpr T value_or(U&&) const &;
    template<class U> 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} within its own storage.
Implementations are not permitted to use additional storage,
such as dynamic memory,
to allocate the object of type \tcode{T} or the object of type \tcode{E}.
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 = 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 = 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
\expects
\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
\expects
\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
\expects
\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
\expects
\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
\expects
\tcode{has_value()} is \tcode{false}.

\pnum
\returns
\tcode{std::move(\exposid{unex})}.
\end{itemdescr}

\indexlibrarymember{value_or}{expected}%
\begin{itemdecl}
template<class U> 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> 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
\mandates
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
\mandates
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
\mandates
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} within its own storage.
Implementations are not permitted to use additional storage,
such as dynamic memory, to allocate the object of type \tcode{E}.
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
\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>}.

\pnum
This operator is defined as deleted unless
\tcode{is_move_constructible_v<E>} is \tcode{true} and
\tcode{is_move_assignable_v<E>} is \tcode{true}.
\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
\expects
\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
\expects
\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
\expects
\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
\mandates
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
\mandates
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 {
      friend class bitset;
      constexpr reference() noexcept;

    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
\expects
\tcode{pos} is valid.

\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
\expects
\tcode{pos} is valid.

\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
               .
               .
               .
    @\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
  }
}
\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(t1)>> ||}
\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(t1)>> ||}
\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...>);
  };

  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.

\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.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 {
  // M is the number of placeholders
  @\seebelow@ _1;
  @\seebelow@ _2;
              .
              .
              .
  @\seebelow@ _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
\indextext{callable type}%
A callable type\iref{func.def} \tcode{F}
is \defn{Lvalue-Callable} for argument
types \tcode{ArgTypes}
and return type \tcode{R}
if the expression
\tcode{\placeholdernc{INVOKE}<R>(declval<F\&>(), declval<ArgTypes>()...)},
considered as an unevaluated operand\iref{term.unevaluated.operand}, is
well-formed\iref{func.require}.

\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 \tcode{f.target()}.

\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{FD} is Lvalue-Callable\iref{func.wrap.func} for argument types
\tcode{ArgTypes...} and return type \tcode{R}.
\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{decay_t<F>} is Lvalue-Callable\iref{func.wrap.func}
for argument types \tcode{ArgTypes...} and return type \tcode{R}.

\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 subclause \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},
the \oldconcept{Copy\-Constructible}, and
the \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[type.index]{Class \tcode{type_index}}

\rSec2[type.index.synopsis]{Header \tcode{<typeindex>} synopsis}

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

namespace std {
  class type_index;
  template<class T> struct hash;
  template<> struct hash<type_index>;
}
\end{codeblock}

\rSec2[type.index.overview]{\tcode{type_index} overview}

\indexlibraryglobal{type_index}%
\begin{codeblock}
namespace std {
  class type_index {
  public:
    type_index(const type_info& rhs) noexcept;
    bool operator==(const type_index& rhs) const noexcept;
    bool operator< (const type_index& rhs) const noexcept;
    bool operator> (const type_index& rhs) const noexcept;
    bool operator<=(const type_index& rhs) const noexcept;
    bool operator>=(const type_index& rhs) const noexcept;
    strong_ordering operator<=>(const type_index& rhs) const noexcept;
    size_t hash_code() const noexcept;
    const char* name() const noexcept;

  private:
    const type_info* target;    // \expos
    // Note that the use of a pointer here, rather than a reference,
    // means that the default copy/move constructor and assignment
    // operators will be provided and work as expected.
  };
}
\end{codeblock}

\pnum
The class \tcode{type_index} provides a simple wrapper for
\tcode{type_info} which can be used as an index type in associative
containers\iref{associative} and in unordered associative
containers\iref{unord}.

\rSec2[type.index.members]{\tcode{type_index} members}

\indexlibraryctor{type_index}%
\begin{itemdecl}
type_index(const type_info& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a \tcode{type_index} object, the equivalent of \tcode{target = \&rhs}.
\end{itemdescr}

\indexlibrarymember{operator==}{type_index}%
\begin{itemdecl}
bool operator==(const type_index& rhs) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{*target == *rhs.target}.
\end{itemdescr}

\indexlibrarymember{operator<}{type_index}%
\begin{itemdecl}
bool operator<(const type_index& rhs) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{target->before(*rhs.target)}.
\end{itemdescr}

\indexlibrarymember{operator>}{type_index}%
\begin{itemdecl}
bool operator>(const type_index& rhs) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rhs.target->before(*target)}.
\end{itemdescr}

\indexlibrarymember{operator<=}{type_index}%
\begin{itemdecl}
bool operator<=(const type_index& rhs) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{!rhs.target->before(*target)}.
\end{itemdescr}

\indexlibrarymember{operator>=}{type_index}%
\begin{itemdecl}
bool operator>=(const type_index& rhs) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{!target->before(*rhs.target)}.
\end{itemdescr}

\indexlibrarymember{operator<=>}{type_index}%
\begin{itemdecl}
strong_ordering operator<=>(const type_index& rhs) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
if (*target == *rhs.target) return strong_ordering::equal;
if (target->before(*rhs.target)) return strong_ordering::less;
return strong_ordering::greater;
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{hash_code}{type_index}%
\begin{itemdecl}
size_t hash_code() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{target->hash_code()}.
\end{itemdescr}

\indexlibrarymember{name}{type_index}%
\begin{itemdecl}
const char* name() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{target->name()}.
\end{itemdescr}

\rSec2[type.index.hash]{Hash support}

\indexlibrarymember{hash}{type_index}%
\begin{itemdecl}
template<> struct hash<type_index>;
\end{itemdecl}

\begin{itemdescr}
\pnum
For an object \tcode{index} of type \tcode{type_index},
\tcode{hash<type_index>()(index)} shall evaluate to the same result as \tcode{index.hash_code()}.
\end{itemdescr}

\rSec1[execpol]{Execution policies}
\rSec2[execpol.general]{In general}

\pnum
Subclause~\ref{execpol} describes classes that are \defn{execution policy} types. An
object of an execution policy type indicates the kinds of parallelism allowed
in the execution of an algorithm and expresses the consequent requirements on
the element access functions.
\begin{example}
\begin{codeblock}
using namespace std;
vector<int> v = @\commentellip@;

// standard sequential sort
sort(v.begin(), v.end());

// explicitly sequential sort
sort(execution::seq, v.begin(), v.end());

// permitting parallel execution
sort(execution::par, v.begin(), v.end());

// permitting vectorization as well
sort(execution::par_unseq, v.begin(), v.end());
\end{codeblock}
\end{example}
\begin{note}
Implementations can provide additional execution policies
to those described in this standard as extensions
to address parallel architectures that require idiosyncratic
parameters for efficient execution.
\end{note}

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

\indexheader{execution}%
\begin{codeblock}
namespace std {
  // \ref{execpol.type}, execution policy type trait
  template<class T> struct is_execution_policy;
  template<class T> constexpr bool @\libglobal{is_execution_policy_v}@ = is_execution_policy<T>::value;
}

namespace std::execution {
  // \ref{execpol.seq}, sequenced execution policy
  class sequenced_policy;

  // \ref{execpol.par}, parallel execution policy
  class parallel_policy;

  // \ref{execpol.parunseq}, parallel and unsequenced execution policy
  class parallel_unsequenced_policy;

  // \ref{execpol.unseq}, unsequenced execution policy
  class unsequenced_policy;

  // \ref{execpol.objects}, execution policy objects
  inline constexpr sequenced_policy            seq{ @\unspec@ };
  inline constexpr parallel_policy             par{ @\unspec@ };
  inline constexpr parallel_unsequenced_policy par_unseq{ @\unspec@ };
  inline constexpr unsequenced_policy          unseq{ @\unspec@ };
}
\end{codeblock}

\rSec2[execpol.type]{Execution policy type trait}

\indexlibraryglobal{is_execution_policy}%
\begin{itemdecl}
template<class T> struct is_execution_policy { @\seebelow@ };
\end{itemdecl}

\begin{itemdescr}
\pnum
\tcode{is_execution_policy} can be used to detect execution policies for the
purpose of excluding function signatures from otherwise ambiguous overload
resolution participation.

\pnum
\tcode{is_execution_policy<T>} is a \oldconcept{UnaryTypeTrait} with a
base characteristic of \tcode{true_type} if \tcode{T} is the type of a standard
or \impldef{additional execution policies supported by parallel algorithms}
execution policy, otherwise \tcode{false_type}.

\begin{note}
This provision reserves the privilege of creating non-standard execution
policies to the library implementation.
\end{note}

\pnum
The behavior of a program that adds specializations for
\tcode{is_execution_policy} is undefined.
\end{itemdescr}

\rSec2[execpol.seq]{Sequenced execution policy}

\indexlibraryglobal{execution::sequenced_policy}%
\begin{itemdecl}
class execution::sequenced_policy { @\unspec@ };
\end{itemdecl}

\begin{itemdescr}
\pnum
The class \tcode{execution::sequenced_policy} is an execution policy type used
as a unique type to disambiguate parallel algorithm overloading and require
that a parallel algorithm's execution may not be parallelized.

\pnum
During the execution of a parallel algorithm with
the \tcode{execution::sequenced_policy} policy,
if the invocation of an element access function exits via an exception,
\tcode{terminate} is invoked\iref{except.terminate}.
\end{itemdescr}

\rSec2[execpol.par]{Parallel execution policy}

\indexlibraryglobal{execution::parallel_policy}%
\begin{itemdecl}
class execution::parallel_policy { @\unspec@ };
\end{itemdecl}

\begin{itemdescr}
\pnum
The class \tcode{execution::parallel_policy} is an execution policy type used as
a unique type to disambiguate parallel algorithm overloading and indicate that
a parallel algorithm's execution may be parallelized.

\pnum
During the execution of a parallel algorithm with
the \tcode{execution::parallel_policy} policy,
if the invocation of an element access function exits via an exception,
\tcode{terminate} is invoked\iref{except.terminate}.
\end{itemdescr}

\rSec2[execpol.parunseq]{Parallel and unsequenced execution policy}

\indexlibraryglobal{execution::parallel_unsequenced_policy}%
\begin{itemdecl}
class execution::parallel_unsequenced_policy { @\unspec@ };
\end{itemdecl}

\begin{itemdescr}
\pnum
The class \tcode{execution::parallel_unsequenced_policy} is an execution policy type
used as a unique type to disambiguate parallel algorithm overloading and
indicate that a parallel algorithm's execution may be parallelized and
vectorized.

\pnum
During the execution of a parallel algorithm with
the \tcode{execution::parallel_unsequenced_policy} policy,
if the invocation of an element access function exits via an exception,
\tcode{terminate} is invoked\iref{except.terminate}.
\end{itemdescr}

\rSec2[execpol.unseq]{Unsequenced execution policy}

\indexlibraryglobal{execution::unsequenced_policy}%
\begin{itemdecl}
class execution::unsequenced_policy { @\unspec@ };
\end{itemdecl}

\begin{itemdescr}
\pnum
The class \tcode{unsequenced_policy} is an execution policy type
used as a unique type to disambiguate parallel algorithm overloading and
indicate that a parallel algorithm's execution may be vectorized,
e.g., executed on a single thread using instructions
that operate on multiple data items.

\pnum
During the execution of a parallel algorithm with
the \tcode{execution::unsequenced_policy} policy,
if the invocation of an element access function exits via an exception,
\tcode{terminate} is invoked\iref{except.terminate}.
\end{itemdescr}

\rSec2[execpol.objects]{Execution policy objects}

\indexlibraryglobal{seq}%
\indexlibraryglobal{par}%
\indexlibraryglobal{par_unseq}%
\indexlibrarymember{execution}{seq}%
\indexlibrarymember{execution}{par}%
\indexlibrarymember{execution}{par_unseq}%
\begin{itemdecl}
inline constexpr execution::sequenced_policy            execution::seq{ @\unspec@ };
inline constexpr execution::parallel_policy             execution::par{ @\unspec@ };
inline constexpr execution::parallel_unsequenced_policy execution::par_unseq{ @\unspec@ };
inline constexpr execution::unsequenced_policy          execution::unseq{ @\unspec@ };
\end{itemdecl}

\begin{itemdescr}
\pnum
The header \libheader{execution} declares global objects associated with each type of execution policy.
\end{itemdescr}

\rSec1[charconv]{Primitive numeric conversions}

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

\pnum
When a function is specified
with a type placeholder of \tcode{\placeholder{integer-type}},
the implementation provides overloads
for all cv-unqualified signed and unsigned integer types and \tcode{char}
in lieu of \tcode{\placeholder{integer-type}}.
When a function is specified
with a type placeholder of \tcode{\placeholder{floating-point-type}},
the implementation provides overloads
for all cv-unqualified floating-point types\iref{basic.fundamental}
in lieu of \tcode{\placeholder{floating-point-type}}.

\indexheader{charconv}%
\begin{codeblock}
@%
\indexlibraryglobal{chars_format}%
\indexlibrarymember{scientific}{chars_format}%
\indexlibrarymember{fixed}{chars_format}%
\indexlibrarymember{hex}{chars_format}%
\indexlibrarymember{general}{chars_format}%
@namespace std {
  // floating-point format for primitive numerical conversion
  enum class chars_format {
    scientific = @\unspec@,
    fixed = @\unspec@,
    hex = @\unspec@,
    general = fixed | scientific
  };
@%
\indexlibraryglobal{to_chars_result}%
\indexlibrarymember{ptr}{to_chars_result}%
\indexlibrarymember{ec}{to_chars_result}
@
  // \ref{charconv.to.chars}, primitive numerical output conversion
  struct to_chars_result {                                              // freestanding
    char* ptr;
    errc ec;
    friend bool operator==(const to_chars_result&, const to_chars_result&) = default;
    constexpr explicit operator bool() const noexcept { return ec == errc{}; }
  };

  constexpr to_chars_result to_chars(char* first, char* last,           // freestanding
                                     @\placeholder{integer-type}@ value, int base = 10);
  to_chars_result to_chars(char* first, char* last,                     // freestanding
                           bool value, int base = 10) = delete;

  to_chars_result to_chars(char* first, char* last,                     // freestanding-deleted
                           @\placeholder{floating-point-type}@ value);
  to_chars_result to_chars(char* first, char* last,                     // freestanding-deleted
                           @\placeholder{floating-point-type}@ value, chars_format fmt);
  to_chars_result to_chars(char* first, char* last,                     // freestanding-deleted
                           @\placeholder{floating-point-type}@ value, chars_format fmt, int precision);
@%
\indexlibraryglobal{from_chars_result}%
\indexlibrarymember{ptr}{from_chars_result}%
\indexlibrarymember{ec}{from_chars_result}
@
  // \ref{charconv.from.chars}, primitive numerical input conversion
  struct from_chars_result {                                            // freestanding
    const char* ptr;
    errc ec;
    friend bool operator==(const from_chars_result&, const from_chars_result&) = default;
    constexpr explicit operator bool() const noexcept { return ec == errc{}; }
  };

  constexpr from_chars_result from_chars(const char* first, const char* last,   // freestanding
                                         @\placeholder{integer-type}@& value, int base = 10);

  from_chars_result from_chars(const char* first, const char* last,     // freestanding-deleted
                               @\placeholder{floating-point-type}@& value,
                               chars_format fmt = chars_format::general);
}
\end{codeblock}

\pnum
The type \tcode{chars_format} is a bitmask type\iref{bitmask.types}
with elements \tcode{scientific}, \tcode{fixed}, and \tcode{hex}.

\pnum
The types \tcode{to_chars_result} and \tcode{from_chars_result}
have the data members and special members specified above.
They have no base classes or members other than those specified.

\rSec2[charconv.to.chars]{Primitive numeric output conversion}

\pnum
All functions named \tcode{to_chars}
convert \tcode{value} into a character string
by successively filling the range
\range{first}{last},
where \range{first}{last} is required to be a valid range.
If the member \tcode{ec}
of the return value
is such that the value
is equal to the value of a value-initialized \tcode{errc},
the conversion was successful
and the member \tcode{ptr}
is the one-past-the-end pointer of the characters written.
Otherwise,
the member \tcode{ec} has the value \tcode{errc::value_too_large},
the member \tcode{ptr} has the value \tcode{last},
and the contents of the range \range{first}{last} are unspecified.

\pnum
The functions that take a floating-point \tcode{value}
but not a \tcode{precision} parameter
ensure that the string representation
consists of the smallest number of characters
such that
there is at least one digit before the radix point (if present) and
parsing the representation using the corresponding \tcode{from_chars} function
recovers \tcode{value} exactly.
\begin{note}
This guarantee applies only if
\tcode{to_chars} and \tcode{from_chars}
are executed on the same implementation.
\end{note}
If there are several such representations,
the representation with the smallest difference from
the floating-point argument value is chosen,
resolving any remaining ties using rounding according to
\tcode{round_to_nearest}\iref{round.style}.

\pnum
The functions taking a \tcode{chars_format} parameter
determine the conversion specifier for \tcode{printf} as follows:
The conversion specifier is
\tcode{f} if \tcode{fmt} is \tcode{chars_format::fixed},
\tcode{e} if \tcode{fmt} is \tcode{chars_format::scientific},
\tcode{a} (without leading \tcode{"0x"} in the result)
if \tcode{fmt} is \tcode{chars_format::hex},
and
\tcode{g} if \tcode{fmt} is \tcode{chars_format::general}.

\indexlibraryglobal{to_chars}%
\begin{itemdecl}
constexpr to_chars_result to_chars(char* first, char* last, @\placeholder{integer-type}@ value, int base = 10);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{base} has a value between 2 and 36 (inclusive).

\pnum
\effects
The value of \tcode{value} is converted
to a string of digits in the given base
(with no redundant leading zeroes).
Digits in the range 10..35 (inclusive)
are represented as lowercase characters \tcode{a}..\tcode{z}.
If \tcode{value} is less than zero,
the representation starts with \tcode{'-'}.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibraryglobal{to_chars}%
\begin{itemdecl}
to_chars_result to_chars(char* first, char* last, @\placeholder{floating-point-type}@ value);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\tcode{value} is converted to a string
in the style of \tcode{printf}
in the \tcode{"C"} locale.
The conversion specifier is \tcode{f} or \tcode{e},
chosen according to the requirement for a shortest representation
(see above);
a tie is resolved in favor of \tcode{f}.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibraryglobal{to_chars}%
\begin{itemdecl}
to_chars_result to_chars(char* first, char* last, @\placeholder{floating-point-type}@ value, chars_format fmt);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{fmt} has the value of
one of the enumerators of \tcode{chars_format}.

\pnum
\effects
\tcode{value} is converted to a string
in the style of \tcode{printf}
in the \tcode{"C"} locale.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibraryglobal{to_chars}%
\begin{itemdecl}
to_chars_result to_chars(char* first, char* last, @\placeholder{floating-point-type}@ value,
                         chars_format fmt, int precision);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{fmt} has the value of
one of the enumerators of \tcode{chars_format}.

\pnum
\effects
\tcode{value} is converted to a string
in the style of \tcode{printf}
in the \tcode{"C"} locale
with the given precision.

\pnum
\throws
Nothing.
\end{itemdescr}

\xrefc{7.21.6.1}

\rSec2[charconv.from.chars]{Primitive numeric input conversion}

\pnum
All functions named \tcode{from_chars}
analyze the string \range{first}{last}
for a pattern,
where \range{first}{last} is required to be a valid range.
If no characters match the pattern,
\tcode{value} is unmodified,
the member \tcode{ptr} of the return value is \tcode{first} and
the member \tcode{ec} is equal to \tcode{errc::invalid_argument}.
\begin{note}
If the pattern allows for an optional sign,
but the string has no digit characters following the sign,
no characters match the pattern.
\end{note}
Otherwise,
the characters matching the pattern
are interpreted as a representation
of a value of the type of \tcode{value}.
The member \tcode{ptr}
of the return value
points to the first character
not matching the pattern,
or has the value \tcode{last}
if all characters match.
If the parsed value
is not in the range
representable by the type of \tcode{value},
\tcode{value} is unmodified and
the member \tcode{ec} of the return value
is equal to \tcode{errc::result_out_of_range}.
Otherwise,
\tcode{value} is set to the parsed value,
after rounding according to \tcode{round_to_nearest}\iref{round.style}, and
the member \tcode{ec} is value-initialized.

\indexlibraryglobal{from_chars}%
\begin{itemdecl}
constexpr from_chars_result from_chars(const char* first, const char* last,
                                       @\placeholder{integer-type}@&@\itcorr[-1]@ value, int base = 10);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{base} has a value between 2 and 36 (inclusive).

\pnum
\effects
The pattern is the expected form of the subject sequence
in the \tcode{"C"} locale
for the given nonzero base,
as described for \tcode{strtol},
except that no \tcode{"0x"} or \tcode{"0X"} prefix shall appear
if the value of \tcode{base} is 16,
and except that \tcode{'-'}
is the only sign that may appear,
and only if \tcode{value} has a signed type.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibraryglobal{from_chars}%
\begin{itemdecl}
from_chars_result from_chars(const char* first, const char* last, @\placeholder{floating-point-type}@& value,
                             chars_format fmt = chars_format::general);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{fmt} has the value of
one of the enumerators of \tcode{chars_format}.

\pnum
\effects
The pattern is the expected form of the subject sequence
in the \tcode{"C"} locale,
as described for \tcode{strtod},
except that
\begin{itemize}
\item
the sign \tcode{'+'} may only appear in the exponent part;
\item
if \tcode{fmt} has \tcode{chars_format::scientific} set
but not \tcode{chars_format::fixed},
the otherwise optional exponent part shall appear;
\item
if \tcode{fmt} has \tcode{chars_format::fixed} set
but not \tcode{chars_format::scientific},
the optional exponent part shall not appear; and
\item
if \tcode{fmt} is \tcode{chars_format::hex},
the prefix \tcode{"0x"} or \tcode{"0X"} is assumed.
\begin{example}
The string \tcode{0x123}
is parsed to have the value
\tcode{0}
with remaining characters \tcode{x123}.
\end{example}
\end{itemize}
In any case, the resulting \tcode{value} is one of
at most two floating-point values
closest to the value of the string matching the pattern.

\pnum
\throws
Nothing.
\end{itemdescr}

\xrefc{7.22.1.3, 7.22.1.4}

\rSec1[format]{Formatting}

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

\indexheader{format}%
\indexlibraryglobal{format_parse_context}%
\indexlibraryglobal{wformat_parse_context}%
\indexlibraryglobal{format_context}%
\indexlibraryglobal{wformat_context}%
\indexlibraryglobal{format_args}%
\indexlibraryglobal{wformat_args}%
\indexlibraryglobal{format_to_n_result}%
\indexlibrarymember{out}{format_to_n_result}%
\indexlibrarymember{size}{format_to_n_result}%
\begin{codeblock}
namespace std {
  // \ref{format.context}, class template \tcode{basic_format_context}
  template<class Out, class charT> class basic_format_context;
  using format_context = basic_format_context<@\unspec@, char>;
  using wformat_context = basic_format_context<@\unspec@, wchar_t>;

  // \ref{format.args}, class template \tcode{basic_format_args}
  template<class Context> class basic_format_args;
  using format_args = basic_format_args<format_context>;
  using wformat_args = basic_format_args<wformat_context>;

  // \ref{format.fmt.string}, class template \tcode{basic_format_string}
  template<class charT, class... Args>
    struct basic_format_string;

  template<class charT> struct @\exposid{runtime-format-string}@ {                  // \expos
  private:
    basic_string_view<charT> @\exposid{str}@;                                       // \expos
  public:
    @\exposid{runtime-format-string}@(basic_string_view<charT> s) noexcept : @\exposid{str}@(s) {}
    @\exposid{runtime-format-string}@(const @\exposid{runtime-format-string}@&) = delete;
    @\exposid{runtime-format-string}@& operator=(const @\exposid{runtime-format-string}@&) = delete;
  };
  @\exposid{runtime-format-string}@<char> runtime_format(string_view fmt) noexcept { return fmt; }
  @\exposid{runtime-format-string}@<wchar_t> runtime_format(wstring_view fmt) noexcept { return fmt; }

  template<class... Args>
    using @\libglobal{format_string}@ = basic_format_string<char, type_identity_t<Args>...>;
  template<class... Args>
    using @\libglobal{wformat_string}@ = basic_format_string<wchar_t, type_identity_t<Args>...>;

  // \ref{format.functions}, formatting functions
  template<class... Args>
    string format(format_string<Args...> fmt, Args&&... args);
  template<class... Args>
    wstring format(wformat_string<Args...> fmt, Args&&... args);
  template<class... Args>
    string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class... Args>
    wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);

  string vformat(string_view fmt, format_args args);
  wstring vformat(wstring_view fmt, wformat_args args);
  string vformat(const locale& loc, string_view fmt, format_args args);
  wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);

  template<class Out, class... Args>
    Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);

  template<class Out>
    Out vformat_to(Out out, string_view fmt, format_args args);
  template<class Out>
    Out vformat_to(Out out, wstring_view fmt, wformat_args args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);

  template<class Out> struct format_to_n_result {
    Out out;
    iter_difference_t<Out> size;
  };
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        format_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        wformat_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        const locale& loc, format_string<Args...> fmt,
                                        Args&&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        const locale& loc, wformat_string<Args...> fmt,
                                        Args&&... args);

  template<class... Args>
    size_t formatted_size(format_string<Args...> fmt, Args&&... args);
  template<class... Args>
    size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
  template<class... Args>
    size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class... Args>
    size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);

  // \ref{format.formatter}, formatter
  template<class T, class charT = char> struct formatter;

  // \ref{format.formattable}, concept \libconcept{formattable}
  template<class T, class charT>
    concept formattable = @\seebelow@;

  template<class R, class charT>
    concept @\defexposconcept{const-formattable-range}@ =                                   // \expos
      ranges::@\libconcept{input_range}@<const R> &&
      @\libconcept{formattable}@<ranges::range_reference_t<const R>, charT>;

  template<class R, class charT>
    using @\exposid{fmt-maybe-const}@ =                                             // \expos
      conditional_t<@\exposconcept{const-formattable-range}@<R, charT>, const R, R>;

  // \ref{format.parse.ctx}, class template \tcode{basic_format_parse_context}
  template<class charT> class basic_format_parse_context;
  using format_parse_context = basic_format_parse_context<char>;
  using wformat_parse_context = basic_format_parse_context<wchar_t>;

  // \ref{format.range}, formatting of ranges
  // \ref{format.range.fmtkind}, variable template \tcode{format_kind}
  enum class @\libglobal{range_format}@ {
    @\libmember{disabled}{range_format}@,
    @\libmember{map}{range_format}@,
    @\libmember{set}{range_format}@,
    @\libmember{sequence}{range_format}@,
    @\libmember{string}{range_format}@,
    @\libmember{debug_string}{range_format}@
  };

  template<class R>
    constexpr @\unspec@ format_kind = @\unspec@;

  template<ranges::@\libconcept{input_range}@ R>
      requires @\libconcept{same_as}@<R, remove_cvref_t<R>>
    constexpr range_format format_kind<R> = @\seebelow@;

  // \ref{format.range.formatter}, class template \tcode{range_formatter}
  template<class T, class charT = char>
    requires @\libconcept{same_as}@<remove_cvref_t<T>, T> && @\libconcept{formattable}@<T, charT>
  class range_formatter;

  // \ref{format.range.fmtdef}, class template \exposid{range-default-formatter}
  template<range_format K, ranges::@\libconcept{input_range}@ R, class charT>
    struct @\exposid{range-default-formatter}@;                                     // \expos

  // \ref{format.range.fmtmap}, \ref{format.range.fmtset}, \ref{format.range.fmtstr}, specializations for maps, sets, and strings
  template<ranges::@\libconcept{input_range}@ R, class charT>
    requires (format_kind<R> != range_format::disabled) &&
             @\libconcept{formattable}@<ranges::range_reference_t<R>, charT>
  struct formatter<R, charT> : @\exposid{range-default-formatter}@<format_kind<R>, R, charT> { };

  // \ref{format.arguments}, arguments
  // \ref{format.arg}, class template \tcode{basic_format_arg}
  template<class Context> class basic_format_arg;

  // \ref{format.arg.store}, class template \exposid{format-arg-store}
  template<class Context, class... Args> class @\exposidnc{format-arg-store}@;        // \expos

  template<class Context = format_context, class... Args>
    @\exposid{format-arg-store}@<Context, Args...>
      make_format_args(Args&... fmt_args);
  template<class... Args>
    @\exposid{format-arg-store}@<wformat_context, Args...>
      make_wformat_args(Args&... args);

  // \ref{format.error}, class \tcode{format_error}
  class format_error;
}
\end{codeblock}


\pnum
The class template \tcode{format_to_n_result}
has the template parameters, data members, and special members specified above. It has no base classes or members other than those specified.

\rSec2[format.string]{Format string}

\rSec3[format.string.general]{In general}

\pnum
A \defn{format string} for arguments \tcode{args} is
a (possibly empty) sequence of
\defnx{replacement fields}{replacement field!format string},
\defnx{escape sequences}{escape sequence!format string},
and characters other than \tcode{\{} and \tcode{\}}.
Let \tcode{charT} be the character type of the format string.
Each character that is not part of
a replacement field or an escape sequence
is copied unchanged to the output.
An escape sequence is one of \tcode{\{\{} or \tcode{\}\}}.
It is replaced with \tcode{\{} or \tcode{\}}, respectively, in the output.
The syntax of replacement fields is as follows:

\begin{ncbnf}
\fmtnontermdef{replacement-field}\br
    \terminal{\{} \opt{arg-id} \opt{format-specifier} \terminal{\}}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{arg-id}\br
    \terminal{0}\br
    positive-integer
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{positive-integer}\br
    nonzero-digit\br
    positive-integer digit
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{nonnegative-integer}\br
    digit\br
    nonnegative-integer digit
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{nonzero-digit} \textnormal{one of}\br
    \terminal{1 2 3 4 5 6 7 8 9}
\end{ncbnf}

% FIXME: This exactly duplicates the digit grammar term from [lex]
\begin{ncbnf}
\fmtnontermdef{digit} \textnormal{one of}\br
    \terminal{0 1 2 3 4 5 6 7 8 9}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{format-specifier}\br
    \terminal{:} format-spec
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{format-spec}\br
    \textnormal{as specified by the \tcode{formatter} specialization for the argument type; cannot start with \terminal{\}} }
\end{ncbnf}

\pnum
The \fmtgrammarterm{arg-id} field specifies the index of
the argument in \tcode{args}
whose value is to be formatted and inserted into the output
instead of the replacement field.
If there is no argument with
the index \fmtgrammarterm{arg-id} in \tcode{args},
the string is not a format string for \tcode{args}.
The optional \fmtgrammarterm{format-specifier} field
explicitly specifies a format for the replacement value.

\pnum
\begin{example}
\begin{codeblock}
string s = format("{0}-{{", 8);         // value of \tcode{s} is \tcode{"8-\{"}
\end{codeblock}
\end{example}

\pnum
If all \fmtgrammarterm{arg-id}s in a format string are omitted
(including those in the \fmtgrammarterm{format-spec},
as interpreted by the corresponding \tcode{formatter} specialization),
argument indices 0, 1, 2, \ldots{} will automatically be used in that order.
If some \fmtgrammarterm{arg-id}s are omitted and some are present,
the string is not a format string.
\begin{note}
A format string cannot contain a
mixture of automatic and manual indexing.
\end{note}
\begin{example}
\begin{codeblock}
string s0 = format("{} to {}",   "a", "b"); // OK, automatic indexing
string s1 = format("{1} to {0}", "a", "b"); // OK, manual indexing
string s2 = format("{0} to {}",  "a", "b"); // not a format string (mixing automatic and manual indexing),
                                            // ill-formed
string s3 = format("{} to {1}",  "a", "b"); // not a format string (mixing automatic and manual indexing),
                                            // ill-formed
\end{codeblock}
\end{example}

\pnum
The \fmtgrammarterm{format-spec} field contains
\defnx{format specifications}{format specification!format string}
that define how the value should be presented.
Each type can define its own
interpretation of the \fmtgrammarterm{format-spec} field.
If \fmtgrammarterm{format-spec} does not conform
to the format specifications for
the argument type referred to by \fmtgrammarterm{arg-id},
the string is not a format string for \tcode{args}.
\begin{example}
\begin{itemize}
\item
For arithmetic, pointer, and string types
the \fmtgrammarterm{format-spec}
is interpreted as a \fmtgrammarterm{std-format-spec}
as described in \iref{format.string.std}.
\item
For chrono types
the \fmtgrammarterm{format-spec}
is interpreted as a \fmtgrammarterm{chrono-format-spec}
as described in \iref{time.format}.
\item
For user-defined \tcode{formatter} specializations,
the behavior of the \tcode{parse} member function
determines how the \fmtgrammarterm{format-spec}
is interpreted.
\end{itemize}
\end{example}

\rSec3[format.string.std]{Standard format specifiers}

\pnum
Each \tcode{formatter} specialization
described in \ref{format.formatter.spec}
for fundamental and string types
interprets \fmtgrammarterm{format-spec} as a
\fmtgrammarterm{std-format-spec}.
\begin{note}
The format specification can be used to specify such details as
minimum field width, alignment, padding, and decimal precision.
Some of the formatting options
are only supported for arithmetic types.
\end{note}
The syntax of format specifications is as follows:

\begin{ncbnf}
\fmtnontermdef{std-format-spec}\br
    \opt{fill-and-align} \opt{sign} \opt{\terminal{\#}} \opt{\terminal{0}} \opt{width} \opt{precision} \opt{\terminal{L}} \opt{type}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{fill-and-align}\br
    \opt{fill} align
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{fill}\br
    \textnormal{any character other than \tcode{\{} or \tcode{\}}}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{align} \textnormal{one of}\br
    \terminal{< > \caret}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{sign} \textnormal{one of}\br
    \terminal{+ -} \textnormal{space}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{width}\br
    positive-integer\br
    \terminal{\{} \opt{arg-id} \terminal{\}}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{precision}\br
    \terminal{.} nonnegative-integer\br
    \terminal{.} \terminal{\{} \opt{arg-id} \terminal{\}}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{type} \textnormal{one of}\br
    \terminal{a A b B c d e E f F g G o p P s x X ?}
\end{ncbnf}

\pnum
Field widths are specified in \defnadj{field width}{units};
the number of column positions required to display a sequence of
characters in a terminal.
The \defnadj{minimum}{field width}
is the number of field width units a replacement field minimally requires of
the formatted sequence of characters produced for a format argument.
The \defnadj{estimated}{field width} is the number of field width units
that are required for the formatted sequence of characters
produced for a format argument independent of
the effects of the \fmtgrammarterm{width} option.
The \defnadj{padding}{width} is the greater of \tcode{0} and
the difference of the minimum field width and the estimated field width.

\begin{note}
The POSIX \tcode{wcswidth} function is an example of a function that,
given a string, returns the number of column positions required by
a terminal to display the string.
\end{note}

\pnum
The \defnadj{fill}{character} is the character denoted by
the \fmtgrammarterm{fill} option or,
if the \fmtgrammarterm{fill} option is absent, the space character.
For a format specification in UTF-8, UTF-16, or UTF-32,
the fill character corresponds to a single Unicode scalar value.
\begin{note}
The presence of a \fmtgrammarterm{fill} option
is signaled by the character following it,
which must be one of the alignment options.
If the second character of \fmtgrammarterm{std-format-spec}
is not a valid alignment option,
then it is assumed that
the \fmtgrammarterm{fill} and \fmtgrammarterm{align} options
are both absent.
\end{note}

\pnum
The \fmtgrammarterm{align} option applies to all argument types.
The meaning of the various alignment options is as specified in \tref{format.align}.
\begin{example}
\begin{codeblock}
char c = 120;
string s0 = format("{:6}", 42);             // value of \tcode{s0} is \tcode{"\ \ \ \ 42"}
string s1 = format("{:6}", 'x');            // value of \tcode{s1} is \tcode{"x\ \ \ \ \ "}
string s2 = format("{:*<6}", 'x');          // value of \tcode{s2} is \tcode{"x*****"}
string s3 = format("{:*>6}", 'x');          // value of \tcode{s3} is \tcode{"*****x"}
string s4 = format("{:*@\caret{}@6}", 'x');          // value of \tcode{s4} is \tcode{"**x***"}
string s5 = format("{:6d}", c);             // value of \tcode{s5} is \tcode{"\ \ \ 120"}
string s6 = format("{:6}", true);           // value of \tcode{s6} is \tcode{"true\ \ "}
string s7 = format("{:*<6.3}", "123456");   // value of \tcode{s7} is \tcode{"123***"}
string s8 = format("{:02}", 1234);          // value of \tcode{s8} is \tcode{"1234"}
string s9 = format("{:*<}", "12");          // value of \tcode{s9} is \tcode{"12"}
string sA = format("{:*<6}", "12345678");   // value of \tcode{sA} is \tcode{"12345678"}
string sB = format("{:@\importexample[-2pt]{example_05}\kern0.75pt\caret{}@6}", "x");         // value of \tcode{sB} is \tcode{"\importexample[-2pt]{example_05}\importexample[-2pt]{example_05}x\importexample[-2pt]{example_05}\importexample[-2pt]{example_05}\importexample[-2pt]{example_05}"}
string sC = format("{:*@\caret{}@6}", "@\importexample[-2pt]{example_05}\kern0.75pt\importexample[-2pt]{example_05}\kern0.75pt\importexample[-2pt]{example_05}\kern0.75pt@");     // value of \tcode{sC} is \tcode{"\importexample[-2pt]{example_05}\importexample[-2pt]{example_05}\importexample[-2pt]{example_05}"}
\end{codeblock}
\end{example}
\begin{note}
The \fmtgrammarterm{fill}, \fmtgrammarterm{align}, and \tcode{0} options
have no effect when the minimum field width
is not greater than the estimated field width
because padding width is \tcode{0} in that case.
Since fill characters are assumed to have a field width of \tcode{1},
use of a character with a different field width can produce misaligned output.
The \importexample[-2pt]{example_05} (\unicode{1f921}{clown face}) character has a field width of \tcode{2}.
The examples above that include that character
illustrate the effect of the field width
when that character is used as a fill character
as opposed to when it is used as a formatting argument.
\end{note}

\begin{floattable}{Meaning of \fmtgrammarterm{align} options}{format.align}{lp{.8\hsize}}
\topline
\lhdr{Option} & \rhdr{Meaning} \\ \rowsep
\tcode{<} &
Forces the formatted argument to be aligned to the start of the field
by inserting $n$ fill characters after the formatted argument
where $n$ is the padding width.
This is the default for
non-arithmetic non-pointer types, \tcode{charT}, and \tcode{bool},
unless an integer presentation type is specified.
\\ \rowsep
%
\tcode{>} &
Forces the formatted argument to be aligned to the end of the field
by inserting $n$ fill characters before the formatted argument
where $n$ is the padding width.
This is the default for
arithmetic types other than \tcode{charT} and \tcode{bool},
pointer types,
or when an integer presentation type is specified.
\\ \rowsep
%
\tcode{\caret} &
Forces the formatted argument to be centered within the field
by inserting
$\bigl\lfloor \frac{n}{2} \bigr\rfloor$
fill characters before and
$\bigl\lceil \frac{n}{2} \bigr\rceil$
fill characters after the formatted argument, where
$n$ is the padding width.
\\
\end{floattable}

\pnum
The \fmtgrammarterm{sign} option is only valid
for arithmetic types other than \tcode{charT} and \tcode{bool}
or when an integer presentation type is specified.
The meaning of the various options is as specified in \tref{format.sign}.

\begin{floattable}{Meaning of \fmtgrammarterm{sign} options}{format.sign}{lp{.8\hsize}}
\topline
\lhdr{Option} & \rhdr{Meaning} \\ \rowsep
\tcode{+} &
Indicates that a sign should be used for both non-negative and negative
numbers.
The \tcode{+} sign is inserted before the output of \tcode{to_chars} for
non-negative numbers other than negative zero.
\begin{tailnote}
For negative numbers and negative zero
the output of \tcode{to_chars} will already contain the sign
so no additional transformation is performed.
\end{tailnote}
\\ \rowsep
%
\tcode{-} &
Indicates that a sign should be used for
negative numbers and negative zero only (this is the default behavior).
\\ \rowsep
%
space &
Indicates that a leading space should be used for
non-negative numbers other than negative zero, and
a minus sign for negative numbers and negative zero.
\\
\end{floattable}

\pnum
The \fmtgrammarterm{sign} option applies to floating-point infinity and NaN.
\begin{example}
\begin{codeblock}
double inf = numeric_limits<double>::infinity();
double nan = numeric_limits<double>::quiet_NaN();
string s0 = format("{0:},{0:+},{0:-},{0: }", 1);        // value of \tcode{s0} is \tcode{"1,+1,1, 1"}
string s1 = format("{0:},{0:+},{0:-},{0: }", -1);       // value of \tcode{s1} is \tcode{"-1,-1,-1,-1"}
string s2 = format("{0:},{0:+},{0:-},{0: }", inf);      // value of \tcode{s2} is \tcode{"inf,+inf,inf, inf"}
string s3 = format("{0:},{0:+},{0:-},{0: }", nan);      // value of \tcode{s3} is \tcode{"nan,+nan,nan, nan"}
\end{codeblock}
\end{example}

\pnum
The \tcode{\#} option causes the
% FIXME: This is not a definition.
\defnx{alternate form}{alternate form!format string}
to be used for the conversion.
This option is valid for arithmetic types other than
\tcode{charT} and \tcode{bool}
or when an integer presentation type is specified, and not otherwise.
For integral types,
the alternate form inserts the
base prefix (if any) specified in \tref{format.type.int}
into the output after the sign character (possibly space) if there is one, or
before the output of \tcode{to_chars} otherwise.
For floating-point types,
the alternate form causes the result of the conversion of finite values
to always contain a decimal-point character,
even if no digits follow it.
% FIXME: This is a weird place for this part of the spec to appear.
Normally, a decimal-point character appears in the result of these
conversions only if a digit follows it.
In addition, for \tcode{g} and \tcode{G} conversions,
% FIXME: Are they normally? What does this even mean? Reach into to_chars and
% alter its behavior?
trailing zeros are not removed from the result.

\pnum
The \tcode{0} option is valid for arithmetic types
other than \tcode{charT} and \tcode{bool}, pointer types, or
when an integer presentation type is specified.
For formatting arguments that have a value
other than an infinity or a NaN,
this option pads the formatted argument by
inserting the \tcode{0} character $n$ times
following the sign or base prefix indicators (if any)
where $n$ is \tcode{0} if the \fmtgrammarterm{align} option is present and
is the padding width otherwise.
\begin{example}
\begin{codeblock}
char c = 120;
string s1 = format("{:+06d}", c);       // value of \tcode{s1} is \tcode{"+00120"}
string s2 = format("{:#06x}", 0xa);     // value of \tcode{s2} is \tcode{"0x000a"}
string s3 = format("{:<06}", -42);      // value of \tcode{s3} is \tcode{"-42\ \ \ "} (\tcode{0} has no effect)
string s4 = format("{:06}", inf);       // value of \tcode{s4} is \tcode{"\ \ \ inf"} (\tcode{0} has no effect)
\end{codeblock}
\end{example}

\pnum
The \fmtgrammarterm{width} option specifies the minimum field width.
If the \fmtgrammarterm{width} option is absent,
the minimum field width is \tcode{0}.

\pnum
If \tcode{\{ \opt{\fmtgrammarterm{arg-id}} \}} is used in
a \fmtgrammarterm{width} or \fmtgrammarterm{precision} option,
the value of the corresponding formatting argument is used as the value of the option.
The option is valid only if the corresponding formatting argument is
of standard signed or unsigned integer type.
If its value is negative,
an exception of type \tcode{format_error} is thrown.

\pnum
% FIXME: What if it's an arg-id?
If \fmtgrammarterm{positive-integer} is used in a
\fmtgrammarterm{width} option, the value of the \fmtgrammarterm{positive-integer}
is interpreted as a decimal integer and used as the value of the option.

\pnum
For the purposes of width computation,
a string is assumed to be in
a locale-independent,
\impldef{encoding assumption for \tcode{format} width computation} encoding.
Implementations should use either UTF-8, UTF-16, or UTF-32,
on platforms capable of displaying Unicode text in a terminal.
\begin{note}
This is the case for Windows
\begin{footnote}
Windows\textregistered\ is a registered trademark of Microsoft Corporation.
This information is given for the convenience of users of this document and
does not constitute an endorsement by ISO or IEC of this product.
\end{footnote}%
-based and
many POSIX-based operating systems.
\end{note}

\pnum
For a sequence of characters in UTF-8, UTF-16, or UTF-32,
an implementation should use as its field width
the sum of the field widths of the first code point
of each extended grapheme cluster.
Extended grapheme clusters are defined by \UAX{29} of the Unicode Standard.
The following code points have a field width of 2:
\begin{itemize}
\item
any code point with the \tcode{East_Asian_Width="W"} or
\tcode{East_Asian_Width="F"} Derived Extracted Property as described by
\UAX{44} of the Unicode Standard
\item
\ucode{4dc0} -- \ucode{4dff} (Yijing Hexagram Symbols)
\item
\ucode{1f300} -- \ucode{1f5ff} (Miscellaneous Symbols and Pictographs)
\item
\ucode{1f900} -- \ucode{1f9ff} (Supplemental Symbols and Pictographs)
\end{itemize}
The field width of all other code points is 1.

\pnum
For a sequence of characters in neither UTF-8, UTF-16, nor UTF-32,
the field width is unspecified.

\pnum
The \fmtgrammarterm{precision} option is valid
for floating-point and string types.
For floating-point types,
the value of this option specifies the precision
to be used for the floating-point presentation type.
For string types,
this option specifies the longest prefix of the formatted argument
to be included in the replacement field such that
the field width of the prefix is no greater than the value of this option.

\pnum
If \fmtgrammarterm{nonnegative-integer} is used in
a \fmtgrammarterm{precision} option,
the value of the decimal integer is used as the value of the option.

\pnum
When the \tcode{L} option is used, the form used for the conversion is called
the \defnx{locale-specific form}{locale-specific form!format string}.
The \tcode{L} option is only valid for arithmetic types, and
its effect depends upon the type.
\begin{itemize}
\item
For integral types, the locale-specific form
causes the context's locale to be used
to insert the appropriate digit group separator characters.

\item
For floating-point types, the locale-specific form
causes the context's locale to be used
to insert the appropriate digit group and radix separator characters.

\item
For the textual representation of \tcode{bool}, the locale-specific form
causes the context's locale to be used
to insert the appropriate string as if obtained
with \tcode{numpunct::truename} or \tcode{numpunct::falsename}.
\end{itemize}

\pnum
The \fmtgrammarterm{type} determines how the data should be presented.

\pnum
% FIXME: What is a "string" here, exactly?
The available string presentation types are specified in \tref{format.type.string}.
%
\begin{floattable}{Meaning of \fmtgrammarterm{type} options for strings}{format.type.string}{ll}
\topline
\lhdr{Type} & \rhdr{Meaning} \\ \rowsep
none, \tcode{s} &
Copies the string to the output.
\\ \rowsep
%
\tcode{?} &
Copies the escaped string\iref{format.string.escaped} to the output.
\\
\end{floattable}

\pnum
The meaning of some non-string presentation types
is defined in terms of a call to \tcode{to_chars}.
In such cases,
let \range{first}{last} be a range
large enough to hold the \tcode{to_chars} output
and \tcode{value} be the formatting argument value.
Formatting is done as if by calling \tcode{to_chars} as specified
and copying the output through the output iterator of the format context.
\begin{note}
Additional padding and adjustments are performed
prior to copying the output through the output iterator
as specified by the format specifiers.
\end{note}

\pnum
The available integer presentation types
for integral types other than \tcode{bool} and \tcode{charT}
are specified in \tref{format.type.int}.
\begin{example}
\begin{codeblock}
string s0 = format("{}", 42);                           // value of \tcode{s0} is \tcode{"42"}
string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42);      // value of \tcode{s1} is \tcode{"101010 42 52 2a"}
string s2 = format("{0:#x} {0:#X}", 42);                // value of \tcode{s2} is \tcode{"0x2a 0X2A"}
string s3 = format("{:L}", 1234);                       // value of \tcode{s3} can be \tcode{"1,234"}
                                                        // (depending on the locale)
\end{codeblock}
\end{example}

\begin{floattable}{Meaning of \fmtgrammarterm{type} options for integer types}{format.type.int}{lp{.8\hsize}}
\topline
\lhdr{Type} & \rhdr{Meaning} \\ \rowsep
\tcode{b} &
\tcode{to_chars(first, last, value, 2)};
\indextext{base prefix}%
the base prefix is \tcode{0b}.
\\ \rowsep
%
\tcode{B} &
The same as \tcode{b}, except that
\indextext{base prefix}%
the base prefix is \tcode{0B}.
\\ \rowsep
%
\tcode{c} &
Copies the character \tcode{static_cast<charT>(value)} to the output.
Throws \tcode{format_error} if \tcode{value} is not
in the range of representable values for \tcode{charT}.
\\ \rowsep
%
\tcode{d} &
\tcode{to_chars(first, last, value)}.
\\ \rowsep
%
\tcode{o} &
\tcode{to_chars(first, last, value, 8)};
\indextext{base prefix}%
the base prefix is \tcode{0} if \tcode{value} is nonzero and is empty otherwise.
\\ \rowsep
%
\tcode{x} &
\tcode{to_chars(first, last, value, 16)};
\indextext{base prefix}%
the base prefix is \tcode{0x}.
\\ \rowsep
%
\tcode{X} &
The same as \tcode{x}, except that
it uses uppercase letters for digits above 9 and
\indextext{base prefix}%
the base prefix is \tcode{0X}.
\\ \rowsep
%
none &
The same as \tcode{d}.
\begin{tailnote}
If the formatting argument type is \tcode{charT} or \tcode{bool},
the default is instead \tcode{c} or \tcode{s}, respectively.
\end{tailnote}
\\
\end{floattable}

\pnum
The available \tcode{charT} presentation types are specified in \tref{format.type.char}.
%
\begin{floattable}{Meaning of \fmtgrammarterm{type} options for \tcode{charT}}{format.type.char}{lp{.8\hsize}}
\topline
\lhdr{Type} & \rhdr{Meaning} \\ \rowsep
none, \tcode{c} &
Copies the character to the output.
\\ \rowsep
%
\tcode{b}, \tcode{B}, \tcode{d}, \tcode{o}, \tcode{x}, \tcode{X} &
As specified in \tref{format.type.int}
with \tcode{value} converted to the unsigned version of the underlying type.
\\ \rowsep
%
\tcode{?} &
Copies the escaped character\iref{format.string.escaped} to the output.
\\
\end{floattable}

\pnum
The available \tcode{bool} presentation types are specified in \tref{format.type.bool}.
%
\begin{floattable}{Meaning of \fmtgrammarterm{type} options for \tcode{bool}}{format.type.bool}{ll}
\topline
\lhdr{Type} & \rhdr{Meaning} \\ \rowsep
none,
\tcode{s} &
Copies textual representation, either \tcode{true} or \tcode{false}, to the output.
\\ \rowsep
%
\tcode{b}, \tcode{B}, \tcode{d}, \tcode{o}, \tcode{x}, \tcode{X} &
As specified in \tref{format.type.int}
for the value
\tcode{static_cast<unsigned char>(value)}.
\\
\end{floattable}

\pnum
The available floating-point presentation types and their meanings
for values other than infinity and NaN are
specified in \tref{format.type.float}.
For lower-case presentation types, infinity and NaN are formatted as
\tcode{inf} and \tcode{nan}, respectively.
For upper-case presentation types, infinity and NaN are formatted as
\tcode{INF} and \tcode{NAN}, respectively.
\begin{note}
In either case, a sign is included
if indicated by the \fmtgrammarterm{sign} option.
\end{note}

\begin{floattable}{Meaning of \fmtgrammarterm{type} options for floating-point types}{format.type.float}{lp{.8\hsize}}
\topline
\lhdr{Type} & \rhdr{Meaning} \\ \rowsep
\tcode{a} &
If \fmtgrammarterm{precision} is specified, equivalent to
\begin{codeblock}
to_chars(first, last, value, chars_format::hex, precision)
\end{codeblock}
where \tcode{precision} is the specified formatting precision; equivalent to
\begin{codeblock}
to_chars(first, last, value, chars_format::hex)
\end{codeblock}
otherwise.
\\
\rowsep
%
\tcode{A} &
The same as \tcode{a}, except that
it uses uppercase letters for digits above 9 and
\tcode{P} to indicate the exponent.
\\ \rowsep
%
\tcode{e} &
Equivalent to
\begin{codeblock}
to_chars(first, last, value, chars_format::scientific, precision)
\end{codeblock}
where \tcode{precision} is the specified formatting precision,
or \tcode{6} if \fmtgrammarterm{precision} is not specified.
\\ \rowsep
%
\tcode{E} &
The same as \tcode{e}, except that it uses \tcode{E} to indicate exponent.
\\ \rowsep
%
\tcode{f}, \tcode{F} &
Equivalent to
\begin{codeblock}
to_chars(first, last, value, chars_format::fixed, precision)
\end{codeblock}
where \tcode{precision} is the specified formatting precision,
or \tcode{6} if \fmtgrammarterm{precision} is not specified.
\\ \rowsep
%
\tcode{g} &
Equivalent to
\begin{codeblock}
to_chars(first, last, value, chars_format::general, precision)
\end{codeblock}
where \tcode{precision} is the specified formatting precision,
or \tcode{6} if \fmtgrammarterm{precision} is not specified.
\\ \rowsep
%
\tcode{G} &
The same as \tcode{g}, except that
it uses \tcode{E} to indicate exponent.
\\ \rowsep
%
none &
If \fmtgrammarterm{precision} is specified, equivalent to
\begin{codeblock}
to_chars(first, last, value, chars_format::general, precision)
\end{codeblock}
where \tcode{precision} is the specified formatting precision; equivalent to
\begin{codeblock}
to_chars(first, last, value)
\end{codeblock}
otherwise.
\\
\end{floattable}

\pnum
The available pointer presentation types and their mapping to
\tcode{to_chars} are specified in \tref{format.type.ptr}.
\begin{note}
Pointer presentation types also apply to \tcode{nullptr_t}.
\end{note}

\begin{floattable}{Meaning of \fmtgrammarterm{type} options for pointer types}{format.type.ptr}{lp{.8\hsize}}
\topline
\lhdr{Type} & \rhdr{Meaning} \\ \rowsep
none, \tcode{p} &
If \tcode{uintptr_t} is defined,
\begin{codeblock}
to_chars(first, last, reinterpret_cast<uintptr_t>(value), 16)
\end{codeblock}
with the prefix \tcode{0x} inserted immediately before the output of \tcode{to_chars};
otherwise, implementation-defined.
\\ \rowsep
\tcode{P} &
The same as \tcode{p},
except that it uses uppercase letters for digits above \tcode{9} and
the base prefix is \tcode{0X}.
\\
\end{floattable}

\rSec2[format.err.report]{Error reporting}

\pnum
Formatting functions throw \tcode{format_error} if
an argument \tcode{fmt} is passed that
is not a format string for \tcode{args}.
They propagate exceptions thrown by operations of
\tcode{formatter} specializations and iterators.
Failure to allocate storage is reported by
throwing an exception as described in~\ref{res.on.exception.handling}.

\rSec2[format.fmt.string]{Class template \tcode{basic_format_string}}

\begin{codeblock}
namespace std {
  template<class charT, class... Args>
  struct @\libglobal{basic_format_string}@ {
  private:
    basic_string_view<charT> @\exposidnc{str}@;         // \expos

  public:
    template<class T> consteval basic_format_string(const T& s);
    basic_format_string(@\exposid{runtime-format-string}@<charT> s) noexcept : str(s.@\exposid{str}@) {}

    constexpr basic_string_view<charT> get() const noexcept { return @\exposid{str}@; }
  };
}
\end{codeblock}

\begin{itemdecl}
template<class T> consteval basic_format_string(const T& s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{const T\&} models \tcode{\libconcept{convertible_to}<basic_string_view<charT>>}.

\pnum
\effects
Direct-non-list-initializes \exposid{str} with \tcode{s}.

\pnum
\remarks
A call to this function is not a core constant expression\iref{expr.const}
unless there exist \tcode{args} of types \tcode{Args}
such that \exposid{str} is a format string for \tcode{args}.
\end{itemdescr}

\rSec2[format.functions]{Formatting functions}

\pnum
In the description of the functions, operator \tcode{+} is used
for some of the iterator categories for which it does not have to be defined.
In these cases the semantics of \tcode{a + n} are
the same as in \ref{algorithms.requirements}.

\indexlibraryglobal{format}%
\begin{itemdecl}
template<class... Args>
  string format(format_string<Args...> fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat(fmt.@\exposid{str}@, make_format_args(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{format}%
\begin{itemdecl}
template<class... Args>
  wstring format(wformat_string<Args...> fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat(fmt.@\exposid{str}@, make_wformat_args(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{format}%
\begin{itemdecl}
template<class... Args>
  string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat(loc, fmt.@\exposid{str}@, make_format_args(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{format}%
\begin{itemdecl}
template<class... Args>
  wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat(loc, fmt.@\exposid{str}@, make_wformat_args(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{vformat}%
\begin{itemdecl}
string vformat(string_view fmt, format_args args);
wstring vformat(wstring_view fmt, wformat_args args);
string vformat(const locale& loc, string_view fmt, format_args args);
wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A string object holding the character representation of
formatting arguments provided by \tcode{args} formatted according to
specifications given in \tcode{fmt}.
If present, \tcode{loc} is used for locale-specific formatting.

\pnum
\throws
As specified in~\ref{format.err.report}.
\end{itemdescr}

\indexlibraryglobal{format_to}%
\begin{itemdecl}
template<class Out, class... Args>
  Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat_to(std::move(out), fmt.@\exposid{str}@, make_format_args(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{format_to}%
\begin{itemdecl}
template<class Out, class... Args>
  Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat_to(std::move(out), fmt.@\exposid{str}@, make_wformat_args(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{format_to}%
\begin{itemdecl}
template<class Out, class... Args>
  Out format_to(Out out, const locale& loc, format_string<Args...>  fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat_to(std::move(out), loc, fmt.@\exposid{str}@, make_format_args(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{format_to}%
\begin{itemdecl}
template<class Out, class... Args>
  Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat_to(std::move(out), loc, fmt.@\exposid{str}@, make_wformat_args(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{vformat_to}%
\begin{itemdecl}
template<class Out>
  Out vformat_to(Out out, string_view fmt, format_args args);
template<class Out>
  Out vformat_to(Out out, wstring_view fmt, wformat_args args);
template<class Out>
  Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
template<class Out>
  Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{charT} be \tcode{decltype(fmt)::value_type}.

\pnum
\constraints
\tcode{Out} satisfies \tcode{\libconcept{output_iterator}<const charT\&>}.

\pnum
\expects
\tcode{Out} models \tcode{\libconcept{output_iterator}<const charT\&>}.

\pnum
\effects
Places the character representation of formatting
the arguments provided by \tcode{args},
formatted according to the specifications given in \tcode{fmt},
into the range \range{out}{out + N},
where \tcode{N} is the number of characters in that character representation.
If present, \tcode{loc} is used for locale-specific formatting.

\pnum
\returns
\tcode{out + N}.

\pnum
\throws
As specified in~\ref{format.err.report}.
\end{itemdescr}

\indexlibraryglobal{format_to_n}%
\begin{itemdecl}
template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                      format_string<Args...> fmt, Args&&... args);
template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                      wformat_string<Args...> fmt, Args&&... args);
template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                      const locale& loc, format_string<Args...> fmt,
                                      Args&&... args);
template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                      const locale& loc, wformat_string<Args...> fmt,
                                      Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let
\begin{itemize}
\item \tcode{charT} be \tcode{decltype(fmt.\exposid{str})::value_type},
\item \tcode{N} be
\tcode{formatted_size(fmt, args...)} for the functions without a \tcode{loc} parameter and
\tcode{formatted_size(loc, fmt, args...)} for the functions with a \tcode{loc} parameter, and
\item \tcode{M} be \tcode{clamp(n, 0, N)}.
\end{itemize}

\pnum
\constraints
\tcode{Out} satisfies \tcode{\libconcept{output_iterator}<const charT\&>}.

\pnum
\expects
\tcode{Out} models \tcode{\libconcept{output_iterator}<const charT\&>}, and
\tcode{formatter<}$\tcode{remove_cvref_t<T}_i$\tcode{>, charT>}
meets the \newoldconcept{BasicFormatter} requirements\iref{formatter.requirements}
for each $\tcode{T}_i$ in \tcode{Args}.

\pnum
\effects
Places the first \tcode{M} characters of the character representation of
formatting the arguments provided by \tcode{args},
formatted according to the specifications given in \tcode{fmt},
into the range \range{out}{out + M}.
If present, \tcode{loc} is used for locale-specific formatting.

\pnum
\returns
\tcode{\{out + M, N\}}.

\pnum
\throws
As specified in~\ref{format.err.report}.
\end{itemdescr}

\indexlibraryglobal{formatted_size}%
\begin{itemdecl}
template<class... Args>
  size_t formatted_size(format_string<Args...> fmt, Args&&... args);
template<class... Args>
  size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
template<class... Args>
  size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
template<class... Args>
  size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{charT} be \tcode{decltype(fmt.\exposid{str})::value_type}.

\pnum
\expects
\tcode{formatter<}$\tcode{remove_cvref_t<T}_i$\tcode{>, charT>}
meets the \newoldconcept{BasicFormatter} requirements\iref{formatter.requirements}
for each $\tcode{T}_i$ in \tcode{Args}.

\pnum
\returns
The number of characters in the character representation of
formatting arguments \tcode{args}
formatted according to specifications given in \tcode{fmt}.
If present, \tcode{loc} is used for locale-specific formatting.

\pnum
\throws
As specified in~\ref{format.err.report}.
\end{itemdescr}

\rSec2[format.formatter]{Formatter}

\rSec3[formatter.requirements]{Formatter requirements}

\pnum
A type \tcode{F} meets the \defnnewoldconcept{BasicFormatter} requirements if
it meets the
\begin{itemize}
\item \oldconcept{DefaultConstructible} (\tref{cpp17.defaultconstructible}),
\item \oldconcept{CopyConstructible} (\tref{cpp17.copyconstructible}),
\item \oldconcept{CopyAssignable} (\tref{cpp17.copyassignable}),
\item \oldconcept{Swappable}\iref{swappable.requirements}, and
\item \oldconcept{Destructible} (\tref{cpp17.destructible})
\end{itemize}
requirements, and
the expressions shown in \tref{formatter.basic} are valid and
have the indicated semantics.

\pnum
A type \tcode{F} meets the \defnnewoldconcept{Formatter} requirements
if it meets the \newoldconcept{BasicFormatter} requirements and
the expressions shown in \tref{formatter} are valid and
have the indicated semantics.

\pnum
Given character type \tcode{charT}, output iterator type
\tcode{Out}, and formatting argument type \tcode{T},
in \tref{formatter.basic} and \tref{formatter}:
\begin{itemize}
\item \tcode{f} is a value of type (possibly const) \tcode{F},
\item \tcode{g} is an lvalue of type \tcode{F},
\item \tcode{u} is an lvalue of type \tcode{T},
\item \tcode{t} is a value of a type convertible to (possibly const) \tcode{T},
\item \tcode{PC} is \tcode{basic_format_parse_context<charT>},
\item \tcode{FC} is \tcode{basic_format_context<Out, charT>},
\item \tcode{pc} is an lvalue of type \tcode{PC}, and
\item \tcode{fc} is an lvalue of type \tcode{FC}.
\end{itemize}
\tcode{pc.begin()} points to the beginning of the
\fmtgrammarterm{format-spec}\iref{format.string}
of the replacement field being formatted
in the format string.
If \fmtgrammarterm{format-spec} is not present or empty then either
\tcode{pc.begin() == pc.end()} or
\tcode{*pc.begin() == '\}'}.

\begin{concepttable}{\newoldconcept{BasicFormatter} requirements}{formatter.basic}
{p{1.2in}p{1in}p{2.9in}}
\topline
\hdstyle{Expression} & \hdstyle{Return type} & \hdstyle{Requirement} \\ \capsep
\tcode{g.parse(pc)} &
\tcode{PC::iterator} &
Parses \fmtgrammarterm{format-spec}\iref{format.string}
for type \tcode{T}
in the range \range{pc.begin()}{pc.end()}
until the first unmatched character.
Throws \tcode{format_error} unless the whole range is parsed
or the unmatched character is \tcode{\}}.
\begin{note}
This allows formatters to emit meaningful error messages.
\end{note}
Stores the parsed format specifiers in \tcode{*this} and
returns an iterator past the end of the parsed range.
\\ \rowsep
\tcode{f.format(u, fc)} &
\tcode{FC::iterator} &
Formats \tcode{u} according to the specifiers stored in \tcode{*this},
writes the output to \tcode{fc.out()}, and
returns an iterator past the end of the output range.
The output shall only depend on
\tcode{u},
\tcode{fc.locale()},
\tcode{fc.arg(n)} for any value \tcode{n} of type \tcode{size_t},
and the range \range{pc.begin()}{pc.end()}
from the last call to \tcode{f.parse(pc)}.
\\
\end{concepttable}

\begin{concepttable}{\newoldconcept{Formatter} requirements}{formatter}
{p{1.2in}p{1in}p{2.9in}}
\topline
\hdstyle{Expression} & \hdstyle{Return type} & \hdstyle{Requirement} \\ \capsep
\tcode{f.format(t, fc)} &
\tcode{FC::iterator} &
Formats \tcode{t} according to the specifiers stored in \tcode{*this},
writes the output to \tcode{fc.out()}, and
returns an iterator past the end of the output range.
The output shall only depend on
\tcode{t},
\tcode{fc.locale()},
\tcode{fc.arg(n)} for any value \tcode{n} of type \tcode{size_t},
and the range \range{pc.begin()}{pc.end()}
from the last call to \tcode{f.parse(pc)}.
\\ \rowsep
\tcode{f.format(u, fc)} &
\tcode{FC::iterator} &
As above, but does not modify \tcode{u}.
\\
\end{concepttable}

\rSec3[format.formattable]{Concept \cname{formattable}}

\pnum
Let \tcode{\placeholder{fmt-iter-for}<charT>} be an unspecified type
that models
\tcode{\libconcept{output_iterator}<const charT\&>}\iref{iterator.concept.output}.

\begin{codeblock}
template<class T, class Context,
         class Formatter = typename Context::template formatter_type<remove_const_t<T>>>
  concept @\defexposconcept{formattable-with}@ =                // \expos
    @\libconcept{semiregular}@<Formatter> &&
    requires(Formatter& f, const Formatter& cf, T&& t, Context fc,
             basic_format_parse_context<typename Context::char_type> pc)
    {
      { f.parse(pc) } -> @\libconcept{same_as}@<typename decltype(pc)::iterator>;
      { cf.format(t, fc) } -> @\libconcept{same_as}@<typename Context::iterator>;
    };

template<class T, class charT>
  concept @\deflibconcept{formattable}@ =
    @\exposconcept{formattable-with}@<remove_reference_t<T>, basic_format_context<@\placeholder{fmt-iter-for}@<charT>, charT>>;
\end{codeblock}

\pnum
A type \tcode{T} and a character type \tcode{charT}
model \libconcept{formattable}
if \tcode{formatter<remove_cvref_t<T>, charT>} meets
the \newoldconcept{BasicFormatter} requirements\iref{formatter.requirements}
and, if \tcode{remove_reference_t<T>} is const-qualified,
the \newoldconcept{Formatter} requirements.

\rSec3[format.formatter.spec]{Formatter specializations}
\indexlibraryglobal{formatter}%

\pnum
% FIXME: Specify this in [format.functions], not here!
The functions defined in \ref{format.functions} use
specializations of the class template \tcode{formatter} to format
individual arguments.

\pnum
Let \tcode{charT} be either \tcode{char} or \keyword{wchar_t}.
Each specialization of \tcode{formatter} is either enabled or disabled,
as described below.
\indextext{\idxcode{formatter}!debug-enabled specialization of}%
A \defn{debug-enabled} specialization of \tcode{formatter}
additionally provides
a public, constexpr, non-static member function \tcode{set_debug_format()}
which modifies the state of the \tcode{formatter} to be as if
the type of the \fmtgrammarterm{std-format-spec}
parsed by the last call to \tcode{parse} were \tcode{?}.
Each header that declares the template \tcode{formatter}
provides the following enabled specializations:
\begin{itemize}
\item
\indexlibrary{\idxcode{formatter}!specializations!character types}%
The debug-enabled specializations
\begin{codeblock}
template<> struct formatter<char, char>;
template<> struct formatter<char, wchar_t>;
template<> struct formatter<wchar_t, wchar_t>;
\end{codeblock}

\item
\indexlibrary{\idxcode{formatter}!specializations!string types}%
For each \tcode{charT},
the debug-enabled string type specializations
\begin{codeblock}
template<> struct formatter<charT*, charT>;
template<> struct formatter<const charT*, charT>;
template<size_t N> struct formatter<charT[N], charT>;
template<class traits, class Allocator>
  struct formatter<basic_string<charT, traits, Allocator>, charT>;
template<class traits>
  struct formatter<basic_string_view<charT, traits>, charT>;
\end{codeblock}

\item
\indexlibrary{\idxcode{formatter}!specializations!arithmetic types}%
For each \tcode{charT},
for each cv-unqualified arithmetic type \tcode{ArithmeticT}
other than
\tcode{char},
\keyword{wchar_t},
\keyword{char8_t},
\keyword{char16_t}, or
\keyword{char32_t},
a specialization
\begin{codeblock}
template<> struct formatter<ArithmeticT, charT>;
\end{codeblock}

\item
\indexlibrary{\idxcode{formatter}!specializations!pointer types}%
\indexlibrary{\idxcode{formatter}!specializations!\idxcode{nullptr_t}}%
For each \tcode{charT},
the pointer type specializations
\begin{codeblock}
template<> struct formatter<nullptr_t, charT>;
template<> struct formatter<void*, charT>;
template<> struct formatter<const void*, charT>;
\end{codeblock}
\end{itemize}
The \tcode{parse} member functions of these formatters
interpret the format specification
as a \fmtgrammarterm{std-format-spec}
as described in \ref{format.string.std}.
\begin{note}
Specializations such as \tcode{formatter<wchar_t, char>}
and \tcode{formatter<const char*, wchar_t>}
that would require implicit
multibyte / wide string or character conversion are disabled.
\end{note}

\pnum
For any types \tcode{T} and \tcode{charT} for which
neither the library nor the user provides
an explicit or partial specialization of
the class template \tcode{formatter},
\tcode{formatter<T, charT>} is disabled.

\pnum
If the library provides an explicit or partial specialization of
\tcode{formatter<T, charT>}, that specialization is enabled
and meets the \newoldconcept{Formatter} requirements
except as noted otherwise.

\pnum
If \tcode{F} is a disabled specialization of \tcode{formatter}, these
values are \tcode{false}:
\begin{itemize}
\item \tcode{is_default_constructible_v<F>},
\item \tcode{is_copy_constructible_v<F>},
\item \tcode{is_move_constructible_v<F>},
\item \tcode{is_copy_assignable_v<F>}, and
\item \tcode{is_move_assignable_v<F>}.
\end{itemize}

\pnum
An enabled specialization \tcode{formatter<T, charT>} meets the
\newoldconcept{BasicFormatter} requirements\iref{formatter.requirements}.
\begin{example}
\begin{codeblock}
#include <format>
#include <string>

enum color { red, green, blue };
const char* color_names[] = { "red", "green", "blue" };

template<> struct std::formatter<color> : std::formatter<const char*> {
  auto format(color c, format_context& ctx) const {
    return formatter<const char*>::format(color_names[c], ctx);
  }
};

struct err {};

std::string s0 = std::format("{}", 42);         // OK, library-provided formatter
std::string s1 = std::format("{}", L"foo");     // error: disabled formatter
std::string s2 = std::format("{}", red);        // OK, user-provided formatter
std::string s3 = std::format("{}", err{});      // error: disabled formatter
\end{codeblock}
\end{example}

\rSec3[format.string.escaped]{Formatting escaped characters and strings}

\pnum
\indextext{string!formatted as escaped}%
\indextext{character!formatted as escaped}%
A character or string can be formatted as \defn{escaped}
to make it more suitable for debugging or for logging.

\pnum
The escaped string \placeholder{E} representation of a string \placeholder{S}
is constructed by encoding a sequence of characters as follows.
The associated character encoding \placeholder{CE}
for \tcode{charT}~(\tref{lex.string.literal})
is used to both interpret \placeholder{S} and construct \placeholder{E}.

\begin{itemize}
\item
\unicode{0022}{quotation mark} (\tcode{"}) is appended to \placeholder{E}.

\item
For each code unit sequence \placeholder{X} in \placeholder{S} that either
encodes a single character,
is a shift sequence, or
is a sequence of ill-formed code units,
processing is in order as follows:

\begin{itemize}
\item
If \placeholder{X} encodes a single character \placeholder{C}, then:

\begin{itemize}
\item
If \placeholder{C} is one of the characters in \tref{format.escape.sequences},
then the two characters shown as the corresponding escape sequence
are appended to \placeholder{E}.

\item
Otherwise, if \placeholder{C} is not \unicode{0020}{space} and

\begin{itemize}
\item
\placeholder{CE} is UTF-8, UTF-16, or UTF-32 and
\placeholder{C} corresponds to a Unicode scalar value
whose Unicode property \tcode{General_Category} has a value in the groups
\tcode{Separator} (\tcode{Z}) or \tcode{Other} (\tcode{C}),
as described by \UAX{44} of the Unicode Standard, or

\item
\placeholder{CE} is UTF-8, UTF-16, or UTF-32 and
\placeholder{C} corresponds to a Unicode scalar value
with the Unicode property \tcode{Grapheme_Extend=Yes}
as described by \UAX{44} of the Unicode Standard and
\placeholder{C} is not immediately preceded in \placeholder{S} by
a character \placeholder{P} appended to \placeholder{E}
without translation to an escape sequence, or

\item
\placeholder{CE} is neither UTF-8, UTF-16, nor UTF-32 and
\placeholder{C} is one of an implementation-defined set
of separator or non-printable characters
\end{itemize}

then the sequence \tcode{\textbackslash u\{\placeholder{hex-digit-sequence}\}}
is appended to \placeholder{E},
where \tcode{\placeholder{hex-digit-sequence}}
is the shortest hexadecimal representation
of \placeholder{C} using lower-case hexadecimal digits.

\item
Otherwise, \placeholder{C} is appended to \placeholder{E}.
\end{itemize}

\item
Otherwise, if \placeholder{X} is a shift sequence,
the effect on \placeholder{E} and further decoding of \placeholder{S}
is unspecified.

\recommended
A shift sequence should be represented in \placeholder{E}
such that the original code unit sequence of \placeholder{S}
can be reconstructed.

\item
Otherwise (\placeholder{X} is a sequence of ill-formed code units),
each code unit \placeholder{U} is appended to \placeholder{E} in order
as the sequence \tcode{\textbackslash x\{\placeholder{hex-digit-sequence}\}},
where \tcode{\placeholder{hex-digit-sequence}}
is the shortest hexadecimal representation of \placeholder{U}
using lower-case hexadecimal digits.
\end{itemize}

\item
Finally, \unicode{0022}{quotation mark} (\tcode{"})
is appended to \placeholder{E}.
\end{itemize}
%
\begin{floattable}{Mapping of characters to escape sequences}{format.escape.sequences}{ll}
\topline
\lhdr{Character} & \rhdr{Escape sequence} \\ \rowsep
\unicode{0009}{character tabulation} &
\tcode{\textbackslash t}
\\ \rowsep
%
\unicode{000a}{line feed} &
\tcode{\textbackslash n}
\\ \rowsep
%
\unicode{000d}{carriage return} &
\tcode{\textbackslash r}
\\ \rowsep
%
\unicode{0022}{quotation mark} &
\tcode{\textbackslash "}
\\ \rowsep
%
\unicode{005c}{reverse solidus} &
\tcode{\textbackslash\textbackslash}
\\
\end{floattable}

\pnum
The escaped string representation of a character \placeholder{C}
is equivalent to the escaped string representation
of a string of \placeholder{C}, except that:

\begin{itemize}
\item
the result starts and ends with \unicode{0027}{apostrophe} (\tcode{'})
instead of \unicode{0022}{quotation mark} (\tcode{"}), and
\item
if \placeholder{C} is \unicode{0027}{apostrophe},
the two characters \tcode{\textbackslash '} are appended to \placeholder{E}, and
\item
if \placeholder{C} is \unicode{0022}{quotation mark},
then \placeholder{C} is appended unchanged.
\end{itemize}

\begin{example}
\begin{codeblock}
string s0 = format("[{}]", "h\tllo");                   // \tcode{s0} has value: \tcode{[h\ \ \ \ llo]}
string s1 = format("[{:?}]", "h\tllo");                 // \tcode{s1} has value: \tcode{["h\textbackslash tllo"]}
string s2 = format("[{:?}]", "@\importexample[-2.5pt]{example_01}@");  @\kern1.25pt@// \tcode{s2} has value: \tcode{["\importexample[-2.5pt]{example_01}"]}
string s3 = format("[{:?}, {:?}]", '\'', '"');          // \tcode{s3} has value: \tcode{['\textbackslash '', '"']}

// The following examples assume use of the UTF-8 encoding
string s4 = format("[{:?}]", string("\0 \n \t \x02 \x1b", 9));
                                                    // \tcode{s4} has value: \tcode{["\textbackslash u\{0\} \textbackslash n \textbackslash t \textbackslash u\{2\} \textbackslash u\{1b\}"]}
string s5 = format("[{:?}]", "\xc3\x28");           // invalid UTF-8, \tcode{s5} has value: \tcode{["\textbackslash x\{c3\}("]}
string s6 = format("[{:?}]", "@\importexample{example_02}@");                 @\kern0.75pt@// \tcode{s6} has value: \tcode{["\importexample{example_03}\textbackslash{u}\{200d\}\importexample{example_04}"]}
string s7 = format("[{:?}]", "\u0301");             // \tcode{s7} has value: \tcode{["\textbackslash u\{301\}"]}
string s8 = format("[{:?}]", "\\\u0301");           // \tcode{s8} has value: \tcode{["\textbackslash \textbackslash \textbackslash u\{301\}"]}
string s9 = format("[{:?}]", "e\u0301\u0323");      // \tcode{s9} has value: \tcode{["\importexample[-2pt]{example_06}"]}
\end{codeblock}
\end{example}

\rSec3[format.parse.ctx]{Class template \tcode{basic_format_parse_context}}

\indexlibraryglobal{basic_format_parse_context}%
\indexlibrarymember{char_type}{basic_format_parse_context}%
\indexlibrarymember{const_iterator}{basic_format_parse_context}%
\indexlibrarymember{iterator}{basic_format_parse_context}%
\begin{codeblock}
namespace std {
  template<class charT>
  class basic_format_parse_context {
  public:
    using char_type = charT;
    using const_iterator = typename basic_string_view<charT>::const_iterator;
    using iterator = const_iterator;

  private:
    iterator begin_;                                    // \expos
    iterator end_;                                      // \expos
    enum indexing { unknown, manual, automatic };       // \expos
    indexing indexing_;                                 // \expos
    size_t next_arg_id_;                                // \expos
    size_t num_args_;                                   // \expos

  public:
    constexpr explicit basic_format_parse_context(basic_string_view<charT> fmt) noexcept;
    basic_format_parse_context(const basic_format_parse_context&) = delete;
    basic_format_parse_context& operator=(const basic_format_parse_context&) = delete;

    constexpr const_iterator begin() const noexcept;
    constexpr const_iterator end() const noexcept;
    constexpr void advance_to(const_iterator it);

    constexpr size_t next_arg_id();
    constexpr void check_arg_id(size_t id);

    template<class... Ts>
      constexpr void check_dynamic_spec(size_t id) noexcept;
    constexpr void check_dynamic_spec_integral(size_t id) noexcept;
    constexpr void check_dynamic_spec_string(size_t id) noexcept;
  };
}
\end{codeblock}

\pnum
An instance of \tcode{basic_format_parse_context} holds
the format string parsing state, consisting of
the format string range being parsed and
the argument counter for automatic indexing.

\indexlibraryctor{basic_format_parse_context}%
\begin{itemdecl}
constexpr explicit basic_format_parse_context(basic_string_view<charT> fmt) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes
\tcode{begin_} with \tcode{fmt.begin()},
\tcode{end_} with \tcode{fmt.end()},
\tcode{indexing_} with \tcode{unknown},
\tcode{next_arg_id_} with \tcode{0}, and
\tcode{num_args_} with \tcode{0}.
\begin{note}
Any call to
\tcode{next_arg_id}, \tcode{check_arg_id}, or \tcode{check_dynamic_spec}
on an instance of \tcode{basic_format_parse_context}
initialized using this constructor is not a core constant expression.
\end{note}
\end{itemdescr}

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

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

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

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

\indexlibrarymember{advance_to}{basic_format_parse_context}%
\begin{itemdecl}
constexpr void advance_to(const_iterator it);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{end()} is reachable from \tcode{it}.

\pnum
\effects
Equivalent to: \tcode{begin_ = it;}
\end{itemdescr}

\indexlibrarymember{next_arg_id}{basic_format_parse_context}%
\begin{itemdecl}
constexpr size_t next_arg_id();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{indexing_ != manual} is \tcode{true}, equivalent to:
\begin{codeblock}
if (indexing_ == unknown)
  indexing_ = automatic;
return next_arg_id_++;
\end{codeblock}

\pnum
\throws
\tcode{format_error} if \tcode{indexing_ == manual} is \tcode{true}.
\begin{note}
This indicates mixing of automatic and manual argument indexing.
\end{note}

\pnum
\remarks
Let \tcode{\placeholder{cur-arg-id}} be the value of \tcode{next_arg_id_} prior to this call.
Call expressions where \tcode{\placeholder{cur-arg-id} >= num_args_} is \tcode{true}
are not core constant expressions\iref{expr.const}.
\end{itemdescr}

\indexlibrarymember{check_arg_id}{basic_format_parse_context}%
\begin{itemdecl}
constexpr void check_arg_id(size_t id);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{indexing_ != automatic} is \tcode{true}, equivalent to:
\begin{codeblock}
if (indexing_ == unknown)
  indexing_ = manual;
\end{codeblock}

\pnum
\throws
\tcode{format_error} if
\tcode{indexing_ == automatic} is \tcode{true}.
\begin{note}
This indicates mixing of automatic and manual argument indexing.
\end{note}

\pnum
\remarks
A call to this function is a core constant expression\iref{expr.const} only if
\tcode{id < num_args_} is \tcode{true}.
\end{itemdescr}

\indexlibrarymember{check_dynamic_spec}{basic_format_parse_context}%
\begin{itemdecl}
template<class... Ts>
  constexpr void check_dynamic_spec(size_t id) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The types in \tcode{Ts...} are unique.
Each type in \tcode{Ts...} is one of
\keyword{bool},
\tcode{char_type},
\keyword{int},
\tcode{\keyword{unsigned} \keyword{int}},
\tcode{\keyword{long} \keyword{long} \keyword{int}},
\tcode{\keyword{unsigned} \keyword{long} \keyword{long} \keyword{int}},
\keyword{float},
\keyword{double},
\tcode{\keyword{long} \keyword{double}},
\tcode{\keyword{const} char_type*},
\tcode{basic_string_view<char_type>}, or
\tcode{\keyword{const} \keyword{void}*}.

\pnum
\remarks
A call to this function is a core constant expression only if
\begin{itemize}
\item
\tcode{id < num_args_} is \tcode{true} and
\item
the type of the corresponding format argument
(after conversion to \tcode{basic_format_arg<Context>}) is one of the types in \tcode{Ts...}.
\end{itemize}
\end{itemdescr}

\indexlibrarymember{check_dynamic_spec_integral}{basic_format_parse_context}%
\begin{itemdecl}
constexpr void check_dynamic_spec_integral(size_t id) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
check_dynamic_spec<int, unsigned int, long long int, unsigned long long int>(id);
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{check_dynamic_spec_string}{basic_format_parse_context}%
\begin{itemdecl}
constexpr void check_dynamic_spec_string(size_t id) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
check_dynamic_spec<const char_type*, basic_string_view<char_type>>(id);
\end{codeblock}
\end{itemdescr}

\rSec3[format.context]{Class template \tcode{basic_format_context}}

\indexlibraryglobal{basic_format_context}%
\indexlibrarymember{iterator}{basic_format_context}%
\indexlibrarymember{char_type}{basic_format_context}%
\indexlibrarymember{formatter_type}{basic_format_context}%
\begin{codeblock}
namespace std {
  template<class Out, class charT>
  class basic_format_context {
    basic_format_args<basic_format_context> args_;      // \expos
    Out out_;                                           // \expos

  public:
    using iterator = Out;
    using char_type = charT;
    template<class T> using formatter_type = formatter<T, charT>;

    basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
    std::locale locale();

    iterator out();
    void advance_to(iterator it);
  };
}
\end{codeblock}

\pnum
An instance of \tcode{basic_format_context} holds formatting state
consisting of the formatting arguments and the output iterator.

\pnum
\tcode{Out} shall model \tcode{\libconcept{output_iterator}<const charT\&>}.

\pnum
\indexlibraryglobal{format_context}%
\tcode{format_context} is an alias for
a specialization of \tcode{basic_format_context}
with an output iterator
that appends to \tcode{string},
such as \tcode{back_insert_iterator<string>}.
\indexlibraryglobal{wformat_context}%
Similarly, \tcode{wformat_context} is an alias for
a specialization of \tcode{basic_format_context}
with an output iterator
that appends to \tcode{wstring}.

\pnum
\recommended
For a given type \tcode{charT},
implementations should provide
a single instantiation of \tcode{basic_format_context}
for appending to
\tcode{basic_string<charT>},
\tcode{vector<charT>},
or any other container with contiguous storage
by wrapping those in temporary objects with a uniform interface
(such as a \tcode{span<charT>}) and polymorphic reallocation.

\indexlibrarymember{arg}{basic_format_context}%
\begin{itemdecl}
basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{args_.get(id)}.
\end{itemdescr}

\indexlibrarymember{locale}{basic_format_context}%
\begin{itemdecl}
std::locale locale();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The locale passed to the formatting function
if the latter takes one,
and \tcode{std::locale()} otherwise.
\end{itemdescr}

\indexlibrarymember{out}{basic_format_context}%
\begin{itemdecl}
iterator out();
\end{itemdecl}

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

\indexlibrarymember{advance_to}{basic_format_context}%
\begin{itemdecl}
void advance_to(iterator it);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{out_ = std::move(it);}
\end{itemdescr}

\indextext{left-pad}%
\begin{example}
\begin{codeblock}
struct S { int value; };

template<> struct std::formatter<S> {
  size_t width_arg_id = 0;

  // Parses a width argument id in the format \tcode{\{} \fmtgrammarterm{digit} \tcode{\}}.
  constexpr auto parse(format_parse_context& ctx) {
    auto iter = ctx.begin();
    auto get_char = [&]() { return iter != ctx.end() ? *iter : 0; };
    if (get_char() != '{')
      return iter;
    ++iter;
    char c = get_char();
    if (!isdigit(c) || (++iter, get_char()) != '}')
      throw format_error("invalid format");
    width_arg_id = c - '0';
    ctx.check_arg_id(width_arg_id);
    return ++iter;
  }

  // Formats an \tcode{S} with width given by the argument \tcode{width_arg_id}.
  auto format(S s, format_context& ctx) const {
    int width = ctx.arg(width_arg_id).visit([](auto value) -> int {
      if constexpr (!is_integral_v<decltype(value)>)
        throw format_error("width is not integral");
      else if (value < 0 || value > numeric_limits<int>::max())
        throw format_error("invalid width");
      else
        return value;
      });
    return format_to(ctx.out(), "{0:x<{1}}", s.value, width);
  }
};

std::string s = std::format("{0:{1}}", S{42}, 10);  // value of \tcode{s} is \tcode{"xxxxxxxx42"}
\end{codeblock}
\end{example}

\rSec2[format.range]{Formatting of ranges}

\rSec3[format.range.fmtkind]{Variable template \tcode{format_kind}}

\indexlibraryglobal{format_kind}
\begin{itemdecl}
template<ranges::@\libconcept{input_range}@ R>
    requires @\libconcept{same_as}@<R, remove_cvref_t<R>>
  constexpr range_format format_kind<R> = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
A program that instantiates the primary template of \tcode{format_kind}
is ill-formed.

\pnum
For a type \tcode{R}, \tcode{format_kind<R>} is defined as follows:
\begin{itemize}
\item
If \tcode{\libconcept{same_as}<remove_cvref_t<ranges::range_reference_t<R>>, R>}
is \tcode{true},
\tcode{format_kind<R>} is \tcode{range_format::disabled}.
\begin{note}
This prevents constraint recursion for ranges whose
reference type is the same range type.
For example,
\tcode{std::filesystem::path} is a range of \tcode{std::filesystem::path}.
\end{note}

\item
Otherwise, if the \grammarterm{qualified-id} \tcode{R::key_type}
is valid and denotes a type:
\begin{itemize}
\item
If the \grammarterm{qualified-id} \tcode{R::mapped_type}
is valid and denotes a type,
let \tcode{U} be \tcode{remove_cvref_t<ranges::range_reference_t<R>>}.
If either \tcode{U} is a specialization of \tcode{pair} or
\tcode{U} is a specialization of \tcode{tuple} and
\tcode{tuple_size_v<U> == 2},
\tcode{format_kind<R>} is \tcode{range_format::map}.
\item
Otherwise, \tcode{format_kind<R>} is \tcode{range_format::set}.
\end{itemize}

\item
Otherwise, \tcode{format_kind<R>} is \tcode{range_format::sequence}.
\end{itemize}

\pnum
\remarks
Pursuant to \ref{namespace.std}, users may specialize \tcode{format_kind}
for cv-unqualified program-defined types
that model \tcode{ranges::\libconcept{input_range}}.
Such specializations shall be usable in constant expressions\iref{expr.const}
and have type \tcode{const range_format}.
\end{itemdescr}

\rSec3[format.range.formatter]{Class template \tcode{range_formatter}}

\indexlibraryglobal{range_formatter}%
\begin{codeblock}
namespace std {
  template<class T, class charT = char>
    requires @\libconcept{same_as}@<remove_cvref_t<T>, T> && @\libconcept{formattable}@<T, charT>
  class range_formatter {
    formatter<T, charT> @\exposid{underlying_}@;                                          // \expos
    basic_string_view<charT> @\exposid{separator_}@ = @\exposid{STATICALLY-WIDEN}@<charT>(", ");      // \expos
    basic_string_view<charT> @\exposid{opening-bracket_}@ = @\exposid{STATICALLY-WIDEN}@<charT>("["); // \expos
    basic_string_view<charT> @\exposid{closing-bracket_}@ = @\exposid{STATICALLY-WIDEN}@<charT>("]"); // \expos

  public:
    constexpr void set_separator(basic_string_view<charT> sep) noexcept;
    constexpr void set_brackets(basic_string_view<charT> opening,
                                basic_string_view<charT> closing) noexcept;
    constexpr formatter<T, charT>& underlying() noexcept { return @\exposid{underlying_}@; }
    constexpr const formatter<T, charT>& underlying() const noexcept { return @\exposid{underlying_}@; }

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<ranges::@\libconcept{input_range}@ R, class FormatContext>
        requires @\libconcept{formattable}@<ranges::range_reference_t<R>, charT> &&
                 @\libconcept{same_as}@<remove_cvref_t<ranges::range_reference_t<R>>, T>
      typename FormatContext::iterator
        format(R&& r, FormatContext& ctx) const;
  };
}
\end{codeblock}

\pnum
The class template \tcode{range_formatter} is a utility
for implementing \tcode{formatter} specializations for range types.

\pnum
\tcode{range_formatter} interprets \fmtgrammarterm{format-spec}
as a \fmtgrammarterm{range-format-spec}.
The syntax of format specifications is as follows:

\begin{ncbnf}
\fmtnontermdef{range-format-spec}\br
    \opt{range-fill-and-align} \opt{width} \opt{\terminal{n}} \opt{range-type} \opt{range-underlying-spec}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{range-fill-and-align}\br
    \opt{range-fill} align
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{range-fill}\br
    \textnormal{any character other than} \terminal{\{} \textnormal{or} \terminal{\}} \textnormal{or} \terminal{:}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{range-type}\br
    \terminal{m}\br
    \terminal{s}\br
    \terminal{?s}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{range-underlying-spec}\br
    \terminal{:} format-spec
\end{ncbnf}

\pnum
For \tcode{range_formatter<T, charT>},
the \fmtgrammarterm{format-spec}
in a \fmtgrammarterm{range-underlying-spec}, if any,
is interpreted by \tcode{formatter<T, charT>}.

\pnum
The \fmtgrammarterm{range-fill-and-align} is interpreted
the same way as a \fmtgrammarterm{fill-and-align}\iref{format.string.std}.
The productions \fmtgrammarterm{align} and \fmtgrammarterm{width}
are described in \ref{format.string}.

\pnum
The \tcode{n} option causes the range to be formatted
without the opening and closing brackets.
\begin{note}
This is equivalent to invoking \tcode{set_brackets(\{\}, \{\})}.
\end{note}

\pnum
The \fmtgrammarterm{range-type} specifier changes the way a range is formatted,
with certain options only valid with certain argument types.
The meaning of the various type options
is as specified in \tref{formatter.range.type}.

\begin{concepttable}{Meaning of \fmtgrammarterm{range-type} options}{formatter.range.type}
{p{1in}p{1.4in}p{2.7in}}
\topline
\hdstyle{Option} & \hdstyle{Requirements} & \hdstyle{Meaning} \\ \capsep
%
\tcode{m} &
\tcode{T} shall be
either a specialization of \tcode{pair} or a specialization of \tcode{tuple}
such that \tcode{tuple_size_v<T>} is \tcode{2}. &
Indicates that
the opening bracket should be \tcode{"\{"},
the closing bracket should be \tcode{"\}"},
the separator should be \tcode{", "}, and
each range element should be formatted as if
\tcode{m} were specified for its \fmtgrammarterm{tuple-type}.
\begin{tailnote}
If the \tcode{n} option is provided in addition to the \tcode{m} option,
both the opening and closing brackets are still empty.
\end{tailnote}
\\ \rowsep
%
\tcode{s} &
\tcode{T} shall be \tcode{charT}. &
Indicates that the range should be formatted as a \tcode{string}.
\\ \rowsep
%
\tcode{?s} &
\tcode{T} shall be \tcode{charT}. &
Indicates that the range should be formatted as
an escaped string\iref{format.string.escaped}.
\\
\end{concepttable}

If the \fmtgrammarterm{range-type} is \tcode{s} or \tcode{?s},
then there shall be
no \tcode{n} option and no \fmtgrammarterm{range-underlying-spec}.

\indexlibrarymember{set_separator}{range_formatter}%
\begin{itemdecl}
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{\exposid{separator_} = sep;}
\end{itemdescr}

\indexlibrarymember{set_brackets}{range_formatter}%
\begin{itemdecl}
constexpr void set_brackets(basic_string_view<charT> opening,
                            basic_string_view<charT> closing) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
@\exposid{opening-bracket_}@ = opening;
@\exposid{closing-bracket_}@ = closing;
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{parse}{range_formatter}%
\begin{itemdecl}
template<class ParseContext>
  constexpr typename ParseContext::iterator
    parse(ParseContext& ctx);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Parses the format specifiers as a \fmtgrammarterm{range-format-spec} and
stores the parsed specifiers in \tcode{*this}.
Calls \tcode{\exposid{underlying_}.parse(ctx)} to parse
\fmtgrammarterm{format-spec} in \fmtgrammarterm{range-format-spec} or,
if the latter is not present, an empty \fmtgrammarterm{format-spec}.
The values of
\exposid{opening-bracket_}, \exposid{closing-bracket_}, and \exposid{separator_}
are modified if and only if required by
the \fmtgrammarterm{range-type} or the \tcode{n} option, if present.
If:
\begin{itemize}
\item
the \fmtgrammarterm{range-type} is neither \tcode{s} nor \tcode{?s},
\item
\tcode{\exposid{underlying_}.set_debug_format()} is a valid expression, and
\item
there is no \fmtgrammarterm{range-underlying-spec},
\end{itemize}
then calls \tcode{\exposid{underlying_}.set_debug_format()}.

\pnum
\returns
An iterator past the end of the \fmtgrammarterm{range-format-spec}.
\end{itemdescr}

\indexlibrarymember{format}{range_formatter}%
\begin{itemdecl}
template<ranges::@\libconcept{input_range}@ R, class FormatContext>
    requires @\libconcept{formattable}@<ranges::range_reference_t<R>, charT> &&
             @\libconcept{same_as}@<remove_cvref_t<ranges::range_reference_t<R>>, T>
  typename FormatContext::iterator
    format(R&& r, FormatContext& ctx) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Writes the following into \tcode{ctx.out()},
adjusted according to the \fmtgrammarterm{range-format-spec}:

\begin{itemize}
\item
If the \fmtgrammarterm{range-type} was \tcode{s},
then as if by formatting \tcode{basic_string<charT>(from_range, r)}.
\item
Otherwise, if the \fmtgrammarterm{range-type} was \tcode{?s},
then as if by formatting \tcode{basic_string<charT>(from_range, r)}
as an escaped string\iref{format.string.escaped}.
\item
Otherwise,
\begin{itemize}
\item
\exposid{opening-bracket_},
\item
for each element \tcode{e} of the range \tcode{r}:
\begin{itemize}
\item
the result of writing \tcode{e} via \exposid{underlying_} and
\item
\exposid{separator_}, unless \tcode{e} is the last element of \tcode{r}, and
\end{itemize}
\item
\exposid{closing-bracket_}.
\end{itemize}
\end{itemize}

\pnum
\returns
An iterator past the end of the output range.
\end{itemdescr}

\rSec3[format.range.fmtdef]{Class template \exposid{range-default-formatter}}

\indexlibrary{range-default-formatter@\exposid{range-default-formatter}}%
\begin{codeblock}
namespace std {
  template<ranges::@\libconcept{input_range}@ R, class charT>
  struct @\exposidnc{range-default-formatter}@<range_format::sequence, R, charT> {    // \expos
  private:
    using @\exposidnc{maybe-const-r}@ = @\exposidnc{fmt-maybe-const}@<R, charT>;                    // \expos
    range_formatter<remove_cvref_t<ranges::range_reference_t<@\exposid{maybe-const-r}@>>,
                    charT> @\exposid{underlying_}@;                                 // \expos

  public:
    constexpr void set_separator(basic_string_view<charT> sep) noexcept;
    constexpr void set_brackets(basic_string_view<charT> opening,
                                basic_string_view<charT> closing) noexcept;

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(@\exposid{maybe-const-r}@& elems, FormatContext& ctx) const;
  };
}
\end{codeblock}

\indexlibrarymemberexpos{set_separator}{range-default-formatter}%
\begin{itemdecl}
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{\exposid{underlying_}.set_separator(sep);}
\end{itemdescr}

\indexlibrarymemberexpos{set_brackets}{range-default-formatter}%
\begin{itemdecl}
constexpr void set_brackets(basic_string_view<charT> opening,
                            basic_string_view<charT> closing) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{\exposid{underlying_}.set_brackets(opening, closing);}
\end{itemdescr}

\indexlibrarymemberexpos{parse}{range-default-formatter}%
\begin{itemdecl}
template<class ParseContext>
  constexpr typename ParseContext::iterator
    parse(ParseContext& ctx);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return \exposid{underlying_}.parse(ctx);}
\end{itemdescr}

\indexlibrarymemberexpos{format}{range-default-formatter}%
\begin{itemdecl}
template<class FormatContext>
  typename FormatContext::iterator
    format(@\exposid{maybe-const-r}@& elems, FormatContext& ctx) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return \exposid{underlying_}.format(elems, ctx);}
\end{itemdescr}

\rSec3[format.range.fmtmap]{Specialization of \exposid{range-default-formatter} for maps}

\indexlibrary{range-default-formatter@\exposid{range-default-formatter}}%
\begin{codeblock}
namespace std {
  template<ranges::@\libconcept{input_range}@ R, class charT>
  struct @\exposid{range-default-formatter}@<range_format::map, R, charT> {
  private:
    using @\exposidnc{maybe-const-map}@ = @\exposidnc{fmt-maybe-const}@<R, charT>;                  // \expos
    using @\exposidnc{element-type}@ =                                                // \expos
      remove_cvref_t<ranges::range_reference_t<@\exposid{maybe-const-map}@>>;
    range_formatter<@\exposidnc{element-type}@, charT> @\exposid{underlying_}@;                   // \expos

  public:
    constexpr @\exposid{range-default-formatter}@();

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(@\exposid{maybe-const-map}@& r, FormatContext& ctx) const;
  };
}
\end{codeblock}

\indexlibrarymisc{range-default-formatter@\exposid{range-default-formatter}}{constructor}%
\begin{itemdecl}
constexpr @\exposid{range-default-formatter}@();
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
Either:
\begin{itemize}
\item
\exposid{element-type} is a specialization of \tcode{pair}, or
\item
\exposid{element-type} is a specialization of \tcode{tuple} and
\tcode{tuple_size_v<\exposid{element-type}> == 2}.
\end{itemize}

\pnum
\effects
Equivalent to:
\begin{codeblock}
@\exposid{underlying_}@.set_brackets(@\exposid{STATICALLY-WIDEN}@<charT>("{"), @\exposid{STATICALLY-WIDEN}@<charT>("}"));
@\exposid{underlying_}@.underlying().set_brackets({}, {});
@\exposid{underlying_}@.underlying().set_separator(@\exposid{STATICALLY-WIDEN}@<charT>(": "));
\end{codeblock}
\end{itemdescr}

\indexlibrarymemberexpos{parse}{range-default-formatter}%
\begin{itemdecl}
template<class ParseContext>
  constexpr typename ParseContext::iterator
    parse(ParseContext& ctx);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return \exposid{underlying_}.parse(ctx);}
\end{itemdescr}

\indexlibrarymemberexpos{format}{range-default-formatter}%
\begin{itemdecl}
template<class FormatContext>
  typename FormatContext::iterator
    format(@\exposid{maybe-const-map}@& r, FormatContext& ctx) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return \exposid{underlying_}.format(r, ctx);}
\end{itemdescr}

\rSec3[format.range.fmtset]{Specialization of \exposid{range-default-formatter} for sets}

\indexlibrary{range-default-formatter@\exposid{range-default-formatter}}%
\begin{codeblock}
namespace std {
  template<ranges::@\libconcept{input_range}@ R, class charT>
  struct @\exposid{range-default-formatter}@<range_format::set, R, charT> {
  private:
    using @\exposidnc{maybe-const-set}@ = @\exposidnc{fmt-maybe-const}@<R, charT>;                  // \expos
    range_formatter<remove_cvref_t<ranges::range_reference_t<@\exposid{maybe-const-set}@>>,
                    charT> @\exposid{underlying_}@;                                 // \expos

  public:
    constexpr @\exposid{range-default-formatter}@();

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(@\exposid{maybe-const-set}@& r, FormatContext& ctx) const;
  };
}
\end{codeblock}

\indexlibrarymisc{range-default-formatter@\exposid{range-default-formatter}}{constructor}%
\begin{itemdecl}
constexpr @\exposid{range-default-formatter}@();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
@\exposid{underlying_}@.set_brackets(@\exposid{STATICALLY-WIDEN}@<charT>("{"), @\exposid{STATICALLY-WIDEN}@<charT>("}"));
\end{codeblock}
\end{itemdescr}

\indexlibrarymemberexpos{parse}{range-default-formatter}%
\begin{itemdecl}
template<class ParseContext>
  constexpr typename ParseContext::iterator
    parse(ParseContext& ctx);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return \exposid{underlying_}.parse(ctx);}
\end{itemdescr}

\indexlibrarymemberexpos{format}{range-default-formatter}%
\begin{itemdecl}
template<class FormatContext>
  typename FormatContext::iterator
    format(@\exposid{maybe-const-set}@& r, FormatContext& ctx) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return \exposid{underlying_}.format(r, ctx);}
\end{itemdescr}

\rSec3[format.range.fmtstr]{Specialization of \exposid{range-default-formatter} for strings}

\indexlibrary{range-default-formatter@\exposid{range-default-formatter}}%
\begin{codeblock}
namespace std {
  template<range_format K, ranges::@\libconcept{input_range}@ R, class charT>
    requires (K == range_format::string || K == range_format::debug_string)
  struct @\exposid{range-default-formatter}@<K, R, charT> {
  private:
    formatter<basic_string<charT>, charT> @\exposid{underlying_}@;                  // \expos

  public:
    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(@\seebelow@& str, FormatContext& ctx) const;
  };
}
\end{codeblock}

\pnum
\mandates
\tcode{\libconcept{same_as}<remove_cvref_t<range_reference_t<R>>, charT>}
is \tcode{true}.

\indexlibrarymemberexpos{parse}{range-default-formatter}%
\begin{itemdecl}
template<class ParseContext>
  constexpr typename ParseContext::iterator
    parse(ParseContext& ctx);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
auto i = @\exposid{underlying_}@.parse(ctx);
if constexpr (K == range_format::debug_string) {
  @\exposid{underlying_}@.set_debug_format();
}
return i;
\end{codeblock}
\end{itemdescr}

\indexlibrarymemberexpos{format}{range-default-formatter}%
\begin{itemdecl}
template<class FormatContext>
  typename FormatContext::iterator
    format(@\seebelow@& r, FormatContext& ctx) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type of \tcode{r} is \tcode{const R\&}
if \tcode{ranges::\libconcept{input_range}<const R>} is \tcode{true} and
\tcode{R\&} otherwise.

\pnum
\effects
Let \tcode{\placeholder{s}} be a \tcode{basic_string<charT>} such that
\tcode{ranges::equal(\placeholder{s}, r)} is \tcode{true}.
Equivalent to: \tcode{return \exposid{underlying_}.format(\placeholder{s}, ctx);}
\end{itemdescr}

\rSec2[format.arguments]{Arguments}

\rSec3[format.arg]{Class template \tcode{basic_format_arg}}

\indexlibraryglobal{basic_format_arg}%
\begin{codeblock}
namespace std {
  template<class Context>
  class basic_format_arg {
  public:
    class handle;

  private:
    using char_type = typename Context::char_type;                              // \expos

    variant<monostate, bool, char_type,
            int, unsigned int, long long int, unsigned long long int,
            float, double, long double,
            const char_type*, basic_string_view<char_type>,
            const void*, handle> value;                                         // \expos

    template<class T> explicit basic_format_arg(T& v) noexcept;                 // \expos

  public:
    basic_format_arg() noexcept;

    explicit operator bool() const noexcept;

    template<class Visitor>
      decltype(auto) visit(this basic_format_arg arg, Visitor&& vis);
    template<class R, class Visitor>
      R visit(this basic_format_arg arg, Visitor&& vis);
  };
}
\end{codeblock}

\pnum
An instance of \tcode{basic_format_arg} provides access to
a formatting argument for user-defined formatters.

\pnum
The behavior of a program that adds specializations of
\tcode{basic_format_arg} is undefined.

\indexlibrary{\idxcode{basic_format_arg}!constructor|(}%
\begin{itemdecl}
basic_format_arg() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{!(*this)}.
\end{itemdescr}

\begin{itemdecl}
template<class T> explicit basic_format_arg(T& v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} satisfies \tcode{\exposconcept{formattable-with}<Context>}.

\pnum
\expects
If \tcode{decay_t<T>} is \tcode{char_type*} or \tcode{const char_type*},
\tcode{static_cast<const char_\linebreak{}type*>(v)} points to a NTCTS\iref{defns.ntcts}.

\pnum
\effects
Let \tcode{TD} be \tcode{remove_const_t<T>}.
\begin{itemize}
\item
If \tcode{TD} is \tcode{bool} or \tcode{char_type},
initializes \tcode{value} with \tcode{v};
\item
otherwise, if \tcode{TD} is \tcode{char} and \tcode{char_type} is
\keyword{wchar_t}, initializes \tcode{value} with
\tcode{static_cast<wchar_t>(static_cast<unsigned char>(v))};
\item
otherwise, if \tcode{TD} is a signed integer type\iref{basic.fundamental}
and \tcode{sizeof(TD) <= sizeof(int)},
initializes \tcode{value} with \tcode{static_cast<int>(v)};
\item
otherwise, if \tcode{TD} is an unsigned integer type and
\tcode{sizeof(TD) <= sizeof(unsigned int)}, initializes
\tcode{value} with \tcode{static_cast<unsigned int>(v)};
\item
otherwise, if \tcode{TD} is a signed integer type and
\tcode{sizeof(TD) <= sizeof(long long int)}, initializes
\tcode{value} with \tcode{static_cast<long long int>(v)};
\item
otherwise, if \tcode{TD} is an unsigned integer type and
\tcode{sizeof(TD) <= sizeof(unsigned long long int)}, initializes
\tcode{value} with
\tcode{static_cast<unsigned long long int>(v)};
\item
otherwise, if \tcode{TD} is a standard floating-point type,
initializes \tcode{value} with \tcode{v};
\item
otherwise, if \tcode{TD} is
a specialization of \tcode{basic_string_view} or \tcode{basic_string} and
\tcode{TD::value_type} is \tcode{char_type},
initializes \tcode{value} with
\tcode{basic_string_view<char_type>(v.data(), v.size())};
\item
otherwise, if \tcode{decay_t<TD>} is
\tcode{char_type*} or \tcode{const char_type*},
initializes \tcode{value} with \tcode{static_cast<const char_type*>(v)};
\item
otherwise, if \tcode{is_void_v<remove_pointer_t<TD>>} is \tcode{true} or
\tcode{is_null_pointer_v<TD>} is \tcode{true},
initializes \tcode{value} with \tcode{static_cast<const void*>(v)};
\item
otherwise, initializes \tcode{value} with \tcode{handle(v)}.
\end{itemize}
\begin{note}
Constructing \tcode{basic_format_arg} from a pointer to a member is ill-formed
unless the user provides an enabled specialization of \tcode{formatter}
for that pointer to member type.
\end{note}
\end{itemdescr}

\indexlibrary{\idxcode{basic_format_arg}!constructor|)}%

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

\begin{itemdescr}
\pnum
\returns
\tcode{!holds_alternative<monostate>(value)}.
\end{itemdescr}

\indexlibrarymember{visit}{basic_format_arg}%
\begin{itemdecl}
template<class Visitor>
  decltype(auto) visit(this basic_format_arg arg, Visitor&& vis);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return arg.value.visit(std::forward<Visitor>(vis));}
\end{itemdescr}

\indexlibrarymember{visit}{basic_format_arg}%
\begin{itemdecl}
template<class R, class Visitor>
  R visit(this basic_format_arg arg, Visitor&& vis);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return arg.value.visit<R>(std::forward<Visitor>(vis));}
\end{itemdescr}

\pnum
The class \tcode{handle} allows formatting an object of a user-defined type.

\indexlibraryglobal{basic_format_arg::handle}%
\indexlibrarymember{handle}{basic_format_arg}%
\begin{codeblock}
namespace std {
  template<class Context>
  class basic_format_arg<Context>::handle {
    const void* ptr_;                                           // \expos
    void (*format_)(basic_format_parse_context<char_type>&,
                    Context&, const void*);                     // \expos

    template<class T> explicit handle(T& val) noexcept;         // \expos

    friend class basic_format_arg<Context>;                     // \expos

  public:
    void format(basic_format_parse_context<char_type>&, Context& ctx) const;
  };
}
\end{codeblock}

\indexlibraryctor{basic_format_arg::handle}%
\begin{itemdecl}
template<class T> explicit handle(T& val) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let
\begin{itemize}
\item
\tcode{TD} be \tcode{remove_const_t<T>},
\item
\tcode{TQ} be \tcode{const TD} if
\tcode{const TD} satisfies \tcode{\exposconcept{formattable-with}<Context>}
and \tcode{TD} otherwise.
\end{itemize}

\pnum
\mandates
\tcode{TQ} satisfies \tcode{\exposconcept{formattable-with}<Context>}.

\pnum
\effects
Initializes
\tcode{ptr_} with \tcode{addressof(val)} and
\tcode{format_} with
\begin{codeblock}
[](basic_format_parse_context<char_type>& parse_ctx,
   Context& format_ctx, const void* ptr) {
  typename Context::template formatter_type<TD> f;
  parse_ctx.advance_to(f.parse(parse_ctx));
  format_ctx.advance_to(f.format(*const_cast<TQ*>(static_cast<const TD*>(ptr)),
                                 format_ctx));
}
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{format}{basic_format_arg::handle}%
\begin{itemdecl}
void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{format_(parse_ctx, format_ctx, ptr_);}
\end{itemdescr}

\rSec3[format.arg.store]{Class template \exposid{format-arg-store}}

\begin{codeblock}
namespace std {
  template<class Context, class... Args>
  class @\exposidnc{format-arg-store}@ {                                      // \expos
    array<basic_format_arg<Context>, sizeof...(Args)> @\exposidnc{args}@;     // \expos
  };
}
\end{codeblock}

\pnum
An instance of \exposid{format-arg-store} stores formatting arguments.

\indexlibraryglobal{make_format_args}%
\begin{itemdecl}
template<class Context = format_context, class... Args>
  @\exposid{format-arg-store}@<Context, Args...> make_format_args(Args&... fmt_args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
The type
\tcode{typename Context::template formatter_type<remove_const_t<}$\tcode{T}_i$\tcode{>>}\linebreak{}
meets the \newoldconcept{BasicFormatter} requirements\iref{formatter.requirements}
for each $\tcode{T}_i$ in \tcode{Args}.

\pnum
\returns
An object of type \tcode{\exposid{format-arg-store}<Context, Args...>}
whose \exposid{args} data member is initialized with
\tcode{\{basic_format_arg<Context>(fmt_args)...\}}.
\end{itemdescr}

\indexlibraryglobal{make_wformat_args}%
\begin{itemdecl}
template<class... Args>
  @\exposid{format-arg-store}@<wformat_context, Args...> make_wformat_args(Args&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\tcode{return make_format_args<wformat_context>(args...);}
\end{itemdescr}

\rSec3[format.args]{Class template \tcode{basic_format_args}}

\begin{codeblock}
namespace std {
  template<class Context>
  class basic_format_args {
    size_t size_;                               // \expos
    const basic_format_arg<Context>* data_;     // \expos

  public:
    basic_format_args() noexcept;

    template<class... Args>
      basic_format_args(const @\exposid{format-arg-store}@<Context, Args...>& store) noexcept;

    basic_format_arg<Context> get(size_t i) const noexcept;
  };

  template<class Context, class... Args>
    basic_format_args(@\exposid{format-arg-store}@<Context, Args...>) -> basic_format_args<Context>;
}
\end{codeblock}

\pnum
An instance of \tcode{basic_format_args} provides access to formatting
arguments.
Implementations should
optimize the representation of \tcode{basic_format_args}
for a small number of formatting arguments.
\begin{note}
For example, by storing indices of type alternatives separately from values
and packing the former.
\end{note}

\indexlibraryctor{basic_format_args}%
\begin{itemdecl}
basic_format_args() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes \tcode{size_} with \tcode{0}.
\end{itemdescr}

\indexlibraryctor{basic_format_args}%
\begin{itemdecl}
template<class... Args>
  basic_format_args(const @\exposid{format-arg-store}@<Context, Args...>& store) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes
\tcode{size_} with \tcode{sizeof...(Args)} and
\tcode{data_} with \tcode{store.args.data()}.
\end{itemdescr}

\indexlibrarymember{get}{basic_format_args}%
\begin{itemdecl}
basic_format_arg<Context> get(size_t i) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{i < size_ ?\ data_[i] :\ basic_format_arg<Context>()}.
\end{itemdescr}

\rSec2[format.tuple]{Tuple formatter}

\pnum
For each of \tcode{pair} and \tcode{tuple},
the library provides the following formatter specialization
where \tcode{\placeholder{pair-or-tuple}} is the name of the template:

\indexlibraryglobal{formatter}%
\begin{codeblock}
namespace std {
  template<class charT, @\libconcept{formattable}@<charT>... Ts>
  struct formatter<@\placeholder{pair-or-tuple}@<Ts...>, charT> {
  private:
    tuple<formatter<remove_cvref_t<Ts>, charT>...> @\exposid{underlying_}@;               // \expos
    basic_string_view<charT> @\exposid{separator_}@ = @\exposid{STATICALLY-WIDEN}@<charT>(", ");      // \expos
    basic_string_view<charT> @\exposid{opening-bracket_}@ = @\exposid{STATICALLY-WIDEN}@<charT>("("); // \expos
    basic_string_view<charT> @\exposid{closing-bracket_}@ = @\exposid{STATICALLY-WIDEN}@<charT>(")"); // \expos

  public:
    constexpr void set_separator(basic_string_view<charT> sep) noexcept;
    constexpr void set_brackets(basic_string_view<charT> opening,
                                basic_string_view<charT> closing) noexcept;

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(@\seebelow@& elems, FormatContext& ctx) const;
  };
}
\end{codeblock}

\pnum
The \tcode{parse} member functions of these formatters
interpret the format specification as
a \fmtgrammarterm{tuple-format-spec} according to the following syntax:

\begin{ncbnf}
\fmtnontermdef{tuple-format-spec}\br
    \opt{tuple-fill-and-align} \opt{width} \opt{tuple-type}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{tuple-fill-and-align}\br
    \opt{tuple-fill} align
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{tuple-fill}\br
    \textnormal{any character other than} \terminal{\{} \textnormal{or} \terminal{\}} \textnormal{or} \terminal{:}
\end{ncbnf}

\begin{ncbnf}
\fmtnontermdef{tuple-type}\br
    \terminal{m}\br
    \terminal{n}
\end{ncbnf}

\pnum
The \fmtgrammarterm{tuple-fill-and-align} is interpreted the same way as
a \fmtgrammarterm{fill-and-align}\iref{format.string.std}.
The productions \fmtgrammarterm{align} and \fmtgrammarterm{width}
are described in \ref{format.string}.

\pnum
The \fmtgrammarterm{tuple-type} specifier
changes the way a \tcode{pair} or \tcode{tuple} is formatted,
with certain options only valid with certain argument types.
The meaning of the various type options
is as specified in \tref{formatter.tuple.type}.

\begin{concepttable}{Meaning of \fmtgrammarterm{tuple-type} options}{formatter.tuple.type}
{p{0.5in}p{1.4in}p{3.2in}}
\topline
\hdstyle{Option} & \hdstyle{Requirements} & \hdstyle{Meaning} \\ \capsep
%
\tcode{m} &
\tcode{sizeof...(Ts) == 2} &
Equivalent to:
\begin{codeblock}
set_separator(@\exposid{STATICALLY-WIDEN}@<charT>(": "));
set_brackets({}, {});
\end{codeblock}%
\\ \rowsep
%
\tcode{n} &
none &
Equivalent to: \tcode{set_brackets(\{\}, \{\});}
\\ \rowsep
%
none &
none &
No effects
\\
\end{concepttable}

\indexlibrarymember{set_separator}{formatter}%
\begin{itemdecl}
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{\exposid{separator_} = sep;}
\end{itemdescr}

\indexlibrarymember{set_brackets}{formatter}%
\begin{itemdecl}
constexpr void set_brackets(basic_string_view<charT> opening,
                            basic_string_view<charT> closing) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
@\exposid{opening-bracket_}@ = opening;
@\exposid{closing-bracket_}@ = closing;
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{parse}{formatter}%
\begin{itemdecl}
template<class ParseContext>
  constexpr typename ParseContext::iterator
    parse(ParseContext& ctx);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Parses the format specifiers as a \fmtgrammarterm{tuple-format-spec} and
stores the parsed specifiers in \tcode{*this}.
The values of
\exposid{opening-bracket_},
\exposid{closing-bracket_}, and
\exposid{separator_}
are modified if and only if
required by the \fmtgrammarterm{tuple-type}, if present.
For each element \tcode{\placeholder{e}} in \exposid{underlying_},
calls \tcode{\placeholder{e}.parse(ctx)} to parse
an empty \fmtgrammarterm{format-spec} and,
if \tcode{\placeholder{e}.set_debug_format()} is a valid expression,
calls \tcode{\placeholder{e}.set_debug_format()}.

\pnum
\returns
An iterator past the end of the \fmtgrammarterm{tuple-format-spec}.
\end{itemdescr}

\indexlibrarymember{format}{formatter}%
\begin{itemdecl}
template<class FormatContext>
  typename FormatContext::iterator
    format(@\seebelow@& elems, FormatContext& ctx) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type of \tcode{elems} is:
\begin{itemize}
\item
If \tcode{(\libconcept{formattable}<const Ts, charT> \&\& ...)} is \tcode{true},
\tcode{const \placeholder{pair-or-tuple}<Ts...>\&}.
\item
Otherwise \tcode{\placeholder{pair-or-tuple}<Ts...>\&}.
\end{itemize}

\pnum
\effects
Writes the following into \tcode{ctx.out()},
adjusted according to the \fmtgrammarterm{tuple-format-spec}:
\begin{itemize}
\item
\exposid{opening-bracket_},
\item
for each index \tcode{I} in the \range{0}{sizeof...(Ts)}:
\begin{itemize}
\item
if \tcode{I != 0}, \exposid{separator_},
\item
the result of writing \tcode{get<I>(elems)}
via \tcode{get<I>(\exposid{underlying_})}, and
\end{itemize}
\item
\exposid{closing-bracket_}.
\end{itemize}

\pnum
\returns
An iterator past the end of the output range.
\end{itemdescr}

\rSec2[format.error]{Class \tcode{format_error}}

\indexlibraryglobal{format_error}%
\begin{codeblock}
namespace std {
  class format_error : public runtime_error {
  public:
    explicit format_error(const string& what_arg);
    explicit format_error(const char* what_arg);
  };
}
\end{codeblock}

\pnum
The class \tcode{format_error} defines the type of objects thrown as
exceptions to report errors from the formatting library.

\indexlibraryctor{format_error}%
\begin{itemdecl}
format_error(const string& what_arg);
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{strcmp(what(), what_arg.c_str()) == 0}.

\indexlibraryctor{format_error}%
\end{itemdescr}
\begin{itemdecl}
format_error(const char* what_arg);
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{strcmp(what(), what_arg) == 0}.
\end{itemdescr}

\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>
    [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
  template<class T>
    [[nodiscard]] 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 behaviour 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>
  [[nodiscard]] 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>
  [[nodiscard]] 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[debugging]{Debugging}

\rSec2[debugging.general]{General}

\pnum
Subclause \ref{debugging} describes functionality to introspect and
interact with the execution of the program.

\begin{note}
The facilities provided by the debugging functionality interact with a program
that could be tracing the execution of a \Cpp{} program, such as a debugger.
\end{note}

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

\indexheader{debugging}%
\begin{codeblock}
// all freestanding
namespace std {
  // \ref{debugging.utility}, utility
  void breakpoint() noexcept;
  void breakpoint_if_debugging() noexcept;
  bool is_debugger_present() noexcept;
}
\end{codeblock}

\rSec2[debugging.utility]{Utility}

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

\begin{itemdescr}

\pnum
The semantics of this function are \impldef{semantics of \tcode{breakpoint}}.

\begin{note}
When invoked, the execution of the program temporarily halts and execution is
handed to the debugger until such a time as: The program is terminated by the
debugger, or the debugger resumes execution of the program as if the function
was not invoked.
\end{note}

\end{itemdescr}

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

\begin{itemdescr}

\pnum
\effects
Equivalent to:
\begin{codeblock}
if (is_debugger_present()) breakpoint();
\end{codeblock}

\end{itemdescr}

\indexlibraryglobal{is_debugger_present}%
\begin{itemdecl}
bool is_debugger_present() noexcept;
\end{itemdecl}

\begin{itemdescr}

\pnum
The semantics of this function are \impldef{semantics of \tcode{is_debugger_present}}.

\begin{note}
When tracing the execution of a program with a debugger, an implementation
returns \tcode{true}. An implementation performs an immediate query, as needed,
to determine if the program is traced by a debugger. On Windows or equivalent
systems, this can be achieved by calling the \tcode{::IsDebuggerPresent()} Win32
function. On POSIX, this can be achieved by checking for a tracer parent process,
with best effort determination that such a tracer parent process is a debugger.
\end{note}

\end{itemdescr}