\rSec0[utilities]{General utilities library}

\rSec1[utilities.general]{General}

This Clause describes utilities that are generally useful in \Cpp{} programs; some

of these utilities are used by other elements of the \Cpp{} standard library.

These utilities are summarized in \tref{utilities.summary}.

\begin{libsumtab}{General utilities library summary}{utilities.summary}

\ref{utility} & Utility components & \tcode{<utility>} \\

\ref{pairs} & Pairs & \\ \rowsep

\ref{tuple} & Tuples & \tcode{<tuple>} \\ \rowsep

\ref{optional} & Optional objects & \tcode{<optional>} \\ \rowsep

\ref{variant} & Variants & \tcode{<variant>} \\ \rowsep

\ref{any} & Storage for any type & \tcode{<any>} \\ \rowsep

\ref{expected} & Expected objects & \tcode{<expected>} \\ \rowsep

\ref{bitset} & Fixed-size sequences of bits & \tcode{<bitset>} \\ \rowsep

\ref{function.objects} & Function objects & \tcode{<functional>} \\ \rowsep

\ref{bit} & Bit manipulation & \tcode{<bit>} \\

\end{libsumtab}

\rSec1[utility]{Utility components}

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

The header \libheaderdef{utility}

contains some basic function and class templates that are used

throughout the rest of the library.

\begin{codeblock}

// all freestanding

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

#include <initializer_list> // see \ref{initializer.list.syn}

namespace std {

// \ref{utility.swap}, swap

template<class T>

constexpr void swap(T& a, T& b) noexcept(@\seebelow@);

template<class T, size_t N>

constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);

// \ref{utility.exchange}, exchange

template<class T, class U = T>

constexpr T exchange(T& obj, U&& new_val) noexcept(@\seebelow@);

// \ref{forward}, forward/move

template<class T>

constexpr T&& forward(remove_reference_t<T>& t) noexcept;

template<class T>

constexpr T&& forward(remove_reference_t<T>&& t) noexcept;

template<class T, class U>

constexpr auto forward_like(U&& x) noexcept -> @\seebelow@;

template<class T>

constexpr remove_reference_t<T>&& move(T&&) noexcept;

template<class T>

constexpr conditional_t<

!is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&>

move_if_noexcept(T& x) noexcept;

// \ref{utility.as.const}, \tcode{as_const}

template<class T>

constexpr add_const_t<T>& as_const(T& t) noexcept;

template<class T>

void as_const(const T&&) = delete;

// \ref{declval}, declval

template<class T>

add_rvalue_reference_t<T> declval() noexcept; // as unevaluated operand

// \ref{utility.intcmp}, integer comparison functions

template<class T, class U>

constexpr bool cmp_equal(T t, U u) noexcept;

template<class T, class U>

constexpr bool cmp_not_equal(T t, U u) noexcept;

template<class T, class U>

constexpr bool cmp_less(T t, U u) noexcept;

template<class T, class U>

constexpr bool cmp_greater(T t, U u) noexcept;

template<class T, class U>

constexpr bool cmp_less_equal(T t, U u) noexcept;

template<class T, class U>

constexpr bool cmp_greater_equal(T t, U u) noexcept;

template<class R, class T>

constexpr bool in_range(T t) noexcept;

// \ref{utility.underlying}, \tcode{to_underlying}

template<class T>

constexpr underlying_type_t<T> to_underlying(T value) noexcept;

// \ref{utility.undefined}, undefined behavior

[[noreturn]] void unreachable();

void observable_checkpoint() noexcept;

// \ref{const.wrap.class}, class template \tcode{constant_wrapper}

template<auto X, class = decltype(X)>

struct constant_wrapper;

template<class T>

concept @\defexposconceptnc{constexpr-param}@ = // \expos

requires { typename constant_wrapper<T::value>; };

struct @\exposidnc{cw-operators}@; // \expos

template<auto X>

constexpr auto @\libglobal{cw}@ = constant_wrapper<X>{};

// \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 @\libglobal{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 @\libglobal{make_index_sequence}@ = make_integer_sequence<size_t, N>;

template<class... T>

using @\libglobal{index_sequence_for}@ = make_index_sequence<sizeof...(T)>;

// \ref{intseq.binding}, structured binding support

template<class T> struct tuple_size;

template<size_t I, class T> struct tuple_element;

template<class T, T... Values>

struct tuple_size<integer_sequence<T, Values...>>;

template<size_t I, class T, T... Values>

struct tuple_element<I, integer_sequence<T, Values...>>;

template<size_t I, class T, T... Values>

struct tuple_element<I, const integer_sequence<T, Values...>>;

template<size_t I, class T, T... Values>

constexpr T get(integer_sequence<T, Values...>) noexcept;

// \ref{pairs}, class template \tcode{pair}

template<class T1, class T2>

struct pair;

template<class T1, class T2, class U1, class U2,

template<class> class TQual, template<class> class UQual>

requires requires { typename pair<common_reference_t<TQual<T1>, UQual<U1>>,

common_reference_t<TQual<T2>, UQual<U2>>>; }

struct basic_common_reference<pair<T1, T2>, pair<U1, U2>, TQual, UQual> {

using type = pair<common_reference_t<TQual<T1>, UQual<U1>>,

common_reference_t<TQual<T2>, UQual<U2>>>;

};

template<class T1, class T2, class U1, class U2>

requires requires { typename pair<common_type_t<T1, U1>, common_type_t<T2, U2>>; }

struct common_type<pair<T1, T2>, pair<U1, U2>> {

using type = pair<common_type_t<T1, U1>, common_type_t<T2, U2>>;

};

// \ref{pairs.spec}, pair specialized algorithms

template<class T1, class T2, class U1, class U2>

constexpr bool operator==(const pair<T1, T2>&, const pair<U1, U2>&);

template<class T1, class T2, class U1, class U2>

constexpr common_comparison_category_t<@\exposid{synth-three-way-result}@<T1, U1>,

@\exposid{synth-three-way-result}@<T2, U2>>

operator<=>(const pair<T1, T2>&, const pair<U1, U2>&);

template<class T1, class T2>

constexpr void swap(pair<T1, T2>& x, pair<T1, T2>& y) noexcept(noexcept(x.swap(y)));

template<class T1, class T2>

constexpr void swap(const pair<T1, T2>& x, const pair<T1, T2>& y)

noexcept(noexcept(x.swap(y)));

template<class T1, class T2>

constexpr @\seebelow@ make_pair(T1&&, T2&&);

// \ref{pair.astuple}, tuple-like access to pair

template<class T1, class T2> struct tuple_size<pair<T1, T2>>;

template<size_t I, class T1, class T2> struct tuple_element<I, pair<T1, T2>>;

template<size_t I, class T1, class T2>

constexpr tuple_element_t<I, pair<T1, T2>>& get(pair<T1, T2>&) noexcept;

template<size_t I, class T1, class T2>

constexpr tuple_element_t<I, pair<T1, T2>>&& get(pair<T1, T2>&&) noexcept;

template<size_t I, class T1, class T2>

constexpr const tuple_element_t<I, pair<T1, T2>>& get(const pair<T1, T2>&) noexcept;

template<size_t I, class T1, class T2>

constexpr const tuple_element_t<I, pair<T1, T2>>&& get(const pair<T1, T2>&&) noexcept;

template<class T1, class T2>

constexpr T1& get(pair<T1, T2>& p) noexcept;

template<class T1, class T2>

constexpr const T1& get(const pair<T1, T2>& p) noexcept;

template<class T1, class T2>

constexpr T1&& get(pair<T1, T2>&& p) noexcept;

template<class T1, class T2>

constexpr const T1&& get(const pair<T1, T2>&& p) noexcept;

template<class T2, class T1>

constexpr T2& get(pair<T1, T2>& p) noexcept;

template<class T2, class T1>

constexpr const T2& get(const pair<T1, T2>& p) noexcept;

template<class T2, class T1>

constexpr T2&& get(pair<T1, T2>&& p) noexcept;

template<class T2, class T1>

constexpr const T2&& get(const pair<T1, T2>&& p) noexcept;

// \ref{pair.piecewise}, pair piecewise construction

struct piecewise_construct_t {

explicit piecewise_construct_t() = default;

};

inline constexpr piecewise_construct_t piecewise_construct{};

template<class... Types> class tuple; // defined in \libheaderref{tuple}

// in-place construction%

\indexlibraryglobal{in_place_t}%

\indexlibraryglobal{in_place}%

\indexlibraryglobal{in_place_type_t}%

\indexlibraryglobal{in_place_type}%

\indexlibraryglobal{in_place_index_t}%

\indexlibraryglobal{in_place_index}

struct in_place_t {

explicit in_place_t() = default;

};

inline constexpr in_place_t in_place{};

template<class T>

struct in_place_type_t {

explicit in_place_type_t() = default;

};

template<class T> constexpr in_place_type_t<T> in_place_type{};

template<size_t I>

struct in_place_index_t {

explicit in_place_index_t() = default;

};

template<size_t I> constexpr in_place_index_t<I> in_place_index{};

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

\indexlibraryglobal{monostate}

struct monostate;

// \ref{variant.monostate.relops}, \tcode{monostate} relational operators%

\indexlibrarymember{operator==}{monostate}%

\indexlibrarymember{operator<=>}{monostate}

constexpr bool operator==(monostate, monostate) noexcept;

constexpr strong_ordering operator<=>(monostate, monostate) noexcept;

// \ref{variant.hash}, hash support%

\indexlibrarymember{hash}{monostate}

template<class T> struct hash;

template<> struct hash<monostate>;

}

\end{codeblock}

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

\indexlibraryglobal{swap}%

\begin{itemdecl}

template<class T>

constexpr void swap(T& a, T& b) noexcept(@\seebelow@);

\end{itemdecl}

\begin{itemdescr}

\tcode{is_move_constructible_v<T>} is \tcode{true} and

\tcode{is_move_assignable_v<T>} is \tcode{true}.

Type

\tcode{T}

meets the

\oldconceptref{MoveConstructible} (\tref{cpp17.moveconstructible})

and

\oldconceptref{MoveAssignable} (\tref{cpp17.moveassignable})

requirements.

Exchanges the values of \tcode{a} and \tcode{b}.

The exception specification is equivalent to:

\begin{codeblock}

is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>

\end{codeblock}

\end{itemdescr}

\indexlibraryglobal{swap}%

\begin{itemdecl}

template<class T, size_t N>

constexpr void swap(T (&a)[N], T (&b)[N]) noexcept(is_nothrow_swappable_v<T>);

\end{itemdecl}

\begin{itemdescr}

\tcode{is_swappable_v<T>} is \tcode{true}.

\tcode{a[i]} is swappable with\iref{swappable.requirements} \tcode{b[i]}

for all \tcode{i} in the range \range{0}{N}.

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

\end{itemdescr}

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

\indexlibraryglobal{exchange}%

\begin{itemdecl}

template<class T, class U = T>

constexpr T exchange(T& obj, U&& new_val) noexcept(@\seebelow@);

\end{itemdecl}

\begin{itemdescr}

Equivalent to:

\begin{codeblock}

T old_val = std::move(obj);

obj = std::forward<U>(new_val);

return old_val;

\end{codeblock}

The exception specification is equivalent to:

\begin{codeblock}

is_nothrow_move_constructible_v<T> && is_nothrow_assignable_v<T&, U>

\end{codeblock}

\end{itemdescr}

\rSec2[forward]{Forward/move helpers}

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 \deflinkx{signal-safe}{evaluation!signal-safe}{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}

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

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

\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: \tcode{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 \tcode{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

\tcode{1.414} is forwarded to \tcode{A}'s constructor as an rvalue.

\end{example}

\end{itemdescr}

\indexlibraryglobal{forward_like}%

\begin{itemdecl}

template<class T, class U>

constexpr auto forward_like(U&& x) noexcept -> @\seebelow@;

\end{itemdecl}

\begin{itemdescr}

\tcode{T} is a referenceable type\iref{defns.referenceable}.

\begin{itemize}

Let \tcode{\exposid{COPY_CONST}(A, B)} be \tcode{const B}

if \tcode{A} is a const type, otherwise \tcode{B}.

Let \tcode{\exposid{OVERRIDE_REF}(A, B)} be \tcode{remove_reference_t<B>\&\&}

if \tcode{A} is an rvalue reference type, otherwise \tcode{B\&}.

Let \tcode{V} be

\begin{codeblock}

@\exposid{OVERRIDE_REF}@(T&&, @\exposid{COPY_CONST}@(remove_reference_t<T>, remove_reference_t<U>))

\end{codeblock}

\end{itemize}

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

The return type is \tcode{V}.

\begin{example}

\begin{codeblock}

struct accessor {

vector<string>* container;

decltype(auto) operator[](this auto&& self, size_t i) {

return std::forward_like<decltype(self)>((*container)[i]);

}

};

void g() {

vector v{"a"s, "b"s};

accessor a{&v};

string& x = a[0]; // OK, binds to lvalue reference

string&& y = std::move(a)[0]; // OK, is rvalue reference

string const&& z = std::move(as_const(a))[1]; // OK, is \tcode{const\&\&}

string& w = as_const(a)[1]; // error: will not bind to non-const

}

\end{codeblock}

\end{example}

\end{itemdescr}

\indexlibrary{\idxcode{move}!function}%

\indextext{\idxcode{move}}%

\begin{itemdecl}

template<class T> constexpr remove_reference_t<T>&& move(T&& t) noexcept;

\end{itemdecl}

\begin{itemdescr}

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

\begin{example}

\begin{codeblock}

template<class T, class A1>

shared_ptr<T> factory(A1&& a1) {

return shared_ptr<T>(new T(std::forward<A1>(a1)));

}

struct A {

A();

A(const A&); // copies from lvalues

A(A&&); // moves from rvalues

};

void g() {

A a;

shared_ptr<A> sp1 = factory<A>(a); // ``\tcode{a}\!'' binds to \tcode{A(const A\&)}

shared_ptr<A> sp2 = factory<A>(std::move(a)); // ``\tcode{a}\!'' binds to \tcode{A(A\&\&)}

}

\end{codeblock}

In the first call to \tcode{factory},

\tcode{A1} is deduced as \tcode{A\&}, so \tcode{a} is forwarded

as a non-const lvalue. This binds to the constructor \tcode{A(const A\&)},

which copies the value from \tcode{a}.

In the second call to \tcode{factory}, because of the call

\tcode{std::move(a)},

\tcode{A1} is deduced as \tcode{A}, so \tcode{a} is forwarded

as an rvalue. This binds to the constructor \tcode{A(A\&\&)},

which moves the value from \tcode{a}.

\end{example}

\end{itemdescr}

\indexlibraryglobal{move_if_noexcept}%

\begin{itemdecl}

template<class T> constexpr conditional_t<

!is_nothrow_move_constructible_v<T> && is_copy_constructible_v<T>, const T&, T&&>

move_if_noexcept(T& x) noexcept;

\end{itemdecl}

\begin{itemdescr}

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

\tcode{t}.

\end{itemdescr}

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

The library provides the function template \tcode{declval} to simplify the definition of

expressions which occur as \deflinkx{unevaluated operands}{unevaluated operand}{expr.context}.

\indexlibraryglobal{declval}%

\begin{itemdecl}

template<class T> add_rvalue_reference_t<T> declval() noexcept; // as unevaluated operand

\end{itemdecl}

\begin{itemdescr}

This function is not odr-used\iref{term.odr.use}.

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

\begin{example}

\begin{codeblock}

template<class To, class From> decltype(static_cast<To>(declval<From>())) convert(From&&);

\end{codeblock}

declares a function template \tcode{convert} which only participates in overload resolution if the

type \tcode{From} can be explicitly converted to type \tcode{To}. For another example see class

template \tcode{common_type}\iref{meta.trans.other}.

\end{example}

\end{itemdescr}

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

\indexlibraryglobal{cmp_equal}%

\begin{itemdecl}

template<class T, class U>

constexpr bool cmp_equal(T t, U u) noexcept;

\end{itemdecl}

\begin{itemdescr}

Each of \tcode{T} and \tcode{U} is

a signed or unsigned integer type\iref{basic.fundamental}.

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}

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}

Each of \tcode{T} and \tcode{U} is

a signed or unsigned integer type\iref{basic.fundamental}.

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}

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}

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}

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}

Each of \tcode{T} and \tcode{R} is

a signed or unsigned integer type\iref{basic.fundamental}.

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}

\begin{note}

These function templates cannot be used to compare

\tcode{byte},

\tcode{char},

\keyword{char8_t},

\keyword{char16_t},

\keyword{char32_t},

\keyword{wchar_t}, and

\tcode{bool}.

\end{note}

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

\indexlibraryglobal{to_underlying}%

\begin{itemdecl}

template<class T>

constexpr underlying_type_t<T> to_underlying(T value) noexcept;

\end{itemdecl}

\begin{itemdescr}

\tcode{static_cast<underlying_type_t<T>>(value)}.

\end{itemdescr}

\rSec2[utility.undefined]{Undefined behavior}

\indexlibraryglobal{unreachable}%

\begin{itemdecl}

[[noreturn]] void unreachable();

\end{itemdecl}

\begin{itemdescr}

\tcode{false} is \tcode{true}.

\begin{note}

This precondition cannot be satisfied, thus the behavior

of calling \tcode{unreachable} is undefined.

\end{note}

\begin{example}

\begin{codeblock}

int f(int x) {

switch (x) {

case 0:

case 1:

return x;

default:

std::unreachable();

}

}

int a = f(1); // OK, \tcode{a} has value \tcode{1}

int b = f(3); // undefined behavior

\end{codeblock}

\end{example}

\end{itemdescr}

\indexlibraryglobal{observable_checkpoint}%

\begin{itemdecl}

void observable_checkpoint() noexcept;

\end{itemdecl}

\begin{itemdescr}

Establishes an observable checkpoint\iref{intro.abstract}.

\end{itemdescr}

\rSec2[const.wrap.class]{Class template \tcode{constant_wrapper}}

\begin{codeblock}

namespace std {

struct @\exposidnc{cw-operators}@ { // \expos

// unary operators

template<@\exposconcept{constexpr-param}@ T>

friend constexpr auto operator+(T) noexcept -> constant_wrapper<(+T::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ T>

friend constexpr auto operator-(T) noexcept -> constant_wrapper<(-T::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ T>

friend constexpr auto operator~(T) noexcept -> constant_wrapper<(~T::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ T>

friend constexpr auto operator!(T) noexcept -> constant_wrapper<(!T::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ T>

friend constexpr auto operator&(T) noexcept -> constant_wrapper<(&T::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ T>

friend constexpr auto operator*(T) noexcept -> constant_wrapper<(*T::value)>

{ return {}; }

// binary operators

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator+(L, R) noexcept -> constant_wrapper<(L::value + R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator-(L, R) noexcept -> constant_wrapper<(L::value - R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator*(L, R) noexcept -> constant_wrapper<(L::value * R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator/(L, R) noexcept -> constant_wrapper<(L::value / R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator%(L, R) noexcept -> constant_wrapper<(L::value % R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator<<(L, R) noexcept -> constant_wrapper<(L::value << R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator>>(L, R) noexcept -> constant_wrapper<(L::value >> R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator&(L, R) noexcept -> constant_wrapper<(L::value & R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator|(L, R) noexcept -> constant_wrapper<(L::value | R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator^(L, R) noexcept -> constant_wrapper<(L::value ^ R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

requires (!is_constructible_v<bool, decltype(L::value)> ||

!is_constructible_v<bool, decltype(R::value)>)

friend constexpr auto operator&&(L, R) noexcept

-> constant_wrapper<(L::value && R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

requires (!is_constructible_v<bool, decltype(L::value)> ||

!is_constructible_v<bool, decltype(R::value)>)

friend constexpr auto operator||(L, R) noexcept

-> constant_wrapper<(L::value || R::value)>

{ return {}; }

// comparisons

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator<=>(L, R) noexcept

-> constant_wrapper<(L::value <=> R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator<(L, R) noexcept -> constant_wrapper<(L::value < R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator<=(L, R) noexcept -> constant_wrapper<(L::value <= R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator==(L, R) noexcept -> constant_wrapper<(L::value == R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator!=(L, R) noexcept -> constant_wrapper<(L::value != R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator>(L, R) noexcept -> constant_wrapper<(L::value > R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator>=(L, R) noexcept -> constant_wrapper<(L::value >= R::value)>

{ return {}; }

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator,(L, R) noexcept = delete;

template<@\exposconcept{constexpr-param}@ L, @\exposconcept{constexpr-param}@ R>

friend constexpr auto operator->*(L, R) noexcept -> constant_wrapper<L::value->*(R::value)>

{ return {}; }

// pseudo-mutators

template<@\exposconcept{constexpr-param}@ T>

constexpr auto operator++(this T) noexcept

-> constant_wrapper<(++T::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T>

constexpr auto operator++(this T, int) noexcept

-> constant_wrapper<(T::value++)> { return {}; }

template<@\exposconcept{constexpr-param}@ T>

constexpr auto operator--(this T) noexcept

-> constant_wrapper<(--T::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T>

constexpr auto operator--(this T, int) noexcept

-> constant_wrapper<(T::value--)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator+=(this T, R) noexcept

-> constant_wrapper<(T::value += R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator-=(this T, R) noexcept

-> constant_wrapper<(T::value -= R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator*=(this T, R) noexcept

-> constant_wrapper<(T::value *= R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator/=(this T, R) noexcept

-> constant_wrapper<(T::value /= R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator%=(this T, R) noexcept

-> constant_wrapper<(T::value %= R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator&=(this T, R) noexcept

-> constant_wrapper<(T::value &= R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator|=(this T, R) noexcept

-> constant_wrapper<(T::value |= R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator^=(this T, R) noexcept

-> constant_wrapper<(T::value ^= R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator<<=(this T, R) noexcept

-> constant_wrapper<(T::value <<= R::value)> { return {}; }

template<@\exposconcept{constexpr-param}@ T, @\exposconcept{constexpr-param}@ R>

constexpr auto operator>>=(this T, R) noexcept

-> constant_wrapper<(T::value >>= R::value)> { return {}; }

};

template<auto X, class T = decltype(X)>

struct @\libglobal{constant_wrapper}@ : @\exposid{cw-operators}@ {

static constexpr decltype(auto) value = (X);

using type = constant_wrapper;

using value_type = decltype(X);

template<@\exposconcept{constexpr-param}@ R>

constexpr auto operator=(R) const noexcept

-> constant_wrapper<(value = R::value)> { return {}; }

constexpr operator decltype(value)() const noexcept { return value; }

template<class... Args>

static constexpr decltype(auto) operator()(Args&&... args) noexcept(@\seebelow@);

template<class... Args>

static constexpr decltype(auto) operator[](Args&&... args) noexcept(@\seebelow@);

};

}

\end{codeblock}

The class template \tcode{constant_wrapper} aids in metaprogramming by ensuring

that the evaluation of expressions comprised entirely of \tcode{constant_wrapper}

are core constant expressions\iref{expr.const.core},

regardless of the context in which they appear.

In particular, this enables use of \tcode{constant_wrapper} values

that are passed as arguments to constexpr functions to be used in constant expressions.

If a specialization of \tcode{constant_wrapper} is instantiated with a type \tcode{T}

such that \tcode{is_same_v<T, value_type>} is \tcode{false},

the program is ill-formed.

\begin{note}

The second template parameter to \tcode{constant_wrapper} is present

to aid argument-dependent lookup\iref{basic.lookup.argdep}

in finding overloads for which \tcode{constant_wrapper}'s wrapped value is a suitable argument,

but for which the \tcode{constant_wrapper} itself is not.

\end{note}

\begin{example}

\begin{codeblock}

constexpr auto initial_phase(auto quantity_1, auto quantity_2) {

return quantity_1 + quantity_2;

}

constexpr auto middle_phase(auto tbd) {

return tbd;

}

void final_phase(auto gathered, auto available) {

if constexpr (gathered == available)

std::cout << "Profit!\n";

}

void impeccable_underground_planning() {

auto gathered_quantity = middle_phase(initial_phase(std::cw<42>, std::cw<13>));

static_assert(gathered_quantity == 55);

auto all_available = std::cw<55>;

final_phase(gathered_quantity, all_available);

}

void deeply_flawed_underground_planning() {

constexpr auto gathered_quantity = middle_phase(initial_phase(42, 13));

constexpr auto all_available = 55;

final_phase(gathered_quantity, all_available); // error: \tcode{gathered == available}

// is not a constant expression

}

\end{codeblock}

\end{example}

\indexlibrarymember{operator()}{constant_wrapper}%

\begin{itemdecl}

template<class... Args>

static constexpr decltype(auto) operator()(Args&&... args) noexcept(@\seebelow@);

\end{itemdecl}

\begin{itemdescr}

Let \tcode{\placeholder{call-expr}} be

\tcode{constant_wrapper<\placeholder{INVOKE}(value, remove_cvref_t<Args>::value...)>\{\}}

if all types in \tcode{remove_cvref_t<Args>...} satisfy \exposconcept{constexpr-param} and

\tcode{constant_wrapper<\placeholder{INVOKE}(val\-ue, remove_cvref_t<Args>::value...)>} is a valid type,

otherwise let \tcode{\placeholder{call-expr}} be \tcode{\placeholder{INVOKE}(value, std::forward<Args>(args)...)}.

\tcode{\placeholder{call-expr}} is a valid expression.

Equivalent to: \tcode{return \placeholder{call-expr};}

The exception specification is equivalent to \tcode{noexcept(\placeholder{call-expr})}.

\end{itemdescr}

\indexlibrarymember{operator[]}{constant_wrapper}%

\begin{itemdecl}

template<class... Args>

static constexpr decltype(auto) operator[](Args&&... args) noexcept(@\seebelow@);

\end{itemdecl}

\begin{itemdescr}