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{intseq}                & Compile-time integer sequences    & \\
\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{bitset}                & Fixed-size sequences of bits      & \tcode{<bitset>}      \\ \rowsep
\ref{memory}                & Memory                            &
  \tcode{<cstdlib>}, \tcode{<memory>} \\ \rowsep
\ref{smartptr}              & Smart pointers                    & \tcode{<memory>}      \\ \rowsep
\ref{mem.res}               & Memory resources                  & \tcode{<memory_resource>} \\ \rowsep
\ref{allocator.adaptor}     & Scoped allocators                 & \tcode{<scoped_allocator>} \\ \rowsep
\ref{function.objects}      & Function objects                  & \tcode{<functional>}  \\ \rowsep
\ref{meta}                  & Type traits                       & \tcode{<type_traits>} \\ \rowsep
\ref{ratio}                 & Compile-time rational arithmetic  & \tcode{<ratio>}       \\ \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>}      \\
\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}
#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);

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

  // \ref{pairs.spec}, pair specialized algorithms
  template<class T1, class T2>
    constexpr bool operator==(const pair<T1, T2>&, const pair<T1, T2>&);
  template<class T1, class T2>
    constexpr common_comparison_category_t<@\placeholder{synth-three-way-result}@<T1>,
                                           @\placeholder{synth-three-way-result}@<T2>>
      operator<=>(const pair<T1, T2>&, const pair<T1, T2>&);

  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 @\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> inline 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> inline constexpr in_place_index_t<I> in_place_index{};
}
\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
This function
is a designated customization point\iref{namespace.std}.
The expression inside \tcode{noexcept} 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);
\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}
\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}

\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> sp1 = 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{expr.prop}.

\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{basic.def.odr}.

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

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

\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},
\tcode{char8_t},
\tcode{char16_t},
\tcode{char32_t},
\tcode{wchar_t}, and
\tcode{bool}.
\end{note}

\rSec1[intseq]{Compile-time integer sequences}

\rSec2[intseq.general]{In general}

\pnum
The library provides a class template that can represent an integer sequence.
When used as an argument to a function template the template parameter pack defining the
sequence can be deduced and used in a pack expansion.
\begin{note}
The \tcode{index_sequence} alias template is provided for the common case of
an integer sequence of type \tcode{size_t}; see also \ref{tuple.apply}.
\end{note}

\rSec2[intseq.intseq]{Class template \tcode{integer_sequence}}

\indexlibraryglobal{integer_sequence}%
\indexlibrarymember{value_type}{integer_sequence}%
\begin{codeblock}
namespace std {
  template<class T, T... I> struct integer_sequence {
    using value_type = T;
    static constexpr size_t size() noexcept { return sizeof...(I); }
  };
}
\end{codeblock}

\pnum
\mandates
\tcode{T} is an integer type.

\rSec2[intseq.make]{Alias template \tcode{make_integer_sequence}}

\indexlibraryglobal{make_integer_sequence}%
\begin{itemdecl}
template<class T, T N>
  using make_integer_sequence = integer_sequence<T, @\seebelow{}@>;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
$\tcode{N} \geq 0$.

\pnum
The alias template
\tcode{make_integer_sequence} denotes a specialization of
\tcode{integer_sequence} with \tcode{N} non-type template arguments.
The type \tcode{make_integer_sequence<T, N>} is an alias for the type
\tcode{integer_sequence<T, 0, 1, ..., N-1>}.
\begin{note}
\tcode{make_integer_sequence<int, 0>} is an alias for the type
\tcode{integer_sequence<int>}.
\end{note}
\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, class U2>
      constexpr explicit(@\seebelow@) pair(U1&& x, U2&& y);
    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... Args1, class... Args2>
      constexpr pair(piecewise_construct_t,
                     tuple<Args1...> first_args, tuple<Args2...> second_args);

    constexpr pair& operator=(const pair& p);
    template<class U1, class U2>
      constexpr pair& operator=(const pair<U1, U2>& p);
    constexpr pair& operator=(pair&& p) noexcept(@\seebelow@);
    template<class U1, class U2>
      constexpr pair& operator=(pair<U1, U2>&& p);

    constexpr void swap(pair& p) 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 satisfy the
requirements for a constexpr function.

\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{temp.param}
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<first_type>} is \tcode{true} and
\item \tcode{is_default_constructible_v<second_type>} is \tcode{true}.
\end{itemize}

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

\pnum
\remarks
The expression inside \tcode{explicit} evaluates to \tcode{true}
if and only if either \tcode{first_type} or
\tcode{second_type} is not implicitly default-constructible.
\begin{note}
This behavior can be implemented with a trait that checks
whether a \tcode{const first_type\&} or a \tcode{const second_type\&}
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<first_type>} is \tcode{true} and
\item \tcode{is_copy_constructible_v<second_type>} is \tcode{true}.
\end{itemize}

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

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

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

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<first_type, U1>} is \tcode{true} and
\item \tcode{is_constructible_v<second_type, 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 \tcode{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<U1, first_type> || !is_convertible_v<U2, second_type>
\end{codeblock}
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<first_type, const U1\&>} is \tcode{true} and
\item \tcode{is_constructible_v<second_type, const U2\&>} is \tcode{true}.
\end{itemize}

\pnum
\effects
Initializes members from the corresponding members of the argument.

\pnum
\remarks
The expression inside explicit is equivalent to:
\begin{codeblock}
!is_convertible_v<const U1&, first_type> || !is_convertible_v<const U2&, second_type>
\end{codeblock}
\end{itemdescr}

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

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

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

\pnum
\remarks
The expression inside explicit is equivalent to:
\begin{codeblock}
!is_convertible_v<U1, first_type> || !is_convertible_v<U2, second_type>
\end{codeblock}
\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<first_type, Args1...>} is \tcode{true} and
\item \tcode{is_constructible_v<second_type, 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}.
\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
\remarks
This operator is defined as deleted unless
\tcode{is_copy_assignable_v<first_type>} is \tcode{true} and
\tcode{is_copy_assignable_v<second_type>} is \tcode{true}.

\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<first_type\&, const U1\&>} is \tcode{true} and
\item \tcode{is_assignable_v<second_type\&, 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<first_type>} is \tcode{true} and
\item \tcode{is_move_assignable_v<second_type>} is \tcode{true}.
\end{itemize}

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

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The expression inside \tcode{noexcept} 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}
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<first_type\&, U1>} is \tcode{true} and
\item \tcode{is_assignable_v<second_type\&, U2>} is \tcode{true}.
\end{itemize}

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

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

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

\begin{itemdescr}
\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 expression inside \tcode{noexcept} is equivalent to:
\begin{codeblock}
is_nothrow_swappable_v<first_type> && is_nothrow_swappable_v<second_type>
\end{codeblock}
\end{itemdescr}

\rSec2[pairs.spec]{Specialized algorithms}

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

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

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

\begin{itemdescr}
\pnum
\constraints
\tcode{is_swappable_v<T1>} is \tcode{true} and
\tcode{is_swappable_v<T2>} is \tcode{true}.

\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 \tcode{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}
#include <compare>              // see \ref{compare.syn}

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

  // \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<class... Tuples>
    constexpr tuple<CTypes...> tuple_cat(Tuples&&...);

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

  template<class T, class 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, class... UTypes>
    constexpr common_comparison_category_t<@\placeholder{synth-three-way-result}@<TTypes, UTypes>...>
      operator<=>(const tuple<TTypes...>&, const tuple<UTypes...>&);

  // \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@);

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

\rSec2[tuple.tuple]{Class template \tcode{tuple}}
\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(const tuple<UTypes...>&);
    template<class... UTypes>
      constexpr explicit(@\seebelow@) tuple(tuple<UTypes...>&&);

    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}

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

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

    template<class... UTypes>
      constexpr tuple& operator=(const tuple<UTypes...>&);
    template<class... UTypes>
      constexpr tuple& operator=(tuple<UTypes...>&&);

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

    // \ref{tuple.swap}, \tcode{tuple} swap
    constexpr void swap(tuple&) 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}

\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 satisfy the requirements for a constexpr function. 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.

\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 \tcode{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 \tcode{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
\constraints
\tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)} and
$\tcode{sizeof...(Types)} \geq 1$ and
\tcode{is_constructible_v<$\tcode{T}_i$, $\tcode{U}_i$>} is \tcode{true} for all $i$.

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

\pnum
\remarks
The expression inside \tcode{explicit} is equivalent to:
\begin{codeblock}
!conjunction_v<is_convertible<UTypes, Types>...>
\end{codeblock}
\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(const tuple<UTypes...>& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)} and

\item
\tcode{is_constructible_v<$\tcode{T}_i$, const $\tcode{U}_i$\&>} is \tcode{true} for all $i$, 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<const tuple<U>\&, T>}, \tcode{is_constructible_v<T, const tuple<U>\&>}, and \tcode{is_same_v<T, U>} are all \tcode{false}.
\end{itemize}

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

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

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

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item
\tcode{sizeof...(Types)} equals \tcode{sizeof...(UTypes)}, and

\item
\tcode{is_constructible_v<$\tcode{T}_i$, $\tcode{U}_i$>} is \tcode{true} for all $i$, 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<tuple<U>, T>}, \tcode{is_constructible_v<T, tuple<U>>},
and \tcode{is_same_v<T, U>} are all \tcode{false}.
\end{itemize}

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

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

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

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

\pnum
\effects
Initializes the first element with \tcode{u.first} and the
second element with \tcode{u.second}.

\pnum
The expression inside \tcode{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<const U1&, @$\tcode{T}_0$@> || !is_convertible_v<const U2&, @$\tcode{T}_1$@>
\end{codeblock}
\end{itemdescr}

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

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

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

\pnum
The expression inside \tcode{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<U1, @$\tcode{T}_0$@> || !is_convertible_v<U2, @$\tcode{T}_1$@>
\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, const tuple<UTypes...>&);
template<class Alloc, class... UTypes>
  constexpr explicit(@\seebelow@)
    tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
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>&&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{Alloc} meets the
\oldconcept{Allocator} requirements (\tref{cpp17.allocator}).

\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
\remarks
This operator is defined as deleted unless
\tcode{is_copy_assignable_v<$\tcode{T}_i$>} is \tcode{true} for all $i$.

\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
\remarks
The expression inside \tcode{noexcept} is equivalent to the logical \textsc{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}.

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

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

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

\begin{itemdescr}
\pnum
\expects
Each element in \tcode{*this} is swappable with\iref{swappable.requirements}
the corresponding element in \tcode{rhs}.

\pnum
\effects
Calls \tcode{swap} for each element in \tcode{*this} and its
corresponding element in \tcode{rhs}.

\pnum
\remarks
The expression inside \tcode{noexcept} is equivalent to the logical
\textsc{and} of the following expressions:

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

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

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

\pnum
In the function descriptions that follow, the members of a template parameter pack \tcode{\placeholder{X}Types}
are denoted by \tcode{\placeholder{X}}$_i$ for $i$ in \range{0}{sizeof...(\placeholder{X}Types)} in
order, where indexing is zero-based.

\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<class... Tuples>
  constexpr tuple<CTypes...> tuple_cat(Tuples&&... tpls);
\end{itemdecl}

\begin{itemdescr}
\pnum
In the following paragraphs, let $\tcode{T}_i$ be the $i^\text{th}$ type in \tcode{Tuples},
$\tcode{U}_i$ be \tcode{remove_reference_t<T$_i$>}, and $\tcode{tp}_i$ be the $i^\text{th}$
parameter in the function parameter pack \tcode{tpls}, where all indexing is
zero-based.

\pnum
\expects
For all $i$, $\tcode{U}_i$ is the type
$\cv_i$ \tcode{tuple<$\tcode{Args}_i$...>}, where $\cv_i$ is the (possibly empty) $i^\text{th}$
\grammarterm{cv-qualifier-seq} and $\tcode{Args}_i$ is the template parameter pack representing the element
types in $\tcode{U}_i$. Let $\tcode{A}_{ik}$ be the ${k}^\text{th}$ type in $\tcode{Args}_i$. For all
$\tcode{A}_{ik}$ the following requirements are met:
\begin{itemize}
\item If $\tcode{T}_i$ is deduced as an lvalue reference type, then
      \tcode{is_constructible_v<$\tcode{A}_{ik}$, $\cv{}_i\;\tcode{A}_{ik}$\&> == true}, otherwise
\item \tcode{is_constructible_v<$\tcode{A}_{ik}$, $\cv{}_i\;\tcode{A}_{ik}$\&\&> == true}.
\end{itemize}

\pnum
\remarks
The types in \tcode{CTypes} are equal to the ordered
sequence of the extended types
\tcode{$\tcode{Args}_0$..., $\tcode{Args}_1$..., $\dotsc$, $\tcode{Args}_{n-1}$...},
where $n$ is
equal to \tcode{sizeof...(Tuples)}. Let \tcode{$\tcode{e}_i$...} be the $i^\text{th}$
ordered sequence of tuple elements of the resulting \tcode{tuple} object
corresponding to the type sequence $\tcode{Args}_i$.

\pnum
\returns
A \tcode{tuple} object constructed by initializing the ${k_i}^\text{th}$
type element $\tcode{e}_{ik}$ in \tcode{$\tcode{e}_i$...} with
\begin{codeblock}
get<@$k_i$@>(std::forward<@$\tcode{T}_i$@>(@$\tcode{tp}_i$@))
\end{codeblock}
for each valid $k_i$ and each group $\tcode{e}_i$ in order.

\pnum
\begin{note}
An implementation can support additional types in the template parameter
pack \tcode{Tuples} that support the \tcode{tuple}-like protocol, such as
\tcode{pair} and \tcode{array}.
\end{note}
\end{itemdescr}

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

\indexlibraryglobal{apply}%
\begin{itemdecl}
template<class F, class Tuple>
  constexpr decltype(auto) apply(F&& f, Tuple&& t);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Given the exposition-only function:
\begin{codeblock}
template<class F, class 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), std::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}
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\effects
Given the exposition-only function:
\begin{codeblock}
template<class T, class Tuple, size_t... I>
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>(
           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
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, 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 member variables 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);
\end{itemdecl}

\begin{itemdescr}
\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
returning a type that is convertible to \tcode{bool}.
\tcode{sizeof...(TTypes)} equals
\tcode{sizeof...(UTypes)}.

\pnum
\returns
\tcode{true} if \tcode{get<i>(t) == get<i>(u)} for all
\tcode{i}, otherwise \tcode{false}.
For any two zero-length tuples \tcode{e} and \tcode{f}, \tcode{e == f} returns \tcode{true}.

\pnum
\effects
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}.
\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);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Performs a lexicographical comparison between \tcode{t} and \tcode{u}.
For any two zero-length tuples \tcode{t} and \tcode{u},
\tcode{t <=> u} 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 tuple \tcode{r}
is a tuple containing all but the first element of \tcode{r}.
\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 required to determine the
result of the comparison.
\end{note}

\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 (\tref{cpp17.allocator}).

\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@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_swappable_v<T>} is \tcode{true}
for every type \tcode{T} in \tcode{Types}.

\pnum
\remarks
The expression inside \tcode{noexcept} is equivalent to:

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

\pnum
\effects
As if by \tcode{x.swap(y)}.
\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}
#include <compare>              // see \ref{compare.syn}

namespace std {
  // \ref{optional.optional}, class template \tcode{optional}
  template<class T>
    class optional;

  // \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, @\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>
    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>
      explicit(@\seebelow@) optional(const optional<U>&);
    template<class U>
      explicit(@\seebelow@) optional(optional<U>&&);

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

    // \ref{optional.assign}, assignment
    optional& operator=(nullopt_t) noexcept;
    constexpr optional& operator=(const optional&);
    constexpr optional& operator=(optional&&) noexcept(@\seebelow@);
    template<class U = T> optional& operator=(U&&);
    template<class U> optional& operator=(const optional<U>&);
    template<class U> optional& operator=(optional<U>&&);
    template<class... Args> T& emplace(Args&&...);
    template<class U, class... Args> T& emplace(initializer_list<U>, Args&&...);

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

    // \ref{optional.observe}, observers
    constexpr const T* operator->() const;
    constexpr T* operator->();
    constexpr const T& operator*() const&;
    constexpr T& operator*() &;
    constexpr T&& operator*() &&;
    constexpr const T&& operator*() const&&;
    constexpr explicit operator bool() const noexcept;
    constexpr bool has_value() const noexcept;
    constexpr const T& value() const&;
    constexpr T& value() &;
    constexpr T&& value() &&;
    constexpr const T&& value() const&&;
    template<class U> constexpr T value_or(U&&) const&;
    template<class U> constexpr T value_or(U&&) &&;

    // \ref{optional.mod}, modifiers
    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.
The contained value shall be allocated in a region of the \tcode{optional<T>} storage suitably aligned for the type \tcode{T}.
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
Member \tcode{val} is provided for exposition only. When an \tcode{optional<T>} object contains a value, \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}

\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, initializes the contained value as if
direct-non-list-initializing an object of type \tcode{T} with the expression \tcode{*rhs}.

\pnum
\ensures
\tcode{bool(rhs) == bool(*this)}.

\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, initializes the contained value as if
direct-non-list-initializing an object of type \tcode{T} with the expression \tcode{std::move(*rhs)}.
\tcode{bool(rhs)} is unchanged.

\pnum
\ensures
\tcode{bool(rhs) == bool(*this)}.

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

\pnum
\remarks
The expression inside \tcode{noexcept} 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
Initializes the contained value as if direct-non-list-initializing an object of type \tcode{T} with the arguments \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
Initializes the contained value as if direct-non-list-initializing an object of type \tcode{T} with the arguments \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
\tcode{is_constructible_v<T, U>} is \tcode{true},
\tcode{is_same_v<remove_cvref_t<U>, in_place_t>} is \tcode{false}, and
\tcode{is_same_v<remove_cvref_t<U>, optional>} is \tcode{false}.

\pnum
\effects
Initializes the contained value as if direct-non-list-initializing
an object of type \tcode{T} with the expression \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 \tcode{explicit} is equivalent to:
\begin{codeblock}
!is_convertible_v<U, T>
\end{codeblock}
\end{itemdescr}

\indexlibraryctor{optional}%
\begin{itemdecl}
template<class U> 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},
\item \tcode{is_constructible_v<T, optional<U>\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, optional<U>\&\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, const optional<U>\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, const optional<U>\&\&>} is \tcode{false},
\item \tcode{is_convertible_v<optional<U>\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<optional<U>\&\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<const optional<U>\&, T>} is \tcode{false}, and
\item \tcode{is_convertible_v<const optional<U>\&\&, T>} is \tcode{false}.
\end{itemize}

\pnum
\effects
If \tcode{rhs} contains a value,
initializes the contained value as if direct-non-list-initializing
an object of type \tcode{T} with the expression \tcode{*rhs}.

\pnum
\ensures
\tcode{bool(rhs)} == \tcode{bool(*this)}.

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

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

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

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{is_constructible_v<T, U>} is true,
\item \tcode{is_constructible_v<T, optional<U>\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, optional<U>\&\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, const optional<U>\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, const optional<U>\&\&>} is \tcode{false},
\item \tcode{is_convertible_v<optional<U>\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<optional<U>\&\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<const optional<U>\&, T>} is \tcode{false}, and
\item \tcode{is_convertible_v<const optional<U>\&\&, T>} is \tcode{false}.
\end{itemize}

\pnum
\effects
If \tcode{rhs} contains a value,
initializes the contained value as if direct-non-list-initializing
an object of type \tcode{T} with the expression \tcode{std::move(*rhs)}.
\tcode{bool(rhs)} is unchanged.

\pnum
\ensures
\tcode{bool(rhs)} == \tcode{bool(*this)}.

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

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

\rSec3[optional.dtor]{Destructor}

\indexlibrarydtor{optional}%
\begin{itemdecl}
~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}
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 &
initializes the contained value as if direct-non-list-initializing an object of type \tcode{T} 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{bool(rhs) == bool(*this)}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
If any exception is thrown, the result of the expression \tcode{bool(*this)} 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{bool(rhs)} 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 &
initializes the contained value as if direct-non-list-initializing an object of type \tcode{T} 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{bool(rhs) == bool(*this)}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The expression inside \tcode{noexcept} 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{bool(*this)} 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> 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 initializes the contained value as if direct-non-list-initializing object of type \tcode{T} 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{bool(*this)} 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> 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{is_constructible_v<T, optional<U>\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, optional<U>\&\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, const optional<U>\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, const optional<U>\&\&>} is \tcode{false},
\item \tcode{is_convertible_v<optional<U>\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<optional<U>\&\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<const optional<U>\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<const optional<U>\&\&, T>} 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 &
initializes the contained value as if direct-non-list-initializing
an object of type \tcode{T} 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{bool(rhs) == bool(*this)}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
If any exception is thrown,
the result of the expression \tcode{bool(*this)} 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> 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{is_constructible_v<T, optional<U>\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, optional<U>\&\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, const optional<U>\&>} is \tcode{false},
\item \tcode{is_constructible_v<T, const optional<U>\&\&>} is \tcode{false},
\item \tcode{is_convertible_v<optional<U>\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<optional<U>\&\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<const optional<U>\&, T>} is \tcode{false},
\item \tcode{is_convertible_v<const optional<U>\&\&, T>} 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{bool(rhs)} 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 &
initializes the contained value as if direct-non-list-initializing
an object of type \tcode{T} 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{bool(rhs) == bool(*this)}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
If any exception is thrown,
the result of the expression \tcode{bool(*this)} 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> 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 initializes the contained value as if direct-non-list-initializing an object of type \tcode{T} with the arguments \tcode{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{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> 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 initializes the contained value as if direct-non-list-initializing an object of type \tcode{T} with the arguments \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{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}
void swap(optional& rhs) noexcept(@\seebelow@);
\end{itemdecl}

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

\pnum
\expects
Lvalues of type \tcode{T} are swappable.

\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)} &
initializes the contained value of \tcode{*this} as if
direct-non-list-initializing an object of type \tcode{T} with the expression \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} &
initializes the contained value of \tcode{rhs} as if
direct-non-list-initializing an object of type \tcode{T} with the expression \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 expression inside \tcode{noexcept} is equivalent to:
\begin{codeblock}
is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T>
\end{codeblock}
If any exception is thrown, the results of the expressions \tcode{bool(*this)} and \tcode{bool(rhs)} 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;
constexpr T* operator->();
\end{itemdecl}

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

\pnum
\returns
\tcode{val}.

\pnum
\throws
Nothing.

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

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

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

\pnum
\returns
\tcode{*val}.

\pnum
\throws
Nothing.

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

\indexlibrarymember{operator*}{optional}%
\begin{itemdecl}
constexpr T&& operator*() &&;
constexpr const T&& operator*() const&&;
\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 bool(*this) ? *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 bool(*this) ? 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 bool(*this) ? **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 bool(*this) ? std::move(**this) : static_cast<T>(std::forward<U>(v));
\end{codeblock}
\end{itemdescr}

\rSec3[optional.mod]{Modifiers}

\indexlibrarymember{reset}{optional}%
\begin{itemdecl}
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}
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{bool(x) != bool(y)}, \tcode{false}; otherwise if \tcode{bool(x) == 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{bool(x) != bool(y)}, \tcode{true};
otherwise, if \tcode{bool(x) == 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{bool(x) <=> bool(y)}.

\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{bool(x) <=> 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 bool(x) ?\ *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 bool(x) ?\ 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 bool(x) ?\ *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 bool(x) ?\ 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 bool(x) ?\ *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 bool(x) ?\ 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 bool(x) ?\ *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 bool(x) ?\ 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 bool(x) ?\ *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 bool(x) ?\ 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 bool(x) ?\ *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 bool(x) ?\ v >= *x :\ true;}
\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 U& v);
\end{itemdecl}

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

\rSec2[optional.specalg]{Specialized algorithms}

\indexlibrarymember{swap}{optional}%
\begin{itemdecl}
template<class T> 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{bool(o) == 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 \tcode{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.

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

\begin{codeblock}
#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>
    inline 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...>&);
  template<size_t I, class... Types>
    constexpr variant_alternative_t<I, variant<Types...>>&& get(variant<Types...>&&);
  template<size_t I, class... Types>
    constexpr const variant_alternative_t<I, variant<Types...>>& get(const variant<Types...>&);
  template<size_t I, class... Types>
    constexpr const variant_alternative_t<I, variant<Types...>>&& get(const variant<Types...>&&);

  template<class T, class... Types>
    constexpr T& get(variant<Types...>&);
  template<class T, class... Types>
    constexpr T&& get(variant<Types...>&&);
  template<class T, class... Types>
    constexpr const T& get(const variant<Types...>&);
  template<class T, class... Types>
    constexpr const T&& get(const variant<Types...>&&);

  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 (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>
    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
    ~variant();

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

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

    // \ref{variant.mod}, modifiers
    template<class T, class... Args>
      T& emplace(Args&&...);
    template<class T, class U, class... Args>
      T& emplace(initializer_list<U>, Args&&...);
    template<size_t I, class... Args>
      variant_alternative_t<I, variant<Types...>>& emplace(Args&&...);
    template<size_t I, class U, class... Args>
      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
    void swap(variant&) noexcept(@\seebelow@);
  };
}
\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.
The contained value shall be allocated in a region of the \tcode{variant}
storage suitably aligned for all types in \tcode{Types}.

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

\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 \tcode{constexpr} if and only if the
value-initialization of the alternative type $\tcode{T}_0$ would satisfy the
requirements for a constexpr function.
The expression inside \tcode{noexcept} 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{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{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 expression inside \tcode{noexcept} is equivalent to the logical \logop{AND} of
\tcode{is_nothrow_move_constructible_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-initializes the contained value as if direct-non-list-initializing it
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 expression inside \tcode{noexcept} 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
Initializes the contained value as if direct-non-list-initializing
an object of type \tcode{T}
with the arguments \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
Initializes the contained value as if direct-non-list-initializing
an object of type \tcode{T}
with the arguments \tcode{il, 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<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
Initializes the contained value as if direct-non-list-initializing
an object of type $\tcode{T}_I$
with the arguments \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
Initializes the contained value as if direct-non-list-initializing
an object of type $\tcode{T}_I$
with the arguments \tcode{il, std::forward<Args>(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}
~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$>(get<$j$>(rhs))}.
\item
Otherwise, equivalent to \tcode{operator=(variant(rhs))}.
\end{itemize}

\pnum
\returns
\tcode{*this}.

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

\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{get<$j$>(std::move(rhs))} to
the value contained in \tcode{*this}.
\item
Otherwise, equivalent to \tcode{emplace<$j$>(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 expression inside \tcode{noexcept} 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> 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{operator=(variant(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 expression inside \tcode{noexcept} 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> 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> 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>
  variant_alternative_t<I, variant<Types...>>& emplace(Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\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 initializes the contained value as if direct-non-list-initializing
a 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>
  variant_alternative_t<I, variant<Types...>>& emplace(initializer_list<U> il, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\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 initializes the contained value as if direct-non-list-initializing
a value of type $\tcode{T}_I$
with the arguments \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}
A \tcode{variant} might not hold a 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}
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
Lvalues of type $\tcode{T}_i$ are swappable\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(get<$i$>(*this), 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(get<$i$>(*this), 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(get<$i$>(*this), 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 expression inside \tcode{noexcept} 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}

\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 \tcode{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{get<$i$>(v) == 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{get<$i$>(v) == 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{get<$i$>(v) != 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{get<$i$>(v) != 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{get<$i$>(v) < 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{get<$i$>(v) < 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{get<$i$>(v) > 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{get<$i$>(v) > 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{get<$i$>(v) <= 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{get<$i$>(v) <= 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{get<$i$>(v) >= 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{get<$i$>(v) >= get<$i$>(w)} with $i$ being \tcode{v.index()}.
\end{itemdescr}

\indexlibrarymember{operator<=>}{variant}%
\begin{itemdecl}
template<class... Types> requires (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 get<@$i$@>(v) <=> 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 $n$ be \tcode{sizeof...(Variants)}. Let \tcode{m} be a pack of $n$
values of type \tcode{size_t}. Such a pack is called valid if $0 \leq
\tcode{m}_i < \tcode{variant_size_v<remove_reference_t<Variants}_i\tcode{>>}$ for
all $0 \leq i < n$. For each valid pack $\tcode{m}$, let $e(\tcode{m})$
denote the expression:
\begin{codeblock}
@\placeholder{INVOKE}@(std::forward<Visitor>(vis), get<m>(std::forward<Variants>(vars))...) // see \ref{func.require}
\end{codeblock}
for the first form and
\begin{codeblock}
@\placeholder{INVOKE}@<R>(std::forward<Visitor>(vis), get<m>(std::forward<Variants>(vars))...) // see \ref{func.require}
\end{codeblock}
for the second form.

\pnum
\mandates
For each valid pack \tcode{m}, $e(\tcode{m})$ is a valid expression.
All such expressions are of the same type and value category.

\pnum
\returns
$e(\tcode{m})$, where \tcode{m} is the pack for which
$\tcode{m}_i$ is \tcode{vars$_i$.index()} for all $0 \leq i < n$.
The return type is $\tcode{decltype(}e(\tcode{m})\tcode{)}$
for the first form.

\pnum
\throws
\tcode{bad_variant_access} if any \tcode{variant} in \tcode{vars} is \tcode{valueless_by_exception()}.

\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{Variants}_0$.
For $n > 1$, the invocation of the callable object has
no complexity requirements.
\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>
  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 expression inside \tcode{noexcept} 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}
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 \tcode{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}
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
Initializes the contained value as if direct-non-list-initializing an object of
type \tcode{VT} with the arguments \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
Initializes the contained value as if direct-non-list-initializing an object of
type \tcode{VT} with the arguments \tcode{il, std::forward<Args>(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
\returns
\tcode{*this}.

\pnum
\ensures
The state of \tcode{*this} is equivalent to the original state of \tcode{rhs}.
\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 initializes the contained value as if direct-non-list-initializing
an object of type \tcode{VT} with the arguments \tcode{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{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 initializes the contained value
as if direct-non-list-initializing an object of type \tcode{VT} with the arguments
\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
\returns
If \tcode{operand != nullptr \&\& operand->type() == typeid(T)},
a pointer to the object contained by \tcode{operand};
otherwise, \tcode{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[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>
#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>
    bitset<N> operator&(const bitset<N>&, const bitset<N>&) noexcept;
  template<size_t N>
    bitset<N> operator|(const bitset<N>&, const bitset<N>&) noexcept;
  template<size_t N>
    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;
      reference() noexcept;

    public:
      reference(const reference&) = default;
      ~reference();
      reference& operator=(bool x) noexcept;            // for \tcode{b[i] = x;}
      reference& operator=(const reference&) noexcept;  // for \tcode{b[i] = b[j];}
      bool operator~() const noexcept;                  // flips the bit
      operator bool() const noexcept;                   // for \tcode{x = b[i];}
      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>
      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>
      explicit bitset(
        const charT* str,
        typename basic_string<charT>::size_type n = basic_string<charT>::npos,
        charT zero = charT('0'),
        charT one = charT('1'));

    // \ref{bitset.members}, bitset operations
    bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator|=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator^=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator<<=(size_t pos) noexcept;
    bitset<N>& operator>>=(size_t pos) noexcept;
    bitset<N>& set() noexcept;
    bitset<N>& set(size_t pos, bool val = true);
    bitset<N>& reset() noexcept;
    bitset<N>& reset(size_t pos);
    bitset<N>  operator~() const noexcept;
    bitset<N>& flip() noexcept;
    bitset<N>& flip(size_t pos);

    // element access
    constexpr bool operator[](size_t pos) const;        // for \tcode{b[i];}
    reference operator[](size_t pos);                   // for \tcode{b[i];}

    unsigned long to_ulong() const;
    unsigned long long to_ullong() const;
    template<class charT = char,
             class traits = char_traits<charT>,
             class Allocator = allocator<charT>>
      basic_string<charT, traits, Allocator>
        to_string(charT zero = charT('0'), charT one = charT('1')) const;

    size_t count() const noexcept;
    constexpr size_t size() const noexcept;
    bool operator==(const bitset<N>& rhs) const noexcept;
    bool test(size_t pos) const;
    bool all() const noexcept;
    bool any() const noexcept;
    bool none() const noexcept;
    bitset<N> operator<<(size_t pos) const noexcept;
    bitset<N> operator>>(size_t pos) 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{basic.types} 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>
  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'));
\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>
  explicit bitset(
    const charT* str,
    typename basic_string<charT>::size_type n = basic_string<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<charT>::npos
          ? basic_string<charT>(str)
          : basic_string<charT>(str, n),
       0, n, zero, one)
\end{codeblock}
\end{itemdescr}


\rSec3[bitset.members]{Members}

\indexlibrarymember{operator\&=}{bitset}%
\begin{itemdecl}
bitset<N>& operator&=(const bitset<N>& 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}
bitset<N>& operator|=(const bitset<N>& 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}
bitset<N>& operator^=(const bitset<N>& 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}
bitset<N>& 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}
bitset<N>& 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}

% Do not use \indexlibrarymember.
\indexlibrary{\idxcode{set} (member)!\idxcode{bitset}}%
\indexlibrary{\idxcode{bitset}!\idxcode{set}}%
\begin{itemdecl}
bitset<N>& 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}
bitset<N>& 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}
bitset<N>& 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}
bitset<N>& 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}
bitset<N> operator~() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object \tcode{x} of class
\tcode{bitset<N>}
and initializes it with
\tcode{*this}.

\pnum
\returns
\tcode{x.flip()}.
\end{itemdescr}

\indexlibrarymember{flip}{bitset}%
\begin{itemdecl}
bitset<N>& 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}
bitset<N>& 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{to_ulong}{bitset}%
\begin{itemdecl}
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}
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>>
  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}
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}
bool operator==(const bitset<N>& 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}
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}
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}
bool any() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{count() != 0}.
\end{itemdescr}

\indexlibrarymember{none}{bitset}%
\begin{itemdecl}
bool none() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{count() == 0}.
\end{itemdescr}

\indexlibrarymember{operator<<}{bitset}%
\begin{itemdecl}
bitset<N> operator<<(size_t pos) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{bitset<N>(*this) <<= pos}.
\end{itemdescr}

\indexlibrarymember{operator>>}{bitset}%
\begin{itemdecl}
bitset<N> operator>>(size_t pos) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{bitset<N>(*this) >>= pos}.
\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}
bitset<N>::reference operator[](size_t pos);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{pos} is valid.

\pnum
\returns
An object of type
\tcode{bitset<N>::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}

\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}
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}
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}
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}, calls
\tcode{is.setstate(ios_base::failbit)}
(which may throw
\tcode{ios_base::failure}\iref{iostate.flags}).

\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[memory]{Memory}

\rSec2[memory.general]{In general}

\pnum
Subclause~\ref{memory} describes the contents of the header
\libheaderref{memory} and some
of the contents of the header \libheaderref{cstdlib}.

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

\pnum
The header \libheaderdef{memory} defines several types and function templates that
describe properties of pointers and pointer-like types, manage memory
for containers and other template types, destroy objects, and
construct objects in
uninitialized memory
buffers~(\ref{pointer.traits}--\ref{specialized.addressof} and \ref{specialized.algorithms}).
The header also defines the templates
\tcode{unique_ptr}, \tcode{shared_ptr}, \tcode{weak_ptr}, and various function
templates that operate on objects of these types\iref{smartptr}.

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

namespace std {
  // \ref{pointer.traits}, pointer traits
  template<class Ptr> struct pointer_traits;
  template<class T> struct pointer_traits<T*>;

  // \ref{pointer.conversion}, pointer conversion
  template<class T>
    constexpr T* to_address(T* p) noexcept;
  template<class Ptr>
    constexpr auto to_address(const Ptr& p) noexcept;

  // \ref{util.dynamic.safety}, pointer safety%
\indexlibraryglobal{in_place}%
\indexlibrarymember{relaxed}{pointer_safety}%
\indexlibrarymember{preferred}{pointer_safety}%
\indexlibrarymember{strict}{pointer_safety}
  enum class pointer_safety { relaxed, preferred, strict };
  void declare_reachable(void* p);
  template<class T>
    T* undeclare_reachable(T* p);
  void declare_no_pointers(char* p, size_t n);
  void undeclare_no_pointers(char* p, size_t n);
  pointer_safety get_pointer_safety() noexcept;

  // \ref{ptr.align}, pointer alignment
  void* align(size_t alignment, size_t size, void*& ptr, size_t& space);
  template<size_t N, class T>
    [[nodiscard]] constexpr T* assume_aligned(T* ptr);

  // \ref{allocator.tag}, allocator argument tag
  struct allocator_arg_t { explicit allocator_arg_t() = default; };
  inline constexpr allocator_arg_t allocator_arg{};

  // \ref{allocator.uses}, \tcode{uses_allocator}
  template<class T, class Alloc> struct uses_allocator;

  // \ref{allocator.uses.trait}, \tcode{uses_allocator}
  template<class T, class Alloc>
    inline constexpr bool @\libglobal{uses_allocator_v}@ = uses_allocator<T, Alloc>::value;

  // \ref{allocator.uses.construction}, uses-allocator construction
  template<class T, class Alloc, class... Args>
    constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                    Args&&... args) noexcept -> @\seebelow@;
  template<class T, class Alloc, class Tuple1, class Tuple2>
    constexpr auto uses_allocator_construction_args(const Alloc& alloc, piecewise_construct_t,
                                                    Tuple1&& x, Tuple2&& y)
                                                    noexcept ->  @\seebelow@;
  template<class T, class Alloc>
    constexpr auto uses_allocator_construction_args(const Alloc& alloc) noexcept -> @\seebelow@;
  template<class T, class Alloc, class U, class V>
    constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                    U&& u, V&& v) noexcept -> @\seebelow@;
  template<class T, class Alloc, class U, class V>
    constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                    const pair<U,V>& pr) noexcept -> @\seebelow@;
  template<class T, class Alloc, class U, class V>
    constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                    pair<U,V>&& pr) noexcept -> @\seebelow@;
  template<class T, class Alloc, class... Args>
    constexpr T make_obj_using_allocator(const Alloc& alloc, Args&&... args);
  template<class T, class Alloc, class... Args>
    constexpr T* uninitialized_construct_using_allocator(T* p, const Alloc& alloc,
                                                         Args&&... args);

  // \ref{allocator.traits}, allocator traits
  template<class Alloc> struct allocator_traits;

  // \ref{default.allocator}, the default allocator
  template<class T> class allocator;
  template<class T, class U>
    constexpr bool operator==(const allocator<T>&, const allocator<U>&) noexcept;

  // \ref{specialized.addressof}, addressof
  template<class T>
    constexpr T* addressof(T& r) noexcept;
  template<class T>
    const T* addressof(const T&&) = delete;

  // \ref{specialized.algorithms}, specialized algorithms
  // \ref{special.mem.concepts}, special memory concepts
  template<class I>
    concept @\exposconcept{no-throw-input-iterator}@ = @\seebelow@;    // \expos
  template<class I>
    concept @\exposconcept{no-throw-forward-iterator}@ = @\seebelow@;  // \expos
  template<class S, class I>
    concept @\exposconcept{no-throw-sentinel}@ = @\seebelow@;          // \expos
  template<class R>
    concept @\exposconcept{no-throw-input-range}@ = @\seebelow@;       // \expos
  template<class R>
    concept @\exposconcept{no-throw-forward-range}@ = @\seebelow@;     // \expos

  template<class NoThrowForwardIterator>
    void uninitialized_default_construct(NoThrowForwardIterator first,
                                         NoThrowForwardIterator last);
  template<class ExecutionPolicy, class NoThrowForwardIterator>
    void uninitialized_default_construct(ExecutionPolicy&& exec,        // see \ref{algorithms.parallel.overloads}
                                         NoThrowForwardIterator first,
                                         NoThrowForwardIterator last);
  template<class NoThrowForwardIterator, class Size>
    NoThrowForwardIterator
      uninitialized_default_construct_n(NoThrowForwardIterator first, Size n);
  template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>
    NoThrowForwardIterator
      uninitialized_default_construct_n(ExecutionPolicy&& exec,         // see \ref{algorithms.parallel.overloads}
                                        NoThrowForwardIterator first, Size n);

  namespace ranges {
    template<@\exposconcept{no-throw-forward-iterator}@ I, @\exposconcept{no-throw-sentinel}@<I> S>
      requires default_initializable<iter_value_t<I>>
        I uninitialized_default_construct(I first, S last);
    template<@\exposconcept{no-throw-forward-range}@ R>
      requires default_initializable<range_value_t<R>>
        borrowed_iterator_t<R> uninitialized_default_construct(R&& r);

    template<@\exposconcept{no-throw-forward-iterator}@ I>
      requires default_initializable<iter_value_t<I>>
        I uninitialized_default_construct_n(I first, iter_difference_t<I> n);
  }

  template<class NoThrowForwardIterator>
    void uninitialized_value_construct(NoThrowForwardIterator first,
                                       NoThrowForwardIterator last);
  template<class ExecutionPolicy, class NoThrowForwardIterator>
    void uninitialized_value_construct(ExecutionPolicy&& exec,  // see \ref{algorithms.parallel.overloads}
                                       NoThrowForwardIterator first,
                                       NoThrowForwardIterator last);
  template<class NoThrowForwardIterator, class Size>
    NoThrowForwardIterator
      uninitialized_value_construct_n(NoThrowForwardIterator first, Size n);
  template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>
    NoThrowForwardIterator
      uninitialized_value_construct_n(ExecutionPolicy&& exec,   // see \ref{algorithms.parallel.overloads}
                                      NoThrowForwardIterator first, Size n);

  namespace ranges {
    template<@\exposconcept{no-throw-forward-iterator}@ I, @\exposconcept{no-throw-sentinel}@<I> S>
      requires default_initializable<iter_value_t<I>>
        I uninitialized_value_construct(I first, S last);
    template<@\exposconcept{no-throw-forward-range}@ R>
      requires default_initializable<range_value_t<R>>
        borrowed_iterator_t<R> uninitialized_value_construct(R&& r);

    template<@\exposconcept{no-throw-forward-iterator}@ I>
      requires default_initializable<iter_value_t<I>>
        I uninitialized_value_construct_n(I first, iter_difference_t<I> n);
  }

  template<class InputIterator, class NoThrowForwardIterator>
    NoThrowForwardIterator uninitialized_copy(InputIterator first, InputIterator last,
                                              NoThrowForwardIterator result);
  template<class ExecutionPolicy, class InputIterator, class NoThrowForwardIterator>
    NoThrowForwardIterator uninitialized_copy(ExecutionPolicy&& exec,   // see \ref{algorithms.parallel.overloads}
                                              InputIterator first, InputIterator last,
                                              NoThrowForwardIterator result);
  template<class InputIterator, class Size, class NoThrowForwardIterator>
    NoThrowForwardIterator uninitialized_copy_n(InputIterator first, Size n,
                                                NoThrowForwardIterator result);
  template<class ExecutionPolicy, class InputIterator, class Size, class NoThrowForwardIterator>
    NoThrowForwardIterator uninitialized_copy_n(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}
                                                InputIterator first, Size n,
                                                NoThrowForwardIterator result);

  namespace ranges {
    template<class I, class O>
      using uninitialized_copy_result = in_out_result<I, O>;
    template<@\libconcept{input_iterator}@ I, @\libconcept{sentinel_for}@<I> S1,
             @\exposconcept{no-throw-forward-iterator}@ O, @\exposconcept{no-throw-sentinel}@<O> S2>
      requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_reference_t<I>>
        uninitialized_copy_result<I, O>
          uninitialized_copy(I ifirst, S1 ilast, O ofirst, S2 olast);
    template<@\libconcept{input_range}@ IR, @\exposconcept{no-throw-forward-range}@ OR>
      requires @\libconcept{constructible_from}@<range_value_t<OR>, range_reference_t<IR>>
        uninitialized_copy_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>
          uninitialized_copy(IR&& in_range, OR&& out_range);

    template<class I, class O>
      using uninitialized_copy_n_result = in_out_result<I, O>;
    template<@\libconcept{input_iterator}@ I, @\exposconcept{no-throw-forward-iterator}@ O, @\exposconcept{no-throw-sentinel}@<O> S>
      requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_reference_t<I>>
        uninitialized_copy_n_result<I, O>
          uninitialized_copy_n(I ifirst, iter_difference_t<I> n, O ofirst, S olast);
  }

  template<class InputIterator, class NoThrowForwardIterator>
    NoThrowForwardIterator uninitialized_move(InputIterator first, InputIterator last,
                                              NoThrowForwardIterator result);
  template<class ExecutionPolicy, class InputIterator, class NoThrowForwardIterator>
    NoThrowForwardIterator uninitialized_move(ExecutionPolicy&& exec,   // see \ref{algorithms.parallel.overloads}
                                              InputIterator first, InputIterator last,
                                              NoThrowForwardIterator result);
  template<class InputIterator, class Size, class NoThrowForwardIterator>
    pair<InputIterator, NoThrowForwardIterator>
      uninitialized_move_n(InputIterator first, Size n, NoThrowForwardIterator result);
  template<class ExecutionPolicy, class InputIterator, class Size, class NoThrowForwardIterator>
    pair<InputIterator, NoThrowForwardIterator>
      uninitialized_move_n(ExecutionPolicy&& exec,              // see \ref{algorithms.parallel.overloads}
                           InputIterator first, Size n, NoThrowForwardIterator result);

  namespace ranges {
    template<class I, class O>
      using uninitialized_move_result = in_out_result<I, O>;
    template<@\libconcept{input_iterator}@ I, @\libconcept{sentinel_for}@<I> S1,
             @\exposconcept{no-throw-forward-iterator}@ O, @\exposconcept{no-throw-sentinel}@<O> S2>
      requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_rvalue_reference_t<I>>
        uninitialized_move_result<I, O>
          uninitialized_move(I ifirst, S1 ilast, O ofirst, S2 olast);
    template<@\libconcept{input_range}@ IR, @\exposconcept{no-throw-forward-range}@ OR>
      requires @\libconcept{constructible_from}@<range_value_t<OR>, range_rvalue_reference_t<IR>>
        uninitialized_move_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>
          uninitialized_move(IR&& in_range, OR&& out_range);

    template<class I, class O>
      using uninitialized_move_n_result = in_out_result<I, O>;
    template<@\libconcept{input_iterator}@ I,
             @\exposconcept{no-throw-forward-iterator}@ O, @\exposconcept{no-throw-sentinel}@<O> S>
      requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_rvalue_reference_t<I>>
        uninitialized_move_n_result<I, O>
          uninitialized_move_n(I ifirst, iter_difference_t<I> n, O ofirst, S olast);
  }

  template<class NoThrowForwardIterator, class T>
    void uninitialized_fill(NoThrowForwardIterator first, NoThrowForwardIterator last,
                            const T& x);
  template<class ExecutionPolicy, class NoThrowForwardIterator, class T>
    void uninitialized_fill(ExecutionPolicy&& exec,             // see \ref{algorithms.parallel.overloads}
                            NoThrowForwardIterator first, NoThrowForwardIterator last,
                            const T& x);
  template<class NoThrowForwardIterator, class Size, class T>
    NoThrowForwardIterator
      uninitialized_fill_n(NoThrowForwardIterator first, Size n, const T& x);
  template<class ExecutionPolicy, class NoThrowForwardIterator, class Size, class T>
    NoThrowForwardIterator
      uninitialized_fill_n(ExecutionPolicy&& exec,              // see \ref{algorithms.parallel.overloads}
                           NoThrowForwardIterator first, Size n, const T& x);

  namespace ranges {
    template<@\exposconcept{no-throw-forward-iterator}@ I, @\exposconcept{no-throw-sentinel}@<I> S, class T>
      requires @\libconcept{constructible_from}@<iter_value_t<I>, const T&>
        I uninitialized_fill(I first, S last, const T& x);
    template<@\exposconcept{no-throw-forward-range}@ R, class T>
      requires @\libconcept{constructible_from}@<range_value_t<R>, const T&>
        borrowed_iterator_t<R> uninitialized_fill(R&& r, const T& x);

    template<@\exposconcept{no-throw-forward-iterator}@ I, class T>
      requires @\libconcept{constructible_from}@<iter_value_t<I>, const T&>
        I uninitialized_fill_n(I first, iter_difference_t<I> n, const T& x);
  }

  // \ref{specialized.construct}, \tcode{construct_at}
  template<class T, class... Args>
    constexpr T* construct_at(T* location, Args&&... args);

  namespace ranges {
    template<class T, class... Args>
      constexpr T* construct_at(T* location, Args&&... args);
  }

  // \ref{specialized.destroy}, \tcode{destroy}
  template<class T>
    constexpr void destroy_at(T* location);
  template<class NoThrowForwardIterator>
    constexpr void destroy(NoThrowForwardIterator first, NoThrowForwardIterator last);
  template<class ExecutionPolicy, class NoThrowForwardIterator>
    void destroy(ExecutionPolicy&& exec,                        // see \ref{algorithms.parallel.overloads}
                 NoThrowForwardIterator first, NoThrowForwardIterator last);
  template<class NoThrowForwardIterator, class Size>
    constexpr NoThrowForwardIterator destroy_n(NoThrowForwardIterator first, Size n);
  template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>
    NoThrowForwardIterator destroy_n(ExecutionPolicy&& exec,    // see \ref{algorithms.parallel.overloads}
                                     NoThrowForwardIterator first, Size n);

  namespace ranges {
    template<@\libconcept{destructible}@ T>
      constexpr void destroy_at(T* location) noexcept;

    template<@\exposconcept{no-throw-input-iterator}@ I, @\exposconcept{no-throw-sentinel}@<I> S>
      requires @\libconcept{destructible}@<iter_value_t<I>>
        constexpr I destroy(I first, S last) noexcept;
    template<@\exposconcept{no-throw-input-range}@ R>
      requires @\libconcept{destructible}@<range_value_t<R>>
        constexpr borrowed_iterator_t<R> destroy(R&& r) noexcept;

    template<@\exposconcept{no-throw-input-iterator}@ I>
      requires @\libconcept{destructible}@<iter_value_t<I>>
        constexpr I destroy_n(I first, iter_difference_t<I> n) noexcept;
  }

  // \ref{unique.ptr}, class template \tcode{unique_ptr}
  template<class T> struct default_delete;
  template<class T> struct default_delete<T[]>;
  template<class T, class D = default_delete<T>> class unique_ptr;
  template<class T, class D> class unique_ptr<T[], D>;

  template<class T, class... Args>
    unique_ptr<T> make_unique(Args&&... args);                                  // \tcode{T} is not array
  template<class T>
    unique_ptr<T> make_unique(size_t n);                                        // \tcode{T} is \tcode{U[]}
  template<class T, class... Args>
    @\unspecnc@ make_unique(Args&&...) = delete;                                // \tcode{T} is \tcode{U[N]}

  template<class T>
    unique_ptr<T> make_unique_for_overwrite();                                  // \tcode{T} is not array
  template<class T>
    unique_ptr<T> make_unique_for_overwrite(size_t n);                          // \tcode{T} is \tcode{U[]}
  template<class T, class... Args>
    @\unspecnc@ make_unique_for_overwrite(Args&&...) = delete;                  // \tcode{T} is \tcode{U[N]}

  template<class T, class D>
    void swap(unique_ptr<T, D>& x, unique_ptr<T, D>& y) noexcept;

  template<class T1, class D1, class T2, class D2>
    bool operator==(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
  template<class T1, class D1, class T2, class D2>
    bool operator<(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
  template<class T1, class D1, class T2, class D2>
    bool operator>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
  template<class T1, class D1, class T2, class D2>
    bool operator<=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
  template<class T1, class D1, class T2, class D2>
    bool operator>=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
  template<class T1, class D1, class T2, class D2>
    requires @\libconcept{three_way_comparable_with}@<typename unique_ptr<T1, D1>::pointer,
                                       typename unique_ptr<T2, D2>::pointer>
    compare_three_way_result_t<typename unique_ptr<T1, D1>::pointer,
                               typename unique_ptr<T2, D2>::pointer>
      operator<=>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);

  template<class T, class D>
    bool operator==(const unique_ptr<T, D>& x, nullptr_t) noexcept;
  template<class T, class D>
    bool operator<(const unique_ptr<T, D>& x, nullptr_t);
  template<class T, class D>
    bool operator<(nullptr_t, const unique_ptr<T, D>& y);
  template<class T, class D>
    bool operator>(const unique_ptr<T, D>& x, nullptr_t);
  template<class T, class D>
    bool operator>(nullptr_t, const unique_ptr<T, D>& y);
  template<class T, class D>
    bool operator<=(const unique_ptr<T, D>& x, nullptr_t);
  template<class T, class D>
    bool operator<=(nullptr_t, const unique_ptr<T, D>& y);
  template<class T, class D>
    bool operator>=(const unique_ptr<T, D>& x, nullptr_t);
  template<class T, class D>
    bool operator>=(nullptr_t, const unique_ptr<T, D>& y);
  template<class T, class D>
    requires @\libconcept{three_way_comparable_with}@<typename unique_ptr<T, D>::pointer, nullptr_t>
    compare_three_way_result_t<typename unique_ptr<T, D>::pointer, nullptr_t>
      operator<=>(const unique_ptr<T, D>& x, nullptr_t);

  template<class E, class T, class Y, class D>
    basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const unique_ptr<Y, D>& p);

  // \ref{util.smartptr.weak.bad}, class \tcode{bad_weak_ptr}
  class bad_weak_ptr;

  // \ref{util.smartptr.shared}, class template \tcode{shared_ptr}
  template<class T> class shared_ptr;

  // \ref{util.smartptr.shared.create}, \tcode{shared_ptr} creation
  template<class T, class... Args>
    shared_ptr<T> make_shared(Args&&... args);                                  // \tcode{T} is not array
  template<class T, class A, class... Args>
    shared_ptr<T> allocate_shared(const A& a, Args&&... args);                  // \tcode{T} is not array

  template<class T>
    shared_ptr<T> make_shared(size_t N);                                        // \tcode{T} is \tcode{U[]}
  template<class T, class A>
    shared_ptr<T> allocate_shared(const A& a, size_t N);                        // \tcode{T} is \tcode{U[]}

  template<class T>
    shared_ptr<T> make_shared();                                                // \tcode{T} is \tcode{U[N]}
  template<class T, class A>
    shared_ptr<T> allocate_shared(const A& a);                                  // \tcode{T} is \tcode{U[N]}

  template<class T>
    shared_ptr<T> make_shared(size_t N, const remove_extent_t<T>& u);           // \tcode{T} is \tcode{U[]}
  template<class T, class A>
    shared_ptr<T> allocate_shared(const A& a, size_t N,
                                  const remove_extent_t<T>& u);                 // \tcode{T} is \tcode{U[]}

  template<class T>
    shared_ptr<T> make_shared(const remove_extent_t<T>& u);                     // \tcode{T} is \tcode{U[N]}
  template<class T, class A>
    shared_ptr<T> allocate_shared(const A& a, const remove_extent_t<T>& u);     // \tcode{T} is \tcode{U[N]}

  template<class T>
    shared_ptr<T> make_shared_for_overwrite();                                  // \tcode{T} is not \tcode{U[]}
  template<class T, class A>
    shared_ptr<T> allocate_shared_for_overwrite(const A& a);                    // \tcode{T} is not \tcode{U[]}

  template<class T>
    shared_ptr<T> make_shared_for_overwrite(size_t N);                          // \tcode{T} is \tcode{U[]}
  template<class T, class A>
    shared_ptr<T> allocate_shared_for_overwrite(const A& a, size_t N);          // \tcode{T} is \tcode{U[]}

  // \ref{util.smartptr.shared.cmp}, \tcode{shared_ptr} comparisons
  template<class T, class U>
    bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
  template<class T, class U>
    strong_ordering operator<=>(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;

  template<class T>
    bool operator==(const shared_ptr<T>& x, nullptr_t) noexcept;
  template<class T>
    strong_ordering operator<=>(const shared_ptr<T>& x, nullptr_t) noexcept;

  // \ref{util.smartptr.shared.spec}, \tcode{shared_ptr} specialized algorithms
  template<class T>
    void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;

  // \ref{util.smartptr.shared.cast}, \tcode{shared_ptr} casts
  template<class T, class U>
    shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;
  template<class T, class U>
    shared_ptr<T> static_pointer_cast(shared_ptr<U>&& r) noexcept;
  template<class T, class U>
    shared_ptr<T> dynamic_pointer_cast(const shared_ptr<U>& r) noexcept;
  template<class T, class U>
    shared_ptr<T> dynamic_pointer_cast(shared_ptr<U>&& r) noexcept;
  template<class T, class U>
    shared_ptr<T> const_pointer_cast(const shared_ptr<U>& r) noexcept;
  template<class T, class U>
    shared_ptr<T> const_pointer_cast(shared_ptr<U>&& r) noexcept;
  template<class T, class U>
    shared_ptr<T> reinterpret_pointer_cast(const shared_ptr<U>& r) noexcept;
  template<class T, class U>
    shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U>&& r) noexcept;

  // \ref{util.smartptr.getdeleter}, \tcode{shared_ptr} \tcode{get_deleter}
  template<class D, class T>
    D* get_deleter(const shared_ptr<T>& p) noexcept;

  // \ref{util.smartptr.shared.io}, \tcode{shared_ptr} I/O
  template<class E, class T, class Y>
    basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const shared_ptr<Y>& p);

  // \ref{util.smartptr.weak}, class template \tcode{weak_ptr}
  template<class T> class weak_ptr;

  // \ref{util.smartptr.weak.spec}, \tcode{weak_ptr} specialized algorithms
  template<class T> void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;

  // \ref{util.smartptr.ownerless}, class template \tcode{owner_less}
  template<class T = void> struct owner_less;

  // \ref{util.smartptr.enab}, class template \tcode{enable_shared_from_this}
  template<class T> class enable_shared_from_this;

  // \ref{util.smartptr.hash}, hash support
  template<class T> struct hash;
  template<class T, class D> struct hash<unique_ptr<T, D>>;
  template<class T> struct hash<shared_ptr<T>>;

  // \ref{util.smartptr.atomic}, atomic smart pointers
  template<class T> struct atomic;
  template<class T> struct atomic<shared_ptr<T>>;
  template<class T> struct atomic<weak_ptr<T>>;
}
\end{codeblock}

\rSec2[pointer.traits]{Pointer traits}

\rSec3[pointer.traits.general]{General}

\pnum
The class template \tcode{pointer_traits} supplies a uniform interface to certain
attributes of pointer-like types.

\indexlibraryglobal{pointer_traits}%
\begin{codeblock}
namespace std {
  template<class Ptr> struct pointer_traits {
    using pointer         = Ptr;
    using element_type    = @\seebelow@;
    using difference_type = @\seebelow@;

    template<class U> using rebind = @\seebelow@;

    static pointer pointer_to(@\seebelow@ r);
  };

  template<class T> struct pointer_traits<T*> {
    using pointer         = T*;
    using element_type    = T;
    using difference_type = ptrdiff_t;

    template<class U> using rebind = U*;

    static constexpr pointer pointer_to(@\seebelow@ r) noexcept;
  };
}
\end{codeblock}

\rSec3[pointer.traits.types]{Member types}

\indexlibrarymember{element_type}{pointer_traits}%
\begin{itemdecl}
using element_type = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Ptr::element_type} if
the \grammarterm{qualified-id} \tcode{Ptr::element_type} is valid and denotes a
type\iref{temp.deduct}; otherwise, \tcode{T} if
\tcode{Ptr} is a class template instantiation of the form \tcode{SomePointer<T, Args>},
where \tcode{Args} is zero or more type arguments; otherwise, the specialization is
ill-formed.
\end{itemdescr}

\indexlibrarymember{difference_type}{pointer_traits}%
\begin{itemdecl}
using difference_type = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Ptr::difference_type} if
the \grammarterm{qualified-id} \tcode{Ptr::difference_type} is valid and denotes a
type\iref{temp.deduct}; otherwise,
\tcode{ptrdiff_t}.
\end{itemdescr}

\indexlibrarymember{rebind}{pointer_traits}%
\begin{itemdecl}
template<class U> using rebind = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\templalias \tcode{Ptr::rebind<U>} if
the \grammarterm{qualified-id} \tcode{Ptr::rebind<U>} is valid and denotes a
type\iref{temp.deduct}; otherwise,
\tcode{SomePointer<U, Args>} if
\tcode{Ptr} is a class template instantiation of the form \tcode{SomePointer<T, Args>},
where \tcode{Args} is zero or more type arguments; otherwise, the instantiation of
\tcode{rebind} is ill-formed.
\end{itemdescr}

\rSec3[pointer.traits.functions]{Member functions}

\indexlibrarymember{pointer_to}{pointer_traits}%
\begin{itemdecl}
static pointer pointer_traits::pointer_to(@\seebelow@ r);
static constexpr pointer pointer_traits<T*>::pointer_to(@\seebelow@ r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
For the first member function,
\tcode{Ptr::pointer_to(r)} is well-formed.

\pnum
\expects
For the first member function,
\tcode{Ptr::pointer_to(r)} returns a pointer to \tcode{r}
through which indirection is valid.

\pnum
\returns
The first member function returns \tcode{Ptr::pointer_to(r)}.
The second member function returns \tcode{addressof(r)}.

\pnum
\remarks
If \tcode{element_type} is \cv{}~\tcode{void}, the type of
\tcode{r} is unspecified; otherwise, it is \tcode{element_type\&}.
\end{itemdescr}

\rSec3[pointer.traits.optmem]{Optional members}

\pnum
Specializations of \tcode{pointer_traits} may define the member declared
in this subclause to customize the behavior of the standard library.

\indexlibrarymember{to_address}{pointer_traits}%
\begin{itemdecl}
static element_type* to_address(pointer p) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pointer of type \tcode{element_type*} that references
the same location as the argument \tcode{p}.

\pnum
\begin{note}
This function is intended to be the inverse of \tcode{pointer_to}.
If defined, it customizes the behavior of
the non-member function
\tcode{to_address}\iref{pointer.conversion}.
\end{note}
\end{itemdescr}

\rSec2[pointer.conversion]{Pointer conversion}

\indexlibraryglobal{to_address}%
\begin{itemdecl}
template<class T> constexpr T* to_address(T* p) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{T} is not a function type.

\pnum
\returns
\tcode{p}.
\end{itemdescr}

\indexlibraryglobal{to_address}%
\begin{itemdecl}
template<class Ptr> constexpr auto to_address(const Ptr& p) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{pointer_traits<Ptr>::to_address(p)} if that expression is well-formed
(see \ref{pointer.traits.optmem}),
otherwise \tcode{to_address(p.operator->())}.
\end{itemdescr}

\rSec2[util.dynamic.safety]{Pointer safety}

\pnum
A complete object is \term{declared reachable} while the number of calls to
\tcode{declare_reachable} with an argument referencing the object exceeds the
number of calls to \tcode{undeclare_reachable} with an argument referencing the
object.

\indexlibraryglobal{declare_reachable}%
\begin{itemdecl}
void declare_reachable(void* p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{p} is a safely-derived pointer\iref{basic.stc.dynamic.safety}
or a null pointer value.

\pnum
\effects
If \tcode{p} is not null, the complete object referenced by \tcode{p}
is subsequently declared reachable\iref{basic.stc.dynamic.safety}.

\pnum
\throws
May throw \tcode{bad_alloc} if the system cannot allocate
additional memory that may be required to track objects declared reachable.
\end{itemdescr}

\indexlibraryglobal{undeclare_reachable}%
\begin{itemdecl}
template<class T> T* undeclare_reachable(T* p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
If \tcode{p} is not null, the complete object referenced by \tcode{p}
has been previously declared reachable, and is
live\iref{basic.life} from the time of the call until the last
\tcode{undeclare_reachable(p)} call on the object.

\pnum
\returns
A safely derived copy of \tcode{p} which compares equal to \tcode{p}.

\pnum
\throws
Nothing.

\pnum
\begin{note}
It is expected that calls to \tcode{declare_reachable(p)} consume
a small amount of memory in addition to that occupied by the referenced object until the
matching call to \tcode{undeclare_reachable(p)} is encountered.
Thus, long-running programs where calls are not matched can exhibit a memory leak.
\end{note}
\end{itemdescr}

\indexlibraryglobal{declare_no_pointers}%
\begin{itemdecl}
void declare_no_pointers(char* p, size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
No bytes in the specified range are currently registered with
\tcode{declare_no_pointers()}. If the specified range is in an allocated object,
then it is entirely within a single allocated object. The object is
live until the corresponding \tcode{undeclare_no_pointers()} call.
\begin{note}
In a garbage-collecting implementation, the fact that a region in an object is
registered with \tcode{declare_no_pointers()} does not prevent the object from
being collected.
\end{note}

\pnum
\effects
The \tcode{n} bytes starting at \tcode{p} no longer contain
traceable pointer locations, independent of their type. Hence
indirection through a pointer located there is undefined if the object
it points to was created by global \tcode{operator new} and not
previously declared reachable.
\begin{note}
This can be used to inform a
garbage collector or leak detector that this region of memory need not
be traced.
\end{note}

\pnum
\throws
Nothing.

\pnum
\begin{note}
The request can be ignored
if a memory allocation needed by the implementation fails.
\end{note}
\end{itemdescr}

\indexlibraryglobal{undeclare_no_pointers}%
\begin{itemdecl}
void undeclare_no_pointers(char* p, size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
The same range has previously been passed to \tcode{declare_no_pointers()}.

\pnum
\effects
Unregisters a range registered with \tcode{declare_no_pointers()} for
destruction. It shall be called before the lifetime of the object ends.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibraryglobal{get_pointer_safety}%
\begin{itemdecl}
pointer_safety get_pointer_safety() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{pointer_safety::strict} if the implementation has strict pointer
safety\iref{basic.stc.dynamic.safety}. It is
\impldef{whether \tcode{get_pointer_safety} returns
\tcode{pointer_safety::relaxed} or
\tcode{pointer_safety::\brk{}preferred} if the implementation has relaxed pointer safety}
whether
\tcode{get_pointer_safety} returns \tcode{pointer_safety::relaxed} or
\tcode{point\-er_safety::preferred} if the implementation has relaxed pointer
safety.\footnote{\tcode{pointer_safety::preferred} might be returned to indicate
that a leak detector is running so that the program can avoid spurious leak
reports.}
\end{itemdescr}


\rSec2[ptr.align]{Pointer alignment}

\indexlibraryglobal{align}%
\begin{itemdecl}
void* align(size_t alignment, size_t size, void*& ptr, size_t& space);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\begin{itemize}
\item
\tcode{alignment} is a power of two

\item
\tcode{ptr} represents the address of contiguous storage of at least
\tcode{space} bytes
\end{itemize}

\pnum
\effects
If it is possible to fit \tcode{size} bytes
of storage aligned by \tcode{alignment} into the buffer pointed to by
\tcode{ptr} with length \tcode{space}, the function updates
\tcode{ptr} to represent the first possible address of such storage
and decreases \tcode{space} by the number of bytes used for alignment.
Otherwise, the function does nothing.

\pnum
\returns
A null pointer if the requested aligned buffer
would not fit into the available space, otherwise the adjusted value
of \tcode{ptr}.

\pnum
\begin{note}
The function updates its \tcode{ptr}
and \tcode{space} arguments so that it can be called repeatedly
with possibly different \tcode{alignment} and \tcode{size}
arguments for the same buffer.
\end{note}
\end{itemdescr}

\indexlibraryglobal{assume_aligned}%
\begin{itemdecl}
template<size_t N, class T>
  [[nodiscard]] constexpr T* assume_aligned(T* ptr);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{N} is a power of two.

\pnum
\expects
\tcode{ptr} points to an object \tcode{X} of
a type similar\iref{conv.qual} to \tcode{T},
where \tcode{X} has alignment \tcode{N}\iref{basic.align}.

\pnum
\returns
\tcode{ptr}.

\pnum
\throws
Nothing.

\pnum
\begin{note}
The alignment assumption on an object \tcode{X}
expressed by a call to \tcode{assume_aligned}
might result in generation of more efficient code.
It is up to the program to ensure that the assumption actually holds.
The call does not cause the compiler to verify or enforce this.
An implementation might only make the assumption
for those operations on \tcode{X} that access \tcode{X}
through the pointer returned by \tcode{assume_aligned}.
\end{note}
\end{itemdescr}

\rSec2[allocator.tag]{Allocator argument tag}

\indexlibraryglobal{allocator_arg_t}%
\indexlibraryglobal{allocator_arg}%
\begin{itemdecl}
namespace std {
  struct allocator_arg_t { explicit allocator_arg_t() = default; };
  inline constexpr allocator_arg_t allocator_arg{};
}
\end{itemdecl}

\pnum
The \tcode{allocator_arg_t} struct is an empty class type used as a unique type to
disambiguate constructor and function overloading. Specifically, several types (see
\tcode{tuple}~\ref{tuple}) have constructors with \tcode{allocator_arg_t} as the first
argument, immediately followed by an argument of a type that meets the
\oldconcept{Allocator} requirements (\tref{cpp17.allocator}).

\rSec2[allocator.uses]{\tcode{uses_allocator}}

\rSec3[allocator.uses.trait]{\tcode{uses_allocator} trait}

\indexlibraryglobal{uses_allocator}%
\begin{itemdecl}
template<class T, class Alloc> struct uses_allocator;
\end{itemdecl}

\begin{itemdescr}
\pnum
\remarks
Automatically detects whether \tcode{T} has a nested \tcode{allocator_type} that
is convertible from \tcode{Alloc}. Meets the \oldconcept{BinaryTypeTrait}
requirements\iref{meta.rqmts}. The implementation shall provide a definition that is
derived from \tcode{true_type} if the \grammarterm{qualified-id} \tcode{T::allocator_type}
is valid and denotes a type\iref{temp.deduct} and
\tcode{is_convertible_v<Alloc, T::allocator_type> != false}, otherwise it shall be
derived from \tcode{false_type}. A program may specialize this template to derive from
\tcode{true_type} for a program-defined type \tcode{T} that does not have a nested
\tcode{allocator_type} but nonetheless can be constructed with an allocator where
either:
\begin{itemize}
\item the first argument of a constructor has type \tcode{allocator_arg_t} and the
second argument has type \tcode{Alloc} or

\item the last argument of a constructor has type \tcode{Alloc}.
\end{itemize}
\end{itemdescr}

\rSec3[allocator.uses.construction]{Uses-allocator construction}

\pnum
\defnx{Uses-allocator construction}{uses-allocator construction}
with allocator \tcode{alloc} and constructor arguments \tcode{args...}
refers to the construction of an object of type \tcode{T}
such that \tcode{alloc} is passed to the constructor of \tcode{T}
if \tcode{T} uses an allocator type compatible with \tcode{alloc}.
When applied to the construction of an object of type \tcode{T},
it is equivalent to initializing it with the value of the expression
\tcode{make_obj_using_allocator<T>(alloc, args...)}, described below.

\pnum
The following utility functions support
three conventions for passing \tcode{alloc} to a constructor:
\begin{itemize}
\item
  If \tcode{T} does not use an allocator compatible with \tcode{alloc},
  then \tcode{alloc} is ignored.
\item
  Otherwise, if \tcode{T} has a constructor invocable as
  \tcode{T(allocator_arg, alloc, args...)} (leading-allocator convention),
  then uses-allocator construction chooses this constructor form.
\item
  Otherwise, if \tcode{T} has a constructor invocable as
  \tcode{T(args..., alloc)} (trailing-allocator convention),
  then uses-allocator construction chooses this constructor form.
\end{itemize}

\pnum
The \tcode{uses_allocator_construction_args} function template
takes an allocator and argument list and
produces (as a tuple) a new argument list matching one of the above conventions.
Additionally, overloads are provided
that treat specializations of \tcode{pair}
such that uses-allocator construction is applied individually
to the \tcode{first} and \tcode{second} data members.
The \tcode{make_obj_using_allocator} and
\tcode{uninitialized_construct_using_allocator} function templates
apply the modified constructor arguments
to construct an object of type \tcode{T}
as a return value or in-place, respectively.
\begin{note}
For \tcode{uses_allocator_construction_args} and
\tcode{make_obj_using_allocator}, type \tcode{T}
is not deduced and must therefore be specified explicitly by the caller.
\end{note}

\indexlibraryglobal{uses_allocator_construction_args}%
\begin{itemdecl}
template<class T, class Alloc, class... Args>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                  Args&&... args) noexcept -> @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not a specialization of \tcode{pair}.

\pnum
\returns
A \tcode{tuple} value determined as follows:
\begin{itemize}
\item
  If \tcode{uses_allocator_v<T, Alloc>} is \tcode{false} and
  \tcode{is_constructible_v<T, Args...>} is \tcode{true},
  return \tcode{forward_as_tuple(std::forward<Args>(args)...)}.
\item
  Otherwise,  if \tcode{uses_allocator_v<T, Alloc>} is \tcode{true} and
  \tcode{is_constructible_v<T, allocator_arg_t, const Alloc\&, Args...>}
  is \tcode{true},
  return
\begin{codeblock}
tuple<allocator_arg_t, const Alloc&, Args&&...>(
  allocator_arg, alloc, std::forward<Args>(args)...)
\end{codeblock}
\item
  Otherwise,  if \tcode{uses_allocator_v<T, Alloc>} is \tcode{true} and
  \tcode{is_constructible_v<T, Args..., const Alloc\&>} is \tcode{true},
  return \tcode{forward_as_tuple(std::forward<Args>(args)..., alloc)}.
\item
  Otherwise, the program is ill-formed.
\end{itemize}
\begin{note}
This definition prevents a silent failure
to pass the allocator to a constructor of a type for which
\tcode{uses_allocator_v<T, Alloc>} is \tcode{true}.
\end{note}
\end{itemdescr}

\indexlibraryglobal{uses_allocator_construction_args}%
\begin{itemdecl}
template<class T, class Alloc, class Tuple1, class Tuple2>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc, piecewise_construct_t,
                                                  Tuple1&& x, Tuple2&& y)
                                                  noexcept -> @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is a specialization of \tcode{pair}.

\pnum
\effects
For \tcode{T} specified as \tcode{pair<T1, T2>}, equivalent to:
\begin{codeblock}
return make_tuple(
  piecewise_construct,
  apply([&alloc](auto&&... args1) {
          return uses_allocator_construction_args<T1>(
            alloc, std::forward<decltype(args1)>(args1)...);
        }, std::forward<Tuple1>(x)),
  apply([&alloc](auto&&... args2) {
          return uses_allocator_construction_args<T2>(
            alloc, std::forward<decltype(args2)>(args2)...);
        }, std::forward<Tuple2>(y)));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{uses_allocator_construction_args}%
\begin{itemdecl}
template<class T, class Alloc>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc) noexcept -> @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is a specialization of \tcode{pair}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return uses_allocator_construction_args<T>(alloc, piecewise_construct,
                                           tuple<>{}, tuple<>{});
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{uses_allocator_construction_args}%
\begin{itemdecl}
template<class T, class Alloc, class U, class V>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                  U&& u, V&& v) noexcept -> @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is a specialization of \tcode{pair}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return uses_allocator_construction_args<T>(alloc, piecewise_construct,
                                           forward_as_tuple(std::forward<U>(u)),
                                           forward_as_tuple(std::forward<V>(v)));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{uses_allocator_construction_args}%
\begin{itemdecl}
template<class T, class Alloc, class U, class V>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                  const pair<U,V>& pr) noexcept -> @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is a specialization of \tcode{pair}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return uses_allocator_construction_args<T>(alloc, piecewise_construct,
                                           forward_as_tuple(pr.first),
                                           forward_as_tuple(pr.second));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{uses_allocator_construction_args}%
\begin{itemdecl}
template<class T, class Alloc, class U, class V>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                  pair<U,V>&& pr) noexcept -> @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is a specialization of \tcode{pair}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return uses_allocator_construction_args<T>(alloc, piecewise_construct,
                                           forward_as_tuple(std::move(pr).first),
                                           forward_as_tuple(std::move(pr).second));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{make_obj_using_allocator}%
\begin{itemdecl}
template<class T, class Alloc, class... Args>
  constexpr T make_obj_using_allocator(const Alloc& alloc, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return make_from_tuple<T>(uses_allocator_construction_args<T>(
                            alloc, std::forward<Args>(args)...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{uninitialized_construct_using_allocator}%
\begin{itemdecl}
template<class T, class Alloc, class... Args>
  constexpr T* uninitialized_construct_using_allocator(T* p, const Alloc& alloc, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return apply([&]<class... U>(U&&... xs) {
       return construct_at(p, std::forward<U>(xs)...);
     }, uses_allocator_construction_args<T>(alloc, std::forward<Args>(args)...));
\end{codeblock}
\end{itemdescr}

\rSec2[allocator.traits]{Allocator traits}

\rSec3[allocator.traits.general]{General}

\pnum
The class template \tcode{allocator_traits} supplies a uniform interface to all
allocator types.
An allocator cannot be a non-class type, however, even if \tcode{allocator_traits}
supplies the entire required interface.
\begin{note}
Thus, it is always possible to create
a derived class from an allocator.
\end{note}

\indexlibraryglobal{allocator_traits}%
\begin{codeblock}
namespace std {
  template<class Alloc> struct allocator_traits {
    using allocator_type     = Alloc;

    using value_type         = typename Alloc::value_type;

    using pointer            = @\seebelow@;
    using const_pointer      = @\seebelow@;
    using void_pointer       = @\seebelow@;
    using const_void_pointer = @\seebelow@;

    using difference_type    = @\seebelow@;
    using size_type          = @\seebelow@;

    using propagate_on_container_copy_assignment = @\seebelow@;
    using propagate_on_container_move_assignment = @\seebelow@;
    using propagate_on_container_swap            = @\seebelow@;
    using is_always_equal                        = @\seebelow@;

    template<class T> using rebind_alloc = @\seebelow@;
    template<class T> using rebind_traits = allocator_traits<rebind_alloc<T>>;

    [[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n);
    [[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n,
                                                    const_void_pointer hint);

    static constexpr void deallocate(Alloc& a, pointer p, size_type n);

    template<class T, class... Args>
      static constexpr void construct(Alloc& a, T* p, Args&&... args);

    template<class T>
      static constexpr void destroy(Alloc& a, T* p);

    static constexpr size_type max_size(const Alloc& a) noexcept;

    static constexpr Alloc select_on_container_copy_construction(const Alloc& rhs);
  };
}
\end{codeblock}

\rSec3[allocator.traits.types]{Member types}

\indexlibrarymember{pointer}{allocator_traits}%
\begin{itemdecl}
using pointer = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::pointer} if
the \grammarterm{qualified-id} \tcode{Alloc::pointer} is valid and denotes a
type\iref{temp.deduct}; otherwise, \tcode{value_type*}.
\end{itemdescr}

\indexlibrarymember{const_pointer}{allocator_traits}%
\begin{itemdecl}
using const_pointer = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::const_pointer} if
the \grammarterm{qualified-id} \tcode{Alloc::const_pointer} is valid and denotes a
type\iref{temp.deduct}; otherwise,
\tcode{pointer_traits<pointer>::rebind<\brk{}const value_type>}.
\end{itemdescr}

\indexlibrarymember{void_pointer}{allocator_traits}%
\begin{itemdecl}
using void_pointer = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::void_pointer} if
the \grammarterm{qualified-id} \tcode{Alloc::void_pointer} is valid and denotes a
type\iref{temp.deduct}; otherwise,
\tcode{pointer_traits<pointer>::rebind<\brk{}void>}.
\end{itemdescr}

\indexlibrarymember{const_void_pointer}{allocator_traits}%
\begin{itemdecl}
using const_void_pointer = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::const_void_pointer} if
the \grammarterm{qualified-id} \tcode{Alloc::const_void_pointer} is valid and denotes a
type\iref{temp.deduct}; otherwise,
\tcode{pointer_traits<pointer>::\brk{}rebind<const void>}.
\end{itemdescr}

\indexlibrarymember{difference_type}{allocator_traits}%
\begin{itemdecl}
using difference_type = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::difference_type} if
the \grammarterm{qualified-id} \tcode{Alloc::difference_type} is valid and denotes a
type\iref{temp.deduct}; otherwise,
\tcode{pointer_traits<pointer>::dif\-ference_type}.
\end{itemdescr}

\indexlibrarymember{size_type}{allocator_traits}%
\begin{itemdecl}
using size_type = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::size_type} if
the \grammarterm{qualified-id} \tcode{Alloc::size_type} is valid and denotes a
type\iref{temp.deduct}; otherwise,
\tcode{make_unsigned_t<difference_type>}.
\end{itemdescr}

\indexlibrarymember{propagate_on_container_copy_assignment}{allocator_traits}%
\begin{itemdecl}
using propagate_on_container_copy_assignment = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::propagate_on_container_copy_assignment} if
the \grammarterm{qualified-id} \tcode{Alloc::propagate_on_container_copy_assignment} is valid and denotes a
type\iref{temp.deduct}; otherwise
\tcode{false_type}.
\end{itemdescr}

\indexlibrarymember{propagate_on_container_move_assignment}{allocator_traits}%
\begin{itemdecl}
using propagate_on_container_move_assignment = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::propagate_on_container_move_assignment} if
the \grammarterm{qualified-id} \tcode{Alloc::propagate_on_container_move_assignment} is valid and denotes a
type\iref{temp.deduct}; otherwise
\tcode{false_type}.
\end{itemdescr}

\indexlibrarymember{propagate_on_container_swap}{allocator_traits}%
\begin{itemdecl}
using propagate_on_container_swap = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::propagate_on_container_swap} if
the \grammarterm{qualified-id} \tcode{Alloc::propagate_on_container_swap} is valid and denotes a
type\iref{temp.deduct}; otherwise
\tcode{false_type}.
\end{itemdescr}

\indexlibrarymember{is_always_equal}{allocator_traits}%
\begin{itemdecl}
using is_always_equal = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::is_always_equal} if
the \grammarterm{qualified-id} \tcode{Alloc::is_always_equal}
is valid and denotes a type\iref{temp.deduct};
otherwise \tcode{is_empty<Alloc>::type}.
\end{itemdescr}

\indexlibrarymember{rebind_alloc}{allocator_traits}%
\begin{itemdecl}
template<class T> using rebind_alloc = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\templalias \tcode{Alloc::rebind<T>::other} if
the \grammarterm{qualified-id} \tcode{Alloc::rebind<T>::other} is valid and denotes a
type\iref{temp.deduct}; otherwise,
\tcode{Alloc<T, Args>} if \tcode{Alloc} is a class template instantiation
of the form \tcode{Alloc<U, Args>}, where \tcode{Args} is zero or more type arguments;
otherwise, the instantiation of \tcode{rebind_alloc} is ill-formed.
\end{itemdescr}

\rSec3[allocator.traits.members]{Static member functions}

\indexlibrarymember{allocate}{allocator_traits}%
\begin{itemdecl}
[[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{a.allocate(n)}.
\end{itemdescr}

\indexlibrarymember{allocate}{allocator_traits}%
\begin{itemdecl}
[[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n, const_void_pointer hint);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{a.allocate(n, hint)} if that expression is well-formed; otherwise, \tcode{a.allocate(n)}.
\end{itemdescr}

\indexlibrarymember{deallocate}{allocator_traits}%
\begin{itemdecl}
static constexpr void deallocate(Alloc& a, pointer p, size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls \tcode{a.deallocate(p, n)}.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibrarymember{construct}{allocator_traits}%
\begin{itemdecl}
template<class T, class... Args>
  static constexpr void construct(Alloc& a, T* p, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls \tcode{a.construct(p, std::forward<Args>(args)...)}
if that call is well-formed;
otherwise, invokes \tcode{construct_at(p, std::forward<Args>(args)...)}.
\end{itemdescr}

\indexlibrarymember{destroy}{allocator_traits}%
\begin{itemdecl}
template<class T>
  static constexpr void destroy(Alloc& a, T* p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls \tcode{a.destroy(p)} if that call is well-formed; otherwise, invokes
\tcode{destroy_at(p)}.
\end{itemdescr}

\indexlibrarymember{max_size}{allocator_traits}%
\begin{itemdecl}
static constexpr size_type max_size(const Alloc& a) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{a.max_size()} if that expression is well-formed; otherwise,
\tcode{numeric_limits<size_type>::\brk{}max()/sizeof(value_type)}.
\end{itemdescr}

\indexlibrarymember{select_on_container_copy_construction}{allocator_traits}%
\begin{itemdecl}
static constexpr Alloc select_on_container_copy_construction(const Alloc& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rhs.select_on_container_copy_construction()} if that expression is
well-formed; otherwise, \tcode{rhs}.
\end{itemdescr}

\rSec2[default.allocator]{The default allocator}

\rSec3[default.allocator.general]{General}

\pnum
All specializations of the default allocator meet the
allocator completeness requirements\iref{allocator.requirements.completeness}.

\indexlibraryglobal{allocator}%
\indexlibrarymember{value_type}{allocator}%
\indexlibrarymember{size_type}{allocator}%
\indexlibrarymember{difference_type}{allocator}%
\indexlibrarymember{propagate_on_container_move_assignment}{allocator}%
\indexlibrarymember{is_always_equal}{allocator}%
\indexlibrarymember{operator=}{allocator}%
\begin{codeblock}
namespace std {
  template<class T> class allocator {
   public:
    using value_type                             = T;
    using size_type                              = size_t;
    using difference_type                        = ptrdiff_t;
    using propagate_on_container_move_assignment = true_type;
    using is_always_equal                        = true_type;

    constexpr allocator() noexcept;
    constexpr allocator(const allocator&) noexcept;
    template<class U> constexpr allocator(const allocator<U>&) noexcept;
    constexpr ~allocator();
    constexpr allocator& operator=(const allocator&) = default;

    [[nodiscard]] constexpr T* allocate(size_t n);
    constexpr void deallocate(T* p, size_t n);
  };
}
\end{codeblock}

\rSec3[allocator.members]{Members}

\pnum
Except for the destructor, member functions of the default allocator shall not introduce
data races\iref{intro.multithread} as a result of concurrent calls to those member
functions from different threads. Calls to these functions that allocate or deallocate a
particular unit of storage shall occur in a single total order, and each such
deallocation call shall happen before the next allocation (if any) in this order.

\indexlibrarymember{allocate}{allocator}%
\begin{itemdecl}
[[nodiscard]] constexpr T* allocate(size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{T} is not an incomplete type\iref{basic.types}.

\pnum
\returns
A pointer to the initial element of an array of \tcode{n} \tcode{T}.

\pnum
\remarks
The storage for the array
is obtained by calling \tcode{::operator new}\iref{new.delete},
but it is unspecified when or how often this
function is called.
This function starts the lifetime of the array object,
but not that of any of the array elements.

\pnum
\throws
\tcode{bad_array_new_length} if
\tcode{numeric_limits<size_t>::max() / sizeof(T) < n}, or
\tcode{bad_alloc} if the storage cannot be obtained.
\end{itemdescr}

\indexlibrarymember{deallocate}{allocator}%
\begin{itemdecl}
constexpr void deallocate(T* p, size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{p} is a pointer value obtained from \tcode{allocate()}.
\tcode{n} equals the value passed as the first argument
to the invocation of allocate which returned \tcode{p}.

\pnum
\effects
Deallocates the storage referenced by \tcode{p}.

\pnum
\remarks
Uses
\tcode{::operator delete}\iref{new.delete},
but it is unspecified
when this function is called.
\end{itemdescr}

\rSec3[allocator.globals]{Operators}

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

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

\rSec2[specialized.addressof]{\tcode{addressof}}

\indexlibraryglobal{addressof}%
\begin{itemdecl}
template<class T> constexpr T* addressof(T& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The actual address of the object or function referenced by \tcode{r}, even in the
presence of an overloaded \tcode{operator\&}.

\pnum
\remarks
An expression \tcode{addressof(E)}
is a constant subexpression\iref{defns.const.subexpr}
if \tcode{E} is an lvalue constant subexpression.
\end{itemdescr}

\rSec2[c.malloc]{C library memory allocation}

\pnum
\begin{note}
The header \libheaderref{cstdlib}
declares the functions described in this subclause.
\end{note}

\indexlibraryglobal{aligned_alloc}%
\indexlibraryglobal{calloc}%
\indexlibraryglobal{malloc}%
\indexlibraryglobal{realloc}%
\begin{itemdecl}
void* aligned_alloc(size_t alignment, size_t size);
void* calloc(size_t nmemb, size_t size);
void* malloc(size_t size);
void* realloc(void* ptr, size_t size);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions have the semantics specified in the C standard library.

\pnum
\remarks
These functions do not attempt to allocate
storage by calling \tcode{::operator new()}\iref{new.delete}.
\indexlibrarymember{new}{operator}%

\pnum
Storage allocated directly with these functions
is implicitly declared reachable
(see~\ref{basic.stc.dynamic.safety}) on allocation, ceases to be declared
reachable on deallocation, and need not cease to be declared reachable as the
result of an \tcode{undeclare_reachable()} call.
\begin{note}
This allows existing
C libraries to remain unaffected by restrictions on pointers that are not safely
derived, at the expense of providing far fewer garbage collection and leak
detection options for \tcode{malloc()}-allocated objects. It also allows
\tcode{malloc()} to be implemented with a separate allocation arena, bypassing
the normal \tcode{declare_reachable()} implementation.
\end{note}

\pnum
These functions implicitly create objects\iref{intro.object}
in the returned region of storage and
return a pointer to a suitable created object.
In the case of \tcode{calloc} and \tcode{realloc},
the objects are created before the storage is zeroed or copied, respectively.
\end{itemdescr}

\indexlibraryglobal{free}%
\begin{itemdecl}
void free(void* ptr);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
This function has the semantics specified in the C standard library.

\pnum
\remarks
This function does not attempt to
deallocate storage by calling
\tcode{::operator delete()}\indexlibrarymember{delete}{operator}.
\end{itemdescr}

\xrefc{7.22.3}

\rSec1[smartptr]{Smart pointers}

\rSec2[unique.ptr]{Class template \tcode{unique_ptr}}

\rSec3[unique.ptr.general]{General}

\pnum
A \defn{unique pointer} is an object that owns another object and
manages that other object through a pointer. More precisely, a unique pointer
is an object \textit{u} that stores a pointer to a second object \textit{p} and
will dispose of \textit{p} when \textit{u} is itself destroyed (e.g., when
leaving block scope\iref{stmt.dcl}). In this context, \textit{u} is said
to \defn{own} \tcode{p}.

\pnum
The mechanism by which \textit{u} disposes of \textit{p} is known as
\textit{p}'s associated \defn{deleter}, a function object whose correct
invocation results in \textit{p}'s appropriate disposition (typically its deletion).

\pnum
Let the notation \textit{u.p} denote the pointer stored by \textit{u}, and
let \textit{u.d} denote the associated deleter. Upon request, \textit{u} can
\defn{reset} (replace) \textit{u.p} and \textit{u.d} with another pointer and
deleter, but properly disposes of its owned object via the associated
deleter before such replacement is considered completed.

\pnum
Each object of a type \tcode{U} instantiated from the \tcode{unique_ptr} template
specified in \ref{unique.ptr} has the strict ownership semantics, specified above,
of a unique pointer. In partial satisfaction of these semantics, each such \tcode{U}
is \oldconcept{MoveConstructible} and \oldconcept{MoveAssignable}, but is not
\oldconcept{CopyConstructible} nor \oldconcept{CopyAssignable}.
The template parameter \tcode{T} of \tcode{unique_ptr} may be an incomplete type.

\pnum
\begin{note}
The uses
of \tcode{unique_ptr} include providing exception safety for
dynamically allocated memory, passing ownership of dynamically allocated
memory to a function, and returning dynamically allocated memory from a
function.
\end{note}

\rSec3[unique.ptr.dltr]{Default deleters}

\rSec4[unique.ptr.dltr.general]{In general}

\pnum
The class template \tcode{default_delete} serves as the default deleter (destruction policy)
for the class template \tcode{unique_ptr}.

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

\rSec4[unique.ptr.dltr.dflt]{\tcode{default_delete}}

\begin{codeblock}
namespace std {
  template<class T> struct default_delete {
    constexpr default_delete() noexcept = default;
    template<class U> default_delete(const default_delete<U>&) noexcept;
    void operator()(T*) const;
  };
}
\end{codeblock}

\indexlibraryctor{default_delete}%
\begin{itemdecl}
template<class U> default_delete(const default_delete<U>& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{U*} is implicitly convertible to \tcode{T*}.

\pnum
\effects
Constructs a \tcode{default_delete} object
from another \tcode{default_delete<U>} object.
\end{itemdescr}

\indexlibrarymember{operator()}{default_delete}%
\begin{itemdecl}
void operator()(T* ptr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{T} is a complete type.

\pnum
\effects
Calls \tcode{delete} on \tcode{ptr}.
\end{itemdescr}

\rSec4[unique.ptr.dltr.dflt1]{\tcode{default_delete<T[]>}}

\begin{codeblock}
namespace std {
  template<class T> struct default_delete<T[]> {
    constexpr default_delete() noexcept = default;
    template<class U> default_delete(const default_delete<U[]>&) noexcept;
    template<class U> void operator()(U* ptr) const;
  };
}
\end{codeblock}

\indexlibraryctor{default_delete}
\begin{itemdecl}
template<class U> default_delete(const default_delete<U[]>& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{U(*)[]} is convertible to \tcode{T(*)[]}.

\pnum
\effects
Constructs a \tcode{default_delete} object from another \tcode{default_delete<U[]>} object.
\end{itemdescr}

\indexlibrarymember{operator()}{default_delete}%
\begin{itemdecl}
template<class U> void operator()(U* ptr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{U} is a complete type.

\pnum
\constraints
\tcode{U(*)[]} is convertible to \tcode{T(*)[]}.

\pnum
\effects
Calls \tcode{delete[]} on \tcode{ptr}.
\end{itemdescr}

\rSec3[unique.ptr.single]{\tcode{unique_ptr} for single objects}

\rSec4[unique.ptr.single.general]{General}

\indexlibraryglobal{unique_ptr}%
\begin{codeblock}
namespace std {
  template<class T, class D = default_delete<T>> class unique_ptr {
  public:
    using pointer      = @\seebelow@;
    using element_type = T;
    using deleter_type = D;

    // \ref{unique.ptr.single.ctor}, constructors
    constexpr unique_ptr() noexcept;
    explicit unique_ptr(pointer p) noexcept;
    unique_ptr(pointer p, @\seebelow@ d1) noexcept;
    unique_ptr(pointer p, @\seebelow@ d2) noexcept;
    unique_ptr(unique_ptr&& u) noexcept;
    constexpr unique_ptr(nullptr_t) noexcept;
    template<class U, class E>
      unique_ptr(unique_ptr<U, E>&& u) noexcept;

    // \ref{unique.ptr.single.dtor}, destructor
    ~unique_ptr();

    // \ref{unique.ptr.single.asgn}, assignment
    unique_ptr& operator=(unique_ptr&& u) noexcept;
    template<class U, class E>
      unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
    unique_ptr& operator=(nullptr_t) noexcept;

    // \ref{unique.ptr.single.observers}, observers
    add_lvalue_reference_t<T> operator*() const;
    pointer operator->() const noexcept;
    pointer get() const noexcept;
    deleter_type& get_deleter() noexcept;
    const deleter_type& get_deleter() const noexcept;
    explicit operator bool() const noexcept;

    // \ref{unique.ptr.single.modifiers}, modifiers
    pointer release() noexcept;
    void reset(pointer p = pointer()) noexcept;
    void swap(unique_ptr& u) noexcept;

    // disable copy from lvalue
    unique_ptr(const unique_ptr&) = delete;
    unique_ptr& operator=(const unique_ptr&) = delete;
  };
}
\end{codeblock}

\pnum
The default type for the template parameter \tcode{D} is
\tcode{default_delete}. A client-supplied template argument
\tcode{D} shall be a function
object type\iref{function.objects}, lvalue reference to function, or
lvalue reference to function object type
for which, given
a value \tcode{d} of type \tcode{D} and a value
\tcode{ptr} of type \tcode{unique_ptr<T, D>::pointer}, the expression
\tcode{d(ptr)} is valid and has the effect of disposing of the
pointer as appropriate for that deleter.

\pnum
If the deleter's type \tcode{D} is not a reference type, \tcode{D} shall meet
the \oldconcept{Destructible} requirements (\tref{cpp17.destructible}).

\pnum
If the \grammarterm{qualified-id} \tcode{remove_reference_t<D>::pointer} is valid and denotes a
type\iref{temp.deduct}, then \tcode{unique_ptr<T,
D>::pointer} shall be a synonym for \tcode{remove_reference_t<D>::pointer}. Otherwise
\tcode{unique_ptr<T, D>::pointer} shall be a synonym for \tcode{element_type*}. The type \tcode{unique_ptr<T,
D>::pointer} shall
meet the \oldconcept{NullablePointer} requirements (\tref{cpp17.nullablepointer}).

\pnum
\begin{example}
Given an allocator type \tcode{X} (\tref{cpp17.allocator}) and
letting \tcode{A} be a synonym for \tcode{allocator_traits<X>}, the types \tcode{A::pointer},
\tcode{A::const_pointer}, \tcode{A::void_pointer}, and \tcode{A::const_void_pointer}
may be used as \tcode{unique_ptr<T, D>::pointer}.
\end{example}

\rSec4[unique.ptr.single.ctor]{Constructors}

\indexlibraryctor{unique_ptr}%
\begin{itemdecl}
constexpr unique_ptr() noexcept;
constexpr unique_ptr(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{D} meets the \oldconcept{DefaultConstructible} requirements (\tref{cpp17.defaultconstructible}),
and that construction does not throw an exception.

\pnum
\constraints
\tcode{is_pointer_v<deleter_type>} is \tcode{false} and
\tcode{is_default_constructible_v<deleter_type>} is \tcode{true}.

\pnum
\effects
Constructs a \tcode{unique_ptr} object that owns
nothing, value-initializing the stored pointer and the stored deleter.

\pnum
\ensures
\tcode{get() == nullptr}. \tcode{get_deleter()}
returns a reference to the stored deleter.
\end{itemdescr}

\indexlibraryctor{unique_ptr}%
\begin{itemdecl}
explicit unique_ptr(pointer p) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_pointer_v<deleter_type>} is \tcode{false} and
\tcode{is_default_constructible_v<deleter_type>} is \tcode{true}.

\pnum
\mandates
This constructor is not selected by
class template argument deduction\iref{over.match.class.deduct}.

\pnum
\expects
\tcode{D} meets the \oldconcept{DefaultConstructible} requirements (\tref{cpp17.defaultconstructible}),
and that construction does not throw an exception.

\pnum
\effects
Constructs a \tcode{unique_ptr} which owns
\tcode{p}, initializing the stored pointer with \tcode{p} and
value-initializing the stored deleter.

\pnum
\ensures
\tcode{get() == p}. \tcode{get_deleter()}
returns a reference to the stored deleter.
\end{itemdescr}

\indexlibraryctor{unique_ptr}%
\begin{itemdecl}
unique_ptr(pointer p, const D& d) noexcept;
unique_ptr(pointer p, remove_reference_t<D>&& d) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<D, decltype(d)>} is \tcode{true}.

\pnum
\mandates
These constructors are not selected by
class template argument deduction\iref{over.match.class.deduct}.

\pnum
\expects
For the first constructor, if \tcode{D} is not a reference type,
\tcode{D} meets the \oldconcept{CopyConstructible} requirements and
such construction does not exit via an exception.
For the second constructor, if \tcode{D} is not a reference type,
\tcode{D} meets the \oldconcept{MoveConstructible} requirements and
such construction does not exit via an exception.

\pnum
\effects
Constructs a \tcode{unique_ptr} object which owns \tcode{p}, initializing
the stored pointer with \tcode{p} and initializing the deleter
from \tcode{std::forward<decltype(d)>(d)}.

\pnum
\ensures
\tcode{get() == p}.
\tcode{get_deleter()} returns a reference to the stored
deleter. If \tcode{D} is a reference type then \tcode{get_deleter()}
returns a reference to the lvalue \tcode{d}.

\pnum
\remarks
If \tcode{D} is a reference type,
the second constructor is defined as deleted.

\pnum
\begin{example}
\begin{codeblock}
D d;
unique_ptr<int, D> p1(new int, D());        // \tcode{D} must be \oldconcept{MoveConstructible}
unique_ptr<int, D> p2(new int, d);          // \tcode{D} must be \oldconcept{CopyConstructible}
unique_ptr<int, D&> p3(new int, d);         // \tcode{p3} holds a reference to \tcode{d}
unique_ptr<int, const D&> p4(new int, D()); // error: rvalue deleter object combined
                                            // with reference deleter type
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryctor{unique_ptr}%
\begin{itemdecl}
unique_ptr(unique_ptr&& u) noexcept;
\end{itemdecl}

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

\pnum
\expects
If \tcode{D} is not a reference type,
\tcode{D} meets the \oldconcept{MoveConstructible}
requirements (\tref{cpp17.moveconstructible}).
Construction
of the deleter from an rvalue of type \tcode{D} does not
throw an exception.

\pnum
\effects
Constructs a \tcode{unique_ptr} from
\tcode{u}. If \tcode{D} is a reference type, this
deleter is copy constructed from \tcode{u}'s deleter; otherwise, this
deleter is move constructed from \tcode{u}'s deleter.
\begin{note}
The
construction of the deleter can be implemented with \tcode{std::forward<D>}.
\end{note}

\pnum
\ensures
\tcode{get()} yields the value \tcode{u.get()}
yielded before the construction. \tcode{u.get() == nullptr}.
\tcode{get_deleter()} returns a reference
to the stored deleter that was constructed from
\tcode{u.get_deleter()}. If \tcode{D} is a reference type then
\tcode{get_deleter()} and \tcode{u.get_deleter()} both reference
the same lvalue deleter.
\end{itemdescr}

\indexlibraryctor{unique_ptr}%
\begin{itemdecl}
template<class U, class E> unique_ptr(unique_ptr<U, E>&& u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{unique_ptr<U, E>::pointer} is implicitly convertible to \tcode{pointer},
\item \tcode{U} is not an array type, and
\item either \tcode{D} is a reference type and \tcode{E} is the same type as \tcode{D}, or
\tcode{D} is not a reference type and \tcode{E} is implicitly convertible to \tcode{D}.
\end{itemize}

\pnum
\expects
If \tcode{E} is not a reference type,
construction of the deleter from an rvalue of type \tcode{E}
is well-formed and does not throw an exception.
Otherwise, \tcode{E} is a reference type and
construction of the deleter from an lvalue of type \tcode{E}
is well-formed and does not throw an exception.

\pnum
\effects
Constructs a \tcode{unique_ptr} from \tcode{u}.
If \tcode{E} is a reference type, this deleter is copy constructed from
\tcode{u}'s deleter; otherwise, this deleter is move constructed from \tcode{u}'s
deleter.
\begin{note}
The deleter constructor can be implemented with
\tcode{std::forward<E>}.
\end{note}

\pnum
\ensures
\tcode{get()} yields the value \tcode{u.get()}
yielded before the construction. \tcode{u.get() == nullptr}.
\tcode{get_deleter()} returns a reference
to the stored deleter that was constructed from
\tcode{u.get_deleter()}.
\end{itemdescr}

\rSec4[unique.ptr.single.dtor]{Destructor}

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

\begin{itemdescr}
\pnum
\expects
The expression \tcode{get_deleter()(get())} is well-formed,
has well-defined behavior, and does not throw exceptions.
\begin{note}
The use of \tcode{default_delete} requires \tcode{T} to be a complete type.
\end{note}

\pnum
\effects
If \tcode{get() == nullptr} there are no effects.
Otherwise \tcode{get_deleter()(get())}.
\end{itemdescr}

\rSec4[unique.ptr.single.asgn]{Assignment}

\indexlibrarymember{operator=}{unique_ptr}%
\begin{itemdecl}
unique_ptr& operator=(unique_ptr&& u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_assignable_v<D>} is \tcode{true}.

\pnum
\expects
If \tcode{D} is not a reference type, \tcode{D} meets the
\oldconcept{MoveAssignable} requirements (\tref{cpp17.moveassignable}) and assignment
of the deleter from an rvalue of type \tcode{D} does not throw an exception.
Otherwise, \tcode{D} is a reference type;
\tcode{remove_reference_t<D>} meets the \oldconcept{CopyAssignable}
requirements and assignment of the deleter from an
lvalue of type \tcode{D} does not throw an exception.

\pnum
\effects
Calls \tcode{reset(u.release())} followed by
\tcode{get_deleter() = std::forward<D>(u.get_dele\-ter())}.

\pnum
\returns
\tcode{*this}.

\pnum
\ensures
\tcode{u.get() == nullptr}.
\end{itemdescr}

\indexlibrarymember{operator=}{unique_ptr}%
\begin{itemdecl}
template<class U, class E> unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{unique_ptr<U, E>::pointer} is implicitly convertible to \tcode{pointer}, and
\item \tcode{U} is not an array type, and
\item \tcode{is_assignable_v<D\&, E\&\&>} is \tcode{true}.
\end{itemize}

\pnum
\expects
If \tcode{E} is not a reference type,
assignment of the deleter from an rvalue of type \tcode{E}
is well-formed and does not throw an exception.
Otherwise, \tcode{E} is a reference type and
assignment of the deleter from an lvalue of type \tcode{E}
is well-formed and does not throw an exception.

\pnum
\effects
Calls \tcode{reset(u.release())} followed by
\tcode{get_deleter() = std::forward<E>(u.get_dele\-ter())}.

\pnum
\returns
\tcode{*this}.

\pnum
\ensures
\tcode{u.get() == nullptr}.
\end{itemdescr}

\indexlibrarymember{operator=}{unique_ptr}%
\begin{itemdecl}
unique_ptr& operator=(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by \tcode{reset()}.

\pnum
\ensures
\tcode{get() == nullptr}.

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

\rSec4[unique.ptr.single.observers]{Observers}

\indexlibrarymember{operator*}{unique_ptr}%
\begin{itemdecl}
add_lvalue_reference_t<T> operator*() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{get() != nullptr}.

\pnum
\returns
\tcode{*get()}.

\end{itemdescr}

\indexlibrarymember{operator->}{unique_ptr}%
\begin{itemdecl}
pointer operator->() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{get() != nullptr}.

\pnum
\returns
\tcode{get()}.

\pnum
\begin{note}
The use of this function typically requires that \tcode{T} be a complete type.
\end{note}
\end{itemdescr}

\indexlibrarymember{get}{unique_ptr}%
\begin{itemdecl}
pointer get() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The stored pointer.
\end{itemdescr}

\indexlibrarymember{get_deleter}{unique_ptr}%
\begin{itemdecl}
deleter_type& get_deleter() noexcept;
const deleter_type& get_deleter() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A reference to the stored deleter.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\returns
\tcode{get() != nullptr}.
\end{itemdescr}

\rSec4[unique.ptr.single.modifiers]{Modifiers}

\indexlibrarymember{release}{unique_ptr}%
\begin{itemdecl}
pointer release() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{get() == nullptr}.

\pnum
\returns
The value \tcode{get()} had at the start of
the call to \tcode{release}.
\end{itemdescr}

\indexlibrarymember{reset}{unique_ptr}%
\begin{itemdecl}
void reset(pointer p = pointer()) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
The expression \tcode{get_deleter()(get())} is well-formed,
has well-defined behavior, and does not throw exceptions.

\pnum
\effects
Assigns \tcode{p} to the stored pointer, and then if and only if the old value of the
stored pointer, \tcode{old_p}, was not equal to \tcode{nullptr}, calls
\tcode{get_deleter()(old_p)}.
\begin{note}
The order of these operations is significant
because the call to \tcode{get_deleter()} might destroy \tcode{*this}.
\end{note}

\pnum
\ensures
\tcode{get() == p}.
\begin{note}
The postcondition does not hold if the call to \tcode{get_deleter()}
destroys \tcode{*this} since \tcode{this->get()} is no longer a valid expression.
\end{note}
\end{itemdescr}

\indexlibrarymember{swap}{unique_ptr}%
\begin{itemdecl}
void swap(unique_ptr& u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{get_deleter()} is swappable\iref{swappable.requirements} and
does not throw an exception under \tcode{swap}.

\pnum
\effects
Invokes \tcode{swap} on the stored pointers and on the stored
deleters of \tcode{*this} and \tcode{u}.
\end{itemdescr}

\rSec3[unique.ptr.runtime]{\tcode{unique_ptr} for array objects with a runtime length}

\rSec4[unique.ptr.runtime.general]{General}

\indexlibraryglobal{unique_ptr}%
\begin{codeblock}
namespace std {
  template<class T, class D> class unique_ptr<T[], D> {
  public:
    using pointer      = @\seebelow@;
    using element_type = T;
    using deleter_type = D;

    // \ref{unique.ptr.runtime.ctor}, constructors
    constexpr unique_ptr() noexcept;
    template<class U> explicit unique_ptr(U p) noexcept;
    template<class U> unique_ptr(U p, @\seebelow@ d) noexcept;
    template<class U> unique_ptr(U p, @\seebelow@ d) noexcept;
    unique_ptr(unique_ptr&& u) noexcept;
    template<class U, class E>
      unique_ptr(unique_ptr<U, E>&& u) noexcept;
    constexpr unique_ptr(nullptr_t) noexcept;

    // destructor
    ~unique_ptr();

    // assignment
    unique_ptr& operator=(unique_ptr&& u) noexcept;
    template<class U, class E>
      unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
    unique_ptr& operator=(nullptr_t) noexcept;

    // \ref{unique.ptr.runtime.observers}, observers
    T& operator[](size_t i) const;
    pointer get() const noexcept;
    deleter_type& get_deleter() noexcept;
    const deleter_type& get_deleter() const noexcept;
    explicit operator bool() const noexcept;

    // \ref{unique.ptr.runtime.modifiers}, modifiers
    pointer release() noexcept;
    template<class U> void reset(U p) noexcept;
    void reset(nullptr_t = nullptr) noexcept;
    void swap(unique_ptr& u) noexcept;

    // disable copy from lvalue
    unique_ptr(const unique_ptr&) = delete;
    unique_ptr& operator=(const unique_ptr&) = delete;
  };
}
\end{codeblock}

\pnum
A specialization for array types is provided with a slightly altered
interface.

\begin{itemize}
\item Conversions between different types of
\tcode{unique_ptr<T[], D>}
that would be disallowed for the corresponding pointer-to-array types,
and conversions to or from the non-array forms of
\tcode{unique_ptr}, produce an ill-formed program.

\item Pointers to types derived from \tcode{T} are
rejected by the constructors, and by \tcode{reset}.

\item The observers \tcode{operator*} and
\tcode{operator->} are not provided.

\item The indexing observer \tcode{operator[]} is provided.

\item The default deleter will call \tcode{delete[]}.
\end{itemize}

\pnum
Descriptions are provided below only for members that
differ from the primary template.

\pnum
The template argument \tcode{T} shall be a complete type.

\rSec4[unique.ptr.runtime.ctor]{Constructors}

\indexlibraryctor{unique_ptr}%
\begin{itemdecl}
template<class U> explicit unique_ptr(U p) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
This constructor behaves the same as
the constructor in the primary template that
takes a single parameter of type \tcode{pointer}.

\pnum
\constraints
\begin{itemize}
\item \tcode{U} is the same type as \tcode{pointer}, or
\item \tcode{pointer} is the same type as \tcode{element_type*},
\tcode{U} is a pointer type \tcode{V*}, and
\tcode{V(*)[]} is convertible to \tcode{element_type(*)[]}.
\end{itemize}
\end{itemdescr}

\indexlibraryctor{unique_ptr}%
\begin{itemdecl}
template<class U> unique_ptr(U p, @\seebelow@ d) noexcept;
template<class U> unique_ptr(U p, @\seebelow@ d) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
These constructors behave the same as
the constructors in the primary template that
take a parameter of type \tcode{pointer} and a second parameter.

\pnum
\constraints
\begin{itemize}
\item \tcode{U} is the same type as \tcode{pointer},
\item \tcode{U} is \tcode{nullptr_t}, or
\item \tcode{pointer} is the same type as \tcode{element_type*},
      \tcode{U} is a pointer type \tcode{V*}, and
      \tcode{V(*)[]} is convertible to \tcode{element_type(*)[]}.
\end{itemize}
\end{itemdescr}

\indexlibraryctor{unique_ptr}%
\begin{itemdecl}
template<class U, class E> unique_ptr(unique_ptr<U, E>&& u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
This constructor behaves the same as in the primary template.

\pnum
\constraints
Where \tcode{UP} is \tcode{unique_ptr<U, E>}:
\begin{itemize}
\item \tcode{U} is an array type, and
\item \tcode{pointer} is the same type as \tcode{element_type*}, and
\item \tcode{UP::pointer} is the same type as \tcode{UP::element_type*}, and
\item \tcode{UP::element_type(*)[]} is convertible to \tcode{element_type(*)[]}, and
\item either \tcode{D} is a reference type and \tcode{E} is the same type as \tcode{D},
      or \tcode{D} is not a reference type and \tcode{E} is implicitly convertible to \tcode{D}.
\end{itemize}

\begin{note}
This replaces the \constraints specification of the primary template.
\end{note}
\end{itemdescr}

\rSec4[unique.ptr.runtime.asgn]{Assignment}

\indexlibrarymember{operator=}{unique_ptr}%
\begin{itemdecl}
template<class U, class E> unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
This operator behaves the same as in the primary template.

\pnum
\constraints
Where \tcode{UP} is \tcode{unique_ptr<U, E>}:
\begin{itemize}
\item \tcode{U} is an array type, and
\item \tcode{pointer} is the same type as \tcode{element_type*}, and
\item \tcode{UP::pointer} is the same type as \tcode{UP::element_type*}, and
\item \tcode{UP::element_type(*)[]} is convertible to \tcode{element_type(*)[]}, and
\item \tcode{is_assignable_v<D\&, E\&\&>} is \tcode{true}.
\end{itemize}

\begin{note}
This replaces the \constraints specification of the primary template.
\end{note}
\end{itemdescr}

\rSec4[unique.ptr.runtime.observers]{Observers}

\indexlibrarymember{operator[]}{unique_ptr}%
\begin{itemdecl}
T& operator[](size_t i) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
$\tcode{i} <$ the
number of elements in the array to which
the stored pointer points.

\pnum
\returns
\tcode{get()[i]}.
\end{itemdescr}

\rSec4[unique.ptr.runtime.modifiers]{Modifiers}

\indexlibrarymember{reset}{unique_ptr}%
\begin{itemdecl}
void reset(nullptr_t p = nullptr) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{reset(pointer())}.
\end{itemdescr}

\indexlibrarymember{reset}{unique_ptr}%
\begin{itemdecl}
template<class U> void reset(U p) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
This function behaves the same as
the \tcode{reset} member of the primary template.

\pnum
\constraints
\begin{itemize}
\item \tcode{U} is the same type as \tcode{pointer}, or
\item \tcode{pointer} is the same type as \tcode{element_type*},
      \tcode{U} is a pointer type \tcode{V*}, and
      \tcode{V(*)[]} is convertible to \tcode{element_type(*)[]}.
\end{itemize}
\end{itemdescr}

\rSec3[unique.ptr.create]{Creation}

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

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not an array type.

\pnum
\returns
\tcode{unique_ptr<T>(new T(std::forward<Args>(args)...))}.

\end{itemdescr}

\indexlibraryglobal{make_unique}%
\begin{itemdecl}
template<class T> unique_ptr<T> make_unique(size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an array of unknown bound.

\pnum
\returns
\tcode{unique_ptr<T>(new remove_extent_t<T>[n]())}.

\end{itemdescr}

\indexlibraryglobal{make_unique}%
\begin{itemdecl}
template<class T, class... Args> @\unspec@ make_unique(Args&&...) = delete;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an array of known bound.

\end{itemdescr}

\indexlibraryglobal{make_unique}%
\begin{itemdecl}
template<class T> unique_ptr<T> make_unique_for_overwrite();
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not an array type.

\pnum
\returns
\tcode{unique_ptr<T>(new T)}.
\end{itemdescr}

\indexlibraryglobal{make_unique}%
\begin{itemdecl}
template<class T> unique_ptr<T> make_unique_for_overwrite(size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an array of unknown bound.

\pnum
\returns
\tcode{unique_ptr<T>(new remove_extent_t<T>[n])}.
\end{itemdescr}

\indexlibraryglobal{make_unique}%
\begin{itemdecl}
template<class T, class... Args> @\unspec@ make_unique_for_overwrite(Args&&...) = delete;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an array of known bound.
\end{itemdescr}

\rSec3[unique.ptr.special]{Specialized algorithms}

\indexlibrary{\idxcode{swap(unique_ptr\&, unique_ptr\&)}}%
\begin{itemdecl}
template<class T, class D> void swap(unique_ptr<T, D>& x, unique_ptr<T, D>& y) noexcept;
\end{itemdecl}

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

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

\indexlibrarymember{operator==}{unique_ptr}%
\begin{itemdecl}
template<class T1, class D1, class T2, class D2>
  bool operator==(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.get() == y.get()}.
\end{itemdescr}

\indexlibrarymember{operator<}{unique_ptr}%
\begin{itemdecl}
template<class T1, class D1, class T2, class D2>
  bool operator<(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{CT} denote
\begin{codeblock}
common_type_t<typename unique_ptr<T1, D1>::pointer,
              typename unique_ptr<T2, D2>::pointer>
\end{codeblock}

\pnum
\mandates
\begin{itemize}
\item \tcode{unique_ptr<T1, D1>::pointer} is implicitly convertible to \tcode{CT} and
\item \tcode{unique_ptr<T2, D2>::pointer} is implicitly convertible to \tcode{CT}.
\end{itemize}

\pnum
\expects
The specialization
\tcode{less<CT>} is a function object type\iref{function.objects} that
induces a strict weak ordering\iref{alg.sorting} on the pointer values.

\pnum
\returns
\tcode{less<CT>()(x.get(), y.get())}.
\end{itemdescr}

\indexlibrarymember{operator>}{unique_ptr}%
\begin{itemdecl}
template<class T1, class D1, class T2, class D2>
  bool operator>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{y < x}.
\end{itemdescr}

\indexlibrarymember{operator<=}{unique_ptr}%
\begin{itemdecl}
template<class T1, class D1, class T2, class D2>
  bool operator<=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{!(y < x)}.
\end{itemdescr}

\indexlibrarymember{operator>=}{unique_ptr}%
\begin{itemdecl}
template<class T1, class D1, class T2, class D2>
  bool operator>=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{!(x < y)}.
\end{itemdescr}

\indexlibrarymember{operator<=>}{unique_ptr}%
\begin{itemdecl}
template<class T1, class D1, class T2, class D2>
  requires @\libconcept{three_way_comparable_with}@<typename unique_ptr<T1, D1>::pointer,
                                     typename unique_ptr<T2, D2>::pointer>
  compare_three_way_result_t<typename unique_ptr<T1, D1>::pointer,
                             typename unique_ptr<T2, D2>::pointer>
    operator<=>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{compare_three_way()(x.get(), y.get())}.
\end{itemdescr}

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

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

\indexlibrarymember{operator<}{unique_ptr}%
\begin{itemdecl}
template<class T, class D>
  bool operator<(const unique_ptr<T, D>& x, nullptr_t);
template<class T, class D>
  bool operator<(nullptr_t, const unique_ptr<T, D>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
The specialization \tcode{less<unique_ptr<T, D>::pointer>} is
a function object type\iref{function.objects} that induces a strict weak
ordering\iref{alg.sorting} on the pointer values.

\pnum
\returns
The first function template returns
\begin{codeblock}
less<unique_ptr<T, D>::pointer>()(x.get(), nullptr)
\end{codeblock}
The second function template returns
\begin{codeblock}
less<unique_ptr<T, D>::pointer>()(nullptr, x.get())
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{operator>}{unique_ptr}%
\begin{itemdecl}
template<class T, class D>
  bool operator>(const unique_ptr<T, D>& x, nullptr_t);
template<class T, class D>
  bool operator>(nullptr_t, const unique_ptr<T, D>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The first function template returns \tcode{nullptr < x}.
The second function template returns \tcode{x < nullptr}.
\end{itemdescr}

\indexlibrarymember{operator<=}{unique_ptr}%
\begin{itemdecl}
template<class T, class D>
  bool operator<=(const unique_ptr<T, D>& x, nullptr_t);
template<class T, class D>
  bool operator<=(nullptr_t, const unique_ptr<T, D>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The first function template returns \tcode{!(nullptr < x)}.
The second function template returns \tcode{!(x < nullptr)}.
\end{itemdescr}

\indexlibrarymember{operator>=}{unique_ptr}%
\begin{itemdecl}
template<class T, class D>
  bool operator>=(const unique_ptr<T, D>& x, nullptr_t);
template<class T, class D>
  bool operator>=(nullptr_t, const unique_ptr<T, D>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The first function template returns \tcode{!(x < nullptr)}.
The second function template returns \tcode{!(nullptr < x)}.
\end{itemdescr}

\indexlibrarymember{operator<=>}{unique_ptr}%
\begin{itemdecl}
template<class T, class D>
  requires @\libconcept{three_way_comparable_with}@<typename unique_ptr<T, D>::pointer, nullptr_t>
  compare_three_way_result_t<typename unique_ptr<T, D>::pointer, nullptr_t>
    operator<=>(const unique_ptr<T, D>& x, nullptr_t);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{compare_three_way()(x.get(), nullptr)}.
\end{itemdescr}

\rSec3[unique.ptr.io]{I/O}

\indexlibrarymember{operator<<}{unique_ptr}%
\begin{itemdecl}
template<class E, class T, class Y, class D>
  basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const unique_ptr<Y, D>& p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{os << p.get()} is a valid expression.

\pnum
\effects
Equivalent to: \tcode{os << p.get();}

\pnum
\returns
\tcode{os}.
\end{itemdescr}

\rSec2[util.smartptr.weak.bad]{Class \tcode{bad_weak_ptr}}%
\indextext{smart pointers|(}%

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

\pnum
An exception of type \tcode{bad_weak_ptr} is thrown by the \tcode{shared_ptr}
constructor taking a \tcode{weak_ptr}.

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

\begin{itemdescr}
\pnum
\returns
An \impldef{return value of \tcode{bad_weak_ptr::what}} \ntbs{}.
\end{itemdescr}

\rSec2[util.smartptr.shared]{Class template \tcode{shared_ptr}}

\rSec3[util.smartptr.shared.general]{General}

\pnum
\indexlibraryglobal{shared_ptr}%
The \tcode{shared_ptr} class template stores a pointer, usually obtained
via \tcode{new}. \tcode{shared_ptr} implements semantics of shared ownership;
the last remaining owner of the pointer is responsible for destroying
the object, or otherwise releasing the resources associated with the stored pointer. A
\tcode{shared_ptr} is said to be empty if it does not own a pointer.

\begin{codeblock}
namespace std {
  template<class T> class shared_ptr {
  public:
    using element_type = remove_extent_t<T>;
    using weak_type    = weak_ptr<T>;

    // \ref{util.smartptr.shared.const}, constructors
    constexpr shared_ptr() noexcept;
    constexpr shared_ptr(nullptr_t) noexcept : shared_ptr() { }
    template<class Y>
      explicit shared_ptr(Y* p);
    template<class Y, class D>
      shared_ptr(Y* p, D d);
    template<class Y, class D, class A>
      shared_ptr(Y* p, D d, A a);
    template<class D>
      shared_ptr(nullptr_t p, D d);
    template<class D, class A>
      shared_ptr(nullptr_t p, D d, A a);
    template<class Y>
      shared_ptr(const shared_ptr<Y>& r, element_type* p) noexcept;
    template<class Y>
      shared_ptr(shared_ptr<Y>&& r, element_type* p) noexcept;
    shared_ptr(const shared_ptr& r) noexcept;
    template<class Y>
      shared_ptr(const shared_ptr<Y>& r) noexcept;
    shared_ptr(shared_ptr&& r) noexcept;
    template<class Y>
      shared_ptr(shared_ptr<Y>&& r) noexcept;
    template<class Y>
      explicit shared_ptr(const weak_ptr<Y>& r);
    template<class Y, class D>
      shared_ptr(unique_ptr<Y, D>&& r);

    // \ref{util.smartptr.shared.dest}, destructor
    ~shared_ptr();

    // \ref{util.smartptr.shared.assign}, assignment
    shared_ptr& operator=(const shared_ptr& r) noexcept;
    template<class Y>
      shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;
    shared_ptr& operator=(shared_ptr&& r) noexcept;
    template<class Y>
      shared_ptr& operator=(shared_ptr<Y>&& r) noexcept;
    template<class Y, class D>
      shared_ptr& operator=(unique_ptr<Y, D>&& r);

    // \ref{util.smartptr.shared.mod}, modifiers
    void swap(shared_ptr& r) noexcept;
    void reset() noexcept;
    template<class Y>
      void reset(Y* p);
    template<class Y, class D>
      void reset(Y* p, D d);
    template<class Y, class D, class A>
      void reset(Y* p, D d, A a);

    // \ref{util.smartptr.shared.obs}, observers
    element_type* get() const noexcept;
    T& operator*() const noexcept;
    T* operator->() const noexcept;
    element_type& operator[](ptrdiff_t i) const;
    long use_count() const noexcept;
    explicit operator bool() const noexcept;
    template<class U>
      bool owner_before(const shared_ptr<U>& b) const noexcept;
    template<class U>
      bool owner_before(const weak_ptr<U>& b) const noexcept;
  };

  template<class T>
    shared_ptr(weak_ptr<T>) -> shared_ptr<T>;
  template<class T, class D>
    shared_ptr(unique_ptr<T, D>) -> shared_ptr<T>;
}
\end{codeblock}

\pnum
Specializations of \tcode{shared_ptr} shall be \oldconcept{CopyConstructible},
\oldconcept{CopyAssignable}, and \oldconcept{\-Less\-Than\-Comparable}, allowing their use in standard
containers. Specializations of \tcode{shared_ptr} shall be
contextually convertible to \tcode{bool},
allowing their use in boolean expressions and declarations in conditions.

\pnum
The template parameter \tcode{T} of \tcode{shared_ptr}
may be an incomplete type.
\begin{note}
\tcode{T} can be a function type.
\end{note}

\pnum
\begin{example}
\begin{codeblock}
if (shared_ptr<X> px = dynamic_pointer_cast<X>(py)) {
  // do something with \tcode{px}
}
\end{codeblock}
\end{example}

\pnum
For purposes of determining the presence of a data race, member functions shall
access and modify only the \tcode{shared_ptr} and \tcode{weak_ptr} objects
themselves and not objects they refer to. Changes in \tcode{use_count()} do not
reflect modifications that can introduce data races.

\pnum
For the purposes of subclause \ref{smartptr},
a pointer type \tcode{Y*} is said to be
\defnx{compatible with}{compatible with!\idxcode{shared_ptr}}
a pointer type \tcode{T*} when either
\tcode{Y*} is convertible to \tcode{T*} or
\tcode{Y} is \tcode{U[N]} and \tcode{T} is \cv{}~\tcode{U[]}.

\rSec3[util.smartptr.shared.const]{Constructors}

\pnum
In the constructor definitions below,
enables \tcode{shared_from_this} with \tcode{p},
for a pointer \tcode{p} of type \tcode{Y*},
means that if \tcode{Y} has an unambiguous and accessible base class
that is a specialization of \tcode{enable_shared_from_this}\iref{util.smartptr.enab},
then \tcode{remove_cv_t<Y>*} shall be implicitly convertible to \tcode{T*} and
the constructor evaluates the statement:
\begin{codeblock}
if (p != nullptr && p->weak_this.expired())
  p->weak_this = shared_ptr<remove_cv_t<Y>>(*this, const_cast<remove_cv_t<Y>*>(p));
\end{codeblock}
The assignment to the \tcode{weak_this} member is not atomic and
conflicts with any potentially concurrent access to the same object\iref{intro.multithread}.

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

\begin{itemdescr}
\pnum
\ensures
\tcode{use_count() == 0 \&\& get() == nullptr}.
\end{itemdescr}

\indexlibraryctor{shared_ptr}%
\begin{itemdecl}
template<class Y> explicit shared_ptr(Y* p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{Y} is a complete type.

\pnum
\constraints
When \tcode{T} is an array type,
the expression \tcode{delete[] p} is well-formed and either
\tcode{T} is \tcode{U[N]} and \tcode{Y(*)[N]} is convertible to \tcode{T*}, or
\tcode{T} is \tcode{U[]} and \tcode{Y(*)[]} is convertible to \tcode{T*}.
When \tcode{T} is not an array type,
the expression \tcode{delete p} is well-formed and
\tcode{Y*} is convertible to \tcode{T*}.

\pnum
\expects
The expression
\tcode{delete[] p}, when \tcode{T} is an array type, or
\tcode{delete p}, when \tcode{T} is not an array type,
has well-defined behavior, and
does not throw exceptions.

\pnum
\effects
When \tcode{T} is not an array type,
constructs a \tcode{shared_ptr} object
that owns the pointer \tcode{p}.
Otherwise, constructs a \tcode{shared_ptr}
that owns \tcode{p} and a deleter of an
unspecified type that calls \tcode{delete[] p}.
When \tcode{T} is not an array type,
enables \tcode{shared_from_this} with \tcode{p}.
If an exception is thrown, \tcode{delete p} is called
when \tcode{T} is not an array type, \tcode{delete[] p} otherwise.

\pnum
\ensures
\tcode{use_count() == 1 \&\& get() == p}.

\pnum
\throws
\tcode{bad_alloc}, or an \impldef{exception type when \tcode{shared_ptr}
constructor fails} exception when a resource other than memory could not be obtained.
\end{itemdescr}

\indexlibraryctor{shared_ptr}%
\begin{itemdecl}
template<class Y, class D> shared_ptr(Y* p, D d);
template<class Y, class D, class A> shared_ptr(Y* p, D d, A a);
template<class D> shared_ptr(nullptr_t p, D d);
template<class D, class A> shared_ptr(nullptr_t p, D d, A a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_move_constructible_v<D>} is \tcode{true}, and
\tcode{d(p)} is a well-formed expression.
For the first two overloads:

\begin{itemize}
\item
If \tcode{T} is an array type, then either
\tcode{T} is \tcode{U[N]} and \tcode{Y(*)[N]} is convertible to \tcode{T*}, or
\tcode{T} is \tcode{U[]} and \tcode{Y(*)[]} is convertible to \tcode{T*}.

\item
If \tcode{T} is not an array type, then \tcode{Y*} is convertible to \tcode{T*}.
\end{itemize}

\pnum
\expects
Construction of \tcode{d} and a deleter of type \tcode{D}
initialized with \tcode{std::move(d)} do not throw exceptions.
The expression \tcode{d(p)}
has well-defined behavior and does not throw exceptions.
\tcode{A} meets the \oldconcept{Allocator} requirements (\tref{cpp17.allocator}).

\pnum
\effects
Constructs a \tcode{shared_ptr} object that owns the
object \tcode{p} and the deleter \tcode{d}.
When \tcode{T} is not an array type,
the first and second constructors enable \tcode{shared_from_this} with \tcode{p}.
The second and fourth constructors shall use a copy of \tcode{a} to
allocate memory for internal use.
If an exception is thrown, \tcode{d(p)} is called.

\pnum
\ensures
\tcode{use_count() == 1 \&\& get() == p}.

\pnum
\throws
\tcode{bad_alloc}, or an \impldef{exception type when \tcode{shared_ptr}
constructor fails} exception
when a resource other than memory could not be obtained.
\end{itemdescr}

\indexlibraryctor{shared_ptr}%
\begin{itemdecl}
template<class Y> shared_ptr(const shared_ptr<Y>& r, element_type* p) noexcept;
template<class Y> shared_ptr(shared_ptr<Y>&& r, element_type* p) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a \tcode{shared_ptr} instance that
stores \tcode{p} and shares ownership with
the initial value of \tcode{r}.

\pnum
\ensures
\tcode{get() == p}.
For the second overload,
\tcode{r} is empty and \tcode{r.get() == nullptr}.

\pnum
\begin{note}
Use of this constructor leads to a dangling pointer
unless \tcode{p} remains valid
at least until the ownership group of \tcode{r} is destroyed.
\end{note}

\pnum
\begin{note}
This constructor allows creation of an empty
\tcode{shared_ptr} instance with a non-null stored pointer.
\end{note}
\end{itemdescr}

\indexlibraryctor{shared_ptr}%
\begin{itemdecl}
shared_ptr(const shared_ptr& r) noexcept;
template<class Y> shared_ptr(const shared_ptr<Y>& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
For the second constructor, \tcode{Y*} is compatible with \tcode{T*}.

\pnum
\effects
If \tcode{r} is empty, constructs
an empty \tcode{shared_ptr} object; otherwise, constructs
a \tcode{shared_ptr} object that shares ownership with \tcode{r}.

\pnum
\ensures
\tcode{get() == r.get() \&\& use_count() == r.use_count()}.
\end{itemdescr}

\indexlibraryctor{shared_ptr}%
\begin{itemdecl}
shared_ptr(shared_ptr&& r) noexcept;
template<class Y> shared_ptr(shared_ptr<Y>&& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
For the second constructor, \tcode{Y*} is compatible with \tcode{T*}.

\pnum
\effects
Move constructs a \tcode{shared_ptr} instance from \tcode{r}.

\pnum
\ensures
\tcode{*this} shall contain the old value of
\tcode{r}. \tcode{r} shall be empty. \tcode{r.get() == nullptr}.
\end{itemdescr}

\indexlibraryctor{shared_ptr}%
\indexlibraryglobal{weak_ptr}%
\begin{itemdecl}
template<class Y> explicit shared_ptr(const weak_ptr<Y>& r);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{Y*} is compatible with \tcode{T*}.

\pnum
\effects
Constructs a \tcode{shared_ptr} object that shares ownership with
\tcode{r} and stores a copy of the pointer stored in \tcode{r}.
If an exception is thrown, the constructor has no effect.

\pnum
\ensures
\tcode{use_count() == r.use_count()}.

\pnum
\throws
\tcode{bad_weak_ptr} when \tcode{r.expired()}.
\end{itemdescr}

\indexlibraryctor{shared_ptr}%
\indexlibraryglobal{unique_ptr}%
\begin{itemdecl}
template<class Y, class D> shared_ptr(unique_ptr<Y, D>&& r);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{Y*} is compatible with \tcode{T*} and
\tcode{unique_ptr<Y, D>::pointer} is convertible to \tcode{element_type*}.

\pnum
\effects
If \tcode{r.get() == nullptr}, equivalent to \tcode{shared_ptr()}.
Otherwise, if \tcode{D} is not a reference type,
equivalent to \tcode{shared_ptr(r.release(), r.get_deleter())}.
Otherwise, equivalent to \tcode{shared_ptr(r.release(), ref(r.get_deleter()))}.
If an exception is thrown, the constructor has no effect.
\end{itemdescr}

\rSec3[util.smartptr.shared.dest]{Destructor}

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

\begin{itemdescr}
\pnum
\effects
\begin{itemize}
\item If \tcode{*this} is empty or shares ownership with another
\tcode{shared_ptr} instance (\tcode{use_count() > 1}), there are no side effects.

\item
Otherwise, if \tcode{*this} owns an object
\tcode{p} and a deleter \tcode{d}, \tcode{d(p)} is called.

\item Otherwise, \tcode{*this} owns a pointer \tcode{p},
and \tcode{delete p} is called.
\end{itemize}
\end{itemdescr}

\pnum
\begin{note}
Since the destruction of \tcode{*this}
decreases the number of instances that share ownership with \tcode{*this}
by one,
after \tcode{*this} has been destroyed
all \tcode{shared_ptr} instances that shared ownership with
\tcode{*this} will report a \tcode{use_count()} that is one less
than its previous value.
\end{note}

\rSec3[util.smartptr.shared.assign]{Assignment}

\indexlibrarymember{operator=}{shared_ptr}%
\begin{itemdecl}
shared_ptr& operator=(const shared_ptr& r) noexcept;
template<class Y> shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{shared_ptr(r).swap(*this)}.

\pnum
\returns
\tcode{*this}.

\pnum
\begin{note}
The use count updates caused by the temporary object
construction and destruction are not observable side
effects, so the implementation can meet the effects (and the
implied guarantees) via different means, without creating a
temporary. In particular, in the example:
\begin{codeblock}
shared_ptr<int> p(new int);
shared_ptr<void> q(p);
p = p;
q = p;
\end{codeblock}
both assignments can be no-ops.
\end{note}
\end{itemdescr}

\indexlibrarymember{operator=}{shared_ptr}%
\begin{itemdecl}
shared_ptr& operator=(shared_ptr&& r) noexcept;
template<class Y> shared_ptr& operator=(shared_ptr<Y>&& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{shared_ptr(std::move(r)).swap(*this)}.

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

\indexlibrarymember{operator=}{shared_ptr}%
\begin{itemdecl}
template<class Y, class D> shared_ptr& operator=(unique_ptr<Y, D>&& r);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{shared_ptr(std::move(r)).swap(*this)}.

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

\rSec3[util.smartptr.shared.mod]{Modifiers}

\indexlibrarymember{swap}{shared_ptr}%
\begin{itemdecl}
void swap(shared_ptr& r) noexcept;
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
Exchanges the contents of \tcode{*this} and \tcode{r}.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{shared_ptr().swap(*this)}.
\end{itemdescr}

\indexlibrarymember{reset}{shared_ptr}%
\begin{itemdecl}
template<class Y> void reset(Y* p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{shared_ptr(p).swap(*this)}.
\end{itemdescr}

\indexlibrarymember{reset}{shared_ptr}%
\begin{itemdecl}
template<class Y, class D> void reset(Y* p, D d);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{shared_ptr(p, d).swap(*this)}.
\end{itemdescr}

\indexlibrarymember{reset}{shared_ptr}%
\begin{itemdecl}
template<class Y, class D, class A> void reset(Y* p, D d, A a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{shared_ptr(p, d, a).swap(*this)}.
\end{itemdescr}

\rSec3[util.smartptr.shared.obs]{Observers}
\indexlibrarymember{get}{shared_ptr}%
\begin{itemdecl}
element_type* get() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The stored pointer.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\expects
\tcode{get() != 0}.

\pnum
\returns
\tcode{*get()}.

\pnum
\remarks
When \tcode{T} is an array type or \cv{}~\tcode{void},
it is unspecified whether this
member function is declared. If it is declared, it is unspecified what its
return type is, except that the declaration (although not necessarily the
definition) of the function shall be well-formed.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\expects
\tcode{get() != 0}.

\pnum
\returns
\tcode{get()}.

\pnum
\remarks
When \tcode{T} is an array type,
it is unspecified whether this member function is declared.
If it is declared, it is unspecified what its return type is,
except that the declaration (although not necessarily the definition)
of the function shall be well-formed.
\end{itemdescr}

\indexlibrarymember{operator[]}{shared_ptr}%
\begin{itemdecl}
element_type& operator[](ptrdiff_t i) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{get() != 0 \&\& i >= 0}.
If \tcode{T} is \tcode{U[N]}, \tcode{i < N}.

\pnum
\returns
\tcode{get()[i]}.

\pnum
\remarks
When \tcode{T} is not an array type,
it is unspecified whether this member function is declared.
If it is declared, it is unspecified what its return type is,
except that the declaration (although not necessarily the definition)
of the function shall be well-formed.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibrarymember{use_count}{shared_ptr}%
\begin{itemdecl}
long use_count() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The number of \tcode{shared_ptr} objects, \tcode{*this} included,
that share ownership with \tcode{*this}, or \tcode{0} when \tcode{*this} is
empty.

\pnum
\sync
None.

\pnum
\begin{note}
\tcode{get() == nullptr}
does not imply a specific return value of \tcode{use_count()}.
\end{note}

\pnum
\begin{note}
\tcode{weak_ptr<T>::lock()}
can affect the return value of \tcode{use_count()}.
\end{note}

\pnum
\begin{note}
When multiple threads
might affect the return value of \tcode{use_count()},
the result is approximate.
In particular, \tcode{use_count() == 1} does not imply that accesses through
a previously destroyed \tcode{shared_ptr} have in any sense completed.
\end{note}
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\returns
\tcode{get() != 0}.
\end{itemdescr}

\indexlibrarymember{owner_before}{shared_ptr}%
\begin{itemdecl}
template<class U> bool owner_before(const shared_ptr<U>& b) const noexcept;
template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An unspecified value such that
\begin{itemize}
\item \tcode{x.owner_before(y)} defines a strict weak ordering as defined in~\ref{alg.sorting};

\item under the equivalence relation defined by \tcode{owner_before},
\tcode{!a.owner_before(b) \&\& !b.owner_before(a)}, two \tcode{shared_ptr} or
\tcode{weak_ptr} instances are equivalent if and only if they share ownership or
are both empty.
\end{itemize}

\end{itemdescr}

\rSec3[util.smartptr.shared.create]{Creation}

\pnum
The common requirements that apply to all
\tcode{make_shared},
\tcode{allocate_shared},
\tcode{make_shared_for_overwrite}, and
\tcode{allocate_shared_for_overwrite} overloads,
unless specified otherwise, are described below.

\indexlibraryglobal{make_shared}%
\indexlibraryglobal{allocate_shared}%
\begin{itemdecl}
template<class T, ...>
  shared_ptr<T> make_shared(@\placeholdernc{args}@);
template<class T, class A, ...>
  shared_ptr<T> allocate_shared(const A& a, @\placeholdernc{args}@);
template<class T, ...>
  shared_ptr<T> make_shared_for_overwrite(@\placeholdernc{args}@);
template<class T, class A, ...>
  shared_ptr<T> allocate_shared_for_overwrite(const A& a, @\placeholdernc{args}@);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{A} meets the \oldconcept{Allocator} requirements (\tref{cpp17.allocator}).

\pnum
\effects
Allocates memory for an object of type \tcode{T}
(or \tcode{U[N]} when \tcode{T} is \tcode{U[]},
where \tcode{N} is determined from \placeholder{args} as specified by the concrete overload).
The object is initialized from \placeholder{args} as specified by the concrete overload.
The \tcode{allocate_shared} and \tcode{allocate_shared_for_overwrite} templates
use a copy of \tcode{a}
(rebound for an unspecified \tcode{value_type}) to allocate memory.
If an exception is thrown, the functions have no effect.

\pnum
\returns
A \tcode{shared_ptr} instance that stores and owns the address of
the newly constructed object.

\pnum
\ensures
\tcode{r.get() != 0 \&\& r.use_count() == 1},
where \tcode{r} is the return value.

\pnum
\throws
\tcode{bad_alloc}, or
an exception thrown from \tcode{allocate} or from the initialization of the object.

\pnum
\remarks
\begin{itemize}
\item
  Implementations should perform no more than one memory allocation.
  \begin{note}
  This provides efficiency equivalent to an intrusive smart pointer.
  \end{note}
\item
  When an object of an array type \tcode{U} is specified to have
  an initial value of \tcode{u} (of the same type),
  this shall be interpreted to mean that
  each array element of the object has as its initial value
  the corresponding element from \tcode{u}.
\item
  When an object of an array type is specified to have
  a default initial value,
  this shall be interpreted to mean that each array element of the object
  has a default initial value.
\item
  When a (sub)object of a non-array type \tcode{U} is specified to have
  an initial value of \tcode{v}, or \tcode{U(l...)},
  where \tcode{l...} is a list of constructor arguments,
  \tcode{make_shared} shall initialize this (sub)object
  via the expression \tcode{::new(pv) U(v)} or \tcode{::new(pv) U(l...)} respectively,
  where \tcode{pv} has type \tcode{void*} and points to storage
  suitable to hold an object of type \tcode{U}.
\item
  When a (sub)object of a non-array type \tcode{U} is specified to have
  an initial value of \tcode{v}, or \tcode{U(l...)},
  where \tcode{l...} is a list of constructor arguments,
  \tcode{allocate_shared} shall initialize this (sub)object
  via the expression
  \begin{itemize}
  \item \tcode{allocator_traits<A2>::construct(a2, pv, v)} or
  \item \tcode{allocator_traits<A2>::construct(a2, pv, l...)}
  \end{itemize}
  respectively,
  where \tcode{pv} points to storage
  suitable to hold an object of type \tcode{U} and
  \tcode{a2} of type \tcode{A2} is a rebound copy of
  the allocator \tcode{a} passed to \tcode{allocate_shared}
  such that its \tcode{value_type} is \tcode{remove_cv_t<U>}.
\item
  When a (sub)object of non-array type \tcode{U} is specified to have
  a default initial value,
  \tcode{make_shared} shall initialize this (sub)object
  via the expression \tcode{::new(pv) U()},
  where \tcode{pv} has type \tcode{void*} and points to storage
  suitable to hold an object of type \tcode{U}.
\item
  When a (sub)object of non-array type \tcode{U} is specified to have
  a default initial value,
  \tcode{allocate_shared} shall initialize this (sub)object
  via the expression \tcode{allocator_traits<A2>::construct(a2, pv)},
  where \tcode{pv} points to storage
  suitable to hold an object of type \tcode{U} and
  \tcode{a2} of type \tcode{A2} is a rebound copy of
  the allocator \tcode{a} passed to \tcode{allocate_shared}
  such that its \tcode{value_type} is \tcode{remove_cv_t<U>}.
\item
  When a (sub)object of non-array type \tcode{U} is initialized by
  \tcode{make_shared_for_overwrite} or\linebreak % avoid Overfull
  \tcode{allocate_shared_for_overwrite},
  it is initialized via the expression \tcode{::new(pv) U},
  where \tcode{pv} has type \tcode{void*} and
  points to storage suitable to hold an object of type \tcode{U}.
\item
  Array elements are initialized in ascending order of their addresses.
\item
  When the lifetime of the object managed by the return value ends, or
  when the initialization of an array element throws an exception,
  the initialized elements are destroyed in the reverse order
  of their original construction.
\item
  When a (sub)object of non-array type \tcode{U}
  that was initialized by \tcode{make_shared} is to be destroyed,
  it is destroyed via the expression \tcode{pv->\~{}U()} where
  \tcode{pv} points to that object of type \tcode{U}.
\item
  When a (sub)object of non-array type \tcode{U}
  that was initialized by \tcode{allocate_shared} is to be destroyed,
  it is destroyed via the expression
  \tcode{allocator_traits<A2>::destroy(a2, pv)} where
  \tcode{pv} points to that object of type \tcode{remove_cv_t<U>} and
  \tcode{a2} of type \tcode{A2} is a rebound copy of
  the allocator \tcode{a} passed to \tcode{allocate_shared}
  such that its \tcode{value_type} is \tcode{remove_cv_t<U>}.
\end{itemize}
\begin{note}
These functions will typically allocate more memory than \tcode{sizeof(T)} to
allow for internal bookkeeping structures such as reference counts.
\end{note}
\end{itemdescr}

\indexlibraryglobal{make_shared}%
\indexlibraryglobal{allocate_shared}%
\begin{itemdecl}
template<class T, class... Args>
  shared_ptr<T> make_shared(Args&&... args);                    // \tcode{T} is not array
template<class T, class A, class... Args>
  shared_ptr<T> allocate_shared(const A& a, Args&&... args);    // \tcode{T} is not array
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not an array type.

\pnum
\returns
A \tcode{shared_ptr} to an object of type \tcode{T}
with an initial value \tcode{T(forward<Args>(args)...)}.

\pnum
\remarks
The \tcode{shared_ptr} constructors called by these functions
enable \tcode{shared_from_this}
with the address of the newly constructed object of type \tcode{T}.

\pnum
\begin{example}
\begin{codeblock}
shared_ptr<int> p = make_shared<int>(); // \tcode{shared_ptr} to \tcode{int()}
shared_ptr<vector<int>> q = make_shared<vector<int>>(16, 1);
  // \tcode{shared_ptr} to vector of \tcode{16} elements with value \tcode{1}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{make_shared}%
\indexlibraryglobal{allocate_shared}%
\begin{itemdecl}
template<class T> shared_ptr<T>
  make_shared(size_t N);                                        // \tcode{T} is \tcode{U[]}
template<class T, class A>
  shared_ptr<T> allocate_shared(const A& a, size_t N);          // \tcode{T} is \tcode{U[]}
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is of the form \tcode{U[]}.

\pnum
\returns
A \tcode{shared_ptr} to an object of type \tcode{U[N]}
with a default initial value,
where \tcode{U} is \tcode{remove_extent_t<T>}.

\pnum
\begin{example}
\begin{codeblock}
shared_ptr<double[]> p = make_shared<double[]>(1024);
  // \tcode{shared_ptr} to a value-initialized \tcode{double[1024]}
shared_ptr<double[][2][2]> q = make_shared<double[][2][2]>(6);
  // \tcode{shared_ptr} to a value-initialized \tcode{double[6][2][2]}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{make_shared}%
\indexlibraryglobal{allocate_shared}%
\begin{itemdecl}
template<class T>
  shared_ptr<T> make_shared();                                  // \tcode{T} is \tcode{U[N]}
template<class T, class A>
  shared_ptr<T> allocate_shared(const A& a);                    // \tcode{T} is \tcode{U[N]}
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is of the form \tcode{U[N]}.

\pnum
\returns
A \tcode{shared_ptr} to an object of type \tcode{T}
with a default initial value.

\pnum
\begin{example}
\begin{codeblock}
shared_ptr<double[1024]> p = make_shared<double[1024]>();
  // \tcode{shared_ptr} to a value-initialized \tcode{double[1024]}
shared_ptr<double[6][2][2]> q = make_shared<double[6][2][2]>();
  // \tcode{shared_ptr} to a value-initialized \tcode{double[6][2][2]}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{make_shared}%
\indexlibraryglobal{allocate_shared}%
\begin{itemdecl}
template<class T>
  shared_ptr<T> make_shared(size_t N,
                            const remove_extent_t<T>& u);       // \tcode{T} is \tcode{U[]}
template<class T, class A>
  shared_ptr<T> allocate_shared(const A& a, size_t N,
                                const remove_extent_t<T>& u);   // \tcode{T} is \tcode{U[]}
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is of the form \tcode{U[]}.

\pnum
\returns
A \tcode{shared_ptr} to an object of type \tcode{U[N]},
where \tcode{U} is \tcode{remove_extent_t<T>} and
each array element has an initial value of \tcode{u}.

\pnum
\begin{example}
\begin{codeblock}
shared_ptr<double[]> p = make_shared<double[]>(1024, 1.0);
  // \tcode{shared_ptr} to a \tcode{double[1024]}, where each element is \tcode{1.0}
shared_ptr<double[][2]> q = make_shared<double[][2]>(6, {1.0, 0.0});
  // \tcode{shared_ptr} to a \tcode{double[6][2]}, where each \tcode{double[2]} element is \tcode{\{1.0, 0.0\}}
shared_ptr<vector<int>[]> r = make_shared<vector<int>[]>(4, {1, 2});
  // \tcode{shared_ptr} to a \tcode{vector<int>[4]}, where each vector has contents \tcode{\{1, 2\}}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{make_shared}%
\indexlibraryglobal{allocate_shared}%
\begin{itemdecl}
template<class T>
  shared_ptr<T> make_shared(const remove_extent_t<T>& u);       // \tcode{T} is \tcode{U[N]}
template<class T, class A>
  shared_ptr<T> allocate_shared(const A& a,
                                const remove_extent_t<T>& u);   // \tcode{T} is \tcode{U[N]}
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is of the form \tcode{U[N]}.

\pnum
\returns
A \tcode{shared_ptr} to an object of type \tcode{T},
where each array element of type \tcode{remove_extent_t<T>}
has an initial value of \tcode{u}.

\pnum
\begin{example}
\begin{codeblock}
shared_ptr<double[1024]> p = make_shared<double[1024]>(1.0);
  // \tcode{shared_ptr} to a \tcode{double[1024]}, where each element is \tcode{1.0}
shared_ptr<double[6][2]> q = make_shared<double[6][2]>({1.0, 0.0});
  // \tcode{shared_ptr} to a \tcode{double[6][2]}, where each double[2] element is \tcode{\{1.0, 0.0\}}
shared_ptr<vector<int>[4]> r = make_shared<vector<int>[4]>({1, 2});
  // \tcode{shared_ptr} to a \tcode{vector<int>[4]}, where each vector has contents \tcode{\{1, 2\}}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{make_shared}%
\indexlibraryglobal{allocate_shared}%
\begin{itemdecl}
template<class T>
  shared_ptr<T> make_shared_for_overwrite();
template<class T, class A>
  shared_ptr<T> allocate_shared_for_overwrite(const A& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is not an array of unknown bound.

\pnum
\returns
A \tcode{shared_ptr} to an object of type \tcode{T}.

\pnum
\begin{example}
\begin{codeblock}
struct X { double data[1024]; };
shared_ptr<X> p = make_shared_for_overwrite<X>();
  // \tcode{shared_ptr} to a default-initialized \tcode{X}, where each element in \tcode{X::data} has an indeterminate value

shared_ptr<double[1024]> q = make_shared_for_overwrite<double[1024]>();
  // \tcode{shared_ptr} to a default-initialized \tcode{double[1024]}, where each element has an indeterminate value
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibraryglobal{make_shared}%
\indexlibraryglobal{allocate_shared}%
\begin{itemdecl}
template<class T>
  shared_ptr<T> make_shared_for_overwrite(size_t N);
template<class T, class A>
  shared_ptr<T> allocate_shared_for_overwrite(const A& a, size_t N);
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an array of unknown bound.

\pnum
\returns
A \tcode{shared_ptr} to an object of type \tcode{U[N]},
where \tcode{U} is \tcode{remove_extent_t<T>}.

\pnum
\begin{example}
\begin{codeblock}
shared_ptr<double[]> p = make_shared_for_overwrite<double[]>(1024);
  // \tcode{shared_ptr} to a default-initialized \tcode{double[1024]}, where each element has an indeterminate value
\end{codeblock}
\end{example}
\end{itemdescr}

\rSec3[util.smartptr.shared.cmp]{Comparison}

\indexlibrarymember{operator==}{shared_ptr}%
\begin{itemdecl}
template<class T, class U>
  bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{a.get() == b.get()}.
\end{itemdescr}

\indexlibrarymember{operator==}{shared_ptr}%
\begin{itemdecl}
template<class T>
  bool operator==(const shared_ptr<T>& a, nullptr_t) noexcept;
\end{itemdecl}

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

\indexlibrarymember{operator<=>}{shared_ptr}%
\begin{itemdecl}
template<class T, class U>
  strong_ordering operator<=>(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{compare_three_way()(a.get(), b.get())}.

\pnum
\begin{note}
Defining a comparison operator function allows \tcode{shared_ptr} objects
to be used as keys in associative containers.
\end{note}
\end{itemdescr}

\indexlibrarymember{operator<=>}{shared_ptr}%
\begin{itemdecl}
template<class T>
  strong_ordering operator<=>(const shared_ptr<T>& a, nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{compare_three_way()(a.get(), nullptr)}.
\end{itemdescr}

\rSec3[util.smartptr.shared.spec]{Specialized algorithms}

\indexlibrarymember{swap}{shared_ptr}%
\begin{itemdecl}
template<class T>
  void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{a.swap(b)}.
\end{itemdescr}

\rSec3[util.smartptr.shared.cast]{Casts}

\indexlibrarymember{static_pointer_cast}{shared_ptr}%
\begin{itemdecl}
template<class T, class U>
  shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;
template<class T, class U>
  shared_ptr<T> static_pointer_cast(shared_ptr<U>&& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The expression \tcode{static_cast<T*>((U*)nullptr)} is well-formed.

\pnum
\returns
\begin{codeblock}
shared_ptr<T>(@\placeholder{R}@, static_cast<typename shared_ptr<T>::element_type*>(r.get()))
\end{codeblock}
where \tcode{\placeholder{R}} is \tcode{r} for the first overload, and
\tcode{std::move(r)} for the second.

\pnum
\begin{note}
The seemingly equivalent expression
\tcode{shared_ptr<T>(static_cast<T*>(r.get()))}
will eventually result in undefined behavior, attempting to delete the
same object twice.
\end{note}
\end{itemdescr}

\indexlibrarymember{dynamic_pointer_cast}{shared_ptr}%
\begin{itemdecl}
template<class T, class U>
  shared_ptr<T> dynamic_pointer_cast(const shared_ptr<U>& r) noexcept;
template<class T, class U>
  shared_ptr<T> dynamic_pointer_cast(shared_ptr<U>&& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The expression \tcode{dynamic_cast<T*>((U*)nullptr)} is well-formed.
The expression \tcode{dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())} is well-formed.

\pnum
\expects
The expression \tcode{dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())} has well-defined behavior.

\pnum
\returns
\begin{itemize}
\item When \tcode{dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())}
  returns a non-null value \tcode{p},
  \tcode{shared_ptr<T>(\placeholder{R}, p)},
  where \tcode{\placeholder{R}} is \tcode{r} for the first overload, and
  \tcode{std::move(r)} for the second.
\item Otherwise, \tcode{shared_ptr<T>()}.
\end{itemize}

\pnum
\begin{note}
The seemingly equivalent expression
\tcode{shared_ptr<T>(dynamic_cast<T*>(r.get()))} will eventually result in
undefined behavior, attempting to delete the same object twice.
\end{note}
\end{itemdescr}

\indexlibrarymember{const_pointer_cast}{shared_ptr}%
\begin{itemdecl}
template<class T, class U>
  shared_ptr<T> const_pointer_cast(const shared_ptr<U>& r) noexcept;
template<class T, class U>
  shared_ptr<T> const_pointer_cast(shared_ptr<U>&& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The expression \tcode{const_cast<T*>((U*)nullptr)} is well-formed.

\pnum
\returns
\begin{codeblock}
shared_ptr<T>(@\placeholder{R}@, const_cast<typename shared_ptr<T>::element_type*>(r.get()))
\end{codeblock}
where \tcode{\placeholder{R}} is \tcode{r} for the first overload, and
\tcode{std::move(r)} for the second.

\pnum
\begin{note}
The seemingly equivalent expression
\tcode{shared_ptr<T>(const_cast<T*>(r.get()))} will eventually result in
undefined behavior, attempting to delete the same object twice.
\end{note}
\end{itemdescr}

\indexlibrarymember{reinterpret_pointer_cast}{shared_ptr}%
\begin{itemdecl}
template<class T, class U>
  shared_ptr<T> reinterpret_pointer_cast(const shared_ptr<U>& r) noexcept;
template<class T, class U>
  shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U>&& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The expression \tcode{reinterpret_cast<T*>((U*)nullptr)} is well-formed.

\pnum
\returns
\begin{codeblock}
shared_ptr<T>(@\placeholder{R}@, reinterpret_cast<typename shared_ptr<T>::element_type*>(r.get()))
\end{codeblock}
where \tcode{\placeholder{R}} is \tcode{r} for the first overload, and
\tcode{std::move(r)} for the second.

\pnum
\begin{note}
The seemingly equivalent expression
\tcode{shared_ptr<T>(reinterpret_cast<T*>(r.get()))} will eventually result in
undefined behavior, attempting to delete the same object twice.
\end{note}
\end{itemdescr}

\rSec3[util.smartptr.getdeleter]{\tcode{get_deleter}}

\indexlibrarymember{get_deleter}{shared_ptr}%
\begin{itemdecl}
template<class D, class T>
  D* get_deleter(const shared_ptr<T>& p) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If \tcode{p} owns a deleter \tcode{d} of type cv-unqualified
\tcode{D}, returns \tcode{addressof(d)}; otherwise returns \tcode{nullptr}.
The returned
pointer remains valid as long as there exists a \tcode{shared_ptr} instance
that owns \tcode{d}.
\begin{note}
It is unspecified whether the pointer
remains valid longer than that. This can happen if the implementation doesn't destroy
the deleter until all \tcode{weak_ptr} instances that share ownership with
\tcode{p} have been destroyed.
\end{note}
\end{itemdescr}

\rSec3[util.smartptr.shared.io]{I/O}

\indexlibrarymember{operator<<}{shared_ptr}%
\begin{itemdecl}
template<class E, class T, class Y>
  basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const shared_ptr<Y>& p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by: \tcode{os <{}< p.get();}

\pnum
\returns
\tcode{os}.
\end{itemdescr}

\rSec2[util.smartptr.weak]{Class template \tcode{weak_ptr}}

\rSec3[util.smartptr.weak.general]{General}

\pnum
\indexlibraryglobal{weak_ptr}%
The \tcode{weak_ptr} class template stores a weak reference to an object
that is already managed by a \tcode{shared_ptr}. To access the object, a
\tcode{weak_ptr} can be converted to a \tcode{shared_ptr} using the member
function \tcode{lock}.

\begin{codeblock}
namespace std {
  template<class T> class weak_ptr {
  public:
    using element_type = remove_extent_t<T>;

    // \ref{util.smartptr.weak.const}, constructors
    constexpr weak_ptr() noexcept;
    template<class Y>
      weak_ptr(const shared_ptr<Y>& r) noexcept;
    weak_ptr(const weak_ptr& r) noexcept;
    template<class Y>
      weak_ptr(const weak_ptr<Y>& r) noexcept;
    weak_ptr(weak_ptr&& r) noexcept;
    template<class Y>
      weak_ptr(weak_ptr<Y>&& r) noexcept;

    // \ref{util.smartptr.weak.dest}, destructor
    ~weak_ptr();

    // \ref{util.smartptr.weak.assign}, assignment
    weak_ptr& operator=(const weak_ptr& r) noexcept;
    template<class Y>
      weak_ptr& operator=(const weak_ptr<Y>& r) noexcept;
    template<class Y>
      weak_ptr& operator=(const shared_ptr<Y>& r) noexcept;
    weak_ptr& operator=(weak_ptr&& r) noexcept;
    template<class Y>
      weak_ptr& operator=(weak_ptr<Y>&& r) noexcept;

    // \ref{util.smartptr.weak.mod}, modifiers
    void swap(weak_ptr& r) noexcept;
    void reset() noexcept;

    // \ref{util.smartptr.weak.obs}, observers
    long use_count() const noexcept;
    bool expired() const noexcept;
    shared_ptr<T> lock() const noexcept;
    template<class U>
      bool owner_before(const shared_ptr<U>& b) const noexcept;
    template<class U>
      bool owner_before(const weak_ptr<U>& b) const noexcept;
  };

  template<class T>
    weak_ptr(shared_ptr<T>) -> weak_ptr<T>;

  // \ref{util.smartptr.weak.spec}, specialized algorithms
  template<class T>
    void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
}
\end{codeblock}

\pnum
Specializations of \tcode{weak_ptr} shall be \oldconcept{CopyConstructible} and
\oldconcept{CopyAssignable}, allowing their use in standard
containers.  The template parameter \tcode{T} of \tcode{weak_ptr} may be an
incomplete type.

\rSec3[util.smartptr.weak.const]{Constructors}

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

\begin{itemdescr}
\pnum
\effects
Constructs an empty \tcode{weak_ptr} object.

\pnum
\ensures
\tcode{use_count() == 0}.
\end{itemdescr}

\indexlibraryctor{weak_ptr}%
\begin{itemdecl}
weak_ptr(const weak_ptr& r) noexcept;
template<class Y> weak_ptr(const weak_ptr<Y>& r) noexcept;
template<class Y> weak_ptr(const shared_ptr<Y>& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
For the second and third constructors, \tcode{Y*} is compatible with \tcode{T*}.

\pnum
\effects
If \tcode{r} is empty, constructs
an empty \tcode{weak_ptr} object; otherwise, constructs
a \tcode{weak_ptr} object that shares ownership
with \tcode{r} and stores a copy of the pointer stored in \tcode{r}.

\pnum
\ensures
\tcode{use_count() == r.use_count()}.
\end{itemdescr}

\indexlibraryctor{weak_ptr}%
\begin{itemdecl}
weak_ptr(weak_ptr&& r) noexcept;
template<class Y> weak_ptr(weak_ptr<Y>&& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
For the second constructor, \tcode{Y*} is compatible with \tcode{T*}.

\pnum
\effects
Move constructs a \tcode{weak_ptr} instance from \tcode{r}.

\pnum
\ensures
\tcode{*this} shall contain the old value of \tcode{r}.
\tcode{r} shall be empty. \tcode{r.use_count() == 0}.
\end{itemdescr}

\rSec3[util.smartptr.weak.dest]{Destructor}

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

\begin{itemdescr}
\pnum
\effects
Destroys this \tcode{weak_ptr} object but has no
effect on the object its stored pointer points to.
\end{itemdescr}

\rSec3[util.smartptr.weak.assign]{Assignment}

\indexlibrarymember{operator=}{weak_ptr}%
\begin{itemdecl}
weak_ptr& operator=(const weak_ptr& r) noexcept;
template<class Y> weak_ptr& operator=(const weak_ptr<Y>& r) noexcept;
template<class Y> weak_ptr& operator=(const shared_ptr<Y>& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{weak_ptr(r).swap(*this)}.

\pnum
\remarks
The implementation may meet the effects (and the
implied guarantees) via different means, without creating a temporary object.

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

\indexlibrarymember{operator=}{weak_ptr}%
\begin{itemdecl}
weak_ptr& operator=(weak_ptr&& r) noexcept;
template<class Y> weak_ptr& operator=(weak_ptr<Y>&& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{weak_ptr(std::move(r)).swap(*this)}.

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

\rSec3[util.smartptr.weak.mod]{Modifiers}
\indexlibrarymember{swap}{weak_ptr}%
\begin{itemdecl}
void swap(weak_ptr& r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Exchanges the contents of \tcode{*this} and \tcode{r}.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{weak_ptr().swap(*this)}.
\end{itemdescr}

\rSec3[util.smartptr.weak.obs]{Observers}
\indexlibrarymember{use_count}{weak_ptr}%
\begin{itemdecl}
long use_count() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{0} if \tcode{*this} is empty;
otherwise, the number of \tcode{shared_ptr} instances
that share ownership with \tcode{*this}.
\end{itemdescr}

\indexlibrarymember{expired}{weak_ptr}%
\begin{itemdecl}
bool expired() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{use_count() == 0}.
\end{itemdescr}

\indexlibrarymember{lock}{weak_ptr}%
\begin{itemdecl}
shared_ptr<T> lock() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{expired() ?\ shared_ptr<T>() :\ shared_ptr<T>(*this)}, executed atomically.
\end{itemdescr}

\indexlibrarymember{owner_before}{weak_ptr}%
\begin{itemdecl}
template<class U> bool owner_before(const shared_ptr<U>& b) const noexcept;
template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An unspecified value such that
\begin{itemize}
\item \tcode{x.owner_before(y)} defines a strict weak ordering as defined in~\ref{alg.sorting};

\item under the equivalence relation defined by \tcode{owner_before},
\tcode{!a.owner_before(b) \&\& !b.owner_before(a)}, two \tcode{shared_ptr} or
\tcode{weak_ptr} instances are equivalent if and only if they share ownership or are
both empty.
\end{itemize}
\end{itemdescr}


\rSec3[util.smartptr.weak.spec]{Specialized algorithms}

\indexlibrarymember{swap}{weak_ptr}%
\begin{itemdecl}
template<class T>
  void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{a.swap(b)}.
\end{itemdescr}

\rSec2[util.smartptr.ownerless]{Class template \tcode{owner_less}}

\pnum
The class template \tcode{owner_less} allows ownership-based mixed comparisons of shared
and weak pointers.

\indexlibraryglobal{owner_less}%
\begin{codeblock}
namespace std {
  template<class T = void> struct owner_less;

  template<class T> struct owner_less<shared_ptr<T>> {
    bool operator()(const shared_ptr<T>&, const shared_ptr<T>&) const noexcept;
    bool operator()(const shared_ptr<T>&, const weak_ptr<T>&) const noexcept;
    bool operator()(const weak_ptr<T>&, const shared_ptr<T>&) const noexcept;
  };

  template<class T> struct owner_less<weak_ptr<T>> {
    bool operator()(const weak_ptr<T>&, const weak_ptr<T>&) const noexcept;
    bool operator()(const shared_ptr<T>&, const weak_ptr<T>&) const noexcept;
    bool operator()(const weak_ptr<T>&, const shared_ptr<T>&) const noexcept;
  };

  template<> struct owner_less<void> {
    template<class T, class U>
      bool operator()(const shared_ptr<T>&, const shared_ptr<U>&) const noexcept;
    template<class T, class U>
      bool operator()(const shared_ptr<T>&, const weak_ptr<U>&) const noexcept;
    template<class T, class U>
      bool operator()(const weak_ptr<T>&, const shared_ptr<U>&) const noexcept;
    template<class T, class U>
      bool operator()(const weak_ptr<T>&, const weak_ptr<U>&) const noexcept;

    using is_transparent = @\unspec@;
  };
}
\end{codeblock}

\indexlibrarymember{operator()}{owner_less}%
\pnum
\tcode{operator()(x, y)} returns \tcode{x.owner_before(y)}.
\begin{note}
Note that
\begin{itemize}
\item \tcode{operator()} defines a strict weak ordering as defined in~\ref{alg.sorting};

\item
two \tcode{shared_ptr} or \tcode{weak_ptr} instances are equivalent
under the equivalence relation defined by \tcode{operator()},
\tcode{!operator()(a, b) \&\& !operator()(b, a)},
if and only if they share ownership or are both empty.
\end{itemize}
\end{note}

\rSec2[util.smartptr.enab]{Class template \tcode{enable_shared_from_this}}

\pnum
\indexlibraryglobal{enable_shared_from_this}%
A class \tcode{T} can inherit from \tcode{enable_shared_from_this<T>}
to inherit the \tcode{shared_from_this} member functions that obtain
a \tcode{shared_ptr} instance pointing to \tcode{*this}.

\pnum
\begin{example}
\begin{codeblock}
struct X: public enable_shared_from_this<X> { };

int main() {
  shared_ptr<X> p(new X);
  shared_ptr<X> q = p->shared_from_this();
  assert(p == q);
  assert(!p.owner_before(q) && !q.owner_before(p)); // p and q share ownership
}
\end{codeblock}
\end{example}

\begin{codeblock}
namespace std {
  template<class T> class enable_shared_from_this {
  protected:
    constexpr enable_shared_from_this() noexcept;
    enable_shared_from_this(const enable_shared_from_this&) noexcept;
    enable_shared_from_this& operator=(const enable_shared_from_this&) noexcept;
    ~enable_shared_from_this();

  public:
    shared_ptr<T> shared_from_this();
    shared_ptr<T const> shared_from_this() const;
    weak_ptr<T> weak_from_this() noexcept;
    weak_ptr<T const> weak_from_this() const noexcept;

  private:
    mutable weak_ptr<T> weak_this;  // \expos
  };
}
\end{codeblock}

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

\indexlibraryctor{enable_shared_from_this}%
\begin{itemdecl}
constexpr enable_shared_from_this() noexcept;
enable_shared_from_this(const enable_shared_from_this<T>&) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Value-initializes \tcode{weak_this}.
\end{itemdescr}

\indexlibrarymember{operator=}{enable_shared_from_this}%
\begin{itemdecl}
enable_shared_from_this<T>& operator=(const enable_shared_from_this<T>&) noexcept;
\end{itemdecl}

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

\pnum
\begin{note}
\tcode{weak_this} is not changed.
\end{note}
\end{itemdescr}

\indexlibraryglobal{shared_ptr}%
\indexlibrarymember{shared_from_this}{enable_shared_from_this}%
\begin{itemdecl}
shared_ptr<T>       shared_from_this();
shared_ptr<T const> shared_from_this() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{shared_ptr<T>(weak_this)}.
\end{itemdescr}

\indexlibraryglobal{weak_ptr}%
\indexlibrarymember{weak_from_this}{enable_shared_from_this}%
\begin{itemdecl}
weak_ptr<T>       weak_from_this() noexcept;
weak_ptr<T const> weak_from_this() const noexcept;
\end{itemdecl}

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

\rSec2[util.smartptr.hash]{Smart pointer hash support}

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

\begin{itemdescr}
\pnum
Letting \tcode{UP} be \tcode{unique_ptr<T,D>},
the specialization \tcode{hash<UP>} is enabled\iref{unord.hash}
if and only if \tcode{hash<typename UP::pointer>} is enabled.
When enabled, for an object \tcode{p} of type \tcode{UP},
\tcode{hash<UP>()(p)} evaluates to
the same value as \tcode{hash<typename UP::pointer>()(p.get())}.
The member functions are not guaranteed to be \tcode{noexcept}.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
For an object \tcode{p} of type \tcode{shared_ptr<T>},
\tcode{hash<shared_ptr<T>>()(p)} evaluates to
the same value as \tcode{hash<typename shared_ptr<T>::element_type*>()(p.get())}.
\end{itemdescr}%
\indextext{smart pointers|)}

\rSec1[mem.res]{Memory resources}

\rSec2[mem.res.syn]{Header \tcode{<memory_resource>} synopsis}

\indexheader{memory_resource}%
\begin{codeblock}
namespace std::pmr {
  // \ref{mem.res.class}, class \tcode{memory_resource}
  class memory_resource;

  bool operator==(const memory_resource& a, const memory_resource& b) noexcept;

  // \ref{mem.poly.allocator.class}, class template \tcode{polymorphic_allocator}
  template<class Tp = byte> class polymorphic_allocator;

  template<class T1, class T2>
    bool operator==(const polymorphic_allocator<T1>& a,
                    const polymorphic_allocator<T2>& b) noexcept;

  // \ref{mem.res.global}, global memory resources
  memory_resource* new_delete_resource() noexcept;
  memory_resource* null_memory_resource() noexcept;
  memory_resource* set_default_resource(memory_resource* r) noexcept;
  memory_resource* get_default_resource() noexcept;

  // \ref{mem.res.pool}, pool resource classes
  struct pool_options;
  class synchronized_pool_resource;
  class unsynchronized_pool_resource;
  class monotonic_buffer_resource;
}
\end{codeblock}

\rSec2[mem.res.class]{Class \tcode{memory_resource}}

\rSec3[mem.res.class.general]{General}

\pnum
The \tcode{memory_resource} class is an abstract interface to an unbounded set of classes encapsulating memory resources.

\indexlibraryglobal{memory_resource}%
\indexlibrarymember{operator=}{memory_resource}%
\begin{codeblock}
namespace std::pmr {
  class memory_resource {
    static constexpr size_t max_align = alignof(max_align_t);   // \expos

  public:
    memory_resource() = default;
    memory_resource(const memory_resource&) = default;
    virtual ~memory_resource();

    memory_resource& operator=(const memory_resource&) = default;

    [[nodiscard]] void* allocate(size_t bytes, size_t alignment = max_align);
    void deallocate(void* p, size_t bytes, size_t alignment = max_align);

    bool is_equal(const memory_resource& other) const noexcept;

  private:
    virtual void* do_allocate(size_t bytes, size_t alignment) = 0;
    virtual void do_deallocate(void* p, size_t bytes, size_t alignment) = 0;

    virtual bool do_is_equal(const memory_resource& other) const noexcept = 0;
  };
}
\end{codeblock}


\rSec3[mem.res.public]{Public member functions}

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

\begin{itemdescr}
\pnum
\effects
Destroys this \tcode{memory_resource}.
\end{itemdescr}

\indexlibrarymember{allocate}{memory_resource}%
\begin{itemdecl}
[[nodiscard]] void* allocate(size_t bytes, size_t alignment = max_align);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return do_allocate(bytes, alignment);}
\end{itemdescr}

\indexlibrarymember{deallocate}{memory_resource}%
\begin{itemdecl}
void deallocate(void* p, size_t bytes, size_t alignment = max_align);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{do_deallocate(p, bytes, alignment)}.
\end{itemdescr}

\indexlibrarymember{is_equal}{memory_resource}%
\begin{itemdecl}
bool is_equal(const memory_resource& other) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return do_is_equal(other);}
\end{itemdescr}


\rSec3[mem.res.private]{Private virtual member functions}

\indexlibrarymember{do_allocate}{memory_resource}%
\begin{itemdecl}
virtual void* do_allocate(size_t bytes, size_t alignment) = 0;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{alignment} is a power of two.

\pnum
\returns
A derived class shall implement this function to
return a pointer to allocated storage\iref{basic.stc.dynamic.allocation}
with a size of at least \tcode{bytes},
aligned to the specified \tcode{alignment}.

\pnum
\throws
A derived class implementation shall throw an appropriate exception if it is unable to allocate memory with the requested size and alignment.
\end{itemdescr}

\indexlibrarymember{do_deallocate}{memory_resource}%
\begin{itemdecl}
virtual void do_deallocate(void* p, size_t bytes, size_t alignment) = 0;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{p} was returned from a prior call to \tcode{allocate(bytes, alignment)}
on a memory resource equal to \tcode{*this},
and the storage at \tcode{p} has not yet been deallocated.

\pnum
\effects
A derived class shall implement this function to dispose of allocated storage.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibrarymember{do_is_equal}{memory_resource}%
\begin{itemdecl}
virtual bool do_is_equal(const memory_resource& other) const noexcept = 0;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A derived class shall implement this function to return \tcode{true} if memory allocated from \tcode{this} can be deallocated from \tcode{other} and vice-versa,
otherwise \tcode{false}.
\begin{note}
The most-derived type of \tcode{other} might not match the type of \tcode{this}.
For a derived class \tcode{D}, an implementation of this function
could immediately return \tcode{false}
if \tcode{dynamic_cast<const D*>(\&other) == nullptr}.
\end{note}
\end{itemdescr}

\rSec3[mem.res.eq]{Equality}

\indexlibrarymember{operator==}{memory_resource}%
\begin{itemdecl}
bool operator==(const memory_resource& a, const memory_resource& b) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{\&a == \&b || a.is_equal(b)}.
\end{itemdescr}

\rSec2[mem.poly.allocator.class]{Class template \tcode{polymorphic_allocator}}

\rSec3[mem.poly.allocator.class.general]{General}

\pnum
A specialization of class template \tcode{pmr::polymorphic_allocator}
meets the \oldconcept{Allocator} requirements (\tref{cpp17.allocator}).
Constructed with different memory resources,
different instances of the same specialization of \tcode{pmr::polymorphic_allocator}
can exhibit entirely different allocation behavior.
This runtime polymorphism allows objects that use \tcode{polymorphic_allocator}
to behave as if they used different allocator types at run time
even though they use the same static allocator type.

\pnum
All specializations of class template \tcode{pmr::polymorphic_allocator}
meet the allocator completeness requirements\iref{allocator.requirements.completeness}.

\indexlibraryglobal{polymorphic_allocator}%
\indexlibrarymember{value_type}{polymorphic_allocator}%
\begin{codeblock}
namespace std::pmr {
  template<class Tp = byte> class polymorphic_allocator {
    memory_resource* memory_rsrc;       // \expos

  public:
    using value_type = Tp;

    // \ref{mem.poly.allocator.ctor}, constructors
    polymorphic_allocator() noexcept;
    polymorphic_allocator(memory_resource* r);

    polymorphic_allocator(const polymorphic_allocator& other) = default;

    template<class U>
      polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;

    polymorphic_allocator& operator=(const polymorphic_allocator&) = delete;

    // \ref{mem.poly.allocator.mem}, member functions
    [[nodiscard]] Tp* allocate(size_t n);
    void deallocate(Tp* p, size_t n);

    [[nodiscard]] void* allocate_bytes(size_t nbytes, size_t alignment = alignof(max_align_t));
    void deallocate_bytes(void* p, size_t nbytes, size_t alignment = alignof(max_align_t));
    template<class T> [[nodiscard]] T* allocate_object(size_t n = 1);
    template<class T> void deallocate_object(T* p, size_t n = 1);
    template<class T, class... CtorArgs> [[nodiscard]] T* new_object(CtorArgs&&... ctor_args);
    template<class T> void delete_object(T* p);

    template<class T, class... Args>
      void construct(T* p, Args&&... args);

    template<class T>
      void destroy(T* p);

    polymorphic_allocator select_on_container_copy_construction() const;

    memory_resource* resource() const;
  };
}
\end{codeblock}

\rSec3[mem.poly.allocator.ctor]{Constructors}

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

\begin{itemdescr}
\pnum
\effects
Sets \tcode{memory_rsrc} to \tcode{get_default_resource()}.
\end{itemdescr}

\indexlibraryctor{polymorphic_allocator}%
\begin{itemdecl}
polymorphic_allocator(memory_resource* r);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{r} is non-null.

\pnum
\effects
Sets \tcode{memory_rsrc} to \tcode{r}.

\pnum
\throws
Nothing.

\pnum
\begin{note}
This constructor provides an implicit conversion from \tcode{memory_resource*}.
\end{note}
\end{itemdescr}

\indexlibraryctor{polymorphic_allocator}%
\begin{itemdecl}
template<class U> polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Sets \tcode{memory_rsrc} to \tcode{other.resource()}.
\end{itemdescr}


\rSec3[mem.poly.allocator.mem]{Member functions}

\indexlibrarymember{allocate}{polymorphic_allocator}%
\begin{itemdecl}
[[nodiscard]] Tp* allocate(size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{numeric_limits<size_t>::max() / sizeof(Tp) < n},
throws \tcode{bad_array_new_length}.
Otherwise equivalent to:
\begin{codeblock}
return static_cast<Tp*>(memory_rsrc->allocate(n * sizeof(Tp), alignof(Tp)));
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{deallocate}{polymorphic_allocator}%
\begin{itemdecl}
void deallocate(Tp* p, size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{p} was allocated from a memory resource \tcode{x},
equal to \tcode{*memory_rsrc},
using \tcode{x.allocate(n * sizeof(Tp), alignof(Tp))}.

\pnum
\effects
Equivalent to \tcode{memory_rsrc->deallocate(p, n * sizeof(Tp), alignof(Tp))}.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibrarymember{allocate_bytes}{polymorphic_allocator}%
\begin{itemdecl}
[[nodiscard]] void* allocate_bytes(size_t nbytes, size_t alignment = alignof(max_align_t));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return memory_rsrc->allocate(nbytes, alignment);}

\pnum
\begin{note}
The return type is \tcode{void*} (rather than, e.g., \tcode{byte*})
to support conversion to an arbitrary pointer type \tcode{U*}
by \tcode{static_cast<U*>}, thus facilitating construction of a \tcode{U}
object in the allocated memory.
\end{note}
\end{itemdescr}

\indexlibrarymember{deallocate_bytes}{polymorphic_allocator}%
\begin{itemdecl}
void deallocate_bytes(void* p, size_t nbytes, size_t alignment = alignof(max_align_t));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{memory_rsrc->deallocate(p, nbytes, alignment)}.
\end{itemdescr}

\indexlibrarymember{allocate_object}{polymorphic_allocator}%
\begin{itemdecl}
template<class T>
  [[nodiscard]] T* allocate_object(size_t n = 1);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Allocates memory suitable for holding
an array of \tcode{n} objects of type \tcode{T}, as follows:
\begin{itemize}
\item
  if \tcode{numeric_limits<size_t>::max() / sizeof(T) < n},
  throws \tcode{bad_array_new_length},
\item
  otherwise equivalent to:
\begin{codeblock}
return static_cast<T*>(allocate_bytes(n*sizeof(T), alignof(T)));
\end{codeblock}
\end{itemize}

\pnum
\begin{note}
\tcode{T} is not deduced and must therefore be provided as a template argument.
\end{note}
\end{itemdescr}

\indexlibrarymember{deallocate_object}{polymorphic_allocator}%
\begin{itemdecl}
template<class T>
  void deallocate_object(T* p, size_t n = 1);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{deallocate_bytes(p, n*sizeof(T), alignof(T))}.
\end{itemdescr}

\indexlibrarymember{new_object}{polymorphic_allocator}%
\begin{itemdecl}
template<class T, class... CtorArgs>
  [[nodiscard]] T* new_object(CtorArgs&&... ctor_args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Allocates and constructs an object of type \tcode{T}, as follows.\newline
Equivalent to:
\begin{codeblock}
T* p = allocate_object<T>();
try {
  construct(p, std::forward<CtorArgs>(ctor_args)...);
} catch (...) {
  deallocate_object(p);
  throw;
}
return p;
\end{codeblock}

\pnum
\begin{note}
\tcode{T} is not deduced and must therefore be provided as a template argument.
\end{note}
\end{itemdescr}

\indexlibrarymember{new_object}{polymorphic_allocator}%
\begin{itemdecl}
template<class T>
  void delete_object(T* p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
destroy(p);
deallocate_object(p);
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{construct}{polymorphic_allocator}%
\begin{itemdecl}
template<class T, class... Args>
  void construct(T* p, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
Uses-allocator construction of \tcode{T}
with allocator \tcode{*this} (see~\ref{allocator.uses.construction})
and constructor arguments \tcode{std::forward<Args>(args)...} is well-formed.

\pnum
\effects
Construct a \tcode{T} object in the storage
whose address is represented by \tcode{p}
by uses-allocator construction with allocator \tcode{*this}
and constructor arguments \tcode{std::forward<Args>(args)...}.

\pnum
\throws
Nothing unless the constructor for \tcode{T} throws.
\end{itemdescr}

\indexlibrarymember{destroy}{polymorphic_allocator}%
\begin{itemdecl}
template<class T>
  void destroy(T* p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by \tcode{p->\~T()}.
\end{itemdescr}

\indexlibrarymember{select_on_container_copy_construction}{polymorphic_allocator}%
\begin{itemdecl}
polymorphic_allocator select_on_container_copy_construction() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{polymorphic_allocator()}.

\pnum
\begin{note}
The memory resource is not propagated.
\end{note}
\end{itemdescr}

\indexlibrarymember{resource}{polymorphic_allocator}%
\begin{itemdecl}
memory_resource* resource() const;
\end{itemdecl}

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

\rSec3[mem.poly.allocator.eq]{Equality}

\indexlibrarymember{operator==}{polymorphic_allocator}%
\begin{itemdecl}
template<class T1, class T2>
  bool operator==(const polymorphic_allocator<T1>& a,
                  const polymorphic_allocator<T2>& b) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{*a.resource() == *b.resource()}.
\end{itemdescr}

\rSec2[mem.res.global]{Access to program-wide \tcode{memory_resource} objects}

\indexlibraryglobal{new_delete_resource}%
\begin{itemdecl}
memory_resource* new_delete_resource() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pointer to a static-duration object of a type derived from \tcode{memory_resource}
that can serve as a resource for allocating memory
using \tcode{::operator new} and \tcode{::operator delete}.
The same value is returned every time this function is called.
For a return value \tcode{p} and a memory resource \tcode{r},
\tcode{p->is_equal(r)} returns \tcode{\&r == p}.
\end{itemdescr}

\indexlibraryglobal{null_memory_resource}%
\begin{itemdecl}
memory_resource* null_memory_resource() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pointer to a static-duration object of a type derived from \tcode{memory_resource}
for which \tcode{allocate()} always throws \tcode{bad_alloc} and
for which \tcode{deallocate()} has no effect.
The same value is returned every time this function is called.
For a return value \tcode{p} and a memory resource \tcode{r},
\tcode{p->is_equal(r)} returns \tcode{\&r == p}.
\end{itemdescr}

\pnum
The \defn{default memory resource pointer} is a pointer to a memory resource
that is used by certain facilities when an explicit memory resource
is not supplied through the interface.
Its initial value is the return value of \tcode{new_delete_resource()}.

\indexlibraryglobal{set_default_resource}%
\begin{itemdecl}
memory_resource* set_default_resource(memory_resource* r) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{r} is non-null,
sets the value of the default memory resource pointer to \tcode{r},
otherwise sets the default memory resource pointer to \tcode{new_delete_resource()}.

\pnum
\returns
The previous value of the default memory resource pointer.

\pnum
\remarks
Calling the \tcode{set_default_resource} and
\tcode{get_default_resource} functions shall not incur a data race.
A call to the \tcode{set_default_resource} function
shall synchronize with subsequent calls to
the \tcode{set_default_resource} and \tcode{get_default_resource} functions.
\end{itemdescr}

\indexlibraryglobal{get_default_resource}%
\begin{itemdecl}
memory_resource* get_default_resource() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The current value of the default memory resource pointer.
\end{itemdescr}

\rSec2[mem.res.pool]{Pool resource classes}

\rSec3[mem.res.pool.overview]{Classes \tcode{synchronized_pool_resource} and \tcode{unsynchronized_pool_resource}}

\pnum
The \tcode{synchronized_pool_resource} and
\tcode{unsynchronized_pool_resource} classes
(collectively called \defn{pool resource classes})
are general-purpose memory resources having the following qualities:
\begin{itemize}
\item
Each resource frees its allocated memory on destruction,
even if \tcode{deallocate} has not been called for some of the allocated blocks.
\item
A pool resource consists of a collection of \defn{pools},
serving requests for different block sizes.
Each individual pool manages a collection of \defn{chunks}
that are in turn divided into blocks of uniform size,
returned via calls to \tcode{do_allocate}.
Each call to \tcode{do_allocate(size, alignment)} is dispatched
to the pool serving the smallest blocks accommodating at least \tcode{size} bytes.
\item
When a particular pool is exhausted,
allocating a block from that pool results in the allocation
of an additional chunk of memory from the \defn{upstream allocator}
(supplied at construction), thus replenishing the pool.
With each successive replenishment,
the chunk size obtained increases geometrically.
\begin{note}
By allocating memory in chunks,
the pooling strategy increases the chance that consecutive allocations
will be close together in memory.
\end{note}
\item
Allocation requests that exceed the largest block size of any pool
are fulfilled directly from the upstream allocator.
\item
A \tcode{pool_options} struct may be passed to the pool resource constructors
to tune the largest block size and the maximum chunk size.
\end{itemize}

\pnum
A \tcode{synchronized_pool_resource} may be accessed from multiple threads
without external synchronization
and may have thread-specific pools to reduce synchronization costs.
An \tcode{unsynchronized_pool_resource} class may not be accessed
from multiple threads simultaneously
and thus avoids the cost of synchronization entirely
in single-threaded applications.

\indexlibraryglobal{pool_options}%
\indexlibraryglobal{synchronized_pool_resource}%
\indexlibraryglobal{unsynchronized_pool_resource}%
\begin{codeblock}
namespace std::pmr {
  struct pool_options {
    size_t max_blocks_per_chunk = 0;
    size_t largest_required_pool_block = 0;
  };

  class synchronized_pool_resource : public memory_resource {
  public:
    synchronized_pool_resource(const pool_options& opts, memory_resource* upstream);

    synchronized_pool_resource()
        : synchronized_pool_resource(pool_options(), get_default_resource()) {}
    explicit synchronized_pool_resource(memory_resource* upstream)
        : synchronized_pool_resource(pool_options(), upstream) {}
    explicit synchronized_pool_resource(const pool_options& opts)
        : synchronized_pool_resource(opts, get_default_resource()) {}

    synchronized_pool_resource(const synchronized_pool_resource&) = delete;
    virtual ~synchronized_pool_resource();

    synchronized_pool_resource& operator=(const synchronized_pool_resource&) = delete;

    void release();
    memory_resource* upstream_resource() const;
    pool_options options() const;

  protected:
    void* do_allocate(size_t bytes, size_t alignment) override;
    void do_deallocate(void* p, size_t bytes, size_t alignment) override;

    bool do_is_equal(const memory_resource& other) const noexcept override;
  };

  class unsynchronized_pool_resource : public memory_resource {
  public:
    unsynchronized_pool_resource(const pool_options& opts, memory_resource* upstream);

    unsynchronized_pool_resource()
        : unsynchronized_pool_resource(pool_options(), get_default_resource()) {}
    explicit unsynchronized_pool_resource(memory_resource* upstream)
        : unsynchronized_pool_resource(pool_options(), upstream) {}
    explicit unsynchronized_pool_resource(const pool_options& opts)
        : unsynchronized_pool_resource(opts, get_default_resource()) {}

    unsynchronized_pool_resource(const unsynchronized_pool_resource&) = delete;
    virtual ~unsynchronized_pool_resource();

    unsynchronized_pool_resource& operator=(const unsynchronized_pool_resource&) = delete;

    void release();
    memory_resource* upstream_resource() const;
    pool_options options() const;

  protected:
    void* do_allocate(size_t bytes, size_t alignment) override;
    void do_deallocate(void* p, size_t bytes, size_t alignment) override;

    bool do_is_equal(const memory_resource& other) const noexcept override;
  };
}
\end{codeblock}

\rSec3[mem.res.pool.options]{\tcode{pool_options} data members}

\pnum
The members of \tcode{pool_options}
comprise a set of constructor options for pool resources.
The effect of each option on the pool resource behavior is described below:

\indexlibrarymember{pool_options}{max_blocks_per_chunk}%
\begin{itemdecl}
size_t max_blocks_per_chunk;
\end{itemdecl}

\begin{itemdescr}
\pnum
The maximum number of blocks that will be allocated at once
from the upstream memory resource\iref{mem.res.monotonic.buffer}
to replenish a pool.
If the value of \tcode{max_blocks_per_chunk} is zero or
is greater than an \impldef{largest supported value to configure the maximum number of blocks to replenish a pool}
limit, that limit is used instead.
The implementation
may choose to use a smaller value than is specified in this field and
may use different values for different pools.
\end{itemdescr}

\indexlibrarymember{pool_options}{largest_required_pool_block}%
\begin{itemdecl}
size_t largest_required_pool_block;
\end{itemdecl}

\begin{itemdescr}
\pnum
The largest allocation size that is required to be fulfilled
using the pooling mechanism.
Attempts to allocate a single block larger than this threshold
will be allocated directly from the upstream memory resource.
If \tcode{largest_required_pool_block} is zero or
is greater than an \impldef{largest supported value to configure the largest allocation satisfied directly by a pool}
limit, that limit is used instead.
The implementation may choose a pass-through threshold
larger than specified in this field.
\end{itemdescr}

\rSec3[mem.res.pool.ctor]{Constructors and destructors}

\indexlibraryctor{synchronized_pool_resource}%
\indexlibraryctor{unsynchronized_pool_resource}%
\begin{itemdecl}
synchronized_pool_resource(const pool_options& opts, memory_resource* upstream);
unsynchronized_pool_resource(const pool_options& opts, memory_resource* upstream);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{upstream} is the address of a valid memory resource.

\pnum
\effects
Constructs a pool resource object that will obtain memory from \tcode{upstream}
whenever the pool resource is unable to satisfy a memory request
from its own internal data structures.
The resulting object will hold a copy of \tcode{upstream},
but will not own the resource to which \tcode{upstream} points.
\begin{note}
The intention is that calls to \tcode{upstream->allocate()}
will be substantially fewer than calls to \tcode{this->allocate()}
in most cases.
\end{note}
The behavior of the pooling mechanism is tuned
according to the value of the \tcode{opts} argument.

\pnum
\throws
Nothing unless \tcode{upstream->allocate()} throws.
It is unspecified if, or under what conditions,
this constructor calls \tcode{upstream->allocate()}.
\end{itemdescr}

\indexlibrarydtor{synchronized_pool_resource}%
\indexlibrarydtor{unsynchronized_pool_resource}%
\begin{itemdecl}
virtual ~synchronized_pool_resource();
virtual ~unsynchronized_pool_resource();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls \tcode{release()}.
\end{itemdescr}

\rSec3[mem.res.pool.mem]{Members}

\indexlibrarymember{release}{synchronized_pool_resource}%
\indexlibrarymember{release}{unsynchronized_pool_resource}%
\begin{itemdecl}
void release();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls \tcode{upstream_resource()->deallocate()} as necessary
to release all allocated memory.
\begin{note}
The memory is released back to \tcode{upstream_resource()}
even if \tcode{deallocate} has not been called
for some of the allocated blocks.
\end{note}
\end{itemdescr}

\indexlibrarymember{upstream_resource}{synchronized_pool_resource}%
\indexlibrarymember{upstream_resource}{unsynchronized_pool_resource}%
\begin{itemdecl}
memory_resource* upstream_resource() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The value of the \tcode{upstream} argument
provided to the constructor of this object.
\end{itemdescr}

\indexlibrarymember{options}{synchronized_pool_resource}%
\indexlibrarymember{options}{unsynchronized_pool_resource}%
\begin{itemdecl}
pool_options options() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The options that control the pooling behavior of this resource.
The values in the returned struct may differ
from those supplied to the pool resource constructor in that
values of zero will be replaced with \impldef{default configuration of a pool}
defaults, and sizes may be rounded to unspecified granularity.
\end{itemdescr}

\indexlibrarymember{do_allocate}{synchronized_pool_resource}%
\indexlibrarymember{do_allocate}{unsynchronized_pool_resource}%
\begin{itemdecl}
void* do_allocate(size_t bytes, size_t alignment) override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pointer to allocated storage\iref{basic.stc.dynamic.allocation}
with a size of at least \tcode{bytes}.
The size and alignment of the allocated memory shall meet the requirements
for a class derived from \tcode{memory_resource}\iref{mem.res.class}.

\pnum
\effects
If the pool selected for a block of size \tcode{bytes}
is unable to satisfy the memory request from its own internal data structures,
it will call \tcode{upstream_resource()->allocate()} to obtain more memory.
If \tcode{bytes} is larger than that which the largest pool can handle,
then memory will be allocated using \tcode{upstream_resource()->allocate()}.

\pnum
\throws
Nothing unless \tcode{upstream_resource()->allocate()} throws.
\end{itemdescr}

\indexlibrarymember{do_deallocate}{synchronized_pool_resource}%
\indexlibrarymember{do_deallocate}{unsynchronized_pool_resource}%
\begin{itemdecl}
void do_deallocate(void* p, size_t bytes, size_t alignment) override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Returns the memory at \tcode{p} to the pool.
It is unspecified if, or under what circumstances,
this operation will result in a call to \tcode{upstream_resource()->deallocate()}.

\pnum
\throws
Nothing.
\end{itemdescr}

\indexlibrarymember{do_is_equal}{synchronized_pool_resource}%
\indexlibrarymember{do_is_equal}{unsynchronized_pool_resource}%
\begin{itemdecl}
bool do_is_equal(const memory_resource& other) const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{this == \&other}.
\end{itemdescr}

\rSec2[mem.res.monotonic.buffer]{Class \tcode{monotonic_buffer_resource}}

\rSec3[mem.res.monotonic.buffer.general]{General}

\pnum
A \tcode{monotonic_buffer_resource} is a special-purpose memory resource
intended for very fast memory allocations in situations
where memory is used to build up a few objects
and then is released all at once when the memory resource object is destroyed.
It has the following qualities:
\begin{itemize}
\item
A call to \tcode{deallocate} has no effect,
thus the amount of memory consumed increases monotonically
until the resource is destroyed.
\item
The program can supply an initial buffer,
which the allocator uses to satisfy memory requests.
\item
When the initial buffer (if any) is exhausted,
it obtains additional buffers from an \defn{upstream} memory resource
supplied at construction.
Each additional buffer is larger than the previous one,
following a geometric progression.
\item
It is intended for access from one thread of control at a time.
Specifically, calls to \tcode{allocate} and \tcode{deallocate}
do not synchronize with one another.
\item
It frees the allocated memory on destruction,
even if \tcode{deallocate} has not been called for some of the allocated blocks.
\end{itemize}

\indexlibraryglobal{monotonic_buffer_resource}%
\begin{codeblock}
namespace std::pmr {
  class monotonic_buffer_resource : public memory_resource {
    memory_resource* upstream_rsrc;     // \expos
    void* current_buffer;               // \expos
    size_t next_buffer_size;            // \expos

  public:
    explicit monotonic_buffer_resource(memory_resource* upstream);
    monotonic_buffer_resource(size_t initial_size, memory_resource* upstream);
    monotonic_buffer_resource(void* buffer, size_t buffer_size, memory_resource* upstream);

    monotonic_buffer_resource()
      : monotonic_buffer_resource(get_default_resource()) {}
    explicit monotonic_buffer_resource(size_t initial_size)
      : monotonic_buffer_resource(initial_size, get_default_resource()) {}
    monotonic_buffer_resource(void* buffer, size_t buffer_size)
      : monotonic_buffer_resource(buffer, buffer_size, get_default_resource()) {}

    monotonic_buffer_resource(const monotonic_buffer_resource&) = delete;

    virtual ~monotonic_buffer_resource();

    monotonic_buffer_resource& operator=(const monotonic_buffer_resource&) = delete;

    void release();
    memory_resource* upstream_resource() const;

  protected:
    void* do_allocate(size_t bytes, size_t alignment) override;
    void do_deallocate(void* p, size_t bytes, size_t alignment) override;

    bool do_is_equal(const memory_resource& other) const noexcept override;
  };
}
\end{codeblock}

\rSec3[mem.res.monotonic.buffer.ctor]{Constructors and destructor}

\indexlibraryctor{monotonic_buffer_resource}%
\begin{itemdecl}
explicit monotonic_buffer_resource(memory_resource* upstream);
monotonic_buffer_resource(size_t initial_size, memory_resource* upstream);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{upstream} is the address of a valid memory resource.
\tcode{initial_size}, if specified, is greater than zero.

\pnum
\effects
Sets \tcode{upstream_rsrc} to \tcode{upstream} and
\tcode{current_buffer} to \tcode{nullptr}.
If \tcode{initial_size} is specified,
sets \tcode{next_buffer_size} to at least \tcode{initial_size};
otherwise sets \tcode{next_buffer_size} to an
\impldef{default \tcode{next_buffer_size} for a \tcode{monotonic_buffer_resource}} size.
\end{itemdescr}

\indexlibraryctor{monotonic_buffer_resource}%
\begin{itemdecl}
monotonic_buffer_resource(void* buffer, size_t buffer_size, memory_resource* upstream);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{upstream} is the address of a valid memory resource.
\tcode{buffer_size} is no larger than the number of bytes in \tcode{buffer}.

\pnum
\effects
Sets \tcode{upstream_rsrc} to \tcode{upstream},
\tcode{current_buffer} to \tcode{buffer}, and
\tcode{next_buffer_size} to \tcode{buffer_size} (but not less than 1),
then increases \tcode{next_buffer_size}
by an \impldef{growth factor for \tcode{monotonic_buffer_resource}} growth factor (which need not be integral).
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\effects
Calls \tcode{release()}.
\end{itemdescr}


\rSec3[mem.res.monotonic.buffer.mem]{Members}

\indexlibrarymember{release}{monotonic_buffer_resource}%
\begin{itemdecl}
void release();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls \tcode{upstream_rsrc->deallocate()} as necessary
to release all allocated memory.

\pnum
\begin{note}
The memory is released back to \tcode{upstream_rsrc}
even if some blocks that were allocated from \tcode{this}
have not been deallocated from \tcode{this}.
\end{note}
\end{itemdescr}

\indexlibrarymember{upstream_resource}{monotonic_buffer_resource}%
\begin{itemdecl}
memory_resource* upstream_resource() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The value of \tcode{upstream_rsrc}.
\end{itemdescr}

\indexlibrarymember{do_allocate}{monotonic_buffer_resource}%
\begin{itemdecl}
void* do_allocate(size_t bytes, size_t alignment) override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pointer to allocated storage\iref{basic.stc.dynamic.allocation}
with a size of at least \tcode{bytes}.
The size and alignment of the allocated memory shall meet the requirements
for a class derived from \tcode{memory_resource}\iref{mem.res.class}.

\pnum
\effects
If the unused space in \tcode{current_buffer}
can fit a block with the specified \tcode{bytes} and \tcode{alignment},
then allocate the return block from \tcode{current_buffer};
otherwise set \tcode{current_buffer} to \tcode{upstream_rsrc->allocate(n, m)},
where \tcode{n} is not less than \tcode{max(bytes, next_buffer_size)} and
\tcode{m} is not less than \tcode{alignment},
and increase \tcode{next_buffer_size}
by an \impldef{growth factor for \tcode{monotonic_buffer_resource}} growth factor (which need not be integral),
then allocate the return block from the newly-allocated \tcode{current_buffer}.

\pnum
\throws
Nothing unless \tcode{upstream_rsrc->allocate()} throws.
\end{itemdescr}

\indexlibrarymember{do_deallocate}{monotonic_buffer_resource}%
\begin{itemdecl}
void do_deallocate(void* p, size_t bytes, size_t alignment) override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
None.

\pnum
\throws
Nothing.

\pnum
\remarks
Memory used by this resource increases monotonically until its destruction.
\end{itemdescr}

\indexlibrarymember{do_is_equal}{monotonic_buffer_resource}%
\begin{itemdecl}
bool do_is_equal(const memory_resource& other) const noexcept override;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{this == \&other}.
\end{itemdescr}


\rSec1[allocator.adaptor]{Class template \tcode{scoped_allocator_adaptor}}

\rSec2[allocator.adaptor.syn]{Header \tcode{<scoped_allocator>} synopsis}

\indexheader{scoped_allocator}%
\begin{codeblock}
namespace std {
  // class template \tcode{scoped allocator adaptor}
  template<class OuterAlloc, class... InnerAlloc>
    class scoped_allocator_adaptor;

  // \ref{scoped.adaptor.operators}, scoped allocator operators
  template<class OuterA1, class OuterA2, class... InnerAllocs>
    bool operator==(const scoped_allocator_adaptor<OuterA1, InnerAllocs...>& a,
                    const scoped_allocator_adaptor<OuterA2, InnerAllocs...>& b) noexcept;
}
\end{codeblock}

\pnum
The class template \tcode{scoped_allocator_adaptor} is an allocator template that
specifies an allocator resource (the outer allocator) to be used by a container (as any
other allocator does) and also specifies an inner allocator resource to be passed to the
constructor of every element within the container. This adaptor is instantiated with one
outer and zero or more inner allocator types. If instantiated with only one allocator
type, the inner allocator becomes the \tcode{scoped_allocator_adaptor} itself, thus
using the same allocator resource for the container and every element within the
container and, if the elements themselves are containers, each of their elements
recursively. If instantiated with more than one allocator, the first allocator is the
outer allocator for use by the container, the second allocator is passed to the
constructors of the container's elements, and, if the elements themselves are
containers, the third allocator is passed to the elements' elements, and so on. If
containers are nested to a depth greater than the number of allocators, the last
allocator is used repeatedly, as in the single-allocator case, for any remaining
recursions.
\begin{note}
The \tcode{scoped_allocator_adaptor} is derived from the outer
allocator type so it can be substituted for the outer allocator type in most
expressions.
\end{note}

\indexlibraryglobal{scoped_allocator_adaptor}%
\indexlibrarymember{outer_allocator_type}{scoped_allocator_adaptor}%
\indexlibrarymember{value_type}{scoped_allocator_adaptor}%
\indexlibrarymember{size_type}{scoped_allocator_adaptor}%
\indexlibrarymember{difference_type}{scoped_allocator_adaptor}%
\indexlibrarymember{pointer}{scoped_allocator_adaptor}%
\indexlibrarymember{const_pointer}{scoped_allocator_adaptor}%
\indexlibrarymember{void_pointer}{scoped_allocator_adaptor}%
\indexlibrarymember{const_void_pointer}{scoped_allocator_adaptor}%
\begin{codeblock}
namespace std {
  template<class OuterAlloc, class... InnerAllocs>
  class scoped_allocator_adaptor : public OuterAlloc {
  private:
    using OuterTraits = allocator_traits<OuterAlloc>;   // \expos
    scoped_allocator_adaptor<InnerAllocs...> inner;     // \expos

  public:
    using outer_allocator_type = OuterAlloc;
    using inner_allocator_type = @\seebelow@;

    using value_type           = typename OuterTraits::value_type;
    using size_type            = typename OuterTraits::size_type;
    using difference_type      = typename OuterTraits::difference_type;
    using pointer              = typename OuterTraits::pointer;
    using const_pointer        = typename OuterTraits::const_pointer;
    using void_pointer         = typename OuterTraits::void_pointer;
    using const_void_pointer   = typename OuterTraits::const_void_pointer;

    using propagate_on_container_copy_assignment = @\seebelow@;
    using propagate_on_container_move_assignment = @\seebelow@;
    using propagate_on_container_swap            = @\seebelow@;
    using is_always_equal                        = @\seebelow@;

    template<class Tp> struct rebind {
      using other = scoped_allocator_adaptor<
        OuterTraits::template rebind_alloc<Tp>, InnerAllocs...>;
    };

    scoped_allocator_adaptor();
    template<class OuterA2>
      scoped_allocator_adaptor(OuterA2&& outerAlloc,
                               const InnerAllocs&... innerAllocs) noexcept;

    scoped_allocator_adaptor(const scoped_allocator_adaptor& other) noexcept;
    scoped_allocator_adaptor(scoped_allocator_adaptor&& other) noexcept;

    template<class OuterA2>
      scoped_allocator_adaptor(
        const scoped_allocator_adaptor<OuterA2, InnerAllocs...>& other) noexcept;
    template<class OuterA2>
      scoped_allocator_adaptor(
        scoped_allocator_adaptor<OuterA2, InnerAllocs...>&& other) noexcept;

    scoped_allocator_adaptor& operator=(const scoped_allocator_adaptor&) = default;
    scoped_allocator_adaptor& operator=(scoped_allocator_adaptor&&) = default;

    ~scoped_allocator_adaptor();

    inner_allocator_type& inner_allocator() noexcept;
    const inner_allocator_type& inner_allocator() const noexcept;
    outer_allocator_type& outer_allocator() noexcept;
    const outer_allocator_type& outer_allocator() const noexcept;

    [[nodiscard]] pointer allocate(size_type n);
    [[nodiscard]] pointer allocate(size_type n, const_void_pointer hint);
    void deallocate(pointer p, size_type n);
    size_type max_size() const;

    template<class T, class... Args>
      void construct(T* p, Args&&... args);

    template<class T>
      void destroy(T* p);

    scoped_allocator_adaptor select_on_container_copy_construction() const;
  };

  template<class OuterAlloc, class... InnerAllocs>
    scoped_allocator_adaptor(OuterAlloc, InnerAllocs...)
      -> scoped_allocator_adaptor<OuterAlloc, InnerAllocs...>;
}
\end{codeblock}

\rSec2[allocator.adaptor.types]{Member types}

\indexlibrarymember{inner_allocator_type}{scoped_allocator_adaptor}%
\begin{itemdecl}
using inner_allocator_type = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{scoped_allocator_adaptor<OuterAlloc>} if \tcode{sizeof...(InnerAllocs)} is
zero; otherwise,\\ \tcode{scoped_allocator_adaptor<InnerAllocs...>}.
\end{itemdescr}

\indexlibrarymember{propagate_on_container_copy_assignment}{scoped_allocator_adaptor}%
\begin{itemdecl}
using propagate_on_container_copy_assignment = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{true_type} if
\tcode{allocator_traits<A>::propagate_on_container_copy_assignment::value} is
\tcode{true} for any \tcode{A} in the set of \tcode{OuterAlloc} and
\tcode{InnerAllocs...}; otherwise, \tcode{false_type}.
\end{itemdescr}

\indexlibrarymember{propagate_on_container_move_assignment}{scoped_allocator_adaptor}%
\begin{itemdecl}
using propagate_on_container_move_assignment = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{true_type} if
\tcode{allocator_traits<A>::propagate_on_container_move_assignment::value} is
\tcode{true} for any \tcode{A} in the set of \tcode{OuterAlloc} and
\tcode{InnerAllocs...}; otherwise, \tcode{false_type}.
\end{itemdescr}

\indexlibrarymember{propagate_on_container_swap}{scoped_allocator_adaptor}%
\begin{itemdecl}
using propagate_on_container_swap = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{true_type} if
\tcode{allocator_traits<A>::propagate_on_container_swap::value} is
\tcode{true} for any \tcode{A} in the set of \tcode{OuterAlloc} and
\tcode{InnerAllocs...}; otherwise, \tcode{false_type}.
\end{itemdescr}

\indexlibrarymember{is_always_equal}{scoped_allocator_adaptor}%
\begin{itemdecl}
using is_always_equal = @\seebelow@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ctype \tcode{true_type} if
\tcode{allocator_traits<A>::is_always_equal::value} is
\tcode{true} for every \tcode{A} in the set of \tcode{OuterAlloc} and
\tcode{InnerAllocs...}; otherwise, \tcode{false_type}.
\end{itemdescr}

\rSec2[allocator.adaptor.cnstr]{Constructors}

\indexlibraryctor{scoped_allocator_adaptor}%
\begin{itemdecl}
scoped_allocator_adaptor();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Value-initializes the \tcode{OuterAlloc} base class and the \tcode{inner} allocator
object.
\end{itemdescr}

\indexlibraryctor{scoped_allocator_adaptor}%
\begin{itemdecl}
template<class OuterA2>
  scoped_allocator_adaptor(OuterA2&& outerAlloc, const InnerAllocs&... innerAllocs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<OuterAlloc, OuterA2>} is \tcode{true}.

\pnum
\effects
Initializes the \tcode{OuterAlloc} base class with
\tcode{std::forward<OuterA2>(outerAlloc)} and \tcode{inner} with \tcode{innerAllocs...}
(hence recursively initializing each allocator within the adaptor with the corresponding
allocator from the argument list).
\end{itemdescr}

\indexlibraryctor{scoped_allocator_adaptor}%
\begin{itemdecl}
scoped_allocator_adaptor(const scoped_allocator_adaptor& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes each allocator within the adaptor with the corresponding allocator
from \tcode{other}.
\end{itemdescr}

\indexlibraryctor{scoped_allocator_adaptor}%
\begin{itemdecl}
scoped_allocator_adaptor(scoped_allocator_adaptor&& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Move constructs each allocator within the adaptor with the corresponding allocator
from \tcode{other}.
\end{itemdescr}

\indexlibraryctor{scoped_allocator_adaptor}%
\begin{itemdecl}
template<class OuterA2>
  scoped_allocator_adaptor(
    const scoped_allocator_adaptor<OuterA2, InnerAllocs...>& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<OuterAlloc, const OuterA2\&>} is \tcode{true}.

\pnum
\effects
Initializes each allocator within the adaptor with the corresponding allocator
from \tcode{other}.
\end{itemdescr}

\indexlibraryctor{scoped_allocator_adaptor}%
\begin{itemdecl}
template<class OuterA2>
  scoped_allocator_adaptor(scoped_allocator_adaptor<OuterA2, InnerAllocs...>&& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{is_constructible_v<OuterAlloc, OuterA2>} is \tcode{true}.

\pnum
\effects
Initializes each allocator within the adaptor with the corresponding allocator rvalue
from \tcode{other}.
\end{itemdescr}

\rSec2[allocator.adaptor.members]{Members}

\pnum
In the \tcode{construct} member functions,
\tcode{\placeholdernc{OUTERMOST}(x)} is
\tcode{\placeholdernc{OUTERMOST}(x.outer_allocator())} if
the expression \tcode{x.outer_allocator()} is
valid~\iref{temp.deduct} and
\tcode{x} otherwise;
\tcode{\placeholdernc{OUTERMOST_ALLOC_TRAITS}(x)} is
\tcode{allocator_traits<remove_reference_t<decltype(\placeholdernc{OUTERMOST}(x))>>}.
\begin{note}
\tcode{\placeholdernc{OUTERMOST}(x)} and
\tcode{\placeholdernc{OUTERMOST_ALL\-OC_TRAITS}(x)} are recursive operations. It
is incumbent upon the definition of \tcode{outer_allocator()} to ensure that the
recursion terminates. It will terminate for all instantiations of
\tcode{scoped_allocator_adaptor}.
\end{note}

\indexlibrarymember{inner_allocator}{scoped_allocator_adaptor}%
\begin{itemdecl}
inner_allocator_type& inner_allocator() noexcept;
const inner_allocator_type& inner_allocator() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{*this} if \tcode{sizeof...(InnerAllocs)} is zero; otherwise,
\tcode{inner}.
\end{itemdescr}

\indexlibrarymember{outer_allocator}{scoped_allocator_adaptor}%
\begin{itemdecl}
outer_allocator_type& outer_allocator() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{static_cast<OuterAlloc\&>(*this)}.
\end{itemdescr}

\indexlibrarymember{outer_allocator}{scoped_allocator_adaptor}%
\begin{itemdecl}
const outer_allocator_type& outer_allocator() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{static_cast<const OuterAlloc\&>(*this)}.
\end{itemdescr}

\indexlibrarymember{allocate}{scoped_allocator_adaptor}%
\begin{itemdecl}
[[nodiscard]] pointer allocate(size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{allocator_traits<OuterAlloc>::allocate(outer_allocator(), n)}.
\end{itemdescr}

\indexlibrarymember{allocate}{scoped_allocator_adaptor}%
\begin{itemdecl}
[[nodiscard]] pointer allocate(size_type n, const_void_pointer hint);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{allocator_traits<OuterAlloc>::allocate(outer_allocator(), n, hint)}.
\end{itemdescr}

\indexlibrarymember{deallocate}{scoped_allocator_adaptor}%
\begin{itemdecl}
void deallocate(pointer p, size_type n) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
As if by:
\tcode{allocator_traits<OuterAlloc>::deallocate(outer_allocator(), p, n);}
\end{itemdescr}

\indexlibrarymember{max_size}{scoped_allocator_adaptor}%
\begin{itemdecl}
size_type max_size() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{allocator_traits<OuterAlloc>::max_size(outer_allocator())}.
\end{itemdescr}

\indexlibrarymember{construct}{scoped_allocator_adaptor}%
\begin{itemdecl}
template<class T, class... Args>
  void construct(T* p, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
apply([p, this](auto&&... newargs) {
        @\placeholdernc{OUTERMOST_ALLOC_TRAITS}@(*this)::construct(
          @\placeholdernc{OUTERMOST}@(*this), p,
          std::forward<decltype(newargs)>(newargs)...);
      },
      uses_allocator_construction_args<T>(inner_allocator(),
                                          std::forward<Args>(args)...));
\end{codeblock}
\end{itemdescr}

\indexlibrarymember{destroy}{scoped_allocator_adaptor}%
\begin{itemdecl}
template<class T>
  void destroy(T* p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls \tcode{\placeholdernc{OUTERMOST_ALLOC_TRAITS}(*this)::destroy(\placeholdernc{OUTERMOST}(*this), p)}.
\end{itemdescr}

\indexlibrarymember{select_on_container_copy_construction}{scoped_allocator_adaptor}%
\begin{itemdecl}
scoped_allocator_adaptor select_on_container_copy_construction() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A new \tcode{scoped_allocator_adaptor} object where each allocator \tcode{A} in the
adaptor is initialized from the result of calling
\tcode{allocator_traits<A>::select_on_container_copy_construction()} on the
corresponding allocator in \tcode{*this}.
\end{itemdescr}

\rSec2[scoped.adaptor.operators]{Operators}

\indexlibrarymember{operator==}{scoped_allocator_adaptor}%
\begin{itemdecl}
template<class OuterA1, class OuterA2, class... InnerAllocs>
  bool operator==(const scoped_allocator_adaptor<OuterA1, InnerAllocs...>& a,
                  const scoped_allocator_adaptor<OuterA2, InnerAllocs...>& b) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If \tcode{sizeof...(InnerAllocs)} is zero,
\begin{codeblock}
a.outer_allocator() == b.outer_allocator()
\end{codeblock}
otherwise
\begin{codeblock}
a.outer_allocator() == b.outer_allocator() && a.inner_allocator() == b.inner_allocator()
\end{codeblock}
\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{basic.types} that can be the type of the
\grammarterm{postfix-expression} in a function call
(\ref{expr.call}, \ref{over.match.call}).\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.} 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)
      noexcept(is_nothrow_invocable_v<F, Args...>);

  // \ref{refwrap}, \tcode{reference_wrapper}
  template<class T> class reference_wrapper;

  template<class T> constexpr reference_wrapper<T> ref(T&) noexcept;
  template<class T> constexpr reference_wrapper<const T> cref(const T&) noexcept;
  template<class T> void ref(const T&&) = delete;
  template<class T> void cref(const T&&) = delete;

  template<class T> constexpr reference_wrapper<T> ref(reference_wrapper<T>) noexcept;
  template<class T> constexpr reference_wrapper<const T> cref(reference_wrapper<T>) noexcept;

  // \ref{arithmetic.operations}, arithmetic operations
  template<class T = void> struct plus;
  template<class T = void> struct minus;
  template<class T = void> struct multiplies;
  template<class T = void> struct divides;
  template<class T = void> struct modulus;
  template<class T = void> struct negate;
  template<> struct plus<void>;
  template<> struct minus<void>;
  template<> struct multiplies<void>;
  template<> struct divides<void>;
  template<> struct modulus<void>;
  template<> struct negate<void>;

  // \ref{comparisons}, comparisons
  template<class T = void> struct equal_to;
  template<class T = void> struct not_equal_to;
  template<class T = void> struct greater;
  template<class T = void> struct less;
  template<class T = void> struct greater_equal;
  template<class T = void> struct less_equal;
  template<> struct equal_to<void>;
  template<> struct not_equal_to<void>;
  template<> struct greater<void>;
  template<> struct less<void>;
  template<> struct greater_equal<void>;
  template<> struct less_equal<void>;

  // \ref{comparisons.three.way}, class \tcode{compare_three_way}
  struct compare_three_way;

  // \ref{logical.operations}, logical operations
  template<class T = void> struct logical_and;
  template<class T = void> struct logical_or;
  template<class T = void> struct logical_not;
  template<> struct logical_and<void>;
  template<> struct logical_or<void>;
  template<> struct logical_not<void>;

  // \ref{bitwise.operations}, bitwise operations
  template<class T = void> struct bit_and;
  template<class T = void> struct bit_or;
  template<class T = void> struct bit_xor;
  template<class T = void> struct bit_not;
  template<> struct bit_and<void>;
  template<> struct bit_or<void>;
  template<> struct bit_xor<void>;
  template<> struct bit_not<void>;

  // \ref{func.identity}, identity
  struct identity;

  // \ref{func.not.fn}, function template \tcode{not_fn}
  template<class F> constexpr @\unspec@ not_fn(F&& f);

  // \ref{func.bind.front}, function template \tcode{bind_front}
  template<class F, class... Args> constexpr @\unspec@ bind_front(F&&, Args&&...);

  // \ref{func.bind}, bind
  template<class T> struct is_bind_expression;
  template<class T>
    inline constexpr bool @\libglobal{is_bind_expression_v}@ = is_bind_expression<T>::value;
  template<class T> struct is_placeholder;
  template<class T>
    inline constexpr int @\libglobal{is_placeholder_v}@ = is_placeholder<T>::value;

  template<class F, class... BoundArgs>
    constexpr @\unspec@ bind(F&&, BoundArgs&&...);
  template<class R, class F, class... BoundArgs>
    constexpr @\unspec@ bind(F&&, BoundArgs&&...);

  namespace placeholders {
    // \tcode{\placeholder{M}} is the \impldef{number of placeholders for bind expressions} number of placeholders
    @\seebelownc@ _1;
    @\seebelownc@ _2;
               .
               .
               .
    @\seebelownc@ _@\placeholdernc{M}@;
  }

  // \ref{func.memfn}, member function adaptors
  template<class R, class T>
    constexpr @\unspec@ mem_fn(R T::*) noexcept;

  // \ref{func.wrap}, polymorphic function wrappers
  class bad_function_call;

  template<class> class function;       // \notdef
  template<class R, class... ArgTypes> class function<R(ArgTypes...)>;

  template<class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;

  template<class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;

  // \ref{func.search}, searchers
  template<class ForwardIterator, class BinaryPredicate = equal_to<>>
    class default_searcher;

  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 hash
  template<class T>
    struct hash;

  namespace ranges {
    // \ref{range.cmp}, concept-constrained comparisons
    struct equal_to;
    struct not_equal_to;
    struct greater;
    struct less;
    struct greater_equal;
    struct less_equal;
  }
}
\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
\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_base_of_v<T, remove_reference_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 \tcode{N == 1} and \tcode{f} is a pointer to
data member of a class \tcode{T}
and \tcode{is_base_of_v<T, remove_reference_t<decltype(t$_1$)>>} is \tcode{true};

\item \tcode{t$_1$.get().*f} when \tcode{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 \tcode{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{}~\tcode{void}, otherwise
\tcode{\placeholdernc{INVOKE}(f, t$_1$, t$_2$, $\dotsc$, t$_N$)} implicitly converted
to \tcode{R}.

\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 wrapped callable 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
\indextext{call wrapper!perfect forwarding}%
A \defn{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
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 \tcode{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]{Function template \tcode{invoke}}
\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
\returns
\tcode{\placeholdernc{INVOKE}(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;

    // construct/copy/destroy
    template<class U>
      constexpr reference_wrapper(U&&) noexcept(@\seebelow@);
    constexpr reference_wrapper(const reference_wrapper& x) noexcept;

    // assignment
    constexpr reference_wrapper& operator=(const reference_wrapper& x) noexcept;

    // access
    constexpr operator T& () const noexcept;
    constexpr T& get() const noexcept;

    // invocation
    template<class... ArgTypes>
      constexpr invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&...) const;
  };

  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{basic.types}.

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

\rSec3[refwrap.const]{Constructors and destructor}

\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 expression inside \tcode{noexcept}
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;
\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{ref(t.get())}.
\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{cref(t.get())}.
\end{itemdescr}

\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~(\ref{expr.mul}, \ref{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~(\ref{expr.rel}, \ref{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}}

\pnum
In this subclause, \tcode{\placeholdernc{BUILTIN-PTR-THREE-WAY}(T, U)}
for types \tcode{T} and \tcode{U} is a boolean constant expression.
\tcode{\placeholdernc{BUILTIN-PTR-THREE-WAY}(T, U)} is \tcode{true}
if and only if \tcode{<=>} in the expression
\begin{codeblock}
declval<T>() <=> declval<U>()
\end{codeblock}
resolves to a built-in operator comparing pointers.

\indexlibraryglobal{compare_three_way}%
\begin{codeblock}
struct compare_three_way {
  template<class T, class U>
    requires three_way_comparable_with<T, U> || @\placeholdernc{BUILTIN-PTR-THREE-WAY}@(T, U)
  constexpr auto operator()(T&& t, U&& u) const;

  using is_transparent = @\unspec@;
};
\end{codeblock}

\begin{itemdecl}
template<class T, class U>
  requires three_way_comparable_with<T, U> || @\placeholdernc{BUILTIN-PTR-THREE-WAY}@(T, U)
constexpr auto operator()(T&& t, U&& u) const;
\end{itemdecl}

\begin{itemdescr}
\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}.

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

\pnum
In this subclause, \tcode{\placeholdernc{BUILTIN-PTR-CMP}(T, $op$, U)} for types \tcode{T}
and \tcode{U} and where $op$ is an equality\iref{expr.eq} or relational
operator\iref{expr.rel} is a boolean constant expression.
\tcode{\placeholdernc{BUILTIN-PTR-CMP}(T, $op$, U)} is \tcode{true} if and only if $op$
in the expression \tcode{declval<T>() $op$ declval<U>()} resolves to a built-in
operator comparing pointers.

\indexlibraryglobal{equal_to}%
\begin{itemdecl}
struct ranges::equal_to {
  template<class T, class U>
    requires equality_comparable_with<T, U> || @\placeholdernc{BUILTIN-PTR-CMP}@(T, ==, U)
  constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{itemdecl}

\begin{itemdescr}
\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}.

\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{itemdecl}
struct ranges::not_equal_to {
  template<class T, class U>
    requires equality_comparable_with<T, U> || @\placeholdernc{BUILTIN-PTR-CMP}@(T, ==, U)
  constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{itemdecl}

\begin{itemdescr}
\pnum
\tcode{operator()} has effects equivalent to:
\begin{codeblock}
return !ranges::equal_to{}(std::forward<T>(t), std::forward<U>(u));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{greater}%
\begin{itemdecl}
struct ranges::greater {
  template<class T, class U>
    requires @\libconcept{totally_ordered_with}@<T, U> || @\placeholdernc{BUILTIN-PTR-CMP}@(U, <, T)
  constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{itemdecl}

\begin{itemdescr}
\pnum
\tcode{operator()} has effects equivalent to:
\begin{codeblock}
return ranges::less{}(std::forward<U>(u), std::forward<T>(t));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{less}%
\begin{itemdecl}
struct ranges::less {
  template<class T, class U>
    requires @\libconcept{totally_ordered_with}@<T, U> || @\placeholdernc{BUILTIN-PTR-CMP}@(T, <, U)
  constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{itemdecl}

\begin{itemdescr}
\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}. 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{itemdecl}
struct ranges::greater_equal {
  template<class T, class U>
    requires @\libconcept{totally_ordered_with}@<T, U> || @\placeholdernc{BUILTIN-PTR-CMP}@(T, <, U)
  constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{itemdecl}

\begin{itemdescr}
\pnum
\tcode{operator()} has 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>
    requires @\libconcept{totally_ordered_with}@<T, U> || @\placeholdernc{BUILTIN-PTR-CMP}@(U, <, T)
  constexpr bool operator()(T&& t, U&& u) const;

  using is_transparent = @\unspecnc@;
};
\end{itemdecl}

\begin{itemdescr}
\pnum
\tcode{operator()} has 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~(\ref{expr.log.and}, \ref{expr.log.or}, \ref{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~(\ref{expr.bit.and}, \ref{expr.or},
\ref{expr.xor}, \ref{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&&) 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 \tcode{g}
with call pattern \tcode{!invoke(fd, call_args...)}.

\pnum
\throws
Any exception thrown by the initialization of \tcode{fd}.
\end{itemdescr}

\rSec2[func.bind.front]{Function template \tcode{bind_front}}

\indexlibraryglobal{bind_front}%
\begin{itemdecl}
template<class F, class... Args>
  constexpr @\unspec@ bind_front(F&& f, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
In the text that follows:
\begin{itemize}
\item \tcode{g} is a value of the result of a \tcode{bind_front} 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 \tcode{g}
with call pattern \tcode{invoke(fd, bound_args..., call_args...)}.

\pnum
\throws
Any exception thrown by
the initialization of the state entities of \tcode{g}\iref{func.def}.
\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
The class template \tcode{is_placeholder} can be used to detect the standard placeholders
\tcode{_1}, \tcode{_2}, and so on. 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}}%
\begin{codeblock}
namespace std::placeholders {
  // M is the \impldef{number of placeholders for bind expressions} number of placeholders
  @\seebelow@ _1;
  @\seebelow@ _2;
              .
              .
              .
  @\seebelow@ _M;
}
\end{codeblock}

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

\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{func.def} \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{pm}.
\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 a polymorphic wrapper class that
encapsulates arbitrary callable objects.

\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> class function;       // \notdef

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

  // \ref{func.wrap.func.nullptr}, null pointer comparison operator functions
  template<class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;

  // \ref{func.wrap.func.alg}, specialized algorithms
  template<class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
}
\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}, allowing functions to be first-class objects.

\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{expr.prop}, 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,
\tcode{*this} targets 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
\constraints
\tcode{F} is Lvalue-Callable\iref{func.wrap.func} for argument types
\tcode{ArgTypes...} and return type \tcode{R}.

\pnum
\expects
\tcode{F} meets the \oldconcept{CopyConstructible} requirements.

\pnum
\ensures
\tcode{!*this} 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{F} is an instance of the \tcode{function} class template, and
  \tcode{!f}.
\end{itemize}

\pnum
Otherwise, \tcode{*this} targets a copy of \tcode{f}
initialized with \tcode{std::move(f)}.

\pnum
\throws
Nothing if \tcode{f} is
a specialization of \tcode{reference_wrapper} or
a function pointer. Otherwise, may throw \tcode{bad_alloc}
or any exception thrown by \tcode{F}'s copy or move constructor.

\pnum
\recommended
Implementations should avoid the use of
dynamically allocated memory for small callable objects, for example,
where \tcode{f} is 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
\tcode{decltype(\brk{}\&F::operator())} is of the form
\tcode{R(G::*)(A...)}~\cv{}~\tcode{\opt{\&}~\opt{noexcept}}
for a class type \tcode{G}.

\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 \tcode{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 \tcode{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 targets 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 wrapped callable 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}%
\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}
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(ForwardIterator pat_first, ForwardIterator 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}
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} requirements,
the \oldconcept{CopyConstructible} requirements, and
the \oldconcept{CopyAssignable} requirements.

\pnum
\expects
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
\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}
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
\expects
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
\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 \tcode{i} 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 \tcode{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}),
\item be swappable\iref{swappable.requirements} for lvalues,
\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 that depends on at least one program-defined type.
\end{itemize}

\rSec1[meta]{Metaprogramming and type traits}

\rSec2[meta.general]{General}

\pnum
Subclause \ref{meta} describes components used by \Cpp{} programs, particularly in
templates, to support the widest possible range of types, optimise
template code usage, detect type related user errors, and perform
type inference and transformation at compile time. It includes type
classification traits, type property inspection traits, and type
transformations. The type classification traits describe a complete taxonomy
of all possible \Cpp{} types, and state where in that taxonomy a given
type belongs. The type property inspection traits allow important
characteristics of types or of combinations of types to be inspected. The
type transformations allow certain properties of types to be manipulated.

\pnum
\indextext{signal-safe!type traits}%
All functions specified in \ref{meta} are signal-safe\iref{support.signal}.

\rSec2[meta.rqmts]{Requirements}

\pnum
A \defnoldconcept{UnaryTypeTrait} describes a property
of a type. It shall be a class template that takes one template type
argument and, optionally, additional arguments that help define the
property being described. It shall be \oldconcept{DefaultConstructible},
\oldconcept{CopyConstructible},
and publicly and unambiguously derived, directly or indirectly, from
its \defn{base characteristic}, which is
a specialization of the template
\tcode{integral_constant}\iref{meta.help}, with
the arguments to the template \tcode{integral_constant} determined by the
requirements for the particular property being described.
The member names of the base characteristic shall not be hidden and shall be
unambiguously available in the \oldconcept{UnaryTypeTrait}.

\pnum
A \defnoldconcept{BinaryTypeTrait} describes a
relationship between two types. It shall be a class template that
takes two template type arguments and, optionally, additional
arguments that help define the relationship being described. It shall
be \oldconcept{DefaultConstructible}, \oldconcept{CopyConstructible},
and publicly and unambiguously derived, directly or
indirectly, from
its \term{base characteristic}, which is a specialization
of the template
\tcode{integral_constant}\iref{meta.help}, with
the arguments to the template \tcode{integral_constant} determined by the
requirements for the particular relationship being described.
The member names of the base characteristic shall not be hidden and shall be
unambiguously available in the \oldconcept{BinaryTypeTrait}.

\pnum
A \defnoldconcept{TransformationTrait}
modifies a property
of a type. It shall be a class template that takes one
template type argument and, optionally, additional arguments that help
define the modification. It shall define a publicly accessible nested type
named \tcode{type}, which shall be a synonym for the modified type.

\pnum
Unless otherwise specified,
the behavior of a program that adds specializations
for any of the templates specified in \ref{meta}
is undefined.

\pnum
Unless otherwise specified, an incomplete type may be used
to instantiate a template specified in \ref{meta}.
The behavior of a program is undefined if:
\begin{itemize}
\item
  an instantiation of a template specified in \ref{meta}
  directly or indirectly depends on
  an incompletely-defined object type \tcode{T}, and
\item
  that instantiation could yield a different result
  were \tcode{T} hypothetically completed.
\end{itemize}

\rSec2[meta.type.synop]{Header \tcode{<type_traits>} synopsis}

\indexheader{type_traits}%
% FIXME: Many index entries missing.
\begin{codeblock}
namespace std {
  // \ref{meta.help}, helper class
  template<class T, T v> struct integral_constant;

  template<bool B>
    using bool_constant = integral_constant<bool, B>;
  using true_type  = bool_constant<true>;
  using false_type = bool_constant<false>;

  // \ref{meta.unary.cat}, primary type categories
  template<class T> struct is_void;
  template<class T> struct is_null_pointer;
  template<class T> struct is_integral;
  template<class T> struct is_floating_point;
  template<class T> struct is_array;
  template<class T> struct is_pointer;
  template<class T> struct is_lvalue_reference;
  template<class T> struct is_rvalue_reference;
  template<class T> struct is_member_object_pointer;
  template<class T> struct is_member_function_pointer;
  template<class T> struct is_enum;
  template<class T> struct is_union;
  template<class T> struct is_class;
  template<class T> struct is_function;

  // \ref{meta.unary.comp}, composite type categories
  template<class T> struct is_reference;
  template<class T> struct is_arithmetic;
  template<class T> struct is_fundamental;
  template<class T> struct is_object;
  template<class T> struct is_scalar;
  template<class T> struct is_compound;
  template<class T> struct is_member_pointer;

  // \ref{meta.unary.prop}, type properties
  template<class T> struct is_const;
  template<class T> struct is_volatile;
  template<class T> struct is_trivial;
  template<class T> struct is_trivially_copyable;
  template<class T> struct is_standard_layout;
  template<class T> struct is_empty;
  template<class T> struct is_polymorphic;
  template<class T> struct is_abstract;
  template<class T> struct is_final;
  template<class T> struct is_aggregate;

  template<class T> struct is_signed;
  template<class T> struct is_unsigned;
  template<class T> struct is_bounded_array;
  template<class T> struct is_unbounded_array;

  template<class T, class... Args> struct is_constructible;
  template<class T> struct is_default_constructible;
  template<class T> struct is_copy_constructible;
  template<class T> struct is_move_constructible;

  template<class T, class U> struct is_assignable;
  template<class T> struct is_copy_assignable;
  template<class T> struct is_move_assignable;

  template<class T, class U> struct is_swappable_with;
  template<class T> struct is_swappable;

  template<class T> struct is_destructible;

  template<class T, class... Args> struct is_trivially_constructible;
  template<class T> struct is_trivially_default_constructible;
  template<class T> struct is_trivially_copy_constructible;
  template<class T> struct is_trivially_move_constructible;

  template<class T, class U> struct is_trivially_assignable;
  template<class T> struct is_trivially_copy_assignable;
  template<class T> struct is_trivially_move_assignable;
  template<class T> struct is_trivially_destructible;

  template<class T, class... Args> struct is_nothrow_constructible;
  template<class T> struct is_nothrow_default_constructible;
  template<class T> struct is_nothrow_copy_constructible;
  template<class T> struct is_nothrow_move_constructible;

  template<class T, class U> struct is_nothrow_assignable;
  template<class T> struct is_nothrow_copy_assignable;
  template<class T> struct is_nothrow_move_assignable;

  template<class T, class U> struct is_nothrow_swappable_with;
  template<class T> struct is_nothrow_swappable;

  template<class T> struct is_nothrow_destructible;

  template<class T> struct has_virtual_destructor;

  template<class T> struct has_unique_object_representations;

  // \ref{meta.unary.prop.query}, type property queries
  template<class T> struct alignment_of;
  template<class T> struct rank;
  template<class T, unsigned I = 0> struct extent;

  // \ref{meta.rel}, type relations
  template<class T, class U> struct is_same;
  template<class Base, class Derived> struct is_base_of;
  template<class From, class To> struct is_convertible;
  template<class From, class To> struct is_nothrow_convertible;
  template<class T, class U> struct is_layout_compatible;
  template<class Base, class Derived> struct is_pointer_interconvertible_base_of;

  template<class Fn, class... ArgTypes> struct is_invocable;
  template<class R, class Fn, class... ArgTypes> struct is_invocable_r;

  template<class Fn, class... ArgTypes> struct is_nothrow_invocable;
  template<class R, class Fn, class... ArgTypes> struct is_nothrow_invocable_r;

  // \ref{meta.trans.cv}, const-volatile modifications
  template<class T> struct remove_const;
  template<class T> struct remove_volatile;
  template<class T> struct remove_cv;
  template<class T> struct add_const;
  template<class T> struct add_volatile;
  template<class T> struct add_cv;

  template<class T>
    using @\libglobal{remove_const_t}@    = typename remove_const<T>::type;
  template<class T>
    using @\libglobal{remove_volatile_t}@ = typename remove_volatile<T>::type;
  template<class T>
    using @\libglobal{remove_cv_t}@       = typename remove_cv<T>::type;
  template<class T>
    using @\libglobal{add_const_t}@       = typename add_const<T>::type;
  template<class T>
    using @\libglobal{add_volatile_t}@    = typename add_volatile<T>::type;
  template<class T>
    using @\libglobal{add_cv_t}@          = typename add_cv<T>::type;

  // \ref{meta.trans.ref}, reference modifications
  template<class T> struct remove_reference;
  template<class T> struct add_lvalue_reference;
  template<class T> struct add_rvalue_reference;

  template<class T>
    using @\libglobal{remove_reference_t}@     = typename remove_reference<T>::type;
  template<class T>
    using @\libglobal{add_lvalue_reference_t}@ = typename add_lvalue_reference<T>::type;
  template<class T>
    using @\libglobal{add_rvalue_reference_t}@ = typename add_rvalue_reference<T>::type;

  // \ref{meta.trans.sign}, sign modifications
  template<class T> struct make_signed;
  template<class T> struct make_unsigned;

  template<class T>
    using @\libglobal{make_signed_t}@   = typename make_signed<T>::type;
  template<class T>
    using @\libglobal{make_unsigned_t}@ = typename make_unsigned<T>::type;

  // \ref{meta.trans.arr}, array modifications
  template<class T> struct remove_extent;
  template<class T> struct remove_all_extents;

  template<class T>
    using @\libglobal{remove_extent_t}@      = typename remove_extent<T>::type;
  template<class T>
    using @\libglobal{remove_all_extents_t}@ = typename remove_all_extents<T>::type;

  // \ref{meta.trans.ptr}, pointer modifications
  template<class T> struct remove_pointer;
  template<class T> struct add_pointer;

  template<class T>
    using @\libglobal{remove_pointer_t}@ = typename remove_pointer<T>::type;
  template<class T>
    using @\libglobal{add_pointer_t}@    = typename add_pointer<T>::type;

  // \ref{meta.trans.other}, other transformations
  template<class T> struct type_identity;
  template<size_t Len, size_t Align = @\textit{default-alignment}@> // see \ref{meta.trans.other}
    struct aligned_storage;
  template<size_t Len, class... Types> struct aligned_union;
  template<class T> struct remove_cvref;
  template<class T> struct decay;
  template<bool, class T = void> struct enable_if;
  template<bool, class T, class F> struct conditional;
  template<class... T> struct common_type;
  template<class T, class U, template<class> class TQual, template<class> class UQual>
    struct basic_common_reference { };
  template<class... T> struct common_reference;
  template<class T> struct underlying_type;
  template<class Fn, class... ArgTypes> struct invoke_result;
  template<class T> struct unwrap_reference;
  template<class T> struct unwrap_ref_decay;

  template<class T>
    using @\libglobal{type_identity_t}@    = typename type_identity<T>::type;
  template<size_t Len, size_t Align = @\textit{default-alignment}@> // see \ref{meta.trans.other}
    using @\libglobal{aligned_storage_t}@  = typename aligned_storage<Len, Align>::type;
  template<size_t Len, class... Types>
    using @\libglobal{aligned_union_t}@    = typename aligned_union<Len, Types...>::type;
  template<class T>
    using @\libglobal{remove_cvref_t}@     = typename remove_cvref<T>::type;
  template<class T>
    using @\libglobal{decay_t}@            = typename decay<T>::type;
  template<bool b, class T = void>
    using @\libglobal{enable_if_t}@        = typename enable_if<b, T>::type;
  template<bool b, class T, class F>
    using @\libglobal{conditional_t}@      = typename conditional<b, T, F>::type;
  template<class... T>
    using @\libglobal{common_type_t}@      = typename common_type<T...>::type;
  template<class... T>
    using @\libglobal{common_reference_t}@ = typename common_reference<T...>::type;
  template<class T>
    using @\libglobal{underlying_type_t}@  = typename underlying_type<T>::type;
  template<class Fn, class... ArgTypes>
    using @\libglobal{invoke_result_t}@    = typename invoke_result<Fn, ArgTypes...>::type;
  template<class T>
    using unwrap_reference_t = typename unwrap_reference<T>::type;
  template<class T>
    using unwrap_ref_decay_t = typename unwrap_ref_decay<T>::type;
  template<class...>
    using @\libglobal{void_t}@             = void;

  // \ref{meta.logical}, logical operator traits
  template<class... B> struct conjunction;
  template<class... B> struct disjunction;
  template<class B> struct negation;

  // \ref{meta.unary.cat}, primary type categories
  template<class T>
    inline constexpr bool @\libglobal{is_void_v}@ = is_void<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_null_pointer_v}@ = is_null_pointer<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_integral_v}@ = is_integral<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_floating_point_v}@ = is_floating_point<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_array_v}@ = is_array<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_pointer_v}@ = is_pointer<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_lvalue_reference_v}@ = is_lvalue_reference<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_rvalue_reference_v}@ = is_rvalue_reference<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_member_object_pointer_v}@ = is_member_object_pointer<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_member_function_pointer_v}@ = is_member_function_pointer<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_enum_v}@ = is_enum<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_union_v}@ = is_union<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_class_v}@ = is_class<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_function_v}@ = is_function<T>::value;

  // \ref{meta.unary.comp}, composite type categories
  template<class T>
    inline constexpr bool @\libglobal{is_reference_v}@ = is_reference<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_arithmetic_v}@ = is_arithmetic<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_fundamental_v}@ = is_fundamental<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_object_v}@ = is_object<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_scalar_v}@ = is_scalar<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_compound_v}@ = is_compound<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_member_pointer_v}@ = is_member_pointer<T>::value;

  // \ref{meta.unary.prop}, type properties
  template<class T>
    inline constexpr bool @\libglobal{is_const_v}@ = is_const<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_volatile_v}@ = is_volatile<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_trivial_v}@ = is_trivial<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_trivially_copyable_v}@ = is_trivially_copyable<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_standard_layout_v}@ = is_standard_layout<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_empty_v}@ = is_empty<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_polymorphic_v}@ = is_polymorphic<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_abstract_v}@ = is_abstract<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_final_v}@ = is_final<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_aggregate_v}@ = is_aggregate<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_signed_v}@ = is_signed<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_unsigned_v}@ = is_unsigned<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_bounded_array_v}@ = is_bounded_array<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_unbounded_array_v}@ = is_unbounded_array<T>::value;
  template<class T, class... Args>
    inline constexpr bool @\libglobal{is_constructible_v}@ = is_constructible<T, Args...>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_default_constructible_v}@ = is_default_constructible<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_copy_constructible_v}@ = is_copy_constructible<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_move_constructible_v}@ = is_move_constructible<T>::value;
  template<class T, class U>
    inline constexpr bool @\libglobal{is_assignable_v}@ = is_assignable<T, U>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_copy_assignable_v}@ = is_copy_assignable<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_move_assignable_v}@ = is_move_assignable<T>::value;
  template<class T, class U>
    inline constexpr bool @\libglobal{is_swappable_with_v}@ = is_swappable_with<T, U>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_swappable_v}@ = is_swappable<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_destructible_v}@ = is_destructible<T>::value;
  template<class T, class... Args>
    inline constexpr bool is_trivially_constructible_v
      = is_trivially_constructible<T, Args...>::value;
  template<class T>
    inline constexpr bool is_trivially_default_constructible_v
      = is_trivially_default_constructible<T>::value;
  template<class T>
    inline constexpr bool is_trivially_copy_constructible_v
      = is_trivially_copy_constructible<T>::value;
  template<class T>
    inline constexpr bool is_trivially_move_constructible_v
      = is_trivially_move_constructible<T>::value;
  template<class T, class U>
    inline constexpr bool @\libglobal{is_trivially_assignable_v}@ = is_trivially_assignable<T, U>::value;
  template<class T>
    inline constexpr bool is_trivially_copy_assignable_v
      = is_trivially_copy_assignable<T>::value;
  template<class T>
    inline constexpr bool is_trivially_move_assignable_v
      = is_trivially_move_assignable<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_trivially_destructible_v}@ = is_trivially_destructible<T>::value;
  template<class T, class... Args>
    inline constexpr bool is_nothrow_constructible_v
      = is_nothrow_constructible<T, Args...>::value;
  template<class T>
    inline constexpr bool is_nothrow_default_constructible_v
      = is_nothrow_default_constructible<T>::value;
  template<class T>
    inline constexpr bool is_nothrow_copy_constructible_v
      = is_nothrow_copy_constructible<T>::value;
  template<class T>
    inline constexpr bool is_nothrow_move_constructible_v
      = is_nothrow_move_constructible<T>::value;
  template<class T, class U>
    inline constexpr bool @\libglobal{is_nothrow_assignable_v}@ = is_nothrow_assignable<T, U>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_nothrow_copy_assignable_v}@ = is_nothrow_copy_assignable<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_nothrow_move_assignable_v}@ = is_nothrow_move_assignable<T>::value;
  template<class T, class U>
    inline constexpr bool @\libglobal{is_nothrow_swappable_with_v}@ = is_nothrow_swappable_with<T, U>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_nothrow_swappable_v}@ = is_nothrow_swappable<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{is_nothrow_destructible_v}@ = is_nothrow_destructible<T>::value;
  template<class T>
    inline constexpr bool @\libglobal{has_virtual_destructor_v}@ = has_virtual_destructor<T>::value;
  template<class T>
    inline constexpr bool has_unique_object_representations_v
      = has_unique_object_representations<T>::value;

  // \ref{meta.unary.prop.query}, type property queries
  template<class T>
    inline constexpr size_t @\libglobal{alignment_of_v}@ = alignment_of<T>::value;
  template<class T>
    inline constexpr size_t @\libglobal{rank_v}@ = rank<T>::value;
  template<class T, unsigned I = 0>
    inline constexpr size_t @\libglobal{extent_v}@ = extent<T, I>::value;

  // \ref{meta.rel}, type relations
  template<class T, class U>
    inline constexpr bool @\libglobal{is_same_v}@ = is_same<T, U>::value;
  template<class Base, class Derived>
    inline constexpr bool @\libglobal{is_base_of_v}@ = is_base_of<Base, Derived>::value;
  template<class From, class To>
    inline constexpr bool @\libglobal{is_convertible_v}@ = is_convertible<From, To>::value;
  template<class From, class To>
    inline constexpr bool @\libglobal{is_nothrow_convertible_v}@ = is_nothrow_convertible<From, To>::value;
  template<class T, class U>
    inline constexpr bool @\libglobal{is_layout_compatible_v}@ = is_layout_compatible<T, U>::value;
  template<class Base, class Derived>
    inline constexpr bool is_pointer_interconvertible_base_of_v
      = is_pointer_interconvertible_base_of<Base, Derived>::value;
  template<class Fn, class... ArgTypes>
    inline constexpr bool @\libglobal{is_invocable_v}@ = is_invocable<Fn, ArgTypes...>::value;
  template<class R, class Fn, class... ArgTypes>
    inline constexpr bool @\libglobal{is_invocable_r_v}@ = is_invocable_r<R, Fn, ArgTypes...>::value;
  template<class Fn, class... ArgTypes>
    inline constexpr bool @\libglobal{is_nothrow_invocable_v}@ = is_nothrow_invocable<Fn, ArgTypes...>::value;
  template<class R, class Fn, class... ArgTypes>
    inline constexpr bool is_nothrow_invocable_r_v
      = is_nothrow_invocable_r<R, Fn, ArgTypes...>::value;

  // \ref{meta.logical}, logical operator traits
  template<class... B>
    inline constexpr bool @\libglobal{conjunction_v}@ = conjunction<B...>::value;
  template<class... B>
    inline constexpr bool @\libglobal{disjunction_v}@ = disjunction<B...>::value;
  template<class B>
    inline constexpr bool @\libglobal{negation_v}@ = negation<B>::value;

  // \ref{meta.member}, member relationships
  template<class S, class M>
    constexpr bool is_pointer_interconvertible_with_class(M S::*m) noexcept;
  template<class S1, class S2, class M1, class M2>
    constexpr bool is_corresponding_member(M1 S1::*m1, M2 S2::*m2) noexcept;

  // \ref{meta.const.eval}, constant evaluation context
  constexpr bool is_constant_evaluated() noexcept;
}
\end{codeblock}

\rSec2[meta.help]{Helper classes}

\indexlibrarymember{value_type}{integral_constant}%
\begin{codeblock}
namespace std {
  template<class T, T v> struct integral_constant {
    static constexpr T value = v;

    using value_type = T;
    using type = integral_constant<T, v>;

    constexpr operator value_type() const noexcept { return value; }
    constexpr value_type operator()() const noexcept { return value; }
  };
}
\end{codeblock}

\indexlibraryglobal{integral_constant}%
\indexlibraryglobal{bool_constant}%
\indexlibraryglobal{true_type}%
\indexlibraryglobal{false_type}%
\pnum
The class template \tcode{integral_constant},
alias template \tcode{bool_constant}, and
its associated \grammarterm{typedef-name}{s}
\tcode{true_type} and \tcode{false_type}
are used as base classes to define
the interface for various type traits.

\rSec2[meta.unary]{Unary type traits}

\rSec3[meta.unary.general]{General}

\pnum
Subclause \ref{meta.unary} contains templates that may be used to query the
properties of a type at compile time.

\pnum
Each of these templates shall be a
\oldconcept{UnaryTypeTrait}\iref{meta.rqmts}
with a base characteristic of
\tcode{true_type} if the corresponding condition is \tcode{true}, otherwise
\tcode{false_type}.

\rSec3[meta.unary.cat]{Primary type categories}

\pnum
The primary type categories correspond to the descriptions given in
subclause~\ref{basic.types} of the \Cpp{} standard.

\pnum
For any given type \tcode{T}, the result of applying one of these templates to
\tcode{T} and to \cv{}~\tcode{T} shall yield the same result.

\pnum
\begin{note}
For any given type \tcode{T}, exactly one of the primary type categories
has a \tcode{value} member that evaluates to \tcode{true}.
\end{note}

\begin{libreqtab3e}{Primary type category predicates}{meta.unary.cat}
\\ \topline
\lhdr{Template} &   \chdr{Condition}    &   \rhdr{Comments} \\\capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \chdr{Condition}    &   \rhdr{Comments} \\ \capsep
\endhead
\indexlibraryglobal{is_void}%
\tcode{template<class T>}\br
 \tcode{struct is_void;}                &
\tcode{T} is \tcode{void}       &   \\ \rowsep
\indexlibraryglobal{is_null_pointer}%
\tcode{template<class T>}\br
 \tcode{struct is_null_pointer;}                &
\tcode{T} is \tcode{nullptr_t}\iref{basic.fundamental}       &   \\ \rowsep
\indexlibraryglobal{is_integral}%
\tcode{template<class T>}\br
 \tcode{struct is_integral;}        &
\tcode{T} is an integral type\iref{basic.fundamental}                 &   \\ \rowsep
\indexlibraryglobal{is_floating_point}%
\tcode{template<class T>}\br
 \tcode{struct is_floating_point;}  &
\tcode{T} is a floating-point type\iref{basic.fundamental}            &   \\ \rowsep
\indexlibraryglobal{is_array}%
\tcode{template<class T>}\br
 \tcode{struct is_array;}           &
\tcode{T} is an array type\iref{basic.compound} of known or unknown extent    &
Class template \tcode{array}\iref{array}
is not an array type.                   \\ \rowsep
\indexlibraryglobal{is_pointer}%
\tcode{template<class T>}\br
 \tcode{struct is_pointer;}         &
\tcode{T} is a pointer type\iref{basic.compound}                      &
Includes pointers to functions
but not pointers to non-static members.                        \\ \rowsep
\indexlibraryglobal{is_lvalue_reference}%
\tcode{template<class T>}\br
 \tcode{struct is_lvalue_reference;}    &
 \tcode{T} is an lvalue reference type\iref{dcl.ref}   &   \\ \rowsep
\indexlibraryglobal{is_rvalue_reference}%
\tcode{template<class T>}\br
 \tcode{struct is_rvalue_reference;}    &
 \tcode{T} is an rvalue reference type\iref{dcl.ref}   &   \\ \rowsep
\indexlibraryglobal{is_member_object_pointer}%
\tcode{template<class T>}\br
 \tcode{struct is_member_object_pointer;}&
 \tcode{T} is a pointer to data member                              &   \\ \rowsep
\indexlibraryglobal{is_member_function_pointer}%
\tcode{template<class T>}\br
 \tcode{struct is_member_function_pointer;}&
\tcode{T} is a pointer to member function                           &   \\ \rowsep
\indexlibraryglobal{is_enum}%
\tcode{template<class T>}\br
 \tcode{struct is_enum;}            &
\tcode{T} is an enumeration type\iref{basic.compound}                 &   \\ \rowsep
\indexlibraryglobal{is_union}%
\tcode{template<class T>}\br
 \tcode{struct is_union;}           &
\tcode{T} is a union type\iref{basic.compound}                        &   \\ \rowsep
\indexlibraryglobal{is_class}%
\tcode{template<class T>}\br
 \tcode{struct is_class;}           &
\tcode{T} is a non-union class type\iref{basic.compound} & \\ \rowsep
\indexlibraryglobal{is_function}%
\tcode{template<class T>}\br
 \tcode{struct is_function;}        &
\tcode{T} is a function type\iref{basic.compound}                     &   \\
\end{libreqtab3e}

\rSec3[meta.unary.comp]{Composite type traits}

\pnum
These templates provide convenient compositions of the primary type
categories, corresponding to the descriptions given in subclause~\ref{basic.types}.

\pnum
For any given type \tcode{T}, the result of applying one of these templates to
\tcode{T} and to \cv{}~\tcode{T} shall yield the same result.

\begin{libreqtab3b}{Composite type category predicates}{meta.unary.comp}
\\ \topline
\lhdr{Template} &   \chdr{Condition}    &   \rhdr{Comments} \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \chdr{Condition}    &   \rhdr{Comments} \\ \capsep
\endhead
\indexlibraryglobal{is_reference}%
\tcode{template<class T>}\br
 \tcode{struct is_reference;}   &
 \tcode{T} is an lvalue reference or an rvalue reference &  \\ \rowsep
\indexlibraryglobal{is_arithmetic}%
\tcode{template<class T>}\br
 \tcode{struct is_arithmetic;}          &
 \tcode{T} is an arithmetic type\iref{basic.fundamental}              &   \\ \rowsep
\indexlibraryglobal{is_fundamental}%
\tcode{template<class T>}\br
 \tcode{struct is_fundamental;}         &
 \tcode{T} is a fundamental type\iref{basic.fundamental}              &   \\ \rowsep
\indexlibraryglobal{is_object}%
\tcode{template<class T>}\br
 \tcode{struct is_object;}              &
 \tcode{T} is an object type\iref{basic.types}                            &   \\ \rowsep
\indexlibraryglobal{is_scalar}%
\tcode{template<class T>}\br
 \tcode{struct is_scalar;}              &
 \tcode{T} is a scalar type\iref{basic.types}                         &   \\ \rowsep
\indexlibraryglobal{is_compound}%
\tcode{template<class T>}\br
 \tcode{struct is_compound;}            &
 \tcode{T} is a compound type\iref{basic.compound}                        &   \\ \rowsep
\indexlibraryglobal{is_member_pointer}%
\tcode{template<class T>}\br
 \tcode{struct is_member_pointer;}      &
 \tcode{T} is a pointer-to-member type\iref{basic.compound}               &   \\
\end{libreqtab3b}

\rSec3[meta.unary.prop]{Type properties}

\pnum
These templates provide access to some of the more important
properties of types.

\pnum
It is unspecified whether the library defines any full or partial
specializations of any of these templates.

\pnum
For all of the class templates \tcode{X} declared in this subclause,
instantiating that template with a template-argument that is a class
template specialization may result in the implicit instantiation of
the template argument if and only if the semantics of \tcode{X} require that
the argument is a complete type.

\pnum
For the purpose of defining the templates in this subclause,
a function call expression \tcode{declval<T>()} for any type \tcode{T}
is considered to be a trivial~(\ref{basic.types}, \ref{special}) function call
that is not an odr-use\iref{basic.def.odr} of \tcode{declval}
in the context of the corresponding definition
notwithstanding the restrictions of~\ref{declval}.

\begin{libreqtab3b}{Type property predicates}{meta.unary.prop}
\\ \topline
\lhdr{Template} &   \chdr{Condition}    &   \rhdr{Preconditions}    \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \chdr{Condition}    &   \rhdr{Preconditions}    \\ \capsep
\endhead

\indexlibraryglobal{is_const}%
\tcode{template<class T>}\br
 \tcode{struct is_const;}               &
 \tcode{T} is const-qualified\iref{basic.type.qualifier}                  &   \\ \rowsep

\indexlibraryglobal{is_volatile}%
\tcode{template<class T>}\br
 \tcode{struct is_volatile;}            &
 \tcode{T} is volatile-qualified\iref{basic.type.qualifier}                   &   \\ \rowsep


\indexlibraryglobal{is_trivial}%
\tcode{template<class T>}\br
 \tcode{struct is_trivial;}                 &
 \tcode{T} is a trivial type\iref{basic.types}     &
 \tcode{remove_all_extents_t<T>} shall be a complete
 type or \cv{}~\tcode{void}.                \\ \rowsep

\indexlibraryglobal{is_trivially_copyable}%
\tcode{template<class T>}\br
 \tcode{struct is_trivially_copyable;}      &
 \tcode{T} is a trivially copyable type\iref{basic.types} &
 \tcode{remove_all_extents_t<T>} shall be a complete type or
 \cv{}~\tcode{void}.                               \\ \rowsep

\indexlibraryglobal{is_standard_layout}%
\tcode{template<class T>}\br
 \tcode{struct is_standard_layout;}                 &
 \tcode{T} is a standard-layout type\iref{basic.types}   &
 \tcode{remove_all_extents_t<T>} shall be a complete
 type or \cv{}~\tcode{void}.                \\ \rowsep

\indexlibrary{\idxcode{is_empty}!class}%
\tcode{template<class T>}\br
 \tcode{struct is_empty;}               &
 \tcode{T} is a class type, but not a union type, with no non-static data
 members other than subobjects of zero size, no virtual member functions,
 no virtual base classes, and no base class \tcode{B} for
 which \tcode{is_empty_v<B>} is \tcode{false}. &
 If \tcode{T} is a non-union class type, \tcode{T} shall be a complete type.                               \\ \rowsep

\indexlibraryglobal{is_polymorphic}%
\tcode{template<class T>}\br
 \tcode{struct is_polymorphic;}         &
 \tcode{T} is a polymorphic class\iref{class.virtual}                             &
 If \tcode{T} is a non-union class type, \tcode{T} shall be a complete type.                \\ \rowsep

\indexlibraryglobal{is_abstract}%
\tcode{template<class T>}\br
 \tcode{struct is_abstract;}            &
 \tcode{T} is an abstract class\iref{class.abstract}                              &
 If \tcode{T} is a non-union class type, \tcode{T} shall be a complete type.                \\ \rowsep

\indexlibraryglobal{is_final}%
\tcode{template<class T>}\br
 \tcode{struct is_final;}               &
 \tcode{T} is a class type marked with the \grammarterm{class-virt-specifier}
 \tcode{final}\iref{class.pre}.
\begin{tailnote}
A union is a class type that
 can be marked with \tcode{final}.
\end{tailnote}
&
 If \tcode{T} is a class type, \tcode{T} shall be a complete type.                          \\ \rowsep

\indexlibraryglobal{is_aggregate}%
\tcode{template<class T>}\br
  \tcode{struct is_aggregate;}           &
 \tcode{T} is an aggregate type\iref{dcl.init.aggr} &
 \tcode{remove_all_extents_t<T>} shall be a complete type or \cv~\tcode{void}.              \\ \rowsep

\indexlibrary{\idxcode{is_signed}!class}%
\tcode{template<class T>}\br
  \tcode{struct is_signed;}              &
  If \tcode{is_arithmetic_v<T>} is \tcode{true}, the same result as
  \tcode{T(-1) < T(0)};
  otherwise, \tcode{false}   &   \\  \rowsep

\indexlibraryglobal{is_unsigned}%
\tcode{template<class T>}\br
  \tcode{struct is_unsigned;}            &
  If \tcode{is_arithmetic_v<T>} is \tcode{true}, the same result as
  \tcode{T(0) < T(-1)};
  otherwise, \tcode{false}   &   \\  \rowsep

\indexlibraryglobal{is_bounded_array}%
\tcode{template<class T>}\br
  \tcode{struct is_bounded_array;}       &
  \tcode{T} is an array type of known bound\iref{dcl.array}
                             &   \\  \rowsep

\indexlibraryglobal{is_unbounded_array}%
\tcode{template<class T>}\br
  \tcode{struct is_unbounded_array;}     &
  \tcode{T} is an array type of unknown bound\iref{dcl.array}
                             &   \\  \rowsep

\indexlibraryglobal{is_constructible}%
\tcode{template<class T, class... Args>}\br
 \tcode{struct is_constructible;}   &
 For a function type \tcode{T} or
 for a \cv{}~\tcode{void} type \tcode{T},
 \tcode{is_constructible_v<T, Args...>} is \tcode{false},
 otherwise \seebelow                &
 \tcode{T} and all types in the template parameter pack \tcode{Args}
 shall be complete types, \cv{}~\tcode{void},
 or arrays of unknown bound.  \\ \rowsep

\indexlibraryglobal{is_default_constructible}%
\tcode{template<class T>}\br
  \tcode{struct is_default_constructible;} &
  \tcode{is_constructible_v<T>} is \tcode{true}. &
  \tcode{T} shall be a complete type, \cv{}~\tcode{void},
  or an array of unknown bound. \\ \rowsep

\indexlibraryglobal{is_copy_constructible}%
\tcode{template<class T>}\br
  \tcode{struct is_copy_constructible;} &
  For a referenceable type \tcode{T}\iref{defns.referenceable}, the same result as
  \tcode{is_constructible_v<T, const T\&>}, otherwise \tcode{false}. &
  \tcode{T} shall be a complete type, \cv{}~\tcode{void},
  or an array of unknown bound. \\ \rowsep

\indexlibraryglobal{is_move_constructible}%
\tcode{template<class T>}\br
  \tcode{struct is_move_constructible;} &
  For a referenceable type \tcode{T}, the same result as
  \tcode{is_constructible_v<T, T\&\&>}, otherwise \tcode{false}. &
  \tcode{T} shall be a complete type, \cv{}~\tcode{void},
  or an array of unknown bound. \\ \rowsep

\indexlibraryglobal{is_assignable}%
\tcode{template<class T, class U>}\br
  \tcode{struct is_assignable;} &
  The expression \tcode{declval<T>() =} \tcode{declval<U>()} is well-formed
  when treated as an unevaluated
  operand\iref{expr.prop}. Access checking is performed as if in a context
  unrelated to \tcode{T} and \tcode{U}. Only the validity of the immediate context
  of the assignment expression is considered.
\begin{tailnote}
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{tailnote}
&
  \tcode{T} and \tcode{U} shall be complete types, \cv{}~\tcode{void},
  or arrays of unknown bound. \\ \rowsep

\indexlibraryglobal{is_copy_assignable}%
\tcode{template<class T>}\br
  \tcode{struct is_copy_assignable;} &
  For a referenceable type \tcode{T}, the same result as
  \tcode{is_assignable_v<T\&, const T\&>}, otherwise \tcode{false}. &
  \tcode{T} shall be a complete type, \cv{}~\tcode{void},
  or an array of unknown bound. \\ \rowsep

\indexlibraryglobal{is_move_assignable}%
\tcode{template<class T>}\br
  \tcode{struct is_move_assignable;} &
  For a referenceable type \tcode{T}, the same result as
  \tcode{is_assignable_v<T\&, T\&\&>}, otherwise \tcode{false}. &
  \tcode{T} shall be a complete type, \cv{}~\tcode{void},
  or an array of unknown bound. \\ \rowsep

\indexlibraryglobal{is_swappable_with}%
\tcode{template<class T, class U>}\br
  \tcode{struct is_swappable_with;} &
  The expressions \tcode{swap(declval<T>(), declval<U>())} and
  \tcode{swap(declval<U>(), declval<T>())} are each well-formed
  when treated as an unevaluated operand\iref{expr.prop}
  in an overload-resolution context
  for swappable values\iref{swappable.requirements}.
  Access checking is performed as if in a context
  unrelated to \tcode{T} and \tcode{U}.
  Only the validity of the immediate context
  of the \tcode{swap} expressions is considered.
  \begin{tailnote}
  The compilation of the expressions 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{tailnote}
&
  \tcode{T} and \tcode{U} shall be complete types,
  \cv{}~\tcode{void}, or
  arrays of unknown bound.  \\ \rowsep

\indexlibraryglobal{is_swappable}%
\tcode{template<class T>}\br
  \tcode{struct is_swappable;} &
  For a referenceable type \tcode{T},
  the same result as \tcode{is_swappable_with_v<T\&, T\&>},
  otherwise \tcode{false}. &
  \tcode{T} shall be a complete type,
  \cv{}~\tcode{void}, or
  an array of unknown bound. \\ \rowsep

\indexlibraryglobal{is_destructible}%
\tcode{template<class T>}\br
  \tcode{struct is_destructible;} &
  Either \tcode{T} is a reference type,
  or \tcode{T} is a complete object type
  for which the expression
  \tcode{declval<U\&>().\~U()}
  is well-formed
  when treated as an unevaluated operand\iref{expr.prop},
  where \tcode{U} is
  \tcode{remove_all_extents_t<T>}. &
  \tcode{T} shall be a complete type, \cv{}~\tcode{void},
  or an array of unknown bound. \\ \rowsep

\indexlibraryglobal{is_trivially_constructible}%
\tcode{template<class T, class... Args>}\br
  \tcode{struct}\br
  \tcode{is_trivially_constructible;} &
  \tcode{is_constructible_v<T,}\br
  \tcode{Args...>} is \tcode{true} and the variable
  definition for \tcode{is_constructible}, as defined below, is known to call
  no operation that is not trivial~(\ref{basic.types}, \ref{special}). &
  \tcode{T} and all types in the template parameter pack \tcode{Args} shall be complete types,
  \cv{}~\tcode{void}, or arrays of unknown bound. \\ \rowsep

\indexlibraryglobal{is_trivially_default_constructible}%
\tcode{template<class T>}\br
 \tcode{struct is_trivially_default_constructible;} &
 \tcode{is_trivially_constructible_v<T>} is \tcode{true}. &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_trivially_copy_constructible}%
\tcode{template<class T>}\br
 \tcode{struct is_trivially_copy_constructible;}      &
  For a referenceable type \tcode{T}, the same result as
 \tcode{is_trivially_constructible_v<T, const T\&>}, otherwise \tcode{false}. &
  \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_trivially_move_constructible}%
\tcode{template<class T>}\br
 \tcode{struct is_trivially_move_constructible;}      &
  For a referenceable type \tcode{T}, the same result as
 \tcode{is_trivially_constructible_v<T, T\&\&>}, otherwise \tcode{false}. &
  \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_trivially_assignable}%
\tcode{template<class T, class U>}\br
  \tcode{struct is_trivially_assignable;} &
  \tcode{is_assignable_v<T, U>} is \tcode{true} and the assignment, as defined by
  \tcode{is_assignable}, is known to call no operation that is not trivial
 ~(\ref{basic.types}, \ref{special}). &
  \tcode{T} and \tcode{U} shall be complete types, \cv{}~\tcode{void},
  or arrays of unknown bound. \\ \rowsep

\indexlibraryglobal{is_trivially_copy_assignable}%
\tcode{template<class T>}\br
 \tcode{struct is_trivially_copy_assignable;} &
  For a referenceable type \tcode{T}, the same result as
 \tcode{is_trivially_assignable_v<T\&, const T\&>}, otherwise \tcode{false}. &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_trivially_move_assignable}%
\tcode{template<class T>}\br
 \tcode{struct is_trivially_move_assignable;} &
  For a referenceable type \tcode{T}, the same result as
 \tcode{is_trivially_assignable_v<T\&, T\&\&>}, otherwise \tcode{false}. &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown bound.                \\ \rowsep

\indexlibraryglobal{is_trivially_destructible}%
\tcode{template<class T>}\br
 \tcode{struct is_trivially_destructible;} &
 \tcode{is_destructible_v<T>} is \tcode{true} and
 \tcode{remove_all_extents_t<T>} is either a non-class type or
 a class type with a trivial destructor. &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_nothrow_constructible}%
\tcode{template<class T, class... Args>}\br
 \tcode{struct is_nothrow_constructible;}   &
 \tcode{is_constructible_v<T,} \tcode{ Args...>} is \tcode{true}
 and the
 variable definition for \tcode{is_constructible}, as defined below, is known not to
 throw any exceptions\iref{expr.unary.noexcept}.
 &
 \tcode{T} and all types in the template parameter pack \tcode{Args}
 shall be complete types, \cv{}~\tcode{void},
 or arrays of unknown bound.  \\ \rowsep

\indexlibraryglobal{is_nothrow_default_constructible}%
\tcode{template<class T>}\br
 \tcode{struct is_nothrow_default_constructible;} &
 \tcode{is_nothrow_constructible_v<T>} is \tcode{true}.  &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_nothrow_copy_constructible}%
\tcode{template<class T>}\br
 \tcode{struct is_nothrow_copy_constructible;}      &
  For a referenceable type \tcode{T}, the same result as
 \tcode{is_nothrow_constructible_v<T, const T\&>}, otherwise \tcode{false}. &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_nothrow_move_constructible}%
\tcode{template<class T>}\br
 \tcode{struct is_nothrow_move_constructible;}      &
  For a referenceable type \tcode{T}, the same result as
 \tcode{is_nothrow_constructible_v<T, T\&\&>}, otherwise \tcode{false}. &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown bound.                \\ \rowsep

\indexlibraryglobal{is_nothrow_assignable}%
\tcode{template<class T, class U>}\br
  \tcode{struct is_nothrow_assignable;} &
  \tcode{is_assignable_v<T, U>} is \tcode{true} and the assignment is known not to
  throw any exceptions\iref{expr.unary.noexcept}. &
  \tcode{T} and \tcode{U} shall be complete types, \cv{}~\tcode{void},
  or arrays of unknown bound. \\ \rowsep

\indexlibraryglobal{is_nothrow_copy_assignable}%
\tcode{template<class T>}\br
 \tcode{struct is_nothrow_copy_assignable;} &
  For a referenceable type \tcode{T}, the same result as
 \tcode{is_nothrow_assignable_v<T\&, const T\&>}, otherwise \tcode{false}. &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_nothrow_move_assignable}%
\tcode{template<class T>}\br
  \tcode{struct is_nothrow_move_assignable;} &
  For a referenceable type \tcode{T}, the same result as
  \tcode{is_nothrow_assignable_v<T\&, T\&\&>}, otherwise \tcode{false}. &
 \tcode{T} shall be a complete type,
 \cv{}~\tcode{void}, or an array of unknown
 bound.                \\ \rowsep

\indexlibraryglobal{is_nothrow_swappable_with}%
\tcode{template<class T, class U>}\br
  \tcode{struct is_nothrow_swappable_with;} &
  \tcode{is_swappable_with_v<T, U>} is \tcode{true} and
  each \tcode{swap} expression of the definition of
  \tcode{is_swappable_with<T, U>} is known not to throw
  any exceptions\iref{expr.unary.noexcept}. &
  \tcode{T} and \tcode{U} shall be complete types,
  \cv{}~\tcode{void}, or
  arrays of unknown bound. \\ \rowsep

\indexlibraryglobal{is_nothrow_swappable}%
\tcode{template<class T>}\br
  \tcode{struct is_nothrow_swappable;} &
  For a referenceable type \tcode{T},
  the same result as \tcode{is_nothrow_swappable_with_v<T\&, T\&>},
  otherwise \tcode{false}. &
  \tcode{T} shall be a complete type,
  \cv{}~\tcode{void}, or
  an array of unknown bound. \\ \rowsep

\indexlibraryglobal{is_nothrow_destructible}%
\tcode{template<class T>}\br
  \tcode{struct is_nothrow_destructible;} &
  \tcode{is_destructible_v<T>} is \tcode{true} and the indicated destructor is known
  not to throw any exceptions\iref{expr.unary.noexcept}. &
  \tcode{T} shall be a complete type,
  \cv{}~\tcode{void}, or an array of unknown
  bound.                \\ \rowsep

\indexlibraryglobal{has_virtual_destructor}%
\tcode{template<class T>}\br
 \tcode{struct has_virtual_destructor;} &
 \tcode{T} has a virtual destructor\iref{class.dtor} &
 If \tcode{T} is a non-union class type, \tcode{T} shall be a complete type.                \\ \rowsep

\indexlibraryglobal{has_unique_object_representations}%
\tcode{template<class T>}\br
  \tcode{struct has_unique_object_representations;} &
  For an array type \tcode{T}, the same result as
  \tcode{has_unique_object_representations_v<remove_all_extents_t<T>>},
  otherwise \seebelow. &
  \tcode{T} shall be a complete type, \cv{}~\tcode{void}, or
  an array of unknown bound. \\ \rowsep

\end{libreqtab3b}

\pnum
\begin{example}
\begin{codeblock}
is_const_v<const volatile int>      // \tcode{true}
is_const_v<const int*>              // \tcode{false}
is_const_v<const int&>              // \tcode{false}
is_const_v<int[3]>                  // \tcode{false}
is_const_v<const int[3]>            // \tcode{true}
\end{codeblock}
\end{example}

\pnum
\begin{example}
\begin{codeblock}
remove_const_t<const volatile int>  // \tcode{volatile int}
remove_const_t<const int* const>    // \tcode{const int*}
remove_const_t<const int&>          // \tcode{const int\&}
remove_const_t<const int[3]>        // \tcode{int[3]}
\end{codeblock}
\end{example}

\pnum
\begin{example}
\begin{codeblock}
// Given:
struct P final { };
union U1 { };
union U2 final { };

// the following assertions hold:
static_assert(!is_final_v<int>);
static_assert(is_final_v<P>);
static_assert(!is_final_v<U1>);
static_assert(is_final_v<U2>);
\end{codeblock}
\end{example}

\indexlibraryglobal{is_constructible}%
\pnum
The predicate condition for a template specialization
\tcode{is_constructible<T, Args...>} shall be satisfied if and only if the
following variable definition would be well-formed for some invented variable \tcode{t}:

\begin{codeblock}
T t(declval<Args>()...);
\end{codeblock}

\begin{note}
These tokens are never interpreted as a function declaration.
\end{note}
Access checking is performed as if in a context unrelated to \tcode{T}
and any of the \tcode{Args}. Only the validity of the immediate context of the
variable initialization is considered.
\begin{note}
The evaluation of the
initialization 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}

\indexlibraryglobal{has_unique_object_representations}%
\pnum
The predicate condition for a template specialization
\tcode{has_unique_object_representations<T>}
shall be satisfied if and only if:
\begin{itemize}
\item \tcode{T} is trivially copyable, and
\item any two objects of type \tcode{T} with the same value
have the same object representation, where
two objects of array or non-union class type are considered to have the same value
if their respective sequences of direct subobjects have the same values, and
two objects of union type are considered to have the same value
if they have the same active member and the corresponding members have the same value.
\end{itemize}
The set of scalar types for which this condition holds is
\impldef{which scalar types have unique object representations}.
\begin{note}
If a type has padding bits, the condition does not hold;
otherwise, the condition holds true for integral types.
\end{note}

\rSec2[meta.unary.prop.query]{Type property queries}

\pnum
This subclause contains templates that may be used to query
properties of types at compile time.

\begin{libreqtab2a}{Type property queries}{meta.unary.prop.query}
\\ \topline
\lhdr{Template} &   \rhdr{Value}    \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \rhdr{Value}    \\ \capsep
\endhead

\indexlibraryglobal{alignment_of}%
\tcode{template<class T>\br
 struct alignment_of;}      &
 \tcode{alignof(T)}.\br
 \mandates
 \tcode{alignof(T)} is a valid expression\iref{expr.alignof}  \\  \rowsep

\indexlibraryglobal{rank}%
\tcode{template<class T>\br
 struct rank;}      &
 If \tcode{T} names an array type, an integer value representing
 the number of dimensions of \tcode{T}; otherwise, 0. \\    \rowsep

\indexlibraryglobal{extent}%
\tcode{template<class T,\br
 unsigned I = 0>\br
 struct extent;}        &
 If \tcode{T} is not an array type, or if it has rank less
 than or equal to \tcode{I}, or if \tcode{I} is 0 and \tcode{T}
 has type ``array of unknown bound of \tcode{U}'', then
 0; otherwise, the bound\iref{dcl.array} of the $\tcode{I}^\text{th}$ dimension of
\tcode{T}, where indexing of \tcode{I} is zero-based \\
\end{libreqtab2a}

\pnum
Each of these templates shall be a \oldconcept{UnaryTypeTrait}\iref{meta.rqmts} with a
base characteristic of \tcode{integral_constant<size_t, Value>}.

\pnum
\begin{example}
\begin{codeblock}
// the following assertions hold:
assert(rank_v<int> == 0);
assert(rank_v<int[2]> == 1);
assert(rank_v<int[][4]> == 2);
\end{codeblock}
\end{example}

\pnum
\begin{example}
\begin{codeblock}
// the following assertions hold:
assert(extent_v<int> == 0);
assert(extent_v<int[2]> == 2);
assert(extent_v<int[2][4]> == 2);
assert(extent_v<int[][4]> == 0);
assert((extent_v<int, 1>) == 0);
assert((extent_v<int[2], 1>) == 0);
assert((extent_v<int[2][4], 1>) == 4);
assert((extent_v<int[][4], 1>) == 4);
\end{codeblock}
\end{example}

\rSec2[meta.rel]{Relationships between types}

\pnum
This subclause contains templates that may be used to query
relationships between types at compile time.

\pnum
Each of these templates shall be a
\oldconcept{BinaryTypeTrait}\iref{meta.rqmts}
with a base characteristic of
\tcode{true_type} if the corresponding condition is true, otherwise
\tcode{false_type}.

\begin{libreqtab3f}{Type relationship predicates}{meta.rel}
\\ \topline
\lhdr{Template} &   \chdr{Condition}    &   \rhdr{Comments} \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \chdr{Condition}    &   \rhdr{Comments} \\ \capsep
\endhead
\tcode{template<class T, class U>}\br
 \tcode{struct is_same;}                    &
 \tcode{T} and \tcode{U} name the same type with the same cv-qualifications                            &   \\ \rowsep

\indexlibraryglobal{is_base_of}%
\tcode{template<class Base, class Derived>}\br
 \tcode{struct is_base_of;}                 &
 \tcode{Base} is a base class of \tcode{Derived}\iref{class.derived}
 without regard to cv-qualifiers
 or \tcode{Base} and \tcode{Derived} are not unions and
 name the same class type
 without regard to cv-qualifiers            &
 If \tcode{Base} and
 \tcode{Derived} are non-union class types and are
not possibly cv-qualified versions of the same type,
 \tcode{Derived} shall be a complete
 type.
 \begin{tailnote}
Base classes that are private, protected, or ambiguous
 are, nonetheless, base classes.
\end{tailnote}
\\ \rowsep

\indexlibraryglobal{is_convertible}%
\tcode{template<class From, class To>}\br
 \tcode{struct is_convertible;}             &
 \seebelow                                  &
 \tcode{From} and \tcode{To} shall be complete types,
 \cv{}~\tcode{void}, or arrays of unknown bound.  \\ \rowsep

\indexlibraryglobal{is_nothrow_convertible}%
\tcode{template<class From, class To>}\br
 \tcode{struct is_nothrow_convertible;}     &
 \tcode{is_convertible_v<From, To>} is \tcode{true} and
 the conversion, as defined by \tcode{is_convertible},
 is known not to throw any exceptions\iref{expr.unary.noexcept} &
 \tcode{From} and \tcode{To} shall be complete types,
 \cv{}~\tcode{void}, or arrays of unknown bound. \\ \rowsep

\indexlibraryglobal{is_layout_compatible}%
\tcode{template<class T, class U>}\br
 \tcode{struct is_layout_compatible;}                 &
 \tcode{T} and \tcode{U} are layout-compatible\iref{basic.types}    &
 \tcode{T} and \tcode{U} shall be complete types,
 \cv{}~\tcode{void},
 or arrays of unknown bound.                \\ \rowsep

\indexlibraryglobal{is_pointer_interconvertible_base_of}%
\tcode{template<class Base, class Derived>}\br
 \tcode{struct is_pointer_interconvertible_base_of;}                 &
 \tcode{Derived} is unambiguously derived from \tcode{Base}
 without regard to cv-qualifiers,
 and each object of type \tcode{Derived}
 is pointer-interconvertible\iref{basic.compound} with
 its \tcode{Base} subobject,
 or \tcode{Base} and \tcode{Derived} are not unions
 and name the same class type
 without regard to cv-qualifiers.   &
 If \tcode{Base} and \tcode{Derived} are non-union class types
 and are not (possibly cv-qualified versions of) the same type,
 \tcode{Derived} shall be a complete type.  \\ \rowsep

\indexlibraryglobal{is_invocable}%
\tcode{template<class Fn, class... ArgTypes>}\br
 \tcode{struct is_invocable;}                      &
 The expression \tcode{\placeholdernc{INVOKE}(declval<Fn>(), declval<ArgTypes>()...)}
 is well-formed when treated as an unevaluated operand                &
 \tcode{Fn} and all types in the template parameter pack \tcode{ArgTypes}
 shall be complete types, \cv{}~\tcode{void}, or
 arrays of unknown bound.                                             \\ \rowsep

\indexlibraryglobal{is_invocable_r}%
\tcode{template<class R, class Fn, class... ArgTypes>}\br
 \tcode{struct is_invocable_r;}                      &
 The expression \tcode{\placeholdernc{INVOKE}<R>(declval<Fn>(), declval<ArgTypes>()...)}
 is well-formed when treated as an unevaluated operand                &
 \tcode{Fn}, \tcode{R}, and all types in the template parameter pack \tcode{ArgTypes}
 shall be complete types, \cv{}~\tcode{void}, or
 arrays of unknown bound.                                             \\ \rowsep

\indexlibraryglobal{is_nothrow_invocable}%
\tcode{template<class Fn, class... ArgTypes>}\br
 \tcode{struct is_nothrow_invocable;}              &
 \tcode{is_invocable_v<}\br\tcode{Fn, ArgTypes...>} is \tcode{true} and
 the expression \tcode{\placeholdernc{INVOKE}(declval<Fn>(), declval<ArgTypes>()...)}
 is known not to throw any exceptions\iref{expr.unary.noexcept}       &
 \tcode{Fn} and all types in the template parameter pack \tcode{ArgTypes}
 shall be complete types, \cv{}~\tcode{void}, or
 arrays of unknown bound.                                             \\ \rowsep

\indexlibraryglobal{is_nothrow_invocable_r}%
\tcode{template<class R, class Fn, class... ArgTypes>}\br
 \tcode{struct is_nothrow_invocable_r;}              &
 \tcode{is_invocable_r_v<}\br\tcode{R, Fn, ArgTypes...>} is \tcode{true} and
 the expression \tcode{\placeholdernc{INVOKE}<R>(declval<Fn>(), declval<ArgTypes>()...)}
 is known not to throw any exceptions\iref{expr.unary.noexcept}       &
 \tcode{Fn}, \tcode{R}, and all types in the template parameter pack \tcode{ArgTypes}
 shall be complete types, \cv{}~\tcode{void}, or
 arrays of unknown bound.                                             \\
\end{libreqtab3f}

\pnum
For the purpose of defining the templates in this subclause,
a function call expression \tcode{declval<T>()} for any type \tcode{T}
is considered to be a trivial~(\ref{basic.types}, \ref{special}) function call
that is not an odr-use\iref{basic.def.odr} of \tcode{declval}
in the context of the corresponding definition
notwithstanding the restrictions of~\ref{declval}.

\pnum
\begin{example}
\begin{codeblock}
struct B {};
struct B1 : B {};
struct B2 : B {};
struct D : private B1, private B2 {};

is_base_of_v<B, D>              // \tcode{true}
is_base_of_v<const B, D>        // \tcode{true}
is_base_of_v<B, const D>        // \tcode{true}
is_base_of_v<B, const B>        // \tcode{true}
is_base_of_v<D, B>              // \tcode{false}
is_base_of_v<B&, D&>            // \tcode{false}
is_base_of_v<B[3], D[3]>        // \tcode{false}
is_base_of_v<int, int>          // \tcode{false}
\end{codeblock}
\end{example}

\indexlibraryglobal{is_convertible}%
\pnum
The predicate condition for a template specialization \tcode{is_convertible<From, To>}
shall be satisfied if and only if the return expression in the following code would be
well-formed, including any implicit conversions to the return type of the function:

\begin{codeblock}
To test() {
  return declval<From>();
}
\end{codeblock}

\begin{note}
This requirement gives well-defined results for reference types, void
types, array types, and function types.
\end{note}
Access checking is performed
in a context unrelated to \tcode{To} and \tcode{From}. Only the validity of
the immediate context of the \grammarterm{expression} of the \tcode{return} statement\iref{stmt.return}
(including initialization of the returned object or reference) is considered.
\begin{note}
The
initialization 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}

\rSec2[meta.trans]{Transformations between types}

\rSec3[meta.trans.general]{General}
\pnum
Subclause \ref{meta.trans} contains templates that may be used to transform one
type to another following some predefined rule.

\pnum
Each of the templates in \ref{meta.trans} shall be a
\oldconcept{TransformationTrait}\iref{meta.rqmts}.

\rSec3[meta.trans.cv]{Const-volatile modifications}

\begin{libreqtab2a}{Const-volatile modifications}{meta.trans.cv}
\\ \topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endhead

\indexlibraryglobal{remove_const}%
\tcode{template<class T>\br
 struct remove_const;}                  &
 The member typedef \tcode{type} names
 the same type as \tcode{T}
 except that any top-level const-qualifier has been removed.
 \begin{tailexample}
\tcode{remove_const_t<const volatile int>} evaluates
 to \tcode{volatile int}, whereas \tcode{remove_const_t<const int*>} evaluates to
 \tcode{const int*}.
\end{tailexample}
\\  \rowsep

\indexlibraryglobal{remove_volatile}%
\tcode{template<class T>\br
 struct remove_volatile;}               &
 The member typedef \tcode{type} names
 the same type as \tcode{T}
 except that any top-level volatile-qualifier has been removed.
 \begin{tailexample}
\tcode{remove_volatile_t<const volatile int>}
 evaluates to \tcode{const int},
 whereas \tcode{remove_volatile_t<volatile int*>} evaluates to \tcode{volatile int*}.
 \end{tailexample}
\\  \rowsep

\indexlibraryglobal{remove_cv}%
\tcode{template<class T>\br
 struct remove_cv;}                 &
 The member typedef \tcode{type} shall be the same as \tcode{T}
 except that any top-level cv-qualifier has been removed.
 \begin{tailexample}
\tcode{remove_cv_t<const volatile int>}
 evaluates to \tcode{int}, whereas \tcode{remove_cv_t<const volatile int*>}
 evaluates to \tcode{const volatile int*}.
\end{tailexample}
\\  \rowsep

\indexlibraryglobal{add_const}%
\tcode{template<class T>\br
 struct add_const;}                 &
 If \tcode{T} is a reference, function, or top-level const-qualified
 type, then \tcode{type} names
 the same type as \tcode{T}, otherwise
 \tcode{T const}.                                                           \\  \rowsep

\indexlibraryglobal{add_volatile}%
\tcode{template<class T>\br
 struct add_volatile;}                  &
 If \tcode{T} is a reference, function, or top-level volatile-qualified
 type, then \tcode{type} names
 the same type as \tcode{T}, otherwise
 \tcode{T volatile}.                                                            \\  \rowsep

\indexlibraryglobal{add_cv}%
\tcode{template<class T>\br
 struct add_cv;}                    &
 The member typedef \tcode{type} names
 the same type as
 \tcode{add_const_t<add_volatile_t<T>{>}}.                               \\
\end{libreqtab2a}

\rSec3[meta.trans.ref]{Reference modifications}

\begin{libreqtab2a}{Reference modifications}{meta.trans.ref}
\\ \topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endhead

\indexlibraryglobal{remove_reference}%
\tcode{template<class T>\br
 struct remove_reference;}                  &
 If \tcode{T} has type ``reference to \tcode{T1}'' then the
 member typedef \tcode{type} names \tcode{T1};
 otherwise, \tcode{type} names \tcode{T}.\\ \rowsep

\indexlibraryglobal{add_lvalue_reference}%
\tcode{template<class T>\br
 struct add_lvalue_reference;}                     &
 If \tcode{T} names a referenceable type\iref{defns.referenceable} then
 the member typedef \tcode{type} names \tcode{T\&};
 otherwise, \tcode{type} names \tcode{T}.
 \begin{tailnote}
 This rule reflects the semantics of reference collapsing\iref{dcl.ref}.
 \end{tailnote}
\\ \rowsep

\indexlibraryglobal{add_rvalue_reference}%
\tcode{template<class T>}\br
 \tcode{struct add_rvalue_reference;}    &
 If \tcode{T} names a referenceable type then
 the member typedef \tcode{type} names \tcode{T\&\&};
 otherwise, \tcode{type} names \tcode{T}.
 \begin{tailnote}
This rule reflects the semantics of reference collapsing\iref{dcl.ref}.
 For example, when a type \tcode{T} names a type \tcode{T1\&}, the type
 \tcode{add_rvalue_reference_t<T>} is not an rvalue reference.
 \end{tailnote}
\\
\end{libreqtab2a}

\rSec3[meta.trans.sign]{Sign modifications}
\begin{libreqtab2a}{Sign modifications}{meta.trans.sign}
\\ \topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endhead

\indexlibraryglobal{make_signed}%
\tcode{template<class T>}\br
 \tcode{struct make_signed;} &
 If \tcode{T} names a (possibly cv-qualified) signed integer
 type\iref{basic.fundamental} then the member typedef
 \tcode{type} names the type \tcode{T}; otherwise,
 if \tcode{T} names a (possibly cv-qualified) unsigned integer
 type then \tcode{type} names the corresponding
 signed integer type, with the same cv-qualifiers as \tcode{T};
 otherwise, \tcode{type} names the signed integer type with smallest
 rank\iref{conv.rank} for which
 \tcode{sizeof(T) == sizeof(type)}, with the same
 cv-qualifiers as \tcode{T}.\br
 \mandates \tcode{T} is an integral or enumeration type
 other than \cv~\tcode{bool}.\\ \rowsep

\indexlibraryglobal{make_unsigned}%
\tcode{template<class T>}\br
 \tcode{struct make_unsigned;} &
 If \tcode{T} names a (possibly cv-qualified) unsigned integer
 type\iref{basic.fundamental} then the member typedef
 \tcode{type} names the type \tcode{T}; otherwise,
 if \tcode{T} names a (possibly cv-qualified) signed integer
 type then \tcode{type} names the corresponding
 unsigned integer type, with the same cv-qualifiers as \tcode{T};
 otherwise, \tcode{type} names the unsigned integer type with smallest
 rank\iref{conv.rank} for which
 \tcode{sizeof(T) == sizeof(type)}, with the same
 cv-qualifiers as \tcode{T}.\br
 \mandates \tcode{T} is an integral or enumeration type
 other than \cv~\tcode{bool}.\\
\end{libreqtab2a}

\rSec3[meta.trans.arr]{Array modifications}
\begin{libreqtab2a}{Array modifications}{meta.trans.arr}
\\ \topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endhead

\indexlibraryglobal{remove_extent}%
\tcode{template<class T>\br
 struct remove_extent;}                 &
 If \tcode{T} names a type ``array of \tcode{U}'',
 the member typedef \tcode{type} shall
 be \tcode{U}, otherwise \tcode{T}.
 \begin{tailnote}
For multidimensional arrays, only the first array dimension is
 removed. For a type ``array of \tcode{const U}'', the resulting type is
 \tcode{const U}.
\end{tailnote}
\\  \rowsep

\indexlibraryglobal{remove_all_extents}%
\tcode{template<class T>\br
 struct remove_all_extents;}                &
 If \tcode{T} is ``multi-dimensional array of \tcode{U}'', the resulting member
 typedef \tcode{type} is \tcode{U}, otherwise \tcode{T}.                                       \\
\end{libreqtab2a}

\pnum
\begin{example}
\begin{codeblock}
// the following assertions hold:
assert((is_same_v<remove_extent_t<int>, int>));
assert((is_same_v<remove_extent_t<int[2]>, int>));
assert((is_same_v<remove_extent_t<int[2][3]>, int[3]>));
assert((is_same_v<remove_extent_t<int[][3]>, int[3]>));
\end{codeblock}
\end{example}

\pnum
\begin{example}
\begin{codeblock}
// the following assertions hold:
assert((is_same_v<remove_all_extents_t<int>, int>));
assert((is_same_v<remove_all_extents_t<int[2]>, int>));
assert((is_same_v<remove_all_extents_t<int[2][3]>, int>));
assert((is_same_v<remove_all_extents_t<int[][3]>, int>));
\end{codeblock}
\end{example}

\rSec3[meta.trans.ptr]{Pointer modifications}
\begin{libreqtab2a}{Pointer modifications}{meta.trans.ptr}
\\ \topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template} &   \rhdr{Comments} \\ \capsep
\endhead

\indexlibraryglobal{remove_pointer}%
\tcode{template<class T>\br
 struct remove_pointer;}                    &
 If \tcode{T} has type ``(possibly cv-qualified) pointer
 to \tcode{T1}'' then the member typedef \tcode{type}
 names \tcode{T1}; otherwise, it names \tcode{T}.\\ \rowsep

\indexlibraryglobal{add_pointer}%
\tcode{template<class T>\br
 struct add_pointer;}                       &
 If \tcode{T} names a referenceable type\iref{defns.referenceable} or a
 \cv{}~\tcode{void} type then
 the member typedef \tcode{type} names the same type as
 \tcode{remove_reference_t<T>*};
 otherwise, \tcode{type} names \tcode{T}.             \\
\end{libreqtab2a}

\rSec3[meta.trans.other]{Other transformations}

\begin{libreqtab2a}{Other transformations}{meta.trans.other}
\\ \topline
\lhdr{Template}   &   \rhdr{Comments} \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Template}   &   \rhdr{Comments} \\ \capsep
\endhead

\indexlibraryglobal{type_identity}%
\tcode{template<class T>\br
 struct type_identity;}
 &
 The member typedef \tcode{type} names the type \tcode{T}. \\ \rowsep

\indexlibraryglobal{aligned_storage}%
\tcode{template<size_t Len,\br
 size_t Align\br
 = \textit{default-alignment}>\br
 struct aligned_storage;}
 &
 The value of \textit{default-alignment} shall be the most
 stringent alignment requirement for any object type whose size
 is no greater than \tcode{Len}\iref{basic.types}.
 The member typedef \tcode{type} shall be a trivial standard-layout type
 suitable for use as uninitialized storage for any object whose size
 is at most \tcode{Len} and whose alignment is a divisor of \tcode{Align}.\br
 \mandates \tcode{Len} is not zero. \tcode{Align} is equal to
 \tcode{alignof(T)} for some type \tcode{T} or to \textit{default-alignment}.\\ \rowsep

\indexlibraryglobal{aligned_union}%
\tcode{template<size_t Len,\br
  class... Types>\br
  struct aligned_union;}
  &
  The member typedef \tcode{type} shall be a trivial standard-layout type suitable for use as
  uninitialized storage for any object whose type is listed in \tcode{Types};
  its size shall be at least \tcode{Len}. The static member \tcode{alignment_value}
  shall be an integral constant of type \tcode{size_t} whose value is the
  strictest alignment of all types listed in \tcode{Types}.\br
 \mandates At least one type is provided.
  Each type in the template parameter pack \tcode{Types}
  is a complete object type.
  \\ \rowsep

\indexlibraryglobal{remove_cvref}%
\tcode{template<class T>\br struct remove_cvref;}
 &
 The member typedef \tcode{type} names the same type as
 \tcode{remove_cv_t<remove_reference_t<T>>}.
 \\ \rowsep

\indexlibraryglobal{decay}%
\tcode{template<class T>\br struct decay;}
 &
 Let \tcode{U} be \tcode{remove_reference_t<T>}. If \tcode{is_array_v<U>} is
 \tcode{true}, the member typedef \tcode{type} equals
 \tcode{remove_extent_t<U>*}. If \tcode{is_function_v<U>} is \tcode{true},
 the member typedef \tcode{type} equals \tcode{add_pointer_t<U>}. Otherwise
 the member typedef \tcode{type} equals \tcode{remove_cv_t<U>}.
\begin{tailnote}
This behavior is similar to the lvalue-to-rvalue\iref{conv.lval},
array-to-pointer\iref{conv.array}, and function-to-pointer\iref{conv.func}
conversions applied when an lvalue is used as an rvalue, but also
strips cv-qualifiers from class types in order to more closely model by-value
argument passing.
\end{tailnote}
 \\ \rowsep

\indexlibraryglobal{enable_if}%
\tcode{template<bool B, class T = void>} \tcode{struct enable_if;}
 &
 If \tcode{B} is \tcode{true}, the member typedef \tcode{type}
 shall equal \tcode{T}; otherwise, there shall be no member
 \tcode{type}. \\ \rowsep

\tcode{template<bool B, class T,}
 \tcode{class F>}\br
 \tcode{struct conditional;}
 &
 If \tcode{B} is \tcode{true},  the member typedef \tcode{type} shall equal \tcode{T}.
 If \tcode{B} is \tcode{false}, the member typedef \tcode{type} shall equal \tcode{F}. \\ \rowsep

 \tcode{template<class... T>} \tcode{struct common_type;}
 &
 Unless this trait is specialized (as specified in Note B, below),
 the member \tcode{type} is defined or omitted as specified in Note A, below.
 If it is omitted, there shall be no member \tcode{type}.
 Each type in the template parameter pack \tcode{T} shall be
 complete, \cv{}~\tcode{void}, or an array of unknown bound. \\ \rowsep

\indexlibraryglobal{basic_common_reference}%
\tcode{template<class, class,}
 \hspace*{2ex}\tcode{template<class> class,}
 \hspace*{2ex}\tcode{template<class> class>}
 \tcode{struct}
 \hspace*{2ex}\tcode{basic_common_reference;}
 &
 Unless this trait is specialized (as specified in Note D, below),
 there shall be no member \tcode{type}. \\ \rowsep

\indexlibraryglobal{common_reference}%
\tcode{template<class... T>} \tcode{struct common_reference;}
 &
 The member \grammarterm{typedef-name} \tcode{type} is defined or omitted
 as specified in Note C, below. Each type in the parameter pack \tcode{T} shall
 be complete or \cv{} \tcode{void}. \\ \rowsep

\indexlibraryglobal{underlying_type}%
\tcode{template<class T>}\br
 \tcode{struct underlying_type;}
 &
 If \tcode{T} is an enumeration type, the member typedef \tcode{type} names
 the underlying type of \tcode{T}\iref{dcl.enum};
 otherwise, there is no member \tcode{type}.\br
 \mandates \tcode{T} is not an incomplete enumeration type. \\ \rowsep

\tcode{template<class Fn,}\br
 \tcode{class... ArgTypes>}\br
 \tcode{struct invoke_result;}
 &
 If the expression \tcode{\placeholdernc{INVOKE}(declval<Fn>(), declval<ArgTypes>()...)}
 is well-formed when treated as an unevaluated operand\iref{expr.prop},
 the member typedef \tcode{type} names the type
 \tcode{decltype(\placeholdernc{INVOKE}(declval<Fn>(), declval<ArgTypes>()...))};
 otherwise, there shall be no member \tcode{type}. Access checking is
 performed as if in a context unrelated to \tcode{Fn} and
 \tcode{ArgTypes}. 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}
\br
 \expects \tcode{Fn} and all types in the template parameter pack \tcode{ArgTypes}
 are complete types, \cv{}~\tcode{void}, or arrays of
 unknown bound.\\ \rowsep

\indexlibraryglobal{unwrap_reference}%
\tcode{template<class T>} \tcode{struct unwrap_reference;}
 &
 If \tcode{T} is
 a specialization \tcode{reference_wrapper<X>} for some type \tcode{X},
 the member typedef \tcode{type} of \tcode{unwrap_reference<T>} is \tcode{X\&},
 otherwise it is \tcode{T}. \\ \rowsep

\indexlibraryglobal{unwrap_ref_decay}%
\tcode{template<class T>} \tcode{unwrap_ref_decay;}
 &
 The member typedef \tcode{type} of \tcode{unwrap_ref_decay<T>}
 denotes the type \tcode{unwrap_reference_t<decay_t<T>>}.\\
\end{libreqtab2a}

\indexlibraryglobal{aligned_storage}%
\pnum
\begin{note}
A typical implementation would define \tcode{aligned_storage} as:

\begin{codeblock}
template<size_t Len, size_t Alignment>
struct aligned_storage {
  typedef struct {
    alignas(Alignment) unsigned char __data[Len];
  } type;
};
\end{codeblock}
\end{note}

\pnum
In addition to being available via inclusion
of the \tcode{<type_traits>} header, the templates
\tcode{unwrap_reference},
\tcode{unwrap_ref_decay},
\tcode{unwrap_reference_t}, and
\tcode{unwrap_ref_decay_t}
are available
when the header \tcode{<func\-tional>}\iref{functional.syn} is included.

\indexlibraryglobal{common_type}%
\pnum
Let:
\begin{itemize}
\item \tcode{\placeholdernc{CREF}(A)} be
  \tcode{add_lvalue_reference_t<const remove_reference_t<A>{}>},
\item \tcode{\placeholdernc{XREF}(A)} denote a unary alias template \tcode{T}
  such that \tcode{T<U>} denotes the same type as \tcode{U} with the addition
  of \tcode{A}'s cv and reference qualifiers, for a non-reference cv-unqualified
  type \tcode{U},
\item \tcode{\placeholdernc{COPYCV}(FROM, TO)} be an alias for type \tcode{TO}
  with the addition of \tcode{FROM}'s top-level cv-qualifiers,
  \begin{example}
    \tcode{\placeholdernc{COPYCV}(const int, volatile short)} is an alias for
    \tcode{const volatile short}.
  \end{example}
\item \tcode{\placeholdernc{COND-RES}(X, Y)} be
  \tcode{decltype(false ?\ declval<X(\&)()>()() :\ declval<Y(\&)()>()())}.
\end{itemize}
Given types \tcode{A} and \tcode{B},
let \tcode{X} be \tcode{remove_reference_t<A>},
let \tcode{Y} be \tcode{remove_reference_t<B>}, and
let \tcode{\placeholdernc{COMMON-\brk{}REF}(A, B)} be:
\begin{itemize}
\item If \tcode{A} and \tcode{B} are both lvalue reference types,
  \tcode{\placeholdernc{COMMON-REF}(A, B)} is
  \tcode{\placeholdernc{COND-RES}(\placeholdernc{COPYCV}(X, Y) \&,
    \placeholdernc{COPYCV}(\brk{}Y, X) \&)} if that type exists
  and is a reference type.
\item Otherwise, let \tcode{C} be
  \tcode{remove_reference_t<\placeholdernc{COMMON-REF}(X\&, Y\&)>\&\&}.
  If \tcode{A} and \tcode{B} are both rvalue reference types,
  \tcode{C} is well-formed, and
  \tcode{is_convertible_v<A, C> \&\& is_convertible_v<B, C>} is \tcode{true},
  then \tcode{\placeholdernc{COMMON-REF}(A, B)} is \tcode{C}.
\item Otherwise, let \tcode{D} be
  \tcode{\placeholdernc{COMMON-REF}(const X\&, Y\&)}. If \tcode{A} is an rvalue
  reference and \tcode{B} is an lvalue reference and \tcode{D} is
  well-formed and \tcode{is_convertible_v<A, D>} is
  \tcode{true}, then \tcode{\placeholdernc{COMMON-REF}(A, B)} is \tcode{D}.
\item Otherwise, if \tcode{A} is an lvalue reference and \tcode{B}
  is an rvalue reference, then \tcode{\placeholdernc{COMMON-REF}(A, B)} is
  \tcode{\placeholdernc{COMMON-REF}(B, A)}.
\item Otherwise, \tcode{\placeholdernc{COMMON-REF}(A, B)} is ill-formed.
\end{itemize}

If any of the types computed above is ill-formed, then
\tcode{\placeholdernc{COMMON-REF}(A, B)} is ill-formed.

\pnum
Note A:
For the \tcode{common_type} trait applied to a template parameter pack \tcode{T} of types,
the member \tcode{type} shall be either defined or not present as follows:

\begin{itemize}
\item If \tcode{sizeof...(T)} is zero, there shall be no member \tcode{type}.

\item If \tcode{sizeof...(T)} is one, let \tcode{T0} denote the sole type
constituting the pack \tcode{T}.
The member \grammarterm{typedef-name} \tcode{type} shall denote the same
type, if any, as \tcode{common_type_t<T0, T0>};
otherwise there shall be no member \tcode{type}.

\item If \tcode{sizeof...(T)} is two,
let the first and second types constituting \tcode{T} be denoted
by \tcode{T1} and \tcode{T2}, respectively, and
let \tcode{D1} and \tcode{D2} denote
the same types as \tcode{decay_t<T1>} and \tcode{decay_t<T2>}, respectively.
  \begin{itemize}
  \item If \tcode{is_same_v<T1, D1>} is \tcode{false} or
     \tcode{is_same_v<T2, D2>} is \tcode{false},
     let \tcode{C} denote the same type, if any,
     as \tcode{common_type_t<D1, D2>}.
  \item
    \begin{note}
      None of the following will apply if there is a specialization
      \tcode{common_type<D1, D2>}.
    \end{note}
  \item Otherwise, if
\begin{codeblock}
decay_t<decltype(false ? declval<D1>() : declval<D2>())>
\end{codeblock}
    denotes a valid type, let \tcode{C} denote that type.
  \item Otherwise, if
    \tcode{\placeholdernc{COND-RES}(\placeholdernc{CREF}(D1),
      \placeholdernc{CREF}(D2))}
    denotes a type, let \tcode{C} denote the type
    \tcode{decay_t<\placeholdernc{COND-RES}(\placeholdernc{CREF}(D1),
      \placeholdernc{CREF}(D2))>}.
  \end{itemize}
In either case, the member \grammarterm{typedef-name} \tcode{type} shall denote
the same type, if any, as \tcode{C}.
Otherwise, there shall be no member \tcode{type}.

\item If \tcode{sizeof...(T)} is greater than two,
let \tcode{T1}, \tcode{T2}, and \tcode{R}, respectively,
denote the first, second, and (pack of) remaining types constituting \tcode{T}.
Let \tcode{C} denote the same type, if any, as \tcode{common_type_t<T1, T2>}.
If there is such a type \tcode{C}, the member \grammarterm{typedef-name} \tcode{type}
shall denote the same type, if any, as \tcode{common_type_t<C, R...>}.
Otherwise, there shall be no member \tcode{type}.
\end{itemize}

\pnum
Note B: Notwithstanding the provisions of \ref{meta.type.synop}, and
pursuant to \ref{namespace.std},
a program may specialize \tcode{common_type<T1, T2>}
for types \tcode{T1} and \tcode{T2} such that
\tcode{is_same_v<T1, decay_t<T1>>} and
\tcode{is_same_v<T2, decay_t<T2>>} are each \tcode{true}.
\begin{note}
Such specializations are needed when only explicit conversions
are desired between the template arguments.
\end{note}
Such a specialization need not have a member named \tcode{type},
but if it does, that member shall be a \grammarterm{typedef-name}
for an accessible and unambiguous cv-unqualified non-reference type \tcode{C}
to which each of the types \tcode{T1} and \tcode{T2} is explicitly convertible.
Moreover, \tcode{common_type_t<T1, T2>} shall denote
the same type, if any, as does \tcode{common_type_t<T2, T1>}.
No diagnostic is required for a violation of this Note's rules.

\pnum
Note C: For the \tcode{common_reference} trait applied to a parameter pack
\tcode{T} of types, the member \tcode{type} shall be either defined or not
present as follows:
\begin{itemize}
\item If \tcode{sizeof...(T)} is zero, there shall be no member \tcode{type}.

\item Otherwise, if \tcode{sizeof...(T)} is one, let \tcode{T0} denote the sole
  type in the pack \tcode{T}. The member typedef \tcode{type} shall denote the
  same type as \tcode{T0}.

\item Otherwise, if \tcode{sizeof...(T)} is two, let \tcode{T1} and \tcode{T2}
  denote the two types in the pack \tcode{T}. Then
  \begin{itemize}
  \item If \tcode{T1} and \tcode{T2} are reference types and
    \tcode{\placeholdernc{COMMON-REF}(T1, T2)} is well-formed, then the member
    typedef \tcode{type} denotes that type.

  \item Otherwise, if
    \tcode{basic_common_reference<remove_cvref_t<T1>, remove_cvref_t<T2>,
      \brk{}\placeholdernc{XREF}(\brk{}T1), \placeholdernc{XREF}(T2)>::type}
    is well-formed, then the member typedef \tcode{type} denotes that type.

  \item Otherwise, if \tcode{\placeholdernc{COND-RES}(T1, T2)} is well-formed,
    then the member typedef \tcode{type} denotes that type.

  \item Otherwise, if \tcode{common_type_t<T1, T2>} is well-formed, then the
    member typedef \tcode{type} denotes that type.

  \item Otherwise, there shall be no member \tcode{type}.
  \end{itemize}

\item Otherwise, if \tcode{sizeof...(T)} is greater than two, let \tcode{T1},
  \tcode{T2}, and \tcode{Rest}, respectively, denote the first, second, and
  (pack of) remaining types comprising \tcode{T}. Let \tcode{C} be the type
  \tcode{common_reference_t<T1, T2>}. Then:
  \begin{itemize}
  \item If there is such a type \tcode{C}, the member typedef \tcode{type} shall
    denote the same type, if any, as \tcode{common_reference_t<C, Rest...>}.

  \item Otherwise, there shall be no member \tcode{type}.
  \end{itemize}
\end{itemize}

\pnum
Note D: Notwithstanding the provisions of \ref{meta.type.synop}, and
pursuant to \ref{namespace.std}, a program may partially specialize
\tcode{basic_common_reference<T, U, TQual, UQual>}
for types \tcode{T} and \tcode{U} such that
\tcode{is_same_v<T, decay_t<T>{>}} and
\tcode{is_same_v<U, decay_t<U>{>}} are each \tcode{true}.
\begin{note}
Such specializations
can be used to influence the result of \tcode{common_reference}, and
are needed when only explicit conversions are desired
between the template arguments.
\end{note}
Such a specialization need not have a member named \tcode{type}, but if it does,
that member shall be a \grammarterm{typedef-name} for an accessible and
unambiguous type \tcode{C} to which each of the types \tcode{TQual<T>} and
\tcode{UQual<U>} is convertible.
Moreover, \tcode{basic_common_reference<T, U, TQual, UQual>::type} shall denote
the same type, if any, as does
\tcode{basic_common_reference<U, T, UQual, TQual>::type}.
No diagnostic is required for a violation of these rules.

\pnum
\begin{example}
Given these definitions:
\begin{codeblock}
using PF1 = bool  (&)();
using PF2 = short (*)(long);

struct S {
  operator PF2() const;
  double operator()(char, int&);
  void fn(long) const;
  char data;
};

using PMF = void (S::*)(long) const;
using PMD = char  S::*;
\end{codeblock}
the following assertions will hold:
\begin{codeblock}
static_assert(is_same_v<invoke_result_t<S, int>, short>);
static_assert(is_same_v<invoke_result_t<S&, unsigned char, int&>, double>);
static_assert(is_same_v<invoke_result_t<PF1>, bool>);
static_assert(is_same_v<invoke_result_t<PMF, unique_ptr<S>, int>, void>);
static_assert(is_same_v<invoke_result_t<PMD, S>, char&&>);
static_assert(is_same_v<invoke_result_t<PMD, const S*>, const char&>);
\end{codeblock}
\end{example}

\rSec2[meta.logical]{Logical operator traits}

\pnum
This subclause describes type traits for applying logical operators
to other type traits.

\indexlibraryglobal{conjunction}%
\begin{itemdecl}
template<class... B> struct conjunction : @\seebelow@ { };
\end{itemdecl}

\begin{itemdescr}
\pnum
The class template \tcode{conjunction}
forms the logical conjunction of its template type arguments.

\pnum
For a specialization \tcode{conjunction<$\tcode{B}_{1}$, $\dotsc$, $\tcode{B}_{N}$>},
if there is a template type argument $\tcode{B}_{i}$
for which \tcode{bool($\tcode{B}_{i}$::value)} is \tcode{false},
then instantiating \tcode{conjunction<$\tcode{B}_{1}$, $\dotsc$, $\tcode{B}_{N}$>::value}
does not require the instantiation of \tcode{$\tcode{B}_{j}$::value} for $j > i$.
\begin{note}
This is analogous to the short-circuiting behavior of
the built-in operator \tcode{\&\&}.
\end{note}

\pnum
Every template type argument
for which \tcode{$\tcode{B}_{i}$::value} is instantiated
shall be usable as a base class and
shall have a member \tcode{value} which
is convertible to \tcode{bool},
is not hidden, and
is unambiguously available in the type.

\pnum
The specialization \tcode{conjunction<$\tcode{B}_{1}$, $\dotsc$, $\tcode{B}_{N}$>}
has a public and unambiguous base that is either
\begin{itemize}
\item
the first type $\tcode{B}_{i}$ in the list \tcode{true_type, $\tcode{B}_{1}$, $\dotsc$, $\tcode{B}_{N}$}
for which \tcode{bool($\tcode{B}_{i}$::value)} is \tcode{false}, or
\item
if there is no such $\tcode{B}_{i}$, the last type in the list.
\end{itemize}
\begin{note}
This means a specialization of \tcode{conjunction}
does not necessarily inherit from
either \tcode{true_type} or \tcode{false_type}.
\end{note}

\pnum
The member names of the base class, other than \tcode{conjunction} and
\tcode{operator=}, shall not be hidden and shall be unambiguously available
in \tcode{conjunction}.
\end{itemdescr}

\indexlibraryglobal{disjunction}%
\begin{itemdecl}
template<class... B> struct disjunction : @\seebelow@ { };
\end{itemdecl}

\begin{itemdescr}
\pnum
The class template \tcode{disjunction}
forms the logical disjunction of its template type arguments.

\pnum
For a specialization \tcode{disjunction<$\tcode{B}_{1}$, $\dotsc$, $\tcode{B}_{N}$>},
if there is a template type argument $\tcode{B}_{i}$
for which \tcode{bool($\tcode{B}_{i}$::value)} is \tcode{true},
then instantiating \tcode{disjunction<$\tcode{B}_{1}$, $\dotsc$, $\tcode{B}_{N}$>::value}
does not require the instantiation of \tcode{$\tcode{B}_{j}$::value} for $j > i$.
\begin{note}
This is analogous to the short-circuiting behavior of
the built-in operator \tcode{||}.
\end{note}

\pnum
Every template type argument
for which \tcode{$\tcode{B}_{i}$::value} is instantiated
shall be usable as a base class and
shall have a member \tcode{value} which
is convertible to \tcode{bool},
is not hidden, and
is unambiguously available in the type.

\pnum
The specialization \tcode{disjunction<$\tcode{B}_{1}$, $\dotsc$, $\tcode{B}_{N}$>}
has a public and unambiguous base that is either
\begin{itemize}
\item the first type $\tcode{B}_{i}$ in the list \tcode{false_type, $\tcode{B}_{1}$, $\dotsc$, $\tcode{B}_{N}$}
for which \tcode{bool($\tcode{B}_{i}$::value)} is \tcode{true}, or
\item if there is no such $\tcode{B}_{i}$, the last type in the list.
\end{itemize}
\begin{note}
This means a specialization of \tcode{disjunction}
does not necessarily inherit from
either \tcode{true_type} or \tcode{false_type}.
\end{note}

\pnum
The member names of the base class,
other than \tcode{disjunction} and \tcode{operator=},
shall not be hidden and shall be unambiguously available in \tcode{disjunction}.
\end{itemdescr}

\indexlibraryglobal{negation}%
\begin{itemdecl}
template<class B> struct negation : @\seebelow@ { };
\end{itemdecl}

\begin{itemdescr}
\pnum
The class template \tcode{negation}
forms the logical negation of its template type argument.
The type \tcode{negation<B>}
is a \oldconcept{UnaryTypeTrait} with a base characteristic of \tcode{bool_constant<!bool(B::\brk{}value)>}.
\end{itemdescr}

\rSec2[meta.member]{Member relationships}

\indexlibraryglobal{is_pointer_interconvertible_with_class}
\begin{itemdecl}
template<class S, class M>
  constexpr bool is_pointer_interconvertible_with_class(M S::*m) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{S} is a complete type.

\pnum
\returns
\tcode{true} if and only if
 \tcode{S} is a standard-layout type,
 \tcode{M} is an object type,
 \tcode{m} is not null,
 and each object \tcode{s} of type \tcode{S}
 is pointer-interconvertible\iref{basic.compound}
 with its subobject \tcode{s.*m}.
\end{itemdescr}

\indexlibraryglobal{is_corresponding_member}
\begin{itemdecl}
template<class S1, class S2, class M1, class M2>
  constexpr bool is_corresponding_member(M1 S1::*m1, M2 S2::*m2) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{S1} and \tcode{S2} are complete types.

\pnum
\returns
\tcode{true} if and only if
 \tcode{S1} and \tcode{S2} are standard-layout types,
 \tcode{M1} and \tcode{M2} are object types,
 \tcode{m1} and \tcode{m2} are not null,
 and \tcode{m1} and \tcode{m2} point to corresponding members of
 the common initial sequence\iref{class.mem} of \tcode{S1} and \tcode{S2}.
\end{itemdescr}

\pnum
\begin{note}
The type of a pointer-to-member expression \tcode{\&C::b}
is not always a pointer to member of \tcode{C},
leading to potentially surprising results
when using these functions in conjunction with inheritance.
\begin{example}
\begin{codeblock}
struct A { int a; };                    // a standard-layout class
struct B { int b; };                    // a standard-layout class
struct C: public A, public B { };       // not a standard-layout class

static_assert( is_pointer_interconvertible_with_class( &C::b ) );
  // Succeeds because, despite its appearance, \tcode{\&C::b} has type
  // ``pointer to member of \tcode{B} of type \tcode{int}''.
static_assert( is_pointer_interconvertible_with_class<C>( &C::b ) );
  // Forces the use of class \tcode{C}, and fails.

static_assert( is_corresponding_member( &C::a, &C::b ) );
  // Succeeds because, despite its appearance, \tcode{\&C::a} and \tcode{\&C::b} have types
  // ``pointer to member of \tcode{A} of type \tcode{int}'' and
  // ``pointer to member of \tcode{B} of type \tcode{int}'', respectively.
static_assert( is_corresponding_member<C, C>( &C::a, &C::b ) );
  // Forces the use of class \tcode{C}, and fails.
\end{codeblock}
\end{example}
\end{note}

\rSec2[meta.const.eval]{Constant evaluation context}
\begin{itemdecl}
constexpr bool is_constant_evaluated() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if and only if evaluation of the call occurs
within the evaluation of an expression or conversion
that is manifestly constant-evaluated\iref{expr.const}.

\pnum
\begin{example}
\begin{codeblock}
constexpr void f(unsigned char *p, int n) {
  if (std::is_constant_evaluated()) {           // should not be a constexpr if statement
    for (int k = 0; k<n; ++k) p[k] = 0;
  } else {
    memset(p, 0, n);                            // not a core constant expression
  }
}
\end{codeblock}
\end{example}
\end{itemdescr}

\rSec1[ratio]{Compile-time rational arithmetic}

\rSec2[ratio.general]{In general}

\pnum
\indexlibraryglobal{ratio}%
Subclause~\ref{ratio} describes the ratio library. It provides a class template
\tcode{ratio} which exactly represents any finite rational number with a
numerator and denominator representable by compile-time constants of type
\tcode{intmax_t}.

\pnum
Throughout subclause~\ref{ratio}, the names of template parameters are used to express
type requirements. If a template parameter is named \tcode{R1} or \tcode{R2},
and the template argument is not a specialization of the \tcode{ratio} template,
the program is ill-formed.

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

\indexheader{ratio}%
\begin{codeblockdigitsep}
namespace std {
  // \ref{ratio.ratio}, class template \tcode{ratio}
  template<intmax_t N, intmax_t D = 1> class ratio;

  // \ref{ratio.arithmetic}, ratio arithmetic
  template<class R1, class R2> using ratio_add = @\seebelow@;
  template<class R1, class R2> using ratio_subtract = @\seebelow@;
  template<class R1, class R2> using ratio_multiply = @\seebelow@;
  template<class R1, class R2> using ratio_divide = @\seebelow@;

  // \ref{ratio.comparison}, ratio comparison
  template<class R1, class R2> struct ratio_equal;
  template<class R1, class R2> struct ratio_not_equal;
  template<class R1, class R2> struct ratio_less;
  template<class R1, class R2> struct ratio_less_equal;
  template<class R1, class R2> struct ratio_greater;
  template<class R1, class R2> struct ratio_greater_equal;

  template<class R1, class R2>
    inline constexpr bool @\libglobal{ratio_equal_v}@ = ratio_equal<R1, R2>::value;
  template<class R1, class R2>
    inline constexpr bool @\libglobal{ratio_not_equal_v}@ = ratio_not_equal<R1, R2>::value;
  template<class R1, class R2>
    inline constexpr bool @\libglobal{ratio_less_v}@ = ratio_less<R1, R2>::value;
  template<class R1, class R2>
    inline constexpr bool @\libglobal{ratio_less_equal_v}@ = ratio_less_equal<R1, R2>::value;
  template<class R1, class R2>
    inline constexpr bool @\libglobal{ratio_greater_v}@ = ratio_greater<R1, R2>::value;
  template<class R1, class R2>
    inline constexpr bool @\libglobal{ratio_greater_equal_v}@ = ratio_greater_equal<R1, R2>::value;

  // \ref{ratio.si}, convenience SI typedefs
  using yocto = ratio<1, 1'000'000'000'000'000'000'000'000>;  // see below
  using zepto = ratio<1,     1'000'000'000'000'000'000'000>;  // see below
  using atto  = ratio<1,         1'000'000'000'000'000'000>;
  using femto = ratio<1,             1'000'000'000'000'000>;
  using pico  = ratio<1,                 1'000'000'000'000>;
  using nano  = ratio<1,                     1'000'000'000>;
  using micro = ratio<1,                         1'000'000>;
  using milli = ratio<1,                             1'000>;
  using centi = ratio<1,                               100>;
  using deci  = ratio<1,                                10>;
  using deca  = ratio<                               10, 1>;
  using hecto = ratio<                              100, 1>;
  using kilo  = ratio<                            1'000, 1>;
  using mega  = ratio<                        1'000'000, 1>;
  using giga  = ratio<                    1'000'000'000, 1>;
  using tera  = ratio<                1'000'000'000'000, 1>;
  using peta  = ratio<            1'000'000'000'000'000, 1>;
  using exa   = ratio<        1'000'000'000'000'000'000, 1>;
  using zetta = ratio<    1'000'000'000'000'000'000'000, 1>;  // see below
  using yotta = ratio<1'000'000'000'000'000'000'000'000, 1>;  // see below
}
\end{codeblockdigitsep}

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

\indexlibraryglobal{ratio}%
\begin{codeblock}
namespace std {
  template<intmax_t N, intmax_t D = 1> class ratio {
  public:
    static constexpr intmax_t num;
    static constexpr intmax_t den;
    using type = ratio<num, den>;
  };
}
\end{codeblock}

\pnum
\indextext{signed integer representation!two's complement}%
If the template argument \tcode{D} is zero or the absolute values of either of the
template arguments \tcode{N} and \tcode{D} is not representable by type
\tcode{intmax_t}, the program is ill-formed.
\begin{note}
These rules ensure that infinite
ratios are avoided and that for any negative input, there exists a representable value
of its absolute value which is positive.
This excludes the most negative value.
\end{note}

\pnum
The static data members \tcode{num} and \tcode{den} shall have the following values,
where \tcode{gcd} represents the greatest common divisor of the absolute values of
\tcode{N} and \tcode{D}:

\begin{itemize}
\item \tcode{num} shall have the value \tcode{sign(N) * sign(D) * abs(N) / gcd}.
\item \tcode{den} shall have the value \tcode{abs(D) / gcd}.
\end{itemize}

\rSec2[ratio.arithmetic]{Arithmetic on \tcode{ratio}{s}}

\pnum
Each of the alias templates \tcode{ratio_add}, \tcode{ratio_subtract}, \tcode{ratio_multiply},
and \tcode{ratio_divide} denotes the result of an arithmetic computation on two
\tcode{ratio}{s} \tcode{R1} and \tcode{R2}. With \tcode{X} and \tcode{Y} computed (in the
absence of arithmetic overflow) as specified by \tref{ratio.arithmetic}, each alias
denotes a \tcode{ratio<U, V>} such that \tcode{U} is the same as \tcode{ratio<X, Y>::num} and
\tcode{V} is the same as \tcode{ratio<X, Y>::den}.

\pnum
If it is not possible to represent \tcode{U} or \tcode{V} with \tcode{intmax_t}, the program is
ill-formed. Otherwise, an implementation should yield correct values of \tcode{U} and
\tcode{V}. If it is not possible to represent \tcode{X} or \tcode{Y} with \tcode{intmax_t}, the
program is ill-formed unless the implementation yields correct values of \tcode{U} and
\tcode{V}.

\begin{floattable}{Expressions used to perform ratio arithmetic}{ratio.arithmetic}
{lll}
\topline
\lhdr{Type}                     &
  \chdr{Value of \tcode{X}}     &
  \rhdr{Value of \tcode{Y}}     \\ \rowsep

\tcode{ratio_add<R1, R2>}       &
  \tcode{R1::num * R2::den +}   &
  \tcode{R1::den * R2::den}     \\
                                &
  \tcode{R2::num * R1::den}     &
                                \\ \rowsep

\tcode{ratio_subtract<R1, R2>}  &
  \tcode{R1::num * R2::den -}   &
  \tcode{R1::den * R2::den}     \\
                                &
  \tcode{R2::num * R1::den}     &
                                \\ \rowsep

\tcode{ratio_multiply<R1, R2>}  &
  \tcode{R1::num * R2::num}     &
  \tcode{R1::den * R2::den}     \\ \rowsep

\tcode{ratio_divide<R1, R2>}    &
  \tcode{R1::num * R2::den}     &
  \tcode{R1::den * R2::num}     \\
\end{floattable}

\pnum
\begin{example}
\begin{codeblock}
static_assert(ratio_add<ratio<1, 3>, ratio<1, 6>>::num == 1, "1/3+1/6 == 1/2");
static_assert(ratio_add<ratio<1, 3>, ratio<1, 6>>::den == 2, "1/3+1/6 == 1/2");
static_assert(ratio_multiply<ratio<1, 3>, ratio<3, 2>>::num == 1, "1/3*3/2 == 1/2");
static_assert(ratio_multiply<ratio<1, 3>, ratio<3, 2>>::den == 2, "1/3*3/2 == 1/2");

// The following cases may cause the program to be ill-formed under some implementations
static_assert(ratio_add<ratio<1, INT_MAX>, ratio<1, INT_MAX>>::num == 2,
  "1/MAX+1/MAX == 2/MAX");
static_assert(ratio_add<ratio<1, INT_MAX>, ratio<1, INT_MAX>>::den == INT_MAX,
  "1/MAX+1/MAX == 2/MAX");
static_assert(ratio_multiply<ratio<1, INT_MAX>, ratio<INT_MAX, 2>>::num == 1,
  "1/MAX * MAX/2 == 1/2");
static_assert(ratio_multiply<ratio<1, INT_MAX>, ratio<INT_MAX, 2>>::den == 2,
  "1/MAX * MAX/2 == 1/2");
\end{codeblock}

\end{example}

\rSec2[ratio.comparison]{Comparison of \tcode{ratio}{s}}

\indexlibraryglobal{ratio_equal}%
\begin{itemdecl}
template<class R1, class R2>
  struct ratio_equal : bool_constant<R1::num == R2::num && R1::den == R2::den> { };
\end{itemdecl}

\indexlibraryglobal{ratio_not_equal}%
\begin{itemdecl}
template<class R1, class R2>
  struct ratio_not_equal : bool_constant<!ratio_equal_v<R1, R2>> { };
\end{itemdecl}

\indexlibraryglobal{ratio_less}%
\begin{itemdecl}
template<class R1, class R2>
  struct ratio_less : bool_constant<@\seebelow@> { };
\end{itemdecl}

\begin{itemdescr}
\pnum
If \tcode{R1::num} $\times$ \tcode{R2::den} is less than \tcode{R2::num} $\times$ \tcode{R1::den},
\tcode{ratio_less<R1, R2>} shall be
derived from \tcode{bool_constant<true>}; otherwise it shall be derived from
\tcode{bool_constant<false>}. Implementations may use other algorithms to
compute this relationship to avoid overflow. If overflow occurs, the program is ill-formed.
\end{itemdescr}

\indexlibraryglobal{ratio_less_equal}%
\begin{itemdecl}
template<class R1, class R2>
  struct ratio_less_equal : bool_constant<!ratio_less_v<R2, R1>> { };
\end{itemdecl}

\indexlibraryglobal{ratio_greater}%
\begin{itemdecl}
template<class R1, class R2>
  struct ratio_greater : bool_constant<ratio_less_v<R2, R1>> { };
\end{itemdecl}

\indexlibraryglobal{ratio_greater_equal}%
\begin{itemdecl}
template<class R1, class R2>
  struct ratio_greater_equal : bool_constant<!ratio_less_v<R1, R2>> { };
\end{itemdecl}

\rSec2[ratio.si]{SI types for \tcode{ratio}}

\pnum
For each of the \grammarterm{typedef-name}{s} \tcode{yocto}, \tcode{zepto},
\tcode{zetta}, and \tcode{yotta}, if both of the constants used in its
specification are representable by \tcode{intmax_t}, the typedef is
defined; if either of the constants is not representable by \tcode{intmax_t},
the typedef is not defined.

\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}
Because different parallel architectures might require idiosyncratic
parameters for efficient execution, implementations
can provide additional execution policies to those described in this
standard as extensions.
\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> inline 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 uncaught exception,
\tcode{terminate()} is called.
\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 uncaught exception,
\tcode{terminate()} is called.
\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 uncaught exception,
\tcode{terminate()} is called.
\end{itemdescr}

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

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

\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 uncaught exception,
\tcode{terminate()} is called.

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

\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 {
    char* ptr;
    errc ec;
    friend bool operator==(const to_chars_result&, const to_chars_result&) = default;
  };

  to_chars_result to_chars(char* first, char* last, @\seebelow@ value, int base = 10);
  to_chars_result to_chars(char* first, char* last, bool value, int base = 10) = delete;

  to_chars_result to_chars(char* first, char* last, float value);
  to_chars_result to_chars(char* first, char* last, double value);
  to_chars_result to_chars(char* first, char* last, long double value);

  to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
  to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
  to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);

  to_chars_result to_chars(char* first, char* last, float value,
                           chars_format fmt, int precision);
  to_chars_result to_chars(char* first, char* last, double value,
                           chars_format fmt, int precision);
  to_chars_result to_chars(char* first, char* last, long double 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 {
    const char* ptr;
    errc ec;
    friend bool operator==(const from_chars_result&, const from_chars_result&) = default;
  };

  from_chars_result from_chars(const char* first, const char* last,
                               @\seebelow@& value, int base = 10);

  from_chars_result from_chars(const char* first, const char* last, float& value,
                               chars_format fmt = chars_format::general);
  from_chars_result from_chars(const char* first, const char* last, double& value,
                               chars_format fmt = chars_format::general);
  from_chars_result from_chars(const char* first, const char* last, long double& 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}
to_chars_result to_chars(char* first, char* last, @\seebelow@ 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.

\pnum
\remarks
The implementation shall provide overloads
for all signed and unsigned integer types
and \tcode{char}
as the type of the parameter \tcode{value}.
\end{itemdescr}

\indexlibraryglobal{to_chars}%
\begin{itemdecl}
to_chars_result to_chars(char* first, char* last, float value);
to_chars_result to_chars(char* first, char* last, double value);
to_chars_result to_chars(char* first, char* last, long double 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, float value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, long double 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, float value,
                         chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, double value,
                         chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, long double 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}
from_chars_result from_chars(const char* first, const char* last,
                             @\seebelow@&@\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.

\pnum
\remarks
The implementation shall provide overloads
for all signed and unsigned integer types
and \tcode{char}
as the referenced type of the parameter \tcode{value}.
\end{itemdescr}

\indexlibraryglobal{from_chars}%
\begin{itemdecl}
from_chars_result from_chars(const char* first, const char* last, float& value,
                             chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, double& value,
                             chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, long double& 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_args_t}%
\indexlibraryglobal{format_to_n_result}%
\indexlibrarymember{out}{format_to_n_result}%
\indexlibrarymember{size}{format_to_n_result}%
\begin{codeblock}
namespace std {
  // \ref{format.functions}, formatting functions
  template<class... Args>
    string format(string_view fmt, const Args&... args);
  template<class... Args>
    wstring format(wstring_view fmt, const Args&... args);
  template<class... Args>
    string format(const locale& loc, string_view fmt, const Args&... args);
  template<class... Args>
    wstring format(const locale& loc, wstring_view fmt, const 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, string_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, wstring_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, string_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);

  template<class Out>
    Out vformat_to(Out out, string_view fmt,
                   format_args_t<type_identity_t<Out>, char> args);
  template<class Out>
    Out vformat_to(Out out, wstring_view fmt,
                   format_args_t<type_identity_t<Out>, wchar_t> args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, string_view fmt,
                   format_args_t<type_identity_t<Out>, char> args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, wstring_view fmt,
                   format_args_t<type_identity_t<Out>, wchar_t> 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,
                                        string_view fmt, const Args&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        wstring_view fmt, const 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, string_view fmt,
                                        const 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, wstring_view fmt,
                                        const Args&... args);

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

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

  // \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.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.arguments}, arguments
  // \ref{format.arg}, class template \tcode{basic_format_arg}
  template<class Context> class basic_format_arg;

  template<class Visitor, class Context>
    @\seebelow@ visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);

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

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

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

  template<class Out, class charT>
    using @\libglobal{format_args_t}@ = basic_format_args<basic_format_context<Out, charT>>;

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

% FIXME: For now, keep the format grammar productions out of the index, since
% they conflict with the main grammar.
% Consider renaming these en masse (to fmt-* ?) to avoid this problem.
\newcommand{\fmtnontermdef}[1]{{\BnfNontermshape#1\itcorr}\textnormal{:}}
\newcommand{\fmtgrammarterm}[1]{\gterm{#1}}

\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}
\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),
                                            // throws \tcode{format_error}
string s3 = format("{} to {1}",  "a", "b"); // not a format string (mixing automatic and manual indexing),
                                            // throws \tcode{format_error}
\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} specializations
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
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 s x X}
\end{ncbnf}

\pnum
\begin{note}
The \fmtgrammarterm{fill} character can be any character
other than \tcode{\{} or \tcode{\}}.
The presence of a fill character 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 both the fill character and the alignment option are
absent.
\end{note}

\pnum
The \fmtgrammarterm{align} specifier 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("{:*^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\ \ "}
\end{codeblock}
\end{example}
\begin{note}
Unless a minimum field width is defined, the field width is determined by
the size of the content and the alignment option has no effect.
\end{note}

\begin{floattable}{Meaning of \fmtgrammarterm{align} options}{format.align}{lp{.8\hsize}}
\topline
\lhdr{Option} & \rhdr{Meaning} \\ \rowsep
\tcode{<} &
Forces the field to be aligned to the start of the available space.
This is the default for
non-arithmetic types, \tcode{charT}, and \tcode{bool},
unless an integer presentation type is specified.
\\ \rowsep
%
\tcode{>} &
Forces the field to be aligned to the end of the available space.
This is the default for
arithmetic types other than \tcode{charT} and \tcode{bool}
or when an integer presentation type is specified.
\\ \rowsep
%
\tcode{\caret} &
Forces the field to be centered within the available space
by inserting
$\bigl\lfloor \frac{n}{2} \bigr\rfloor$
characters before and
$\bigl\lceil \frac{n}{2} \bigr\rceil$
characters after the value, where
$n$ is the total number of fill characters to insert.
\\
\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
If \tcode{\{ \opt{\fmtgrammarterm{arg-id}} \}} is used in
a \fmtgrammarterm{width} or \fmtgrammarterm{precision},
the value of the corresponding formatting argument is used in its place.
If the corresponding formatting argument is not of integral type, or
its value is
negative for \fmtgrammarterm{precision} or
non-positive for \fmtgrammarterm{width},
an exception of type \tcode{format_error} is thrown.

\pnum
% FIXME: What if it's an arg-id?
The \fmtgrammarterm{positive-integer} in
\fmtgrammarterm{width} is a decimal integer defining the minimum field width.
If \fmtgrammarterm{width} is not specified,
there is no minimum field width, and
the field width is determined based on the content of the field.

\pnum
\indextext{string!width}%
The \defn{width} of a string is defined as
the estimated number of column positions appropriate
for displaying it in a terminal.
\begin{note}
This is similar to the semantics of the POSIX \tcode{wcswidth} function.
\end{note}

\pnum
For the purposes of width computation,
a string is assumed to be in
a locale-independent, implementation-defined encoding.
Implementations should use a Unicode encoding
on platforms capable of displaying Unicode text in a terminal.
\begin{note}
This is the case for Windows%
\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.}-based and
many POSIX-based operating systems.
\end{note}

\pnum
For a string in a Unicode encoding,
implementations should estimate the width of a string
as the sum of estimated widths of
the first code points in its extended grapheme clusters.
The extended grapheme clusters of a string are defined by UAX \#29.
The estimated width of the following code points is 2:
\begin{itemize}
\item \tcode{U+1100-U+115F}
\item \tcode{U+2329-U+232A}
\item \tcode{U+2E80-U+303E}
\item \tcode{U+3040-U+A4CF}
\item \tcode{U+AC00-U+D7A3}
\item \tcode{U+F900-U+FAFF}
\item \tcode{U+FE10-U+FE19}
\item \tcode{U+FE30-U+FE6F}
\item \tcode{U+FF00-U+FF60}
\item \tcode{U+FFE0-U+FFE6}
\item \tcode{U+1F300-U+1F64F}
\item \tcode{U+1F900-U+1F9FF}
\item \tcode{U+20000-U+2FFFD}
\item \tcode{U+30000-U+3FFFD}
\end{itemize}
The estimated width of other code points is 1.

\pnum
For a string in a non-Unicode encoding, the width of a string is unspecified.

\pnum
A zero (\tcode{0}) character
preceding the \fmtgrammarterm{width} field
pads the field with leading zeros (following any indication of sign or base)
to the field width,
except when applied to an infinity or NaN.
This option is only valid for
arithmetic types other than \tcode{charT} and \tcode{bool}
or when an integer presentation type is specified.
If the \tcode{0} character and an \fmtgrammarterm{align} option both appear,
the \tcode{0} character is ignored.
\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} is ignored because of \tcode{<} alignment)
\end{codeblock}
\end{example}

\pnum
% FIXME: What if it's an arg-id?
The \fmtgrammarterm{nonnegative-integer} in
\fmtgrammarterm{precision} is a decimal integer defining
the precision or maximum field size.
It can only be used with floating-point and string types.
For floating-point types this field specifies the formatting precision.
For string types, this field provides an upper bound
for the estimated width of the prefix of
the input string that is copied into the output.
For a string in a Unicode encoding,
the formatter copies to the output
the longest prefix of whole extended grapheme clusters
whose estimated width is no greater than the precision.

\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.
\\
\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} might 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}{ll}
\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}.
\\
\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{c}, \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} added to the output;
otherwise, implementation-defined.
\\
\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.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(string_view fmt, const Args&... args);
\end{itemdecl}

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

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

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

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

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

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

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return vformat(loc, fmt, 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, string_view fmt, const Args&... args);
template<class Out, class... Args>
  Out format_to(Out out, wstring_view fmt, const Args&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
using context = basic_format_context<Out, decltype(fmt)::value_type>;
return vformat_to(out, fmt, make_format_args<context>(args...));
\end{codeblock}
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
using context = basic_format_context<Out, decltype(fmt)::value_type>;
return vformat_to(out, loc, fmt, make_format_args<context>(args...));
\end{codeblock}
\end{itemdescr}

\indexlibraryglobal{vformat_to}%
\begin{itemdecl}
template<class Out>
  Out vformat_to(Out out, string_view fmt,
                 format_args_t<type_identity_t<Out>, char> args);
template<class Out>
  Out vformat_to(Out out, wstring_view fmt,
                 format_args_t<type_identity_t<Out>, wchar_t> args);
template<class Out>
  Out vformat_to(Out out, const locale& loc, string_view fmt,
                 format_args_t<type_identity_t<Out>, char> args);
template<class Out>
  Out vformat_to(Out out, const locale& loc, wstring_view fmt,
                 format_args_t<type_identity_t<Out>, wchar_t> 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
\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.
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,
                                      string_view fmt, const Args&... args);
template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                      wstring_view fmt, const 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, string_view fmt,
                                      const 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, wstring_view fmt,
                                      const Args&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let
\begin{itemize}
\item \tcode{charT} be \tcode{decltype(fmt)::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{T}_i$\tcode{, charT>}
meets the \newoldconcept{Formatter} 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(string_view fmt, const Args&... args);
template<class... Args>
  size_t formatted_size(wstring_view fmt, const Args&... args);
template<class... Args>
  size_t formatted_size(const locale& loc, string_view fmt, const Args&... args);
template<class... Args>
  size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
\end{itemdecl}

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

\pnum
\expects
\tcode{formatter<}$\tcode{T}_i$\tcode{, charT>}
meets the \newoldconcept{Formatter} 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{Formatter} requirements if:
\begin{itemize}
\item
it meets the
\begin{itemize}
\item \oldconcept{DefaultConstructible} (\tref{cpp17.defaultconstructible}),
\item \oldconcept{CopyConstructible} (\tref{cpp17.copyconstructible}),
\item \oldconcept{CopyAssignable} (\tref{cpp17.copyassignable}), and
\item \oldconcept{Destructible} (\tref{cpp17.destructible})
\end{itemize}
requirements,

\item
it is swappable\iref{swappable.requirements} for lvalues, and

\item
the expressions shown in \tref{formatter} are valid and
have the indicated semantics.
\end{itemize}

\pnum
Given character type \tcode{charT}, output iterator type
\tcode{Out}, and formatting argument type \tcode{T},
in \tref{formatter}:
\begin{itemize}
\item \tcode{f} is a value 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 empty then either
\tcode{pc.begin() == pc.end()} or
\tcode{*pc.begin() == '\}'}.

\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.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(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()},
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.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 \tcode{wchar_t}.
Each specialization of \tcode{formatter} is either enabled or disabled,
as described below.
\begin{note}
Enabled specializations meet the \newoldconcept{Formatter} requirements,
and disabled specializations do not.
\end{note}
Each header that declares the template \tcode{formatter}
provides the following enabled specializations:
\begin{itemize}
\item
\indexlibrary{\idxcode{formatter}!specializations!character types}%
The 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 string type specializations
\begin{codeblock}
template<> struct formatter<charT*, charT>;
template<> struct formatter<const charT*, charT>;
template<size_t N> struct formatter<const 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},
\tcode{wchar_t},
\tcode{char8_t},
\tcode{char16_t}, or
\tcode{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
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{Formatter} requirements\iref{formatter.requirements}.
\begin{example}
\begin{codeblock}
#include <format>

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) {
    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.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,
                                                  size_t num_args = 0) 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);
  };
}
\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,
                                              size_t num_args = 0) 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{num_args}.
\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}, equivalent to:
\begin{codeblock}
if (indexing_ == unknown)
  indexing_ = automatic;
return next_arg_id_++;
\end{codeblock}

\pnum
\throws
\tcode{format_error} if \tcode{indexing_ == manual}
which indicates mixing of automatic and manual argument indexing.
\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}, equivalent to:
\begin{codeblock}
if (indexing_ == unknown)
  indexing_ = manual;
\end{codeblock}

\pnum
\throws
\tcode{format_error} if
\tcode{indexing_ == automatic} which indicates mixing of automatic and
manual argument indexing.

\pnum
\remarks
Call expressions where \tcode{id >= num_args_} are not
core constant expressions\iref{expr.const}.
\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;
    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
\begin{note}
For a given type \tcode{charT},
implementations are encouraged to 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.
\end{note}

\indexlibrarymember{arg}{basic_format_context}%
\begin{itemdecl}
basic_format_arg<basic_format_context> arg(size_t id) const;
\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
\returns
\tcode{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_ = 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) {
    int width = visit_format_arg([](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;
      }, ctx.arg(width_arg_id));
    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.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(const T& v) noexcept;           // \expos
    explicit basic_format_arg(float n) noexcept;                                // \expos
    explicit basic_format_arg(double n) noexcept;                               // \expos
    explicit basic_format_arg(long double n) noexcept;                          // \expos
    explicit basic_format_arg(const char_type* s);                              // \expos

    template<class traits>
      explicit basic_format_arg(
        basic_string_view<char_type, traits> s) noexcept;                       // \expos

    template<class traits, class Allocator>
      explicit basic_format_arg(
        const basic_string<char_type, traits, Allocator>& s) noexcept;          // \expos

    explicit basic_format_arg(nullptr_t) noexcept;                              // \expos

    template<class T>
      explicit basic_format_arg(const T* p) noexcept;                           // \expos

  public:
    basic_format_arg() noexcept;

    explicit operator bool() const noexcept;
  };
}
\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(const T& v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
The template specialization
\begin{codeblock}
typename Context::template formatter_type<T>
\end{codeblock}
meets the \newoldconcept{Formatter} requirements\iref{formatter.requirements}.
The extent to which an implementation determines that
the specialization meets the \newoldconcept{Formatter} requirements
is unspecified,
except that as a minimum the expression
\begin{codeblock}
typename Context::template formatter_type<T>()
  .format(declval<const T&>(), declval<Context&>())
\end{codeblock}
shall be well-formed when treated as an unevaluated operand.

\pnum
\effects
\begin{itemize}
\item
if \tcode{T} is \tcode{bool} or \tcode{char_type},
initializes \tcode{value} with \tcode{v};
\item
otherwise, if \tcode{T} is \tcode{char} and \tcode{char_type} is
\tcode{wchar_t}, initializes \tcode{value} with
\tcode{static_cast<wchar_t>(v)};
\item
otherwise, if \tcode{T} is a signed integer type\iref{basic.fundamental}
and \tcode{sizeof(T) <= sizeof(int)},
initializes \tcode{value} with \tcode{static_cast<int>(v)};
\item
otherwise, if \tcode{T} is an unsigned integer type and
\tcode{sizeof(T) <= sizeof(unsigned int)}, initializes
\tcode{value} with \tcode{static_cast<unsigned int>(v)};
\item
otherwise, if \tcode{T} is a signed integer type and
\tcode{sizeof(T) <= sizeof(long long int)}, initializes
\tcode{value} with \tcode{static_cast<long long int>(v)};
\item
otherwise, if \tcode{T} is an unsigned integer type and
\tcode{sizeof(T) <= sizeof(unsigned long long int)}, initializes
\tcode{value} with
\tcode{static_cast<unsigned long long int>(v)};
\item
otherwise, initializes \tcode{value} with \tcode{handle(v)}.
\end{itemize}
\end{itemdescr}

\begin{itemdecl}
explicit basic_format_arg(float n) noexcept;
explicit basic_format_arg(double n) noexcept;
explicit basic_format_arg(long double n) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes \tcode{value} with \tcode{n}.
\end{itemdescr}

\begin{itemdecl}
explicit basic_format_arg(const char_type* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{s} points to a NTCTS\iref{defns.ntcts}.

\pnum
\effects
Initializes \tcode{value} with \tcode{s}.
\end{itemdescr}

\begin{itemdecl}
template<class traits>
  explicit basic_format_arg(basic_string_view<char_type, traits> s) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes \tcode{value} with \tcode{s}.
\end{itemdescr}

\begin{itemdecl}
template<class traits, class Allocator>
  explicit basic_format_arg(
    const basic_string<char_type, traits, Allocator>& s) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes \tcode{value} with
\tcode{basic_string_view<char_type>(s.data(), s.size())}.
\end{itemdescr}

\begin{itemdecl}
explicit basic_format_arg(nullptr_t) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Initializes \tcode{value} with
  \tcode{static_cast<const void*>(nullptr)}.
\end{itemdescr}

\begin{itemdecl}
template<class T> explicit basic_format_arg(const T* p) noexcept;
\end{itemdecl}

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

\pnum
\effects
Initializes \tcode{value} with \tcode{p}.

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

\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(const 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(const T& val) noexcept;
\end{itemdecl}

\begin{itemdescr}
\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<T> f;
  parse_ctx.advance_to(f.parse(parse_ctx));
  format_ctx.advance_to(f.format(*static_cast<const T*>(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}

\indexlibraryglobal{visit_format_arg}%
\begin{itemdecl}
template<class Visitor, class Context>
  @\seebelow@ visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
\end{itemdecl}

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

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

\begin{codeblock}
namespace std {
  template<class Context, class... Args>
  struct @\placeholder{format-arg-store}@ {      // \expos
    array<basic_format_arg<Context>, sizeof...(Args)> args;
  };
}
\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>
  @\placeholder{format-arg-store}@<Context, Args...> make_format_args(const Args&... args);
\end{itemdecl}

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

\pnum
\returns
\tcode{\{basic_format_arg<Context>(args)...\}}.
\end{itemdescr}

\indexlibraryglobal{make_wformat_args}%
\begin{itemdecl}
template<class... Args>
  @\placeholder{format-arg-store}@<wformat_context, Args...> make_wformat_args(const 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 @\placeholder{format-arg-store}@<Context, Args...>& store) noexcept;

    basic_format_arg<Context> get(size_t i) const noexcept;
  };
}
\end{codeblock}

\pnum
An instance of \tcode{basic_format_args} provides access to formatting
arguments.

\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 @\placeholder{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}

\pnum
\begin{note}
Implementations are encouraged
to optimize the representation of \tcode{basic_format_args}
for small number of formatting arguments
by storing indices of type alternatives separately from values
and packing the former.
\end{note}

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