\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 Table~\ref{tab:util.lib.summary}.

\begin{libsumtab}{General utilities library summary}{tab:util.lib.summary}

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

\ref{pairs} & Pairs & \tcode{<utility>} \\ \rowsep

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

\ref{intseq} & Compile-time integer sequences & \tcode{<utility>} \\ \rowsep

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

& & \tcode{<memory>} \\

\ref{memory} & Memory & \tcode{<cstdlib>} \\

& & \tcode{<cstring>} \\ \rowsep

\ref{smartptr} & Smart pointers & \tcode{<memory>} \\ \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{time} & Time utilities & \tcode{<chrono>} \\

& & \tcode{<ctime>} \\ \rowsep

\ref{allocator.adaptor} & Scoped allocators & \tcode{<scoped_allocator>} \\ \rowsep

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

\end{libsumtab}

\rSec1[utility]{Utility components}

This subclause contains some basic function and class templates that are used

throughout the rest of the library.

\indexlibrary{\idxhdr{utility}}%

\indexlibrary{\idxcode{rel_ops}}%

\synopsis{Header \tcode{<utility>} synopsis}

The header \tcode{<utility>} defines several types and function templates

that are described in this Clause. It also defines the template \tcode{pair}

and various function templates that operate on \tcode{pair} objects.

\begin{codeblock}

#include <initializer_list>

namespace std {

// \ref{operators}, operators:

namespace rel_ops {

template<class T> bool operator!=(const T&, const T&);

template<class T> bool operator> (const T&, const T&);

template<class T> bool operator<=(const T&, const T&);

template<class T> bool operator>=(const T&, const T&);

}

// \ref{utility.swap}, swap:

template<class T> void swap(T& a, T& b) noexcept(@\seebelow@);

template <class T, size_t N> void swap(T (&a)[N], T (&b)[N]) noexcept(noexcept(swap(*a, *b)));

// \ref{utility.exchange}, exchange:

template <class T, class U=T> 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<T>::value && is_copy_constructible<T>::value,

const T&, T&&> move_if_noexcept(T& x) noexcept;

// \ref{declval}, declval:

template <class T>

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

// \ref{pairs}, pairs:

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 bool operator< (const pair<T1,T2>&, const pair<T1,T2>&);

template <class T1, class T2>

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

template <class T1, class T2>

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

template <class T1, class T2>

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

template <class T1, class T2>

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

template <class T1, class T2>

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> class tuple_size;

template <size_t I, class T> class tuple_element;

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

template <class T1, class T2> struct tuple_element<0, std::pair<T1, T2> >;

template <class T1, class T2> struct tuple_element<1, std::pair<T1, T2> >;

template<size_t I, class T1, class T2>

constexpr typename tuple_element<I, std::pair<T1, T2> >::type&

get(std::pair<T1, T2>&) noexcept;

template<size_t I, class T1, class T2>

constexpr typename tuple_element<I, std::pair<T1, T2> >::type&&

get(std::pair<T1, T2>&&) noexcept;

template<size_t I, class T1, class T2>

constexpr const typename tuple_element<I, std::pair<T1, T2> >::type&

get(const std::pair<T1, T2>&) noexcept;

template <class T, class U>

constexpr T& get(pair<T, U>& p) noexcept;

template <class T, class U>

constexpr const T& get(const pair<T, U>& p) noexcept;

template <class T, class U>

constexpr T&& get(pair<T, U>&& p) noexcept;

template <class T, class U>

constexpr T& get(pair<U, T>& p) noexcept;

template <class T, class U>

constexpr const T& get(const pair<U, T>& p) noexcept;

template <class T, class U>

constexpr T&& get(pair<U, T>&& p) noexcept;

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

struct piecewise_construct_t { };

constexpr piecewise_construct_t piecewise_construct = piecewise_construct_t();

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

// \ref{intseq}, Compile-time integer sequences

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

}

\end{codeblock}

\rSec2[operators]{Operators}

To avoid redundant definitions of \tcode{operator!=} out of \tcode{operator==}

and operators \tcode{>}, \tcode{<=}, and \tcode{>=} out of \tcode{operator<},

the library provides the following:

\indexlibrary{\idxcode{operator"!=}}%

\begin{itemdecl}

template <class T> bool operator!=(const T& x, const T& y);

\end{itemdecl}

\begin{itemdescr}

Type \tcode{T} is \tcode{EqualityComparable} (Table~\ref{equalitycomparable}).

\tcode{!(x == y)}.

\end{itemdescr}

\indexlibrary{\idxcode{operator>}}%

\begin{itemdecl}

template <class T> bool operator>(const T& x, const T& y);

\end{itemdecl}

\begin{itemdescr}

Type \tcode{T} is \tcode{LessThanComparable} (Table~\ref{lessthancomparable}).

\tcode{y < x}.

\end{itemdescr}

\indexlibrary{\idxcode{operator<=}}%

\begin{itemdecl}

template <class T> bool operator<=(const T& x, const T& y);

\end{itemdecl}

\begin{itemdescr}

Type \tcode{T} is \tcode{LessThanComparable} (Table~\ref{lessthancomparable}).

\tcode{!(y < x)}.

\end{itemdescr}

\indexlibrary{\idxcode{operator>=}}%

\begin{itemdecl}

template <class T> bool operator>=(const T& x, const T& y);

\end{itemdecl}

\begin{itemdescr}

Type \tcode{T} is \tcode{LessThanComparable} (Table~\ref{lessthancomparable}).

\tcode{!(x < y)}.

\end{itemdescr}

In this library, whenever a declaration is provided for an \tcode{operator!=},

\tcode{operator>}, \tcode{operator>=}, or \tcode{operator<=},

and requirements and semantics are not explicitly provided,

the requirements and semantics are as specified in this Clause.

\rSec2[utility.swap]{swap}

\indexlibrary{\idxcode{swap}}%

\begin{itemdecl}

template<class T> void swap(T& a, T& b) noexcept(@\seebelow@);

\end{itemdecl}

\begin{itemdescr}

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

\begin{codeblock}

is_nothrow_move_constructible<T>::value &&

is_nothrow_move_assignable<T>::value

\end{codeblock}

Type

\tcode{T}

shall be

\tcode{MoveConstructible} (Table~\ref{moveconstructible})

and

\tcode{MoveAssignable} (Table~\ref{moveassignable}).

Exchanges values stored in two locations.

\end{itemdescr}

\indexlibrary{\idxcode{swap}}%

\begin{itemdecl}

template<class T, size_t N>

void swap(T (&a)[N], T (&b)[N]) noexcept(noexcept(swap(*a, *b)));

\end{itemdecl}

\begin{itemdescr}

\tcode{a[i]} shall be swappable with~(\ref{swappable.requirements}) \tcode{b[i]}

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

\effects \tcode{swap_ranges(a, a + N, b)}

\end{itemdescr}

\rSec2[utility.exchange]{exchange}

\begin{itemdecl}

template <class T, class U=T> T exchange(T& obj, U&& new_val);

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

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

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

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

\remark If the second form is instantiated with an lvalue reference type, the program is ill-formed.

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

\indexlibrary{\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{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{itemdescr}

\indexlibrary{\idxcode{move_if_noexcept}}%

\begin{itemdecl}

template <class T> constexpr conditional_t<

!is_nothrow_move_constructible<T>::value && is_copy_constructible<T>::value,

const T&, T&&> move_if_noexcept(T& x) noexcept;

\end{itemdecl}

\begin{itemdescr}

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

\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 unevaluated operands (Clause~\ref{expr}).

\indexlibrary{\idxcode{declval}}%

\begin{itemdecl}

template <class T>

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

\end{itemdecl}

\begin{itemdescr}

\notes If this function is odr-used~(\ref{basic.def.odr}), the program is ill-formed.

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

\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}~(\ref{meta.trans.other}).

\end{itemdescr}

\rSec1[pairs]{Pairs}

\rSec2[pairs.general]{In general}

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}).%

\indexlibrary{\idxcode{pair}}%

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

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

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

\indexlibrary{\idxcode{pair}}%

\begin{codeblock}

// defined in header \tcode{<utility>}

namespace std {

template <class T1, class T2>

struct pair {

typedef T1 first_type;

typedef T2 second_type;

T1 first;

T2 second;

pair(const pair&) = default;

pair(pair&&) = default;

constexpr pair();

constexpr pair(const T1& x, const T2& y);

template<class U, class V> constexpr pair(U&& x, V&& y);

template<class U, class V> constexpr pair(const pair<U, V>& p);

template<class U, class V> constexpr pair(pair<U, V>&& p);

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

pair(piecewise_construct_t,

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

pair& operator=(const pair& p);

template<class U, class V> pair& operator=(const pair<U, V>& p);

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

template<class U, class V> pair& operator=(pair<U, V>&& p);

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

};

}

\end{codeblock}

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

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

throws an exception.

The defaulted move and copy constructor, respectively, of pair shall

be a \tcode{constexpr} function if and only if all required element-wise

initializations for copy and move, respectively, would satisfy the

requirements for a \tcode{constexpr} function.

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\begin{itemdecl}

constexpr pair();

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_default_constructible<first_type>::value} is \tcode{true}

and \tcode{is_default_construct-}\\\tcode{ible<second_type>::value} is \tcode{true}.

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

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\begin{itemdecl}

constexpr pair(const T1& x, const T2& y);

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_copy_constructible<first_type>::value} is \tcode{true}

and \tcode{is_copy_constructible<sec\-ond_type>::value} is \tcode{true}.

The constructor initializes \tcode{first} with \tcode{x} and \tcode{second}

with \tcode{y}.

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\begin{itemdecl}

template<class U, class V> constexpr pair(U&& x, V&& y);

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_constructible<first_type, U\&\&>::value} is \tcode{true}

and \tcode{is_constructible<second_type, V\&\&>::value} is \tcode{true}.

The constructor initializes \tcode{first} with

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

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

If \tcode{U} is not implicitly convertible to \tcode{first_type} or \tcode{V} is not

implicitly convertible to \tcode{second_type} this constructor shall not participate in

overload resolution.

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\begin{itemdecl}

template<class U, class V> constexpr pair(const pair<U, V>& p);

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_constructible<first_type, const U\&>::value} is \tcode{true}

and \tcode{is_constructible<sec\-ond_type, const V\&>::value} is \tcode{true}.

Initializes members from the corresponding members of the argument.

\remark This constructor shall not participate in overload resolution unless

\tcode{const U\&} is implicitly convertible to \tcode{first_type} and

\tcode{const V\&} is implicitly convertible to \tcode{second_type}.

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\begin{itemdecl}

template<class U, class V> constexpr pair(pair<U, V>&& p);

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_constructible<first_type, U\&\&>::value} is \tcode{true}

and \tcode{is_constructible<second_type, V\&\&>::value} is \tcode{true}.

The constructor initializes \tcode{first} with

\tcode{std::forward<U>(p.first)}

and \tcode{second} with

\tcode{std::\brk{}forward<V>(p.second)}.

\remark This constructor shall not participate in overload resolution unless

\tcode{U} is implicitly convertible to \tcode{first_type} and

\tcode{V} is implicitly convertible to \tcode{second_type}.

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{pair}}

\begin{itemdecl}

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

pair(piecewise_construct_t,

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

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_constructible<first_type, Args1\&\&...>::value} is \tcode{true}

and \tcode{is_con\-structible<second_type, Args2\&\&...>::value} is \tcode{true}.

\effects The constructor 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}

\indexlibrary{\idxcode{operator=}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{operator=}}

\begin{itemdecl}

pair& operator=(const pair& p);

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_copy_assignable<first_type>::value} is \tcode{true}

and \tcode{is_copy_assignable<second_type>::value} is \tcode{true}.

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

\returns \tcode{*this}.

\end{itemdescr}

\indexlibrary{\idxcode{operator=}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{operator=}}

\begin{itemdecl}

template<class U, class V> pair& operator=(const pair<U, V>& p);

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_assignable<first_type\&, const U\&>::value} is \tcode{true}

and \tcode{is_assignable<second_type\&, const V\&>::value} is \tcode{true}.

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

\returns \tcode{*this}.

\end{itemdescr}

\indexlibrary{\idxcode{operator=}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{operator=}}

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

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

\begin{codeblock}

is_nothrow_move_assignable<T1>::value &&

is_nothrow_move_assignable<T2>::value

\end{codeblock}

\requires \tcode{is_move_assignable<first_type>::value} is \tcode{true}

and \tcode{is_move_assignable<second_type>::value} is \tcode{true}.

Assigns to \tcode{first} with \tcode{std::forward<first_type>(p.first)}

and to \tcode{second} with\\ \tcode{std::forward<second_type>(p.second)}.

\returns \tcode{*this}.

\end{itemdescr}

\indexlibrary{\idxcode{operator=}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{operator=}}

\begin{itemdecl}

template<class U, class V> pair& operator=(pair<U, V>&& p);

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{is_assignable<first_type\&, U\&\&>::value} is \tcode{true}

and \tcode{is_assignable<second_type\&, V\&\&>::value} is \tcode{true}.

Assigns to \tcode{first} with \tcode{std::forward<U>(p.first)}

and to \tcode{second} with\\ \tcode{std::forward<V>(p.second)}.

\returns \tcode{*this}.

\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{pair}}

\indexlibrary{\idxcode{pair}!\idxcode{swap}}

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

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

\begin{codeblock}

noexcept(swap(first, p.first)) &&

noexcept(swap(second, p.second))

\end{codeblock}

\tcode{first} shall be swappable with~(\ref{swappable.requirements})

\tcode{p.first} and \tcode{second} shall be swappable with \tcode{p.second}.

\effects Swaps

\tcode{first} with \tcode{p.first} and

\tcode{second} with \tcode{p.second}.

\end{itemdescr}

\rSec2[pairs.spec]{Specialized algorithms}

\indexlibrary{\idxcode{operator==}!\tcode{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}

\tcode{x.first == y.first \&\& x.second == y.second}.

\end{itemdescr}

\indexlibrary{\idxcode{operator<}!\tcode{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}

\tcode{x.first < y.first || (!(y.first < x.first) \&\& x.second < y.second)}.

\end{itemdescr}

\indexlibrary{\idxcode{operator"!=}!\tcode{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}

\returns \tcode{!(x == y)}

\end{itemdescr}

\indexlibrary{\idxcode{operator>}!\tcode{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}

\returns \tcode{y < x}

\end{itemdescr}

\indexlibrary{\idxcode{operator>=}!\tcode{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}

\returns \tcode{!(x < y)}

\end{itemdescr}

\indexlibrary{\idxcode{operator<=}!\tcode{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}

\returns \tcode{!(y < x)}

\end{itemdescr}

\indexlibrary{\idxcode{swap}!\tcode{pair}}%

\begin{itemdecl}

template<class T1, class T2> void swap(pair<T1, T2>& x, pair<T1, T2>& y)

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

\end{itemdecl}

\begin{itemdescr}

\effects \tcode{x.swap(y)}

\end{itemdescr}

\indexlibrary{\idxcode{make_pair}}%

\begin{itemdecl}

template <class T1, class T2>

constexpr pair<V1, V2> make_pair(T1&& x, T2&& y);

\end{itemdecl}

\begin{itemdescr}

\returns \tcode{pair<V1, V2>(std::forward<T1>(x), std::forward<T2>(y))};

where \tcode{V1} and \tcode{V2} are determined as follows: Let \tcode{Ui} be

\tcode{decay_t<Ti>} for each \tcode{Ti}. Then each \tcode{Vi} is \tcode{X\&}

if \tcode{Ui} equals \tcode{reference_wrapper<X>}, otherwise \tcode{Vi} is

\tcode{Ui}.

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{itemdescr}

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

\indexlibrary{\idxcode{tuple_size}}%

\begin{itemdecl}

tuple_size<pair<T1, T2> >::value

\end{itemdecl}

\begin{itemdescr}

\pnum\returns Integral constant expression.

\pnum\textit{Value:} 2.

\end{itemdescr}

\indexlibrary{\idxcode{tuple_element}}%

\begin{itemdecl}

tuple_element<0, pair<T1, T2> >::type

\end{itemdecl}

\begin{itemdescr}

\pnum\textit{Value:} the type \tcode{T1}.

\end{itemdescr}

\indexlibrary{\idxcode{tuple_element}}%

\begin{itemdecl}

tuple_element<1, pair<T1, T2> >::type

\end{itemdecl}

\begin{itemdescr}

\pnum\textit{Value:} the type T2.

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{get}}%

\indexlibrary{\idxcode{get}!\idxcode{pair}}%

\begin{itemdecl}

template<size_t I, class T1, class T2>

constexpr typename tuple_element<I, std::pair<T1, T2> >::type&

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

template<size_t I, class T1, class T2>

constexpr const typename tuple_element<I, std::pair<T1, T2> >::type&

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

\end{itemdecl}

\begin{itemdescr}

\pnum\returns If \tcode{I == 0} returns \tcode{p.first};

if \tcode{I == 1} returns \tcode{p.second}; otherwise the program is ill-formed.

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{get}}%

\indexlibrary{\idxcode{get}!\idxcode{pair}}%

\begin{itemdecl}

template<size_t I, class T1, class T2>

constexpr typename tuple_element<I, std::pair<T1, T2> >::type&&

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

\end{itemdecl}

\begin{itemdescr}

\returns If \tcode{I == 0} returns \tcode{std::forward<T1\&\&>(p.first)};

if \tcode{I == 1} returns

\tcode{std::forward<T2\&\&>(\brk{}p.second)};

otherwise the program is ill-formed.

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{get}}%

\indexlibrary{\idxcode{get}!\idxcode{pair}}%

\begin{itemdecl}

template <class T, class U>

constexpr T& get(pair<T, U>& p) noexcept;

template <class T, class U>

constexpr const T& get(const pair<T, U>& p) noexcept;

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{T} and \tcode{U} are distinct types. Otherwise, the program is ill-formed.

\returns \tcode{get<0>(p);}

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{get}}%

\indexlibrary{\idxcode{get}!\idxcode{pair}}%

\begin{itemdecl}

template <class T, class U>

constexpr T&& get(pair<T, U>&& p) noexcept;

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{T} and \tcode{U} are distinct types. Otherwise, the program is ill-formed.

\returns \tcode{get<0>(std::move(p));}

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{get}}%

\indexlibrary{\idxcode{get}!\idxcode{pair}}%

\begin{itemdecl}

template <class T, class U>

constexpr T& get(pair<U, T>& p) noexcept;

template <class T, class U>

constexpr const T& get(const pair<U, T>& p) noexcept;

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{T} and \tcode{U} are distinct types. Otherwise, the program is ill-formed.

\returns \tcode{get<1>(p);}

\end{itemdescr}

\indexlibrary{\idxcode{pair}!\idxcode{get}}%

\indexlibrary{\idxcode{get}!\idxcode{pair}}%

\begin{itemdecl}

template <class T, class U>

constexpr T&& get(pair<U, T>&& p) noexcept;

\end{itemdecl}

\begin{itemdescr}

\requires \tcode{T} and \tcode{U} are distinct types. Otherwise, the program is ill-formed.

\returns \tcode{get<1>(std::move(p));}

\end{itemdescr}

\rSec2[pair.piecewise]{Piecewise construction}

\indexlibrary{\idxcode{piecewise_construct_t}}%

\indexlibrary{\idxcode{piecewise_construct}}%

\begin{itemdecl}

struct piecewise_construct_t { };

constexpr piecewise_construct_t piecewise_construct = piecewise_construct_t();

\end{itemdecl}

The \tcode{struct} \tcode{piecewise_construct_t} is an empty structure 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}~(\ref{tuple}) arguments used

for piecewise construction of the elements of the \tcode{pair} object.

\rSec1[tuple]{Tuples}

\rSec2[tuple.general]{In general}

\indexlibrary{\idxcode{tuple}}%

This subclause 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}.

\synopsis{Header \tcode{<tuple>} synopsis}

\indexlibrary{\idxhdr{tuple}}%

\begin{codeblock}

namespace std {

// \ref{tuple.tuple}, class template \tcode{tuple}:

template <class... Types> class tuple;

// \ref{tuple.creation}, tuple creation functions: