%!TEX root = std.tex

\rSec0[utilities]{General utilities library}

\rSec1[utilities.general]{General}

\pnum

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

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

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

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

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

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

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

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

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

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

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

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

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

\ref{type.index} & Type indexes & \tcode{<typeindex>} \\ \rowsep

\ref{execpol} & Execution policies & \tcode{<execution>} \\ \rowsep

\ref{charconv} & Primitive numeric conversions & \tcode{<charconv>} \\ \rowsep

\ref{format} & Formatting & \tcode{<format>} \\ \rowsep

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

\ref{debugging} & Debugging & \tcode{<debugging>} \\

\end{libsumtab}

\rSec1[utility]{Utility components}

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

\pnum

The header \libheaderdef{utility}

contains some basic function and class templates that are used

throughout the rest of the library.

\begin{codeblock}

// all freestanding

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

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

namespace std {

// \ref{utility.swap}, swap

template<class T>

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

template<class T, size_t N>

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

// \ref{utility.exchange}, exchange

template<class T, class U = T>

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

// \ref{forward}, forward/move

template<class T>

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

template<class T>

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

template<class T, class U>

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

template<class T>

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

template<class T>

constexpr conditional_t<

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

move_if_noexcept(T& x) noexcept;

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

template<class T>

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

template<class T>

void as_const(const T&&) = delete;

// \ref{declval}, declval

template<class T>

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

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

template<class T, class U>

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

template<class T, class U>

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

template<class T, class U>

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

template<class T, class U>

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

template<class T, class U>

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

template<class T, class U>

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

template<class R, class T>

constexpr bool in_range(T t) noexcept;

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

template<class T>

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

// \ref{utility.unreachable}, unreachable

[[noreturn]] void unreachable();

// \ref{intseq}, compile-time integer sequences%

\indexlibraryglobal{index_sequence}%

\indexlibraryglobal{make_index_sequence}%

\indexlibraryglobal{index_sequence_for}

template<class T, T...>

struct integer_sequence;

template<size_t... I>

using index_sequence = integer_sequence<size_t, I...>;

template<class T, T N>

using make_integer_sequence = integer_sequence<T, @\seebelow{}@>;

template<size_t N>

using make_index_sequence = make_integer_sequence<size_t, N>;

template<class... T>

using index_sequence_for = make_index_sequence<sizeof...(T)>;

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

template<class T1, class T2>

struct pair;

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

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

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

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

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

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

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

};

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

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

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

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

};

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

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

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

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

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

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

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

template<class T1, class T2>

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

template<class T1, class T2>

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

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

template<class T1, class T2>

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

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

template<class T> struct tuple_size;

template<size_t I, class T> struct tuple_element;

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

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

template<size_t I, class T1, class T2>

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

template<size_t I, class T1, class T2>

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

template<size_t I, class T1, class T2>

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

template<size_t I, class T1, class T2>

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

template<class T1, class T2>

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

template<class T1, class T2>

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

template<class T1, class T2>

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

template<class T1, class T2>

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

template<class T2, class T1>

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

template<class T2, class T1>

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

template<class T2, class T1>

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

template<class T2, class T1>

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

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

struct piecewise_construct_t {

explicit piecewise_construct_t() = default;

};

inline constexpr piecewise_construct_t piecewise_construct{};

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

// in-place construction%

\indexlibraryglobal{in_place_t}%

\indexlibraryglobal{in_place}%

\indexlibraryglobal{in_place_type_t}%

\indexlibraryglobal{in_place_type}%

\indexlibraryglobal{in_place_index_t}%

\indexlibraryglobal{in_place_index}

struct in_place_t {

explicit in_place_t() = default;

};

inline constexpr in_place_t in_place{};

template<class T>

struct in_place_type_t {

explicit in_place_type_t() = default;

};

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

template<size_t I>

struct in_place_index_t {

explicit in_place_index_t() = default;

};

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

// \tcode{nontype} argument tag%

\indexlibraryglobal{nontype_t}%

\indexlibraryglobal{nontype}

template<auto V>

struct nontype_t {

explicit nontype_t() = default;

};

template<auto V> constexpr nontype_t<V> nontype{};

}

\end{codeblock}

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

\indexlibraryglobal{swap}%

\begin{itemdecl}

template<class T>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\constraints

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

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

\pnum

\expects

Type

\tcode{T}

meets the

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

and

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

requirements.

\pnum

\effects

Exchanges values stored in two locations.

\pnum

\remarks

The exception specification is equivalent to:

\begin{codeblock}

is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>

\end{codeblock}

\end{itemdescr}

\indexlibraryglobal{swap}%

\begin{itemdecl}

template<class T, size_t N>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\constraints

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

\pnum

\expects

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

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

\pnum

\effects

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

\end{itemdescr}

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

\indexlibraryglobal{exchange}%

\begin{itemdecl}

template<class T, class U = T>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to:

\begin{codeblock}

T old_val = std::move(obj);

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

return old_val;

\end{codeblock}

\pnum

\remarks

The exception specification is equivalent to:

\begin{codeblock}

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

\end{codeblock}

\end{itemdescr}

\rSec2[forward]{Forward/move helpers}

\pnum

The library provides templated helper functions to simplify

applying move semantics to an lvalue and to simplify the implementation

of forwarding functions.

\indextext{signal-safe!\idxcode{forward}}%

\indextext{signal-safe!\idxcode{move}}%

\indextext{signal-safe!\idxcode{move_if_noexcept}}%

All functions specified in this subclause are signal-safe\iref{support.signal}.

\indexlibraryglobal{forward}%

\indextext{\idxcode{forward}}%

\begin{itemdecl}

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

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

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

\pnum

\returns

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

\pnum

\begin{example}

\begin{codeblock}

template<class T, class A1, class A2>

shared_ptr<T> factory(A1&& a1, A2&& a2) {

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

}

struct A {

A(int&, const double&);

};

void g() {

shared_ptr<A> sp1 = factory<A>(2, 1.414); // error: 2 will not bind to \tcode{int\&}

int i = 2;

shared_ptr<A> sp2 = factory<A>(i, 1.414); // OK

}

\end{codeblock}

In the first call to \tcode{factory},

\tcode{A1} is deduced as \tcode{int}, so 2 is forwarded

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

In the second call to \tcode{factory},

\tcode{A1} is deduced as \tcode{int\&}, so \tcode{i} is forwarded

to \tcode{A}'s constructor as an lvalue. In

both cases, \tcode{A2} is deduced as \tcode{double}, so

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

\end{example}

\end{itemdescr}

\indexlibraryglobal{forward_like}%

\begin{itemdecl}

template<class T, class U>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

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

\pnum

\begin{itemize}

\item

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

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

\item

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

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

\item

Let \tcode{V} be

\begin{codeblock}

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

\end{codeblock}

\end{itemize}

\pnum

\returns

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

\pnum

\remarks

The return type is \tcode{V}.

\pnum

\begin{example}

\begin{codeblock}

struct accessor {

vector<string>* container;

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

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

}

};

void g() {

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

accessor a{&v};

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

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

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

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

}

\end{codeblock}

\end{example}

\end{itemdescr}

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

\indextext{\idxcode{move}}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

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

\pnum

\begin{example}

\begin{codeblock}

template<class T, class A1>

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

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

}

struct A {

A();

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

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

};

void g() {

A a;

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

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

}

\end{codeblock}

In the first call to \tcode{factory},

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

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

which copies the value from \tcode{a}.

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

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

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

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

which moves the value from \tcode{a}.

\end{example}

\end{itemdescr}

\indexlibraryglobal{move_if_noexcept}%

\begin{itemdecl}

template<class T> constexpr conditional_t<

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

move_if_noexcept(T& x) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{std::move(x)}.

\end{itemdescr}

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

\indexlibraryglobal{as_const}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{t}.

\end{itemdescr}

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

\pnum

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

expressions which occur as unevaluated operands\iref{term.unevaluated.operand}.

\indexlibraryglobal{declval}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

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

\pnum

\remarks

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

\pnum

\begin{example}

\begin{codeblock}

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

\end{codeblock}

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

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

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

\end{example}

\end{itemdescr}

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

\indexlibraryglobal{cmp_equal}%

\begin{itemdecl}

template<class T, class U>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

Both \tcode{T} and \tcode{U} are standard integer types or

extended integer types\iref{basic.fundamental}.

\pnum

\effects

Equivalent to:

\begin{codeblock}

using UT = make_unsigned_t<T>;

using UU = make_unsigned_t<U>;

if constexpr (is_signed_v<T> == is_signed_v<U>)

return t == u;

else if constexpr (is_signed_v<T>)

return t < 0 ? false : UT(t) == u;

else

return u < 0 ? false : t == UU(u);

\end{codeblock}

\end{itemdescr}

\indexlibraryglobal{cmp_not_equal}%

\begin{itemdecl}

template<class T, class U>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to: \tcode{return !cmp_equal(t, u);}

\end{itemdescr}

\indexlibraryglobal{cmp_less}%

\begin{itemdecl}

template<class T, class U>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

Both \tcode{T} and \tcode{U} are standard integer types or

extended integer types\iref{basic.fundamental}.

\pnum

\effects

Equivalent to:

\begin{codeblock}

using UT = make_unsigned_t<T>;

using UU = make_unsigned_t<U>;

if constexpr (is_signed_v<T> == is_signed_v<U>)

return t < u;

else if constexpr (is_signed_v<T>)

return t < 0 ? true : UT(t) < u;

else

return u < 0 ? false : t < UU(u);

\end{codeblock}

\end{itemdescr}

\indexlibraryglobal{cmp_greater}%

\begin{itemdecl}

template<class T, class U>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to: \tcode{return cmp_less(u, t);}

\end{itemdescr}

\indexlibraryglobal{cmp_less_equal}%

\begin{itemdecl}

template<class T, class U>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to: \tcode{return !cmp_greater(t, u);}

\end{itemdescr}

\indexlibraryglobal{cmp_greater_equal}%

\begin{itemdecl}

template<class T, class U>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to: \tcode{return !cmp_less(t, u);}

\end{itemdescr}

\indexlibraryglobal{in_range}%

\begin{itemdecl}

template<class R, class T>

constexpr bool in_range(T t) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

Both \tcode{T} and \tcode{R} are standard integer types or

extended integer types\iref{basic.fundamental}.

\pnum

\effects

Equivalent to:

\begin{codeblock}

return cmp_greater_equal(t, numeric_limits<R>::min()) &&

cmp_less_equal(t, numeric_limits<R>::max());

\end{codeblock}

\end{itemdescr}

\pnum

\begin{note}

These function templates cannot be used to compare

\tcode{byte},

\tcode{char},

\keyword{char8_t},

\keyword{char16_t},

\keyword{char32_t},

\keyword{wchar_t}, and

\tcode{bool}.

\end{note}

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

\indexlibraryglobal{to_underlying}%

\begin{itemdecl}

template<class T>

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

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

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

\end{itemdescr}

\rSec2[utility.unreachable]{Function \tcode{unreachable}}

\indexlibraryglobal{unreachable}%

\begin{itemdecl}

[[noreturn]] void unreachable();

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

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

\begin{note}

This precondition cannot be satisfied, thus the behavior

of calling \tcode{unreachable} is undefined.

\end{note}

\pnum

\begin{example}

\begin{codeblock}

int f(int x) {

switch (x) {

case 0:

case 1:

return x;

default:

std::unreachable();

}

}

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

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

\end{codeblock}

\end{example}

\end{itemdescr}

\rSec1[pairs]{Pairs}

\rSec2[pairs.general]{In general}

\pnum

The library provides a template for heterogeneous pairs of values.

The library also provides a matching function template to simplify

their construction and several templates that provide access to \tcode{pair}

objects as if they were \tcode{tuple} objects (see~\ref{tuple.helper}

and~\ref{tuple.elem}).%

\indexlibraryglobal{pair}%

\indextext{\idxcode{pair}!tuple interface to}%

\indextext{\idxcode{tuple}!and pair@and \tcode{pair}}%

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

\indexlibraryglobal{pair}%

\begin{codeblock}

namespace std {

template<class T1, class T2>

struct pair {

using first_type = T1;

using second_type = T2;

T1 first;

T2 second;

pair(const pair&) = default;

pair(pair&&) = default;

constexpr explicit(@\seebelow@) pair();

constexpr explicit(@\seebelow@) pair(const T1& x, const T2& y);

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

constexpr explicit(@\seebelow@) pair(U1&& x, U2&& y);

template<class U1, class U2>

constexpr explicit(@\seebelow@) pair(pair<U1, U2>& p);

template<class U1, class U2>

constexpr explicit(@\seebelow@) pair(const pair<U1, U2>& p);

template<class U1, class U2>

constexpr explicit(@\seebelow@) pair(pair<U1, U2>&& p);

template<class U1, class U2>

constexpr explicit(@\seebelow@) pair(const pair<U1, U2>&& p);

template<@\exposconcept{pair-like}@ P>

constexpr explicit(@\seebelow@) pair(P&& p);

template<class... Args1, class... Args2>

constexpr pair(piecewise_construct_t,

tuple<Args1...> first_args, tuple<Args2...> second_args);

constexpr pair& operator=(const pair& p);

constexpr const pair& operator=(const pair& p) const;

template<class U1, class U2>

constexpr pair& operator=(const pair<U1, U2>& p);

template<class U1, class U2>

constexpr const pair& operator=(const pair<U1, U2>& p) const;

constexpr pair& operator=(pair&& p) noexcept(@\seebelow@);

constexpr const pair& operator=(pair&& p) const;

template<class U1, class U2>

constexpr pair& operator=(pair<U1, U2>&& p);

template<class U1, class U2>

constexpr const pair& operator=(pair<U1, U2>&& p) const;

template<@\exposconcept{pair-like}@ P>

constexpr pair& operator=(P&& p);

template<@\exposconcept{pair-like}@ P>

constexpr const pair& operator=(P&& p) const;

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

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

};

template<class T1, class T2>

pair(T1, T2) -> pair<T1, T2>;

}

\end{codeblock}

\pnum

Constructors and member functions of \tcode{pair} do not throw exceptions unless one of

the element-wise operations specified to be called for that operation

throws an exception.

\pnum

The defaulted move and copy constructor, respectively, of \tcode{pair}

is a constexpr function if and only if all required element-wise

initializations for move and copy, respectively,

would be constexpr-suitable\iref{dcl.constexpr}.

\pnum

If \tcode{(is_trivially_destructible_v<T1> \&\& is_trivially_destructible_v<T2>)}

is \tcode{true}, then the destructor of \tcode{pair} is trivial.

\pnum

\tcode{pair<T, U>} is a structural type\iref{term.structural.type}

if \tcode{T} and \tcode{U} are both structural types.

Two values \tcode{p1} and \tcode{p2} of type \tcode{pair<T, U>}

are template-argument-equivalent\iref{temp.type} if and only if

\tcode{p1.first} and \tcode{p2.first} are template-argument-equivalent and

\tcode{p1.second} and \tcode{p2.second} are template-argument-equivalent.

\indexlibraryctor{pair}%

\begin{itemdecl}

constexpr explicit(@\seebelow@) pair();

\end{itemdecl}

\begin{itemdescr}

\pnum

\constraints

\begin{itemize}

\item \tcode{is_default_constructible_v<T1>} is \tcode{true} and

\item \tcode{is_default_constructible_v<T2>} is \tcode{true}.

\end{itemize}

\pnum

\effects

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

\pnum

\remarks

The expression inside \keyword{explicit} evaluates to \tcode{true}

if and only if either \tcode{T1} or

\tcode{T2} is not implicitly default-constructible.

\begin{note}

This behavior can be implemented with a trait that checks

whether a \tcode{const T1\&} or a \tcode{const T2\&}

can be initialized with \tcode{\{\}}.

\end{note}

\end{itemdescr}

\indexlibraryctor{pair}%

\begin{itemdecl}

constexpr explicit(@\seebelow@) pair(const T1& x, const T2& y);

\end{itemdecl}

\begin{itemdescr}

\pnum

\constraints

\begin{itemize}

\item \tcode{is_copy_constructible_v<T1>} is \tcode{true} and

\item \tcode{is_copy_constructible_v<T2>} is \tcode{true}.

\end{itemize}

\pnum

\effects

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

\pnum

\remarks

The expression inside \keyword{explicit} is equivalent to:

\begin{codeblock}

!is_convertible_v<const T1&, T1> || !is_convertible_v<const T2&, T2>

\end{codeblock}

\end{itemdescr}

\indexlibraryctor{pair}%

\begin{itemdecl}

template<class U1 = T1, class U2 = T2> constexpr explicit(@\seebelow@) pair(U1&& x, U2&& y);

\end{itemdecl}

\begin{itemdescr}

\pnum

\constraints

\begin{itemize}

\item \tcode{is_constructible_v<T1, U1>} is \tcode{true} and

\item \tcode{is_constructible_v<T2, U2>} is \tcode{true}.

\end{itemize}

\pnum

\effects

Initializes \tcode{first} with

\tcode{std::forward<U1>(x)} and \tcode{second}

with \tcode{std::forward<U2>(y)}.

\pnum

\remarks

The expression inside \keyword{explicit} is equivalent to:

\begin{codeblock}

!is_convertible_v<U1, T1> || !is_convertible_v<U2, T2>

\end{codeblock}

This constructor is defined as deleted if

\tcode{reference_constructs_from_temporary_v<first_type, U1\&\&>}

is \tcode{true} or

\tcode{reference_constructs_from_temporary_v<second_type, U2\&\&>}

is \tcode{true}.

\end{itemdescr}

\indexlibraryctor{pair}%

\begin{itemdecl}

template<class U1, class U2> constexpr explicit(@\seebelow@) pair(pair<U1, U2>& p);

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

template<class U1, class U2> constexpr explicit(@\seebelow@) pair(pair<U1, U2>&& p);

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

template<@\exposconcept{pair-like}@ P> constexpr explicit(@\seebelow@) pair(P&& p);

\end{itemdecl}

\begin{itemdescr}

\pnum

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

\pnum

\constraints

\begin{itemize}

\item

For the last overload,

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

\item

\tcode{is_constructible_v<T1, decltype(get<0>(\exposid{FWD}(p)))>}

is \tcode{true}, and

\item

\tcode{is_constructible_v<T2, decltype(get<1>(\exposid{FWD}(p)))>}

is \tcode{true}.

\end{itemize}

\pnum

\effects

Initializes \tcode{first} with \tcode{get<0>(\exposid{FWD}(p))} and

\tcode{second} with \tcode{get<1>(\exposid{FWD}(p))}.

\pnum

\remarks

The expression inside \keyword{explicit} is equivalent to:

\begin{codeblock}

!is_convertible_v<decltype(get<0>(@\exposid{FWD}@(p))), T1> ||

!is_convertible_v<decltype(get<1>(@\exposid{FWD}@(p))), T2>

\end{codeblock}

The constructor is defined as deleted if

\begin{codeblock}

reference_constructs_from_temporary_v<first_type, decltype(get<0>(@\exposid{FWD}@(p)))> ||

reference_constructs_from_temporary_v<second_type, decltype(get<1>(@\exposid{FWD}@(p)))>

\end{codeblock}

is \tcode{true}.

\end{itemdescr}

\indexlibraryctor{pair}%

\begin{itemdecl}

template<class... Args1, class... Args2>

constexpr pair(piecewise_construct_t,

tuple<Args1...> first_args, tuple<Args2...> second_args);

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

\begin{itemize}

\item \tcode{is_constructible_v<T1, Args1...>} is \tcode{true} and

\item \tcode{is_constructible_v<T2, Args2...>} is \tcode{true}.

\end{itemize}

\pnum

\effects

Initializes \tcode{first} with arguments of types

\tcode{Args1...} obtained by forwarding the elements of \tcode{first_args}

and initializes \tcode{second} with arguments of types \tcode{Args2...}

obtained by forwarding the elements of \tcode{second_args}. (Here, forwarding

an element \tcode{x} of type \tcode{U} within a \tcode{tuple} object means calling

\tcode{std::forward<U>(x)}.) This form of construction, whereby constructor

arguments for \tcode{first} and \tcode{second} are each provided in a separate

\tcode{tuple} object, is called \defn{piecewise construction}.

\begin{note}

If a data member of \tcode{pair} is of reference type and

its initialization binds it to a temporary object,

the program is ill-formed\iref{class.base.init}.

\end{note}

\end{itemdescr}

\indexlibrarymember{operator=}{pair}%

\begin{itemdecl}

constexpr pair& operator=(const pair& p);

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

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

\pnum

\returns

\tcode{*this}.

\pnum

\remarks

This operator is defined as deleted unless

\tcode{is_copy_assignable_v<T1>} is \tcode{true} and

\tcode{is_copy_assignable_v<T2>} is \tcode{true}.

\end{itemdescr}

\indexlibrarymember{operator=}{pair}%

\begin{itemdecl}

constexpr const pair& operator=(const pair& p) const;

\end{itemdecl}

\begin{itemdescr}

\pnum