Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
11872 lines (9809 sloc) 382 KB
\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 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{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}
\pnum
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}
\pnum
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{forward}, forward/move:
template <class T> T&& forward(typename remove_reference<T>::type& t) noexcept;
template <class T> T&& forward(typename remove_reference<T>::type&& t) noexcept;
template <class T> typename remove_reference<T>::type&& move(T&&) noexcept;
template <class T> typename conditional<
!is_nothrow_move_constructible<T>::value && is_copy_constructible<T>::value,
const T&, T&&>::type move_if_noexcept(T& x) noexcept;
// \ref{declval}, declval:
template <class T>
typename add_rvalue_reference<T>::type 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>
bool operator==(const pair<T1,T2>&, const pair<T1,T2>&);
template <class T1, class T2>
bool operator< (const pair<T1,T2>&, const pair<T1,T2>&);
template <class T1, class T2>
bool operator!=(const pair<T1,T2>&, const pair<T1,T2>&);
template <class T1, class T2>
bool operator> (const pair<T1,T2>&, const pair<T1,T2>&);
template <class T1, class T2>
bool operator>=(const pair<T1,T2>&, const pair<T1,T2>&);
template <class T1, class T2>
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>
@\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>
typename tuple_element<I, std::pair<T1, T2> >::type& get(std::pair<T1, T2>&) noexcept;
template<size_t I, class T1, class T2>
typename tuple_element<I, std::pair<T1, T2> >::type&& get(std::pair<T1, T2>&&) noexcept;
template<size_t I, class T1, class T2>
const typename tuple_element<I, std::pair<T1, T2> >::type&
get(const std::pair<T1, T2>&) 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>}
}
\end{codeblock}
\rSec2[operators]{Operators}
\pnum
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}
\pnum
\requires
Type \tcode{T} is \tcode{EqualityComparable} (Table~\ref{equalitycomparable}).
\pnum
\returns
\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}
\pnum
\requires
Type \tcode{T} is \tcode{LessThanComparable} (Table~\ref{lessthancomparable}).
\pnum
\returns
\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}
\pnum
\requires
Type \tcode{T} is \tcode{LessThanComparable} (Table~\ref{lessthancomparable}).
\pnum
\returns
\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}
\pnum
\requires
Type \tcode{T} is \tcode{LessThanComparable} (Table~\ref{lessthancomparable}).
\pnum
\returns
\tcode{!(x < y)}.
\end{itemdescr}
\pnum
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}
\pnum
\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}
\pnum
\requires
Type
\tcode{T}
shall be
\tcode{MoveConstructible} (Table~\ref{moveconstructible})
and
\tcode{MoveAssignable} (Table~\ref{moveassignable}).
\pnum
\effects
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}
\pnum
\requires
\tcode{a[i]} shall be swappable with~(\ref{swappable.requirements}) \tcode{b[i]}
for all \tcode{i} in the range \range{0}{N}.
\pnum
\effects \tcode{swap_ranges(a, a + N, b)}
\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.
\indexlibrary{\idxcode{forward}}%
\begin{itemdecl}
template <class T> T&& forward(typename remove_reference<T>::type& t) noexcept;
template <class T> T&& forward(typename remove_reference<T>::type&& t) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{static_cast<T\&\&>(t)}.
\pnum
if the second form is instantiated with an lvalue reference type, the program is ill-formed.
\pnum
\enterexample
\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}
\pnum
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.
\exitexample
\end{itemdescr}
\indexlibrary{\idxcode{move}}%
\begin{itemdecl}
template <class T> typename remove_reference<T>::type&& move(T&& t) noexcept;
\end{itemdecl}
\begin{itemdescr}
\returns
\tcode{static_cast<typename remove_reference<T>::type\&\&>(t)}.
\pnum
\enterexample
\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}
\pnum
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}.
\exitexample
\end{itemdescr}
\indexlibrary{\idxcode{move_if_noexcept}}%
\begin{itemdecl}
template <class T> typename conditional<
!is_nothrow_move_constructible<T>::value && is_copy_constructible<T>::value,
const T&, T&&>::type move_if_noexcept(T& x) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{std::move(x)}
\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 (Clause~\ref{expr}).
\indexlibrary{\idxcode{declval}}%
\begin{itemdecl}
template <class T>
typename add_rvalue_reference<T>::type declval() noexcept; // as unevaluated operand
\end{itemdecl}
\begin{itemdescr}
\pnum
\notes If this function is odr-used~(\ref{basic.def.odr}), the program is ill-formed.
\pnum
\notes The template parameter \tcode{T} of \tcode{declval} may be an incomplete type.
\enterexample
\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}).
\exitexample
\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}).%
\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();
pair(const T1& x, const T2& y);
template<class U, class V> pair(U&& x, V&& y);
template<class U, class V> pair(const pair<U, V>& p);
template<class U, class V> 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}
\pnum
Constructors and member function of \tcode{pair} shall not throw exceptions unless one of
the element-wise operations specified to be called for that operation throws an exception.
\indexlibrary{\idxcode{pair}!\idxcode{pair}}
\indexlibrary{\idxcode{pair}!\idxcode{pair}}
\begin{itemdecl}
constexpr pair();
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_default_constructible<first_type>::value} is \tcode{true}
and \tcode{is_default_construct-}\\\tcode{ible<second_type>::value} is \tcode{true}.
\pnum
\effects
Value-initializes \tcode{first} and \tcode{second}.
\end{itemdescr}
\indexlibrary{\idxcode{pair}!\idxcode{pair}}
\indexlibrary{\idxcode{pair}!\idxcode{pair}}
\begin{itemdecl}
pair(const T1& x, const T2& y);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_copy_constructible<first_type>::value} is \tcode{true}
and \tcode{is_copy_constructible<sec\-ond_type>::value} is \tcode{true}.
\pnum
\effects
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> pair(U&& x, V&& y);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_constructible<first_type, U\&\&>::value} is \tcode{true}
and \tcode{is_constructible<second_type, V\&\&>::value} is \tcode{true}.
\pnum
\effects
The constructor initializes \tcode{first} with
\tcode{std::forward<U>(x)} and \tcode{second}
with \tcode{std::forward<\brk{}V>(y)}.
\pnum
\notes
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> pair(const pair<U, V>& p);
\end{itemdecl}
\begin{itemdescr}
\pnum
\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}.
\pnum
\effects
Initializes members from the corresponding members of the argument.
\pnum
\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> pair(pair<U, V>&& p);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_constructible<first_type, U\&\&>::value} is \tcode{true}
and \tcode{is_constructible<second_type, V\&\&>::value} is \tcode{true}.
\pnum
\effects
The constructor initializes \tcode{first} with
\tcode{std::forward<U>(p.first)}
and \tcode{second} with
\tcode{std::\brk{}forward<V>(p.second)}.
\pnum
\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}
\pnum
\requires
\requires \tcode{is_constructible<first_type, Args1\&\&...>::value} is \tcode{true}
and \tcode{is_con\-structible<second_type, Args2\&\&...>::value} is \tcode{true}.
\pnum
\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}
\pnum
\requires \tcode{is_copy_assignable<first_type>::value} is \tcode{true}
and \tcode{is_copy_assignable<second_type>::value} is \tcode{true}.
\pnum
\effects Assigns \tcode{p.first} to \tcode{first} and \tcode{p.second} to \tcode{second}.
\pnum
\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}
\pnum
\requires \tcode{is_assignable<first_type\&, const U\&>::value} is \tcode{true}
and \tcode{is_assignable<second_type\&, const V\&>::value} is \tcode{true}.
\pnum
\effects Assigns \tcode{p.first} to \tcode{first} and \tcode{p.second} to \tcode{second}.
\pnum
\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}
\pnum
\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}
\pnum
\requires \tcode{is_move_assignable<first_type>::value} is \tcode{true}
and \tcode{is_move_assignable<second_type>::value} is \tcode{true}.
\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}.
\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}
\pnum
\requires \tcode{is_assignable<first_type\&, U\&\&>::value} is \tcode{true}
and \tcode{is_assignable<second_type\&, V\&\&>::value} is \tcode{true}.
\pnum
\effects
Assigns to \tcode{first} with \tcode{std::forward<U>(p.first)}
and to \tcode{second} with\\ \tcode{std::forward<V>(p.second)}.
\pnum
\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}
\pnum
\remarks The expression inside \tcode{noexcept} is equivalent to:
\begin{codeblock}
noexcept(swap(first, p.first)) &&
noexcept(swap(second, p.second))
\end{codeblock}
\pnum
\requires
\tcode{first} shall be swappable with~(\ref{swappable.requirements})
\tcode{p.first} and \tcode{second} shall be swappable with \tcode{p.second}.
\pnum
\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>
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}
\indexlibrary{\idxcode{operator<}!\tcode{pair}}%
\begin{itemdecl}
template <class T1, class T2>
bool operator<(const pair<T1, T2>& x, const pair<T1, T2>& y);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\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>
bool operator!=(const pair<T1, T2>& x, const pair<T1, T2>& y);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{!(x == y)}
\end{itemdescr}
\indexlibrary{\idxcode{operator>}!\tcode{pair}}%
\begin{itemdecl}
template <class T1, class T2>
bool operator>(const pair<T1, T2>& x, const pair<T1, T2>& y);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{y < x}
\end{itemdescr}
\indexlibrary{\idxcode{operator>=}!\tcode{pair}}%
\begin{itemdecl}
template <class T1, class T2>
bool operator>=(const pair<T1, T2>& x, const pair<T1, T2>& y);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{!(x < y)}
\end{itemdescr}
\indexlibrary{\idxcode{operator<=}!\tcode{pair}}%
\begin{itemdecl}
template <class T1, class T2>
bool operator<=(const pair<T1, T2>& x, const pair<T1, T2>& y);
\end{itemdecl}
\begin{itemdescr}
\pnum
\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}
\pnum
\effects \tcode{x.swap(y)}
\end{itemdescr}
\indexlibrary{\idxcode{make_pair}}%
\begin{itemdecl}
template <class T1, class T2>
pair<V1, V2> make_pair(T1&& x, T2&& y);
\end{itemdecl}
\begin{itemdescr}
\pnum
\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<Ti>::type} 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}.
\pnum
\enterexample
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}
\exitexample
\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>
typename tuple_element<I, std::pair<T1, T2> >::type& get(pair<T1, T2>&) noexcept;
template<size_t I, class T1, class T2>
const typename tuple_element<I, std::pair<T1, T2> >::type& get(const pair<T1, T2>&) 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>
typename tuple_element<I, std::pair<T1, T2> >::type&& get(std::pair<T1, T2>&&) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\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}
\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}
\pnum
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}
\pnum
\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}.
\pnum
\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:
const @\unspec@ ignore;
template <class... Types>
tuple<@\textit{VTypes}@...> make_tuple(Types&&...);
template <class... Types>
tuple<@\textit{Types}@...> forward_as_tuple(Types&&...) noexcept;
template<class... Types>
tuple<Types&...> tie(Types&...) noexcept;
template <class... Tuples>
tuple<@\textit{Ctypes}@...> tuple_cat(Tuples&&...);
// \ref{tuple.helper}, tuple helper classes:
template <class T> class tuple_size; // undefined
template <class T> class tuple_size<const T>;
template <class T> class tuple_size<volatile T>;
template <class T> class tuple_size<const volatile T>;
template <class... Types> class tuple_size<tuple<Types...> >;
template <size_t I, class T> class tuple_element; // undefined
template <size_t I, class T> class tuple_element<I, const T>;
template <size_t I, class T> class tuple_element<I, volatile T>;
template <size_t I, class T> class tuple_element<I, const volatile T>;
template <size_t I, class... Types> class tuple_element<I, tuple<Types...> >;
// \ref{tuple.elem}, element access:
template <size_t I, class... Types>
typename tuple_element<I, tuple<Types...> >::type& get(tuple<Types...>&) noexcept;
template <size_t I, class... types>
typename tuple_element<I, tuple<Types...> >::type&& get(tuple<Types...>&&) noexcept;
template <size_t I, class... types>
typename tuple_element<I, tuple<Types...> >::type const& get(const tuple<Types...>&) noexcept;
// \ref{tuple.rel}, relational operators:
template<class... TTypes, class... UTypes>
bool operator==(const tuple<TTypes...>&, const tuple<UTypes...>&);
template<class... TTypes, class... UTypes>
bool operator<(const tuple<TTypes...>&, const tuple<UTypes...>&);
template<class... TTypes, class... UTypes>
bool operator!=(const tuple<TTypes...>&, const tuple<UTypes...>&);
template<class... TTypes, class... UTypes>
bool operator>(const tuple<TTypes...>&, const tuple<UTypes...>&);
template<class... TTypes, class... UTypes>
bool operator<=(const tuple<TTypes...>&, const tuple<UTypes...>&);
template<class... TTypes, class... UTypes>
bool 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>
void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(@\seebelow@);
}
\end{codeblock}
\rSec2[tuple.tuple]{Class template \tcode{tuple}}
\indexlibrary{\idxcode{tuple}}%
\begin{codeblock}
namespace std {
template <class... Types>
class tuple {
public:
// \ref{tuple.cnstr}, \tcode{tuple} construction
constexpr tuple();
explicit tuple(const Types&...);
template <class... UTypes>
explicit tuple(UTypes&&...);
tuple(const tuple&) = default;
tuple(tuple&&) = default;
template <class... UTypes>
tuple(const tuple<UTypes...>&);
template <class... UTypes>
tuple(tuple<UTypes...>&&);
template <class U1, class U2>
tuple(const pair<U1, U2>&); // iff \tcode{sizeof...(Types) == 2}
template <class U1, class U2>
tuple(pair<U1, U2>&&); // iff \tcode{sizeof...(Types) == 2}
// allocator-extended constructors
template <class Alloc>
tuple(allocator_arg_t, const Alloc& a);
template <class Alloc>
tuple(allocator_arg_t, const Alloc& a, const Types&...);
template <class Alloc, class... UTypes>
tuple(allocator_arg_t, const Alloc& a, UTypes&&...);
template <class Alloc>
tuple(allocator_arg_t, const Alloc& a, const tuple&);
template <class Alloc>
tuple(allocator_arg_t, const Alloc& a, tuple&&);
template <class Alloc, class... UTypes>
tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&);
template <class Alloc, class... UTypes>
tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
template <class Alloc, class U1, class U2>
tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
template <class Alloc, class U1, class U2>
tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&);
// \ref{tuple.assign}, \tcode{tuple} assignment
tuple& operator=(const tuple&);
tuple& operator=(tuple&&) noexcept(@\seebelow@);
template <class... UTypes>
tuple& operator=(const tuple<UTypes...>&);
template <class... UTypes>
tuple& operator=(tuple<UTypes...>&&);
template <class U1, class U2>
tuple& operator=(const pair<U1, U2>&); // iff \tcode{sizeof...(Types) == 2}
template <class U1, class U2>
tuple& operator=(pair<U1, U2>&&); // iff \tcode{sizeof...(Types) == 2}
// \ref{tuple.swap}, \tcode{tuple} swap
void swap(tuple&) noexcept(@\seebelow@);
};
}
\end{codeblock}
\rSec3[tuple.cnstr]{Construction}
\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
In the constructor descriptions that follow, let $i$ be in the range
\range{0}{sizeof...(Types)} in order, $T_i$ be the $i^{th}$ type in \tcode{Types}, and
$U_i$ be the $i^{th}$ type in a template parameter pack named \tcode{UTypes}, where indexing
is zero-based.
\indexlibrary{\idxcode{tuple}!\idxcode{tuple}}%
\begin{itemdecl}
constexpr tuple();
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_default_constructible<$T_i$>::value} is true for all $i$.
\pnum
\effects Value initializes each element.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\begin{itemdecl}
explicit tuple(const Types&...);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_copy_constructible<$T_i$>::value} is true for all $i$.
\pnum
\effects Initializes each element with the value of the
corresponding parameter.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\begin{itemdecl}
template <class... UTypes>
explicit tuple(UTypes&&... u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{sizeof...(Types)} \tcode{==} \tcode{sizeof...(UTypes)}.
\tcode{is_constructible<$T_i$, $U_i$\&\&>::value} 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
\remark This constructor shall not participate in overload resolution unless each type
in \tcode{UTypes} is implicitly convertible to its corresponding type in \tcode{Types}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\begin{itemdecl}
tuple(const tuple& u) = default;
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_copy_constructible<$T_i$>::value} is \tcode{true} for all $i$.
\pnum
\effects Initializes each element of \tcode{*this} with the
corresponding element of \tcode{u}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\begin{itemdecl}
tuple(tuple&& u) = default;
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_move_constructible<$T_i$>::value} is \tcode{true} for all $i$.
\pnum
\effects For all $i$, initializes the $i^{th}$ element of \tcode{*this} with
\tcode{std::forward<$T_i$>(get<$i$>(u))}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\begin{itemdecl}
template <class... UTypes> tuple(const tuple<UTypes...>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{sizeof...(Types)} \tcode{==} \tcode{sizeof...(UTypes)}.
\tcode{is_constructible<$T_i$, const $U_i$\&>::value} is \tcode{true} for all $i$.
\pnum
\effects Constructs each element of \tcode{*this} with the corresponding
element of \tcode{u}.
\pnum
\remark This constructor shall not participate in overload resolution unless
\tcode{const $U_i$\&} is implicitly convertible to $T_i$ for all $i$.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\begin{itemdecl}
template <class... UTypes> tuple(tuple<UTypes...>&& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{sizeof...(Types)} \tcode{==} \tcode{sizeof...(UTypes)}.
\tcode{is_constructible<$T_i$, $U_i$\&\&>::value} is \tcode{true} for all $i$.
\pnum
\effects For all $i$, initializes the $i^{th}$ element of \tcode{*this} with
\tcode{std::forward<$U_i$>(get<$i$>(u))}.
\pnum
\remark This constructor shall not participate in overload resolution unless
each type in \tcode{UTypes} is implicitly convertible to its corresponding type in
\tcode{Types}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\indexlibrary{\idxcode{pair}}%
\begin{itemdecl}
template <class U1, class U2> tuple(const pair<U1, U2>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{sizeof...(Types) == 2}.
\tcode{is_constructible<$T_0$, const U1\&>::value} is \tcode{true} for the first type
$T_0$ in \tcode{Types} and
\tcode{is_constructible<$T_1$, const U2\&>::value} is \tcode{true} for the second type
$T_1$ in \tcode{Types}.
\pnum
\effects Constructs the first element with \tcode{u.first} and the
second element with \tcode{u.second}.
\pnum
\remark This constructor shall not participate in overload resolution unless
\tcode{const U1\&} is implicitly convertible to $T_0$ and \tcode{const U2\&}
is implicitly convertible to $T_1$.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\indexlibrary{\idxcode{pair}}%
\begin{itemdecl}
template <class U1, class U2> tuple(pair<U1, U2>&& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{sizeof...(Types) == 2}.
\tcode{is_constructible<$T_0$, U1\&\&>::value} is \tcode{true} for the first type
$T_0$ in \tcode{Types} and
\tcode{is_constructible<$T_1$, U2\&\&>::value} is \tcode{true} for the second type
$T_1$ in \tcode{Types}.
\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
\remark This constructor shall not participate in overload resolution unless
\tcode{U1} is implicitly convertible to $T_0$ and \tcode{U2}
is implicitly convertible to $T_1$.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!constructor}%
\begin{itemdecl}
template <class Alloc>
tuple(allocator_arg_t, const Alloc& a);
template <class Alloc>
tuple(allocator_arg_t, const Alloc& a, const Types&...);
template <class Alloc, class... UTypes>
tuple(allocator_arg_t, const Alloc& a, UTypes&&...);
template <class Alloc>
tuple(allocator_arg_t, const Alloc& a, const tuple&);
template <class Alloc>
tuple(allocator_arg_t, const Alloc& a, tuple&&);
template <class Alloc, class... UTypes>
tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes...>&);
template <class Alloc, class... UTypes>
tuple(allocator_arg_t, const Alloc& a, tuple<UTypes...>&&);
template <class Alloc, class U1, class U2>
tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
template <class Alloc, class U1, class U2>
tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&&);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{Alloc} shall meet the requirements for an
\tcode{Allocator}~(\ref{allocator.requirements}).
\pnum
\effects Equivalent to the preceding constructors except that each element is constructed with
uses-allocator construction~(\ref{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, $T_i$ be the $i^{th}$ type in \tcode{Types}, and $U_i$ be the $i^{th}$ type in a
template parameter pack named \tcode{UTypes}, where indexing is zero-based.
\indexlibrary{\idxcode{tuple}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{tuple}}%
\begin{itemdecl}
tuple& operator=(const tuple& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{is_copy_assignable<$T_i$>::value} is \tcode{true} for all $i$.
\pnum
\effects Assigns each element of \tcode{u} to the corresponding
element of \tcode{*this}.
\pnum
\returns \tcode{*this}
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{tuple}}%
\begin{itemdecl}
tuple& operator=(tuple&& u) noexcept(@\seebelow@);
\end{itemdecl}
\begin{itemdescr}
\pnum
\remark The expression inside \tcode{noexcept} is equivalent to the logical \textsc{and} of the
following expressions:
\begin{codeblock}
is_nothrow_move_assignable<@$T_i$@>::value
\end{codeblock}
where $T_i$ is the $i^{th}$ type in \tcode{Types}.
\pnum
\requires \tcode{is_move_assignable<$T_i$>::value} is \tcode{true} for all $i$.
\pnum
\effects For all $i$, assigns \tcode{std::forward<$T_i$>(get<$i$>(u))} to
\tcode{get<$i$>(*this)}.
\pnum
\returns \tcode{*this}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{tuple}}%
\begin{itemdecl}
template <class... UTypes>
tuple& operator=(const tuple<UTypes...>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{sizeof...(Types) == sizeof...(UTypes)} and
\tcode{is_assignable<$T_i$\&, const $U_i$\&>::value} is \tcode{true} for all $i$.
\pnum
\effects Assigns each element of \tcode{u} to the corresponding element
of \tcode{*this}.
\pnum
\returns \tcode{*this}
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{tuple}}%
\begin{itemdecl}
template <class... UTypes>
tuple& operator=(tuple<UTypes...>&& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{is_assignable<Ti\&, Ui\&\&>::value == true} for all \tcode{i}.
\tcode{sizeof...(Types)} \tcode{==}\\\tcode{sizeof...(UTypes)}.
\pnum
\effects For all $i$, assigns \tcode{std::forward<$U_i$>(get<$i$)>(u))} to
\tcode{get<$i$>(*this)}.
\pnum
\returns \tcode{*this}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{tuple}}%
\indexlibrary{\idxcode{pair}}%
\begin{itemdecl}
template <class U1, class U2> tuple& operator=(const pair<U1, U2>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{sizeof...(Types) == 2}.
\tcode{is_assignable<$T_0$\&, const U1\&>::value} is \tcode{true} for the first type $T_0$ in
\tcode{Types} and \tcode{is_assignable<$T_1$\&, const U2\&>::value} is \tcode{true} for the
second type $T_1$ in \tcode{Types}.
\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}
\indexlibrary{\idxcode{tuple}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{tuple}}%
\indexlibrary{\idxcode{pair}}%
\begin{itemdecl}
template <class U1, class U2> tuple& operator=(pair<U1, U2>&& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{sizeof...(Types) == 2}.
\tcode{is_assignable<$T_0$\&, U1\&\&>::value} is \tcode{true} for the first type $T_0$ in
\tcode{Types} and \tcode{is_assignable<$T_1$\&, U2\&\&>::value} is \tcode{true} for the second
type $T_1$ in \tcode{Types}.
\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}}
\indexlibrary{\idxcode{swap}!\idxcode{tuple}}
\indexlibrary{\idxcode{tuple}!\idxcode{swap}}
\begin{itemdecl}
void swap(tuple& rhs) noexcept(@\seebelow@);
\end{itemdecl}
\begin{itemdescr}
\pnum
\remark The expression inside \tcode{noexcept} is equivalent to the logical
\textsc{and} of the following expressions:
\begin{codeblock}
noexcept(swap(declval<@$T_i$@&>>(), declval<@$T_i$@&>()))
\end{codeblock}
where $T_1$ is the $i^{th}$ type in \tcode{Types}.
\pnum
\requires
Each element in \tcode{*this} shall be swappable with~(\ref{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
\throws Nothing unless one of the element-wise \tcode{swap} calls throws an exception.
\end{itemdescr}
\rSec3[tuple.creation]{Tuple creation functions}
\pnum
In the function descriptions that follow, let $i$ be in the range \range{0}{sizeof...(TTypes)}
in order and let $T_i$ be the $i^{th}$ type in a template parameter pack named \tcode{TTypes};
let $j$ be in the range \range{0}{sizeof...(UTypes)} in order and $U_j$ be the $j^{th}$ type
in a template parameter pack named \tcode{UTypes}, where indexing is zero-based.
\indexlibrary{\idxcode{make_tuple}}%
\indexlibrary{\idxcode{tuple}!\idxcode{make_tuple}}%
\begin{itemdecl}
template<class... Types>
tuple<@\textit{VTypes}@...> make_tuple(Types&&... t);
\end{itemdecl}
\begin{itemdescr} \pnum Let \tcode{$U_i$} be \tcode{decay<$T_i$>::type} for each
$T_i$ in \tcode{Types}. Then each $V_i$ in \tcode{VTypes} is
\tcode{X\&} if $U_i$ equals \tcode{reference_wrapper<X>}, otherwise
$V_i$ is $U_i$.
\pnum
\returns \tcode{tuple<VTypes...>(std::forward<Types>(t)...)}.
\pnum
\enterexample
\begin{codeblock}
int i; float j;
make_tuple(1, ref(i), cref(j))
\end{codeblock}
creates a tuple of type
\begin{codeblock}
tuple<int, int&, const float&>
\end{codeblock}
\exitexample
\end{itemdescr}
\indexlibrary{\idxcode{forward_as_tuple}}%
\indexlibrary{\idxcode{tuple}!\idxcode{forward_as_tuple}}%
\begin{itemdecl}
template<class... Types>
tuple<Types&&...> forward_as_tuple(Types&&... 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 variables, 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<Types\&\&...>(std::forward<Types>(t)...)}
\end{itemdescr}
\indexlibrary{\idxcode{tie}}%
\indexlibrary{\idxcode{tuple}!\idxcode{tie}}%
\begin{itemdecl}
template<class... Types>
tuple<Types&...> tie(Types&... t) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{tuple<Types\&>(t...)}. When an
argument in \tcode{t} is \tcode{ignore}, assigning
any value to the corresponding tuple element has no effect.
\pnum
\enterexample
\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}
\exitexample
\end{itemdescr}
\indexlibrary{\idxcode{tuple_cat}}
\begin{itemdecl}
template <class... Tuples>
tuple<@\textit{CTypes}@...> tuple_cat(Tuples&&... tpls);
\end{itemdecl}
\begin{itemdescr}
\pnum
In the following paragraphs, let $T_i$ be the $i^{th}$ type in \tcode{Tuples},
$U_i$ be \tcode{remove_reference<Ti>::type}, and $tp_i$ be the $i^{th}$
parameter in the function parameter pack \tcode{tpls}, where all indexing is
zero-based.
\pnum
\requires For all $i$, $U_i$ shall be the type
$\cv_i$ \tcode{tuple<$Args_i...$>}, where $\cv_i$ is the (possibly empty) $i^{th}$
cv-qualifier-seq and $Args_i$ is the parameter pack representing the element
types in $U_i$. Let ${A_{ik}}$ be the ${k_i}^{th}$ type in $Args_i$. For all
$A_{ik}$ the following requirements shall be satisfied: If $T_i$ is
deduced as an lvalue reference type, then
\tcode{is_constructible<$A_{ik}$, $cv_i$ $A_{ik}$\&>::value == true}, otherwise
\tcode{is_constructible<$A_{ik}$, $cv_i A_{ik}$\&\&>::value == true}.
\pnum
\remarks The types in \tcode{\textit{Ctypes}} shall be equal to the ordered
sequence of the extended types
\tcode{$Args_0$..., $Args_1$...,} ... \tcode{$Args_{n-1}$...}, where $n$ is
equal to \tcode{sizeof...(Tuples)}. Let \tcode{$e_i$...} be the $i^{th}$
ordered sequence of tuple elements of the resulting \tcode{tuple} object
corresponding to the type sequence $Args_i$.
\pnum
\returns A \tcode{tuple} object constructed by initializing the ${k_i}^{th}$
type element $e_{ik}$ in \tcode{$e_i$...} with\\
\tcode{get<$k_i$>(std::forward<$T_i$>($tp_i$))} for each valid $k_i$ and
each group $e_i$ in order.
\pnum
\realnote An implementation may support additional types in the parameter
pack \tcode{Tuples} that support the \tcode{tuple}-like protocol, such as
\tcode{pair} and \tcode{array}.
\end{itemdescr}
\rSec3[tuple.helper]{Tuple helper classes}
\indexlibrary{\idxcode{tuple_size}}%
\begin{itemdecl}
template <class... Types>
class tuple_size<tuple<Types...> >
: public integral_constant<size_t, sizeof...(Types)> { };
\end{itemdecl}
\indexlibrary{\idxcode{tuple_element}}%
\begin{itemdecl}
template <size_t I, class... Types>
class tuple_element<I, tuple<Types...> > {
public:
typedef TI type;
};
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{I < sizeof...(Types)}.
The program is ill-formed if \tcode{I} is out of bounds.
\pnum
\ctype \tcode{TI} is the
type of the \tcode{I}th element of \tcode{Types},
where indexing is zero-based.
\end{itemdescr}
\begin{itemdecl}
template <class T> class tuple_size<const T>;
template <class T> class tuple_size<volatile T>;
template <class T> class tuple_size<const volatile T>;
\end{itemdecl}
\begin{itemdescr}
\pnum
Let \term{TS} denote \tcode{tuple_size<T>} of the \cv-unqualified type \tcode{T}. Then each
of the three templates shall meet the \tcode{UnaryTypeTrait} requirements~(\ref{meta.rqmts})
with a \tcode{BaseCharacteristic} of
\begin{codeblock}
integral_constant<remove_cv<decltype(TS::value)>::type, TS::value>
\end{codeblock}
\end{itemdescr}
\begin{itemdecl}
template <size_t I, class T> class tuple_element<I, const T>;
template <size_t I, class T> class tuple_element<I, volatile T>;
template <size_t I, class T> class tuple_element<I, const volatile T>;
\end{itemdecl}
\begin{itemdescr}
Let \term{TE} denote \tcode{tuple_element<I, T>} of the \cv-unqualified type \tcode{T}. Then
each of the three templates shall meet the \tcode{TransformationTrait}
requirements~(\ref{meta.rqmts}) with a member typedef \tcode{type} that names the following
type:
\begin{itemize}
\item
for the first specialization, \tcode{add_const<\term{TE}::type>::type},
\item
for the second specialization, \tcode{add_volatile<\term{TE}::type>::type}, and
\item
for the third specialization, \tcode{add_cv<\term{TE}::type>::type}.
\end{itemize}
\end{itemdescr}
\rSec3[tuple.elem]{Element access}
\indexlibrary{\idxcode{tuple}!\idxcode{get}}%
\indexlibrary{\idxcode{get}!\idxcode{tuple}}%
\begin{itemdecl}
template <size_t I, class... Types>
typename tuple_element<I, tuple<Types...> >::type& get(tuple<Types...>& t) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{I < sizeof...(Types)}.
The program is ill-formed if \tcode{I} is out of bounds.
\pnum
\returns A reference to the \tcode{I}th element of \tcode{t}, where
indexing is zero-based.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{get}}%
\indexlibrary{\idxcode{get}!\idxcode{tuple}}%
\begin{itemdecl}
template <size_t I, class... types>
typename tuple_element<I, tuple<Types...> >::type&& get(tuple<Types...>&& t) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects Equivalent to
\tcode{return std::forward<typename tuple_element<I, tuple<Types...> >}\\
\tcode{::type\&\&>(get<I>(t));}
\pnum
\realnote if a \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{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{get}}%
\indexlibrary{\idxcode{get}!\idxcode{tuple}}%
\begin{itemdecl}
template <size_t I, class... Types>
typename tuple_element<I, tuple<Types...> >::type const& get(const tuple<Types...>& t) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{I < sizeof...(Types)}.
The program is ill-formed if \tcode{I} is out of bounds.
\pnum
\returns A const reference to the \tcode{I}th element of \tcode{t}, where
indexing is zero-based.
\pnum
\enternote Constness is shallow. If a \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 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. \exitnote
\pnum
\enternote The reason \tcode{get} is a
nonmember 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 \tcode{template} keyword. \exitnote
\end{itemdescr}
\rSec3[tuple.rel]{Relational operators}
\indexlibrary{\idxcode{tuple}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{tuple}}%
\begin{itemdecl}
template<class... TTypes, class... UTypes>
bool operator==(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires For all \tcode{i},
where \tcode{0 <= i} and
\tcode{i < sizeof...(Types)}, \tcode{get<i>(t) == get<i>(u)} is a valid expression
returning a type that is convertible to \tcode{bool}.
\tcode{sizeof...(TTypes)} \tcode{==}
\tcode{sizeof...(UTypes)}.
\pnum
\returns \tcode{true} iff \tcode{get<i>(t) == get<i>(u)} for all \tcode{i}.
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}
\indexlibrary{\idxcode{tuple}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<}!\idxcode{tuple}}%
\begin{itemdecl}
template<class... TTypes, class... UTypes>
bool operator<(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires For all \tcode{i},
where \tcode{0 <= i} and
\tcode{i < sizeof...(Types)}, \tcode{get<i>(t) < get<i>(u)}
and \tcode{get<i>(u) < get<i>(t)}
are valid expressions returning types that are
convertible to \tcode{bool}.
\tcode{sizeof...(TTypes)} \tcode{==}
\tcode{sizeof...(UTypes)}.
\pnum\returns The result of a lexicographical comparison
between \tcode{t} and \tcode{u}. The result is defined
as: \tcode{(bool)(get<0>(t) < get<0>(u)) ||
(!(bool)(get<0>(u) < get<0>(t)) \&\& t$_{\mathrm{tail}}$ <
u$_{\mathrm{tail}}$)}, where \tcode{r$_{\mathrm{tail}}$} for some
tuple \tcode{r} is a tuple containing all but the first element
of \tcode{r}. For any two zero-length tuples \tcode{e}
and \tcode{f}, \tcode{e < f} returns \tcode{false}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{tuple}}%
\begin{itemdecl}
template<class... TTypes, class... UTypes>
bool operator!=(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum\returns \tcode{!(t == u)}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{operator>}}%
\indexlibrary{\idxcode{operator>}!\idxcode{tuple}}%
\begin{itemdecl}
template<class... TTypes, class... UTypes>
bool operator>(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum\returns \tcode{u < t}.
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{operator<=}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{tuple}}%
\begin{itemdecl}
template<class... TTypes, class... UTypes>
bool operator<=(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum\returns \tcode{!(u < t)}
\end{itemdescr}
\indexlibrary{\idxcode{tuple}!\idxcode{operator>=}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{tuple}}%
\begin{itemdecl}
template<class... TTypes, class... UTypes>
bool operator>=(const tuple<TTypes...>& t, const tuple<UTypes...>& u);
\end{itemdecl}
\begin{itemdescr}
\pnum\returns \tcode{!(t < u)}
\end{itemdescr}
\pnum \enternote The above definitions for comparison operators
do not require \tcode{t$_{\mathrm{tail}}$}
(or \tcode{u$_{\mathrm{tail}}$}) to be constructed. It may not
even be possible, as \tcode{t} and \tcode{u} are not required to be copy
constructible. Also, all comparison operators are short circuited;
they do not perform element accesses beyond what is required to determine the
result of the comparison. \exitnote
\rSec3[tuple.traits]{Tuple traits}
\indexlibrary{\idxcode{uses_allocator<tuple>}}
\begin{itemdecl}
template <class... Types, class Alloc>
struct uses_allocator<tuple<Types...>, Alloc> : true_type { };
\end{itemdecl}
\begin{itemdescr}
\requires \tcode{Alloc} shall be an \tcode{Allocator}~(\ref{allocator.requirements}).
\pnum
\enternote 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}. \exitnote
\end{itemdescr}
\rSec3[tuple.special]{Tuple specialized algorithms}
\indexlibrary{\idxcode{swap}}%
\begin{itemdecl}
template <class... Types>
void swap(tuple<Types...>& x, tuple<Types...>& y) noexcept(@\seebelow@);
\end{itemdecl}
\begin{itemdescr}
\pnum
\remark The expression inside \tcode{noexcept} is equivalent to:
\begin{codeblock}
noexcept(x.swap(y))
\end{codeblock}
\pnum
\effects \tcode{x.swap(y)}
\end{itemdescr}
\rSec1[template.bitset]{Class template \tcode{bitset}}%
\indexlibrary{\idxcode{bitset}}
\synopsis{Header \tcode{<bitset>} synopsis}%
\indexlibrary{\idxhdr{bitset}}
\begin{codeblock}
#include <string>
#include <iosfwd> // for \tcode{istream}, \tcode{ostream}
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}
\pnum
The header
\tcode{<bitset>}
defines a
class template
and several related functions for representing
and manipulating fixed-size sequences of bits.
\begin{codeblock}
namespace std {
template<size_t N> class bitset {
public:
// bit reference:
class reference {
friend class bitset;
reference() noexcept;
public:
~reference() noexcept;
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() noexcept;
bool operator==(const bitset<N>& rhs) 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 \shl pos}.
The integral value corresponding to two
or more bits is the sum of their bit values.
\pnum
The functions described in this subclause 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}~(\ref{invalid.argument});
\indexlibrary{\idxcode{invalid_argument}}%
\item
an
\term{out-of-range}
error is associated with exceptions of type
\tcode{out_of_range}~(\ref{out.of.range});
\indexlibrary{\idxcode{out_of_range}}%
\item
an
\term{overflow}
error is associated with exceptions of type
\tcode{overflow_error}~(\ref{overflow.error}).
\indexlibrary{\idxcode{overflow_error}}%
\end{itemize}
\rSec2[bitset.cons]{\tcode{bitset} constructors}
\indexlibrary{\idxcode{bitset}!\idxcode{bitset}}%
\begin{itemdecl}
constexpr bitset() noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{bitset<N>},
initializing all bits to zero.
\end{itemdescr}
\indexlibrary{\idxcode{bitset}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{bitset}}
\begin{itemdecl}
constexpr bitset(unsigned long long val) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{bitset<N>},
initializing 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~(\ref{basic.types}) of \tcode{unsigned long long}.
If \tcode{M < N}, the remaining bit positions are initialized to zero.
\end{itemdescr}
\indexlibrary{\idxcode{bitset}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{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
\requires
\tcode{pos <= str.size()}.
\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos > str.size()}.%
\indexlibrary{\idxcode{out_of_range}}
\pnum
\effects
Determines the effective length
\tcode{rlen} of the initializing string as the smaller of
\tcode{n} and
\tcode{str.size() - pos}.
The function then throws%
\indexlibrary{\idxcode{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}. The function uses \tcode{traits::eq()}
to compare the character values.
Otherwise, the function constructs an object of class
\tcode{bitset<N>},
initializing 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 string has value zero if the
corresponding character in \tcode{str}, beginning at position
\tcode{pos}, is
\tcode{0} \tcode{zero}.
Otherwise, the element has the value 1.
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.
\end{itemdescr}
\indexlibrary{\idxcode{bitset}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{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 Constructs an object of class \tcode{bitset<N>} 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}
\rSec2[bitset.members]{\tcode{bitset} members}
\indexlibrary{\idxcode{operator\&=}!\idxcode{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}
\indexlibrary{\idxcode{operator"|=}!\idxcode{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}
\indexlibrary{\idxcode{operator\^{}=}!\idxcode{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}
\indexlibrary{operator<<=@\tcode{operator\shl=}!\idxcode{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}
\indexlibrary{operator>>=@\tcode{operator\shr=}!\idxcode{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}
\indexlibrary{\idxcode{set}!\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}
\indexlibrary{\idxcode{set}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{set}}
\begin{itemdecl}
bitset<N>& set(size_t pos, bool val = true);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{pos} is valid
\pnum
\throws
\tcode{out_of_range}
if \tcode{pos} does not correspond to a valid bit position.%
\indexlibrary{\idxcode{out_of_range}}
\pnum
\effects
Stores a new value in the bit at position \tcode{pos} in
\tcode{*this}.
If \tcode{val} is nonzero, the stored value is one, otherwise it is zero.
\pnum
\returns
\tcode{*this}.
\end{itemdescr}
\indexlibrary{\idxcode{reset}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{reset}}
\begin{itemdecl}
bitset<N>& reset() noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Resets all bits in
\tcode{*this}.
\pnum
\returns
\tcode{*this}.
\end{itemdescr}
\indexlibrary{\idxcode{reset}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{reset}}
\begin{itemdecl}
bitset<N>& reset(size_t pos);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{pos} is valid
\pnum
\throws
\tcode{out_of_range}
if \tcode{pos} does not correspond to a valid bit position.
\indexlibrary{\idxcode{out_of_range}}%
\pnum
\effects
Resets the bit at position \tcode{pos} in
\tcode{*this}.
\pnum
\returns
\tcode{*this}.
\end{itemdescr}
\indexlibrary{\idxcode{operator\~{}}!\idxcode{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}
\indexlibrary{\idxcode{flip}!\tcode{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}
\indexlibrary{\idxcode{flip}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{flip}}
\begin{itemdecl}
bitset<N>& flip(size_t pos);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{pos} is valid
\pnum
\throws
\tcode{out_of_range}
if \tcode{pos} does not correspond to a valid bit position.%
\indexlibrary{\idxcode{out_of_range}}
\pnum
\effects
Toggles the bit at position \tcode{pos} in
\tcode{*this}.
\pnum
\returns
\tcode{*this}.
\end{itemdescr}
\indexlibrary{\idxcode{to_ulong}!\idxcode{bitset}}%
\begin{itemdecl}
unsigned long to_ulong() const;
\end{itemdecl}
\begin{itemdescr}
\pnum
\throws
\tcode{overflow_error}%
\indexlibrary{\idxcode{overflow_error}}
if the integral value \tcode{x} corresponding to the bits in
\tcode{*this}
cannot be represented as type
\tcode{unsigned long}.
\pnum
\returns
\tcode{x}.
\end{itemdescr}
\indexlibrary{\idxcode{to_ullong}!\idxcode{bitset}}%
\begin{itemdecl}
unsigned long long to_ullong() const;
\end{itemdecl}
\begin{itemdescr}
\pnum
\indexlibrary{\idxcode{overflow_error}}%
\throws
\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}.
\pnum
\returns
\tcode{x}.
\end{itemdescr}
\indexlibrary{\idxcode{to_string}!\idxcode{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}
\indexlibrary{\idxcode{count}!\idxcode{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}
\indexlibrary{\idxcode{size}!\idxcode{bitset}}%
\begin{itemdecl}
constexpr size_t size() noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{N}.
\end{itemdescr}
\indexlibrary{\idxcode{operator==}!\idxcode{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}
\indexlibrary{\idxcode{operator"!=}!\idxcode{bitset}}%
\begin{itemdecl}
bool operator!=(const bitset<N>& rhs) const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{true} if
\tcode{!(*this == rhs)}.
\end{itemdescr}
\indexlibrary{\idxcode{test}!\idxcode{bitset}}%
\begin{itemdecl}
bool test(size_t pos) const;
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{pos} is valid
\pnum
\throws
\tcode{out_of_range}
if \tcode{pos} does not correspond to a valid bit position.%
\indexlibrary{\idxcode{out_of_range}}
\pnum
\returns
\tcode{true}
if the bit at position \tcode{pos}
in
\tcode{*this}
has the value one.
\end{itemdescr}
\indexlibrary{\idxcode{all}!\idxcode{bitset}}%
\begin{itemdecl}
bool all() const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{count() == size()}
\end{itemdescr}
\indexlibrary{\idxcode{any}!\idxcode{bitset}}%
\begin{itemdecl}
bool any() const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{count() != 0}
\end{itemdescr}
\indexlibrary{\idxcode{none}!\idxcode{bitset}}%
\begin{itemdecl}
bool none() const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{count() == 0}
\end{itemdescr}
\indexlibrary{operator<<@\tcode{operator\shl}!\idxcode{bitset}}%
\begin{itemdecl}
bitset<N> operator<<(size_t pos) const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{bitset<N>(*this) \shl= pos}.
\end{itemdescr}
\indexlibrary{operator>>@\tcode{operator\shr}!\idxcode{bitset}}%
\begin{itemdecl}
bitset<N> operator>>(size_t pos) const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{bitset<N>(*this) \shr= pos}.
\end{itemdescr}
\indexlibrary{\idxcode{operator[]}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{operator[]}}
\begin{itemdecl}
constexpr bool operator[](size_t pos);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{pos} shall be 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}
\indexlibrary{\idxcode{operator[]}!\idxcode{bitset}}
\indexlibrary{\idxcode{bitset}!\idxcode{operator[]}}
\begin{itemdecl}
bitset<N>::reference operator[](size_t pos);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{pos} shall be 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
\remark For the purpose of determining the presence of a data
race~(\ref{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}
\indexlibrary{\idxcode{hash_code}}%
\begin{itemdecl}
template <size_t N> struct hash<bitset<N> >;
\end{itemdecl}
\begin{itemdescr}
\pnum\requires the template specialization shall meet the requirements of class template
\tcode{hash}~(\ref{unord.hash}).
\end{itemdescr}
\rSec2[bitset.operators]{\tcode{bitset} operators}
\indexlibrary{\idxcode{operator\&}!\idxcode{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}
\indexlibrary{\idxcode{operator"|}!\idxcode{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}
\indexlibrary{\idxcode{operator\^{}}!\idxcode{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}
\indexlibrary{operator>>@\tcode{operator\shr}!\idxcode{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~(\ref{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
end-of-file occurs on the input sequence;%
\indextext{end-of-file}
\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 no characters are stored in \tcode{str}, calls
\tcode{is.setstate(ios_base::failbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).
\pnum
\returns
\tcode{is}.
\end{itemdescr}
\indexlibrary{operator<<@\tcode{operator\shl}!\idxcode{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 @\shl@ 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
This subclause describes the contents of the header
\tcode{<memory>}~(\ref{memory.syn}) and some
of the contents of the C headers \tcode{<cstdlib>} and
\tcode{cstring>}~(\ref{c.malloc}).
\rSec2[memory.syn]{Header \tcode{<memory>} synopsis}
\pnum
The header \tcode{<memory>} defines several types and function templates that
describe properties of pointers and pointer-like types, manage memory
for containers and other template types, and construct multiple objects in
uninitialized memory
buffers~(\ref{pointer.traits}--\ref{specialized.algorithms}).
The header also defines the templates
\tcode{unique_ptr}, \tcode{shared_ptr}, \tcode{weak_ptr}, and various template
functions that operate on objects of these types~(\ref{smartptr}).
\indexlibrary{\idxhdr{memory}}%
\begin{codeblock}
namespace std {
// \ref{pointer.traits}, pointer traits
template <class Ptr> struct pointer_traits;
template <class T> struct pointer_traits<T*>;
// \ref{util.dynamic.safety}, 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 function
void *align(std::size_t alignment, std::size_t size,
void *&ptr, std::size_t& space);
// \ref{allocator.tag}, allocator argument tag
struct allocator_arg_t { };
constexpr allocator_arg_t allocator_arg = allocator_arg_t();
// \ref{allocator.uses}, \tcode{uses_allocator}
template <class T, class Alloc> struct uses_allocator;
// \ref{allocator.traits}, allocator traits
template <class Alloc> struct allocator_traits;
// \ref{default.allocator}, the default allocator:
template <class T> class allocator;
template <> class allocator<void>;
template <class T, class U>
bool operator==(const allocator<T>&, const allocator<U>&) noexcept;
template <class T, class U>
bool operator!=(const allocator<T>&, const allocator<U>&) noexcept;
// \ref{storage.iterator}, raw storage iterator:
template <class OutputIterator, class T> class raw_storage_iterator;
// \ref{temporary.buffer}, temporary buffers:
template <class T>
pair<T*,ptrdiff_t> get_temporary_buffer(ptrdiff_t n) noexcept;
template <class T>
void return_temporary_buffer(T* p);
// \ref{specialized.algorithms}, specialized algorithms:
template <class T> T* addressof(T& r) noexcept;
template <class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_copy(InputIterator first, InputIterator last,
ForwardIterator result);
template <class InputIterator, class Size, class ForwardIterator>
ForwardIterator uninitialized_copy_n(InputIterator first, Size n,
ForwardIterator result);
template <class ForwardIterator, class T>
void uninitialized_fill(ForwardIterator first, ForwardIterator last,
const T& x);
template <class ForwardIterator, class Size, class T>
ForwardIterator uninitialized_fill_n(ForwardIterator first, Size n, const T& x);
// \ref{unique.ptr} class template 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 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>
bool 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==(nullptr_t, const unique_ptr<T, D>& y) noexcept;
template <class T, class D>
bool operator!=(const unique_ptr<T, D>& x, nullptr_t) noexcept;
template <class T, class D>
bool operator!=(nullptr_t, const unique_ptr<T, D>& y) 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);
// \ref{util.smartptr.weakptr}, class bad_weak_ptr:
class bad_weak_ptr;
// \ref{util.smartptr.shared}, class template shared_ptr:
template<class T> class shared_ptr;
// \ref{util.smartptr.shared.cmp}, shared_ptr comparisons:
template<class T, class U>
bool operator==(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
template<class T, class U>
bool operator!=(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
template<class T, class U>
bool operator<(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
template<class T, class U>
bool operator>(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
template<class T, class U>
bool operator<=(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
template<class T, class U>
bool operator>=(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
template <class T>
bool operator==(const shared_ptr<T>& x, nullptr_t) noexcept;
template <class T>
bool operator==(nullptr_t, const shared_ptr<T>& y) noexcept;
template <class T>
bool operator!=(const shared_ptr<T>& x, nullptr_t) noexcept;
template <class T>
bool operator!=(nullptr_t, const shared_ptr<T>& y) noexcept;
template <class T>
bool operator<(const shared_ptr<T>& x, nullptr_t) noexcept;
template <class T>
bool operator<(nullptr_t, const shared_ptr<T>& y) noexcept;
template <class T>
bool operator<=(const shared_ptr<T>& x, nullptr_t) noexcept;
template <class T>
bool operator<=(nullptr_t, const shared_ptr<T>& y) noexcept;
template <class T>
bool operator>(const shared_ptr<T>& x, nullptr_t) noexcept;
template <class T>
bool operator>(nullptr_t, const shared_ptr<T>& y) noexcept;
template <class T>
bool operator>=(const shared_ptr<T>& x, nullptr_t) noexcept;
template <class T>
bool operator>=(nullptr_t, const shared_ptr<T>& y) noexcept;
// \ref{util.smartptr.shared.spec}, shared_ptr specialized algorithms:
template<class T> void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;
// \ref{util.smartptr.shared.cast}, shared_ptr casts:
template<class T, class U>
shared_ptr<T> static_pointer_cast(shared_ptr<U> const& r) noexcept;
template<class T, class U>
shared_ptr<T> dynamic_pointer_cast(shared_ptr<U> const& r) noexcept;
template<class T, class U>
shared_ptr<T> const_pointer_cast(shared_ptr<U> const& r) noexcept;
// \ref{util.smartptr.getdeleter}, shared_ptr get_deleter:
template<class D, class T> D* get_deleter(shared_ptr<T> const& p) noexcept;
// \ref{util.smartptr.shared.io}, shared_ptr I/O:
template<class E, class T, class Y>
basic_ostream<E, T>& operator<< (basic_ostream<E, T>& os, shared_ptr<Y> const& p);
// \ref{util.smartptr.weak}, class template weak_ptr:
template<class T> class weak_ptr;
// \ref{util.smartptr.weak.spec}, weak_ptr specialized algorithms:
template<class T> void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
// \ref{util.smartptr.ownerless}, class template owner_less:
template<class T> class owner_less;
// \ref{util.smartptr.enab}, class template enable_shared_from_this:
template<class T> class enable_shared_from_this;
// \ref{util.smartptr.shared.atomic}, shared_ptr atomic access:
template<class T>
bool atomic_is_lock_free(const shared_ptr<T>* p);
template<class T>
shared_ptr<T> atomic_load(const shared_ptr<T>* p);
template<class T>
shared_ptr<T> atomic_load_explicit(const shared_ptr<T>* p, memory_order mo);
template<class T>
void atomic_store(shared_ptr<T>* p, shared_ptr<T> r);
template<class T>
void atomic_store_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);
template<class T>
shared_ptr<T> atomic_exchange(shared_ptr<T>* p, shared_ptr<T> r);
template<class T>
shared_ptr<T> atomic_exchange_explicit(shared_ptr<T>* p, shared_ptr<T> r,
memory_order mo);
template<class T>
bool atomic_compare_exchange_weak(
shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);
template<class T>
bool atomic_compare_exchange_strong(
shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);
template<class T>
bool atomic_compare_exchange_weak_explicit(
shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w,
memory_order success, memory_order failure);
template<class T>
bool atomic_compare_exchange_strong_explicit(
shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w,
memory_order success, memory_order failure);
// \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{depr.auto.ptr}, auto_ptr (deprecated)
template <class X> class auto_ptr;
}
\end{codeblock}
\rSec2[pointer.traits]{Pointer traits}
\pnum
The class template \tcode{pointer_traits} supplies a uniform interface to certain
attributes of pointer-like types.
\indexlibrary{\idxcode{pointer_traits}}%
\begin{codeblock}
namespace std {
template <class Ptr> struct pointer_traits {
typedef Ptr pointer;
typedef @\seebelow@ element_type;
typedef @\seebelow@ difference_type;
template <class U> using rebind = @\seebelow@;
static pointer pointer_to(@\seebelow@ r);
};
template <class T> struct pointer_traits<T*> {
typedef T* pointer;
typedef T element_type;
typedef ptrdiff_t difference_type;
template <class U> using rebind = U*;
static pointer pointer_to(@\seebelow@ r) noexcept;
};
}
\end{codeblock}
\rSec3[pointer.traits.types]{Pointer traits member types}
\indexlibrary{\idxcode{pointer_traits}!\idxcode{element_type}}%
\indexlibrary{\idxcode{element_type}!\idxcode{pointer_traits}}%
\begin{itemdecl}
typedef @\seebelow@ element_type;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Ptr::element_type} if such a type exists; 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}
\indexlibrary{\idxcode{pointer_traits}!\idxcode{difference_type}}%
\indexlibrary{\idxcode{difference_type}!\idxcode{pointer_traits}}%
\begin{itemdecl}
typedef @\seebelow@ difference_type;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Ptr::difference_type} if such a type exists; otherwise,
\tcode{std::ptrdiff_t}.
\end{itemdescr}
\indexlibrary{\idxcode{pointer_traits}!\idxcode{rebind}}%
\indexlibrary{\idxcode{rebind}!\idxcode{pointer_traits}}%
\begin{itemdecl}
template <class U> using rebind = @\seebelow@;
\end{itemdecl}
\begin{itemdescr}
\pnum
\templalias \tcode{Ptr::rebind<U>} if such a type exists; 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]{Pointer traits member functions}
\indexlibrary{\idxcode{pointer_traits}!\idxcode{pointer_to}}%
\indexlibrary{\idxcode{pointer_to}!\idxcode{pointer_traits}}%
\begin{itemdecl}
static pointer pointer_traits::pointer_to(@\seebelow@ r);
static pointer pointer_traits<T*>::pointer_to(@\seebelow@ r) noexcept;
\end{itemdecl}
\begin{itemdescr}
\remark if \tcode{element_type} is (possibly cv-qualified) \tcode{void}, the type of
\tcode{r} is unspecified; otherwise, it is \tcode{element_type\&}.
\returns The first member function returns a dereferenceable pointer to \tcode{r}
obtained by calling \tcode{Ptr::pointer_to(r)}; an instantiation of this function is
ill-formed if \tcode{Ptr} does not have a matching \tcode{pointer_to} static member
function. The second member function returns \tcode{std::addressof(r)}.
\end{itemdescr}
\rSec2[util.dynamic.safety]{Pointer safety}
\pnum
A complete object is \techterm{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.
\indexlibrary{\idxcode{declare_reachable}}%
\begin{itemdecl}
void declare_reachable(void *p);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires \tcode{p} shall be a safely-derived
pointer~(\ref{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~(\ref{basic.stc.dynamic.safety}).
\pnum
\throws May throw \tcode{std::bad_alloc} if the system cannot allocate
additional memory that may be required to track objects declared reachable.
\end{itemdescr}
\indexlibrary{\idxcode{undeclare_reachable}}%
\begin{itemdecl}
template <class T> T *undeclare_reachable(T *p);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires If \tcode{p} is not null, the complete object referenced by \tcode{p}
shall have been previously declared reachable, and shall be
live~(\ref{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 shall compare equal to \tcode{p}.
\pnum
\throws Nothing.
\pnum \enternote It is expected that calls to \tcode{declare_reachable(p)} will 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. Long running programs
should arrange that calls are matched. \exitnote \end{itemdescr}
\indexlibrary{\idxcode{declare_no_pointers}}%
\begin{itemdecl}
void declare_no_pointers(char *p, size_t n);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires 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 must be entirely within a single allocated object. The object must be
live until the corresponding \tcode{undeclare_no_pointers()} call. \enternote In
a garbage-collecting implementation, the fact that a region in an object is
registered with \tcode{declare_no_pointers()} should not prevent the object from
being collected. \exitnote
\pnum
\effects The \tcode{n} bytes starting at \tcode{p} no longer contain traceable
pointer locations, independent of their type. Hence pointers located there may
not be dereferenced if the object they point to was created by global
\tcode{operator new} and not previously declared reachable. \enternote This may
be used to inform a garbage collector or leak detector that this region of
memory need not be traced. \exitnote
\pnum
\throws Nothing.
\pnum
\enternote Under some conditions implementations may need to allocate memory.
However, the request can be ignored if memory allocation fails. \exitnote
\end{itemdescr}
\indexlibrary{\idxcode{undeclare_no_pointers}}%
\begin{itemdecl}
void undeclare_no_pointers(char *p, size_t n);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires The same range must previously have been passed to
\tcode{declare_no_pointers()}.
\pnum
\effects Unregisters a range registered with \tcode{declare_no_pointers()} for
destruction. It must be called before the lifetime of the object ends.
\pnum
\throws Nothing.
\end{itemdescr}
\indexlibrary{\idxcode{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~(\ref{basic.stc.dynamic.safety}). It is implementation defined%
\indeximpldef{whether \tcode{get_pointer_safety} returns
\tcode{pointer_safety::\brk{}relaxed} or
\tcode{pointer_safety::preferred} if the implementation has relaxed pointer safety}
whether
\tcode{get_pointer_safety} returns \tcode{pointer_safety::relaxed} or
\tcode{pointer_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]{Align}
\indexlibrary{\idxcode{align}}%
\begin{itemdecl}
void *align(std::size_t alignment, std::size_t size,
void *&ptr, std::size_t& space);
\end{itemdecl}
\begin{itemdescr}
\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 point to 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
\requires
\begin{itemize}
\item \tcode{alignment} shall be a fundamental alignment value or an
extended alignment value supported by the implementation in this context
\item \tcode{ptr} shall point to contiguous storage of at least
\tcode{space} bytes
\end{itemize}
\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
\enternote 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{itemdescr}
\rSec2[allocator.tag]{Allocator argument tag}
\indexlibrary{\idxcode{allocator_arg_t}}
\indexlibrary{\idxcode{allocator_arg}}
\begin{itemdecl}
namespace std {
struct allocator_arg_t { };
constexpr allocator_arg_t allocator_arg = allocator_arg_t();
}
\end{itemdecl}
\pnum
The \tcode{allocator_arg_t} struct is an empty structure 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 satisfies the
\tcode{Allocator} requirements~(\ref{allocator.requirements}).
\rSec2[allocator.uses]{\tcode{uses_allocator}}
\rSec3[allocator.uses.trait]{\tcode{uses_allocator} trait}
\indexlibrary{\idxcode{uses_allocator}}%
\begin{itemdecl}
template <class T, class Alloc> struct uses_allocator;
\end{itemdecl}
\begin{itemdescr}
\pnum
\remark automatically detects whether \tcode{T} has a nested \tcode{allocator_type} that
is convertible from \tcode{Alloc}. Meets the BinaryTypeTrait
requirements~(\ref{meta.rqmts}). The implementation shall provide a definition that is
derived from \tcode{true_type} if a type \tcode{T::allocator_type} exists and
\tcode{is_convertible<Alloc, T::allocator_type>::value != false}, otherwise it shall be
derived from \tcode{false_type}. A program may specialize this template to derive from
\tcode{true_type} for a user-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
\defn{Uses-allocator construction} with allocator \tcode{Alloc} refers to the
construction of an object \tcode{obj} of type \tcode{T}, using constructor arguments
\tcode{v1, v2, ..., vN} of types \tcode{V1, V2, ..., VN}, respectively, and an allocator
\tcode{alloc} of type \tcode{Alloc}, according to the following rules:
\begin{itemize}
\item if \tcode{uses_allocator<T, Alloc>::value} is \tcode{false} and
\tcode{is_constructible<T, V1, V2, ..., VN>::value} is \tcode{true}, then \tcode{obj} is
initialized as \tcode{obj(v1, v2, ..., vN)};
\item otherwise, if \tcode{uses_allocator<T, Alloc>::value} is \tcode{true} and
\tcode{is_constructible<T, allocator_arg_t, Alloc,} \tcode{V1, V2, ..., VN>::value} is
\tcode{true}, then \tcode{obj} is initialized as \tcode{obj(allocator_arg, alloc, v1,
v2, ..., vN)};
\item otherwise, if \tcode{uses_allocator<T, Alloc>::value} is \tcode{true} and
\tcode{is_constructible<T, V1, V2, ..., VN, Alloc>::value} is \tcode{true}, then
\tcode{obj} is initialized as \tcode{obj(v1, v2, ..., vN, alloc)};
\item otherwise, the request for uses-allocator construction is ill-formed. \enternote
An error will result if \tcode{uses_allocator<T, Alloc>::value} is \tcode{true} but the
specific constructor does not take an allocator. This definition prevents a silent
failure to pass the allocator to an element. \exitnote
\end{itemize}
\rSec2[allocator.traits]{Allocator traits}
\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. \enternote Thus, it is always possible to create
a derived class from an allocator. \exitnote
\indexlibrary{\idxcode{allocator_traits}}%
\begin{codeblock}
namespace std {
template <class Alloc> struct allocator_traits {
typedef Alloc allocator_type;
typedef typename Alloc::value_type value_type;
typedef @\seebelow@ pointer;
typedef @\seebelow@ const_pointer;
typedef @\seebelow@ void_pointer;
typedef @\seebelow@ const_void_pointer;
typedef @\seebelow@ difference_type;
typedef @\seebelow@ size_type;
typedef @\seebelow@ propagate_on_container_copy_assignment;
typedef @\seebelow@ propagate_on_container_move_assignment;
typedef @\seebelow@ propagate_on_container_swap;
template <class T> using rebind_alloc = @\seebelow@;
template <class T> using rebind_traits = allocator_traits<rebind_alloc<T> >;
static pointer allocate(Alloc& a, size_type n);
static pointer allocate(Alloc& a, size_type n, const_void_pointer hint);
static void deallocate(Alloc& a, pointer p, size_type n);
template <class T, class... Args>
static void construct(Alloc& a, T* p, Args&&... args);
template <class T>
static void destroy(Alloc& a, T* p);
static size_type max_size(const Alloc& a);
static Alloc select_on_container_copy_construction(const Alloc& rhs);
};
}
\end{codeblock}
\rSec3[allocator.traits.types]{Allocator traits member types}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{pointer}}%
\indexlibrary{\idxcode{pointer}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ pointer;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::pointer} if such a type exists; otherwise, \tcode{value_type*}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{const_pointer}}%
\indexlibrary{\idxcode{const_pointer}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ const_pointer;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::const_pointer} if such a type exists; otherwise,
\tcode{pointer_traits<pointer>::rebind<\brk{}const value_type>}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{void_pointer}}%
\indexlibrary{\idxcode{void_pointer}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ void_pointer;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::void_pointer} if such a type exists; otherwise,
\tcode{pointer_traits<pointer>::rebind<\brk{}void>}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{const_void_pointer}}%
\indexlibrary{\idxcode{const_void_pointer}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ const_void_pointer;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::const_void_pointer} if such a type exists; otherwise,
\tcode{pointer_traits<pointer>::\brk{}rebind<const void>}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{difference_type}}%
\indexlibrary{\idxcode{difference_type}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ difference_type;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::difference_type} if such a type exists; otherwise,
\tcode{pointer_traits<pointer>::dif\-ference_type}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{size_type}}%
\indexlibrary{\idxcode{size_type}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ size_type;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::size_type} if such a type exists; otherwise,
\tcode{make_unsigned<difference_type>::type}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{propagate_on_container_copy_assignment}}%
\indexlibrary{\idxcode{propagate_on_container_copy_assignment}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ propagate_on_container_copy_assignment;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::propagate_on_container_copy_assignment} if such a type
exists, otherwise \tcode{false_type}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{propagate_on_container_move_assignment}}%
\indexlibrary{\idxcode{propagate_on_container_move_assignment}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ propagate_on_container_move_assignment;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::propagate_on_container_move_assignment} if such a type
exists, otherwise \tcode{false_type}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{propagate_on_container_swap}}%
\indexlibrary{\idxcode{propagate_on_container_swap}!\idxcode{allocator_traits}}%
\begin{itemdecl}
typedef @\seebelow@ propagate_on_container_swap;
\end{itemdecl}
\begin{itemdescr}
\pnum
\ctype \tcode{Alloc::propagate_on_container_swap} if such a type exists, otherwise \tcode{false_type}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{rebind_alloc}}%
\indexlibrary{\idxcode{rebind_alloc}!\idxcode{allocator_traits}}%
\begin{itemdecl}
template <class T> using rebind_alloc = @\seebelow@;
\end{itemdecl}
\begin{itemdescr}
\pnum
\templalias \tcode{Alloc::rebind<T>::other} if such a type exists; 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]{Allocator traits static member functions}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{allocate}}%
\indexlibrary{\idxcode{allocate}!\idxcode{allocator_traits}}%
\begin{itemdecl}
static pointer allocate(Alloc& a, size_type n);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{a.allocate(n)}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{allocate}}%
\indexlibrary{\idxcode{allocate}!\idxcode{allocator_traits}}%
\begin{itemdecl}
static 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}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{deallocate}}%
\indexlibrary{\idxcode{deallocate}!\idxcode{allocator_traits}}%
\begin{itemdecl}
static 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}
\indexlibrary{\idxcode{allocator_traits}!constructor}%
\begin{itemdecl}
template <class T, class... Args>
static 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{::new (static_cast<void*>(p)) T(std::forward<Args>(args)...)}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!destructor}%
\begin{itemdecl}
template <class T>
static 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{p->\~{}T()}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{max_size}}%
\indexlibrary{\idxcode{max_size}!\idxcode{allocator_traits}}%
\begin{itemdecl}
static size_type max_size(Alloc& a);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns \tcode{a.max_size()} if that expression is well-formed; otherwise,
\tcode{numeric_limits<size_type>::\brk{}max()}.
\end{itemdescr}
\indexlibrary{\idxcode{allocator_traits}!\idxcode{select_on_container_copy_construction}}%
\indexlibrary{\idxcode{select_on_container_copy_construction}!\idxcode{allocator_traits}}%
\begin{itemdecl}
static 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}
\indexlibrary{\idxcode{allocator}}%
\begin{codeblock}
namespace std {
template <class T> class allocator;
// specialize for \tcode{void}:
template <> class allocator<void> {
public:
typedef void* pointer;
typedef const void* const_pointer;
// reference-to-\tcode{void} members are impossible.
typedef void value_type;
template <class U> struct rebind { typedef allocator<U> other; };
};
template <class T> class allocator {
public:
typedef size_t size_type;
typedef ptrdiff_t difference_type;
typedef T* pointer;
typedef const T* const_pointer;
typedef T& reference;
typedef const T& const_reference;
typedef T value_type;
template <class U> struct rebind { typedef allocator<U> other; };
allocator() noexcept;
allocator(const allocator&) noexcept;
template <class U> allocator(const allocator<U>&) noexcept;
~allocator();
pointer address(reference x) const noexcept;
const_pointer address(const_reference x) const noexcept;
pointer allocate(
size_type, allocator<void>::const_pointer hint = 0);
void deallocate(pointer p, size_type n);
size_type max_size() const noexcept;
template<class U, class... Args>
void construct(U* p, Args&&... args);
template <class U>
void destroy(U* p);
};
}
\end{codeblock}
\rSec3[allocator.members]{\tcode{allocator} members}
\pnum
Except for the destructor, member functions of the default allocator shall not introduce
data races~(\ref{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.
\indexlibrary{\idxcode{address}!\idxcode{allocator}}
\indexlibrary{\idxcode{allocator}!\idxcode{address}}
\begin{itemdecl}
pointer address(reference x) const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
The actual address of the object referenced by \tcode{x}, even in the presence of an
overloaded operator\&.
\end{itemdescr}
\indexlibrary{\idxcode{address}!\idxcode{allocator}}
\indexlibrary{\idxcode{allocator}!\idxcode{address}}
\begin{itemdecl}
const_pointer address(const_reference x) const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
The actual address of the object referenced by \tcode{x}, even in the presence of an
overloaded operator\&.
\end{itemdescr}
\indexlibrary{\idxcode{allocate}!\idxcode{allocator}}
\indexlibrary{\idxcode{allocator}!\idxcode{allocate}}
\begin{itemdecl}
pointer allocate(size_type n, allocator<void>::const_pointer hint = 0);
\end{itemdecl}
\begin{itemdescr}
\pnum
\enternote In a container member function, the address of an adjacent
element is often a good choice to pass for the \tcode{hint} argument. \exitnote
\pnum
\returns
A pointer to the initial element of an array of storage of size \tcode{n}
\tcode{* sizeof(T)}, aligned appropriately for objects of type \tcode{T}.
It is \impldef{support for over-aligned types} whether over-aligned types are
supported~(\ref{basic.align}).
\pnum
\note
the storage is obtained by calling \tcode{::operator
new(std::size_t)}~(\ref{new.delete}), but it is unspecified when or how often this
function is called. The use of \tcode{hint} is unspecified, but intended as an aid to
locality if an implementation so desires.
\pnum
\throws
\tcode{bad_alloc} if the storage cannot be obtained.
\end{itemdescr}
\indexlibrary{\idxcode{deallocate}!\idxcode{allocator}}
\indexlibrary{\idxcode{allocator}!\idxcode{deallocate}}
\begin{itemdecl}
void deallocate(pointer p, size_type n);
\end{itemdecl}
\begin{itemdescr}
\pnum
\requires
\tcode{p} shall be a pointer value obtained from \tcode{allocate()}.
\tcode{n} shall equal 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
\notes
Uses
\tcode{::operator delete(void*)}~(\ref{new.delete}), but it is unspecified when this function is called.
\end{itemdescr}
\indexlibrary{\idxcode{max_size}!\idxcode{allocator}}
\indexlibrary{\idxcode{allocator}!\idxcode{max_size}}
\begin{itemdecl}
size_type max_size() const noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
The largest value \textit{N} for which the call \tcode{allocate(N,0)}
might succeed.
\end{itemdescr}
\indexlibrary{\idxcode{allocator}!constructor}%
\begin{itemdecl}
template <class U, class... Args>
void construct(U* p, Args&&... args);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
\tcode{::new((void *)p) U(std::forward<Args>(args)...)}
\end{itemdescr}
\indexlibrary{\idxcode{allocator}!destructor}%
\begin{itemdecl}
template <class U>
void destroy(U* p);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
\tcode{p->\~{}U()}
\end{itemdescr}
\rSec3[allocator.globals]{\tcode{allocator} globals}
\indexlibrary{\idxcode{operator==}!\idxcode{allocator}}%
\indexlibrary{\idxcode{allocator}!\idxcode{operator==}}%
\begin{itemdecl}
template <class T1, class T2>
bool operator==(const allocator<T1>&, const allocator<T2>&) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{true}.
\end{itemdescr}
\indexlibrary{\idxcode{operator"!=}!\idxcode{allocator}}%
\indexlibrary{\idxcode{allocator}!\idxcode{operator"!=}}%
\begin{itemdecl}
template <class T1, class T2>
bool operator!=(const allocator<T1>&, const allocator<T2>&) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{false}.
\end{itemdescr}
\rSec2[storage.iterator]{Raw storage iterator}
\pnum
\tcode{raw_storage_iterator} is provided to enable algorithms to store their
results into uninitialized memory. The formal template parameter
\tcode{OutputIterator} is required to have its \tcode{operator*} return an
object for which \tcode{operator\&} is defined and returns a pointer to
\tcode{T}, and is also required to satisfy the requirements of an output
iterator~(\ref{output.iterators}).
\begin{codeblock}
namespace std {
template <class OutputIterator, class T>
class raw_storage_iterator
: public iterator<output_iterator_tag,void,void,void,void> {
public:
explicit raw_storage_iterator(OutputIterator x);
raw_storage_iterator& operator*();
raw_storage_iterator& operator=(const T& element);
raw_storage_iterator& operator++();
raw_storage_iterator operator++(int);
};
}
\end{codeblock}
\indexlibrary{\idxcode{raw_storage_iterator}!constructor}%
\begin{itemdecl}
explicit raw_storage_iterator(OutputIterator x);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Initializes the iterator to point to the same value to which \tcode{x} points.
\end{itemdescr}
\indexlibrary{\idxcode{operator*}!\idxcode{raw_storage_iterator}}
\indexlibrary{\idxcode{raw_storage_iterator}!\idxcode{operator*}}
\begin{itemdecl}
raw_storage_iterator& operator*();
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{*this}
\end{itemdescr}
\indexlibrary{\idxcode{operator=}!\idxcode{raw_storage_iterator}}
\indexlibrary{\idxcode{raw_storage_iterator}!\idxcode{operator=}}
\begin{itemdecl}
raw_storage_iterator& operator=(const T& element);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Constructs a value from \tcode{element} at the location to which the iterator points.
\pnum
\returns
A reference to the iterator.
\end{itemdescr}
\indexlibrary{\idxcode{operator++}!\idxcode{raw_storage_iterator}}
\indexlibrary{\idxcode{raw_storage_iterator}!\idxcode{operator++}}
\begin{itemdecl}
raw_storage_iterator& operator++();
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Pre-increment: advances the iterator and returns a reference to the updated iterator.
\end{itemdescr}
\indexlibrary{\idxcode{operator++}!\idxcode{raw_storage_iterator}}
\indexlibrary{\idxcode{raw_storage_iterator}!\idxcode{operator++}}
\begin{itemdecl}
raw_storage_iterator operator++(int);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Post-increment: advances the iterator and returns the old value of the iterator.
\end{itemdescr}
\rSec2[temporary.buffer]{Temporary buffers}
\indexlibrary{\idxcode{get_temporary_buffer}}%
\begin{itemdecl}
template <class T>
pair<T*, ptrdiff_t> get_temporary_buffer(ptrdiff_t n) noexcept;
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Obtains a pointer to storage sufficient to store up to \tcode{n}
adjacent \tcode{T} objects.
It is \impldef{support for over-aligned types} whether over-aligned types are
supported~(\ref{basic.align}).
\pnum
\returns
A \tcode{pair} containing the buffer's address and capacity (in the units of
\tcode{sizeof(T)}), or a pair of 0 values if no storage can be obtained or
if \tcode{n <= 0}.
\end{itemdescr}
\indexlibrary{\idxcode{return_temporary_buffer}}%
\begin{itemdecl}
template <class T> void return_temporary_buffer(T* p);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
Deallocates the buffer to which \tcode{p}
points.
\pnum
\requires
The buffer shall have been previously allocated by \tcode{get_temporary_buffer}.
\end{itemdescr}
\rSec2[specialized.algorithms]{Specialized algorithms}
\pnum
All the iterators that are used as formal template parameters in the following
algorithms are required to have their \tcode{operator*} return an object
for which \tcode{operator\&} is defined and returns a pointer to \tcode{T}.
In the algorithm \tcode{uninitialized_copy}, the formal template parameter
\tcode{InputIterator} is required to satisfy the requirements of an input
iterator~(\ref{input.iterators}). In all of the following algorithms,
the formal template parameter \tcode{ForwardIterator} is required to satisfy the
requirements of a forward iterator~(\ref{forward.iterators}),
and is required to have the property that no exceptions are thrown
from increment, assignment, comparison, or dereference of valid iterators.
In the following algorithms, if an exception is thrown there are no effects.
\rSec3[specialized.addressof]{\tcode{addressof}}
\indexlibrary{\idxcode{addressof}}%
\begin{itemdecl}
template <class T> 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\&}.
\end{itemdescr}
\rSec3[uninitialized.copy]{\tcode{uninitialized_copy}}
\indexlibrary{\idxcode{uninitialized_copy}}%
\begin{itemdecl}
template <class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_copy(InputIterator first, InputIterator last,
ForwardIterator result);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
for (; first != last; ++result, ++first)
::new (static_cast<void*>(&*result))
typename iterator_traits<ForwardIterator>::value_type(*first);
\end{codeblock}
\pnum
\returns
\tcode{result}
\end{itemdescr}
\indexlibrary{\idxcode{uninitialized_copy_n}}%
\begin{itemdecl}
template <class InputIterator, class Size, class ForwardIterator>
ForwardIterator uninitialized_copy_n(InputIterator first, Size n,
ForwardIterator result);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
for ( ; n > 0; ++result, ++first, --n) {
::new (static_cast<void*>(&*result))
typename iterator_traits<ForwardIterator>::value_type(*first);
}
\end{codeblock}
\pnum
\returns \tcode{result}
\end{itemdescr}
\rSec3[uninitialized.fill]{\tcode{uninitialized_fill}}
\indexlibrary{\idxcode{uninitialized_fill}}%
\begin{itemdecl}
template <class ForwardIterator, class T>
void uninitialized_fill(ForwardIterator first, ForwardIterator last,
const T& x);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
for (; first != last; ++first)
::new (static_cast<void*>(&*first))
typename iterator_traits<ForwardIterator>::value_type(x);
\end{codeblock}
\end{itemdescr}
\rSec3[uninitialized.fill.n]{\tcode{uninitialized_fill_n}}
\indexlibrary{\idxcode{uninitialized_fill_n}}%
\begin{itemdecl}
template <class ForwardIterator, class Size, class T>
ForwardIterator uninitialized_fill_n(ForwardIterator first, Size n, const T& x);
\end{itemdecl}
\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
for (; n--; ++first)
::new (static_cast<void*>(&*first))
typename iterator_traits<ForwardIterator>::value_type(x);
return first;
\end{codeblock}
\end{itemdescr}
\rSec2[c.malloc]{C library}
\pnum
Table~\ref{tab:util.hdr.cstdlib} describes the header
\tcode{<cstdlib>}.
\begin{libsyntab3}{cstdlib}{tab:util.hdr.cstdlib}
\functions & \tcode{calloc} & \tcode{malloc} \\
& \tcode{free} & \tcode{realloc} \\
\end{libsyntab3}
\pnum
The contents are the same as the Standard C library header
\tcode{<stdlib.h>,}
with the following changes:
\pnum
The functions \tcode{calloc()}\indexlibrary{\idxcode{calloc}},
\tcode{malloc()}\indexlibrary{\idxcode{malloc}}, and
\tcode{realloc()}\indexlibrary{\idxcode{realloc}} do not attempt to allocate
storage by calling \tcode{::operator new()}~(\ref{support.dynamic}).
\indexlibrary{\idxcode{new}!\idxcode{operator}}%
\pnum
The function \tcode{free()}\indexlibrary{\idxcode{free}} does not attempt to
deallocate storage by calling
\tcode{::operator delete()}\indexlibrary{\idxcode{delete}!\tcode{operator}}.
\xref
ISO C Clause 7.11.2.
\pnum
Storage allocated directly with \tcode{malloc()}, \tcode{calloc()}, or
\tcode{realloc()} is implicitly declared reachable