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 pair objects as if they were tuple objects (see [tuple.helper] and [tuple.elem]).
// defined in header <utility> namespace std { template <class T1, class T2> struct pair { typedef T1 first_type; typedef T2 second_type; T1 first; T2 second; pair(const pair&) = default; pair(pair&&) = default; constexpr pair(); constexpr pair(const T1& x, const T2& y); template<class U, class V> constexpr pair(U&& x, V&& y); template<class U, class V> constexpr pair(const pair<U, V>& p); template<class U, class V> constexpr pair(pair<U, V>&& p); template <class... Args1, class... Args2> pair(piecewise_construct_t, tuple<Args1...> first_args, tuple<Args2...> second_args); pair& operator=(const pair& p); template<class U, class V> pair& operator=(const pair<U, V>& p); pair& operator=(pair&& p) noexcept(see below); template<class U, class V> pair& operator=(pair<U, V>&& p); void swap(pair& p) noexcept(see below); }; }
Constructors and member functions of pair shall not throw exceptions unless one of the element-wise operations specified to be called for that operation throws an exception.
The defaulted move and copy constructor, respectively, of pair shall be a constexpr function if and only if all required element-wise initializations for copy and move, respectively, would satisfy the requirements for a constexpr function.
Requires: is_default_constructible<first_type>::value is true
and is_default_construct-
ible<second_type>::value is true.
Effects: Value-initializes first and second.
constexpr pair(const T1& x, const T2& y);
Requires: is_copy_constructible<first_type>::value is true and is_copy_constructible<second_type>::value is true.
Effects: The constructor initializes first with x and second with y.
template<class U, class V> constexpr pair(U&& x, V&& y);
Requires: is_constructible<first_type, U&&>::value is true and is_constructible<second_type, V&&>::value is true.
Effects: The constructor initializes first with std::forward<U>(x) and second with std::forward<V>(y).
Remarks: If U is not implicitly convertible to first_type or V is not implicitly convertible to second_type this constructor shall not participate in overload resolution.
template<class U, class V> constexpr pair(const pair<U, V>& p);
Requires: is_constructible<first_type, const U&>::value is true and is_constructible<second_type, const V&>::value is true.
Effects: Initializes members from the corresponding members of the argument.
Remark: This constructor shall not participate in overload resolution unless const U& is implicitly convertible to first_type and const V& is implicitly convertible to second_type.
template<class U, class V> constexpr pair(pair<U, V>&& p);
Requires: is_constructible<first_type, U&&>::value is true and is_constructible<second_type, V&&>::value is true.
Effects: The constructor initializes first with std::forward<U>(p.first) and second with std::forward<V>(p.second).
Remark: This constructor shall not participate in overload resolution unless U is implicitly convertible to first_type and V is implicitly convertible to second_type.
template<class... Args1, class... Args2>
pair(piecewise_construct_t,
tuple<Args1...> first_args, tuple<Args2...> second_args);
Requires: is_constructible<first_type, Args1&&...>::value is true and is_constructible<second_type, Args2&&...>::value is true.
Effects: The constructor initializes first with arguments of types Args1... obtained by forwarding the elements of first_args and initializes second with arguments of types Args2... obtained by forwarding the elements of second_args. (Here, forwarding an element x of type U within a tuple object means calling std::forward<U>(x).) This form of construction, whereby constructor arguments for first and second are each provided in a separate tuple object, is called piecewise construction.
pair& operator=(const pair& p);
Requires: is_copy_assignable<first_type>::value is true and is_copy_assignable<second_type>::value is true.
Effects: Assigns p.first to first and p.second to second.
Returns: *this.
template<class U, class V> pair& operator=(const pair<U, V>& p);
Requires: is_assignable<first_type&, const U&>::value is true and is_assignable<second_type&, const V&>::value is true.
Effects: Assigns p.first to first and p.second to second.
Returns: *this.
pair& operator=(pair&& p) noexcept(see below);
Remarks: The expression inside noexcept is equivalent to:
is_nothrow_move_assignable<T1>::value && is_nothrow_move_assignable<T2>::value
Requires: is_move_assignable<first_type>::value is true and is_move_assignable<second_type>::value is true.
Effects:
Assigns to first with std::forward<first_type>(p.first)
and to second with
std::forward<second_type>(p.second).
Returns: *this.
template<class U, class V> pair& operator=(pair<U, V>&& p);
Requires: is_assignable<first_type&, U&&>::value is true and is_assignable<second_type&, V&&>::value is true.
Effects:
Assigns to first with std::forward<U>(p.first)
and to second with
std::forward<V>(p.second).
Returns: *this.
void swap(pair& p) noexcept(see below);
Remarks: The expression inside noexcept is equivalent to:
noexcept(swap(first, p.first)) && noexcept(swap(second, p.second))
Requires: first shall be swappable with ([swappable.requirements]) p.first and second shall be swappable with p.second.
Effects: Swaps first with p.first and second with p.second.
template <class T1, class T2>
constexpr bool operator==(const pair<T1, T2>& x, const pair<T1, T2>& y);
Returns: x.first == y.first && x.second == y.second.
template <class T1, class T2>
constexpr bool operator<(const pair<T1, T2>& x, const pair<T1, T2>& y);
Returns: x.first < y.first || (!(y.first < x.first) && x.second < y.second).
template <class T1, class T2>
constexpr bool operator!=(const pair<T1, T2>& x, const pair<T1, T2>& y);
Returns: !(x == y)
template <class T1, class T2>
constexpr bool operator>(const pair<T1, T2>& x, const pair<T1, T2>& y);
Returns: y < x
template <class T1, class T2>
constexpr bool operator>=(const pair<T1, T2>& x, const pair<T1, T2>& y);
Returns: !(x < y)
template <class T1, class T2>
constexpr bool operator<=(const pair<T1, T2>& x, const pair<T1, T2>& y);
Returns: !(y < x)
template<class T1, class T2> void swap(pair<T1, T2>& x, pair<T1, T2>& y)
noexcept(noexcept(x.swap(y)));
Effects: x.swap(y)
template <class T1, class T2>
constexpr pair<V1, V2> make_pair(T1&& x, T2&& y);
Returns: pair<V1, V2>(std::forward<T1>(x), std::forward<T2>(y));
where V1 and V2 are determined as follows: Let Ui be decay_t<Ti> for each Ti. Then each Vi is X& if Ui equals reference_wrapper<X>, otherwise Vi is Ui.
[ Example: In place of:
return pair<int, double>(5, 3.1415926); // explicit types
a C++ program may contain:
return make_pair(5, 3.1415926); // types are deduced
— end example ]
template <class T1, class T2>
struct tuple_size<pair<T1, T2>>
: integral_constant<size_t, 2> { };
tuple_element<0, pair<T1, T2> >::type
Value: the type T1.
tuple_element<1, pair<T1, T2> >::type
Value: the type T2.
template<size_t I, class T1, class T2>
constexpr tuple_element_t<I, pair<T1, T2>>&
get(pair<T1, T2>& p) noexcept;
template<size_t I, class T1, class T2>
constexpr const tuple_element_t<I, pair<T1, T2>>&
get(const pair<T1, T2>& p) noexcept;
Returns: If I == 0 returns p.first; if I == 1 returns p.second; otherwise the program is ill-formed.
template<size_t I, class T1, class T2>
constexpr tuple_element_t<I, pair<T1, T2>>&&
get(pair<T1, T2>&& p) noexcept;
Returns: If I == 0 returns std::forward<T1&&>(p.first); if I == 1 returns std::forward<T2&&>(p.second); otherwise the program is ill-formed.
template <class T, class U>
constexpr T& get(pair<T, U>& p) noexcept;
template <class T, class U>
constexpr const T& get(const pair<T, U>& p) noexcept;
Requires: T and U are distinct types. Otherwise, the program is ill-formed.
Returns: get<0>(p);
template <class T, class U>
constexpr T&& get(pair<T, U>&& p) noexcept;
Requires: T and U are distinct types. Otherwise, the program is ill-formed.
Returns: get<0>(std::move(p));
template <class T, class U>
constexpr T& get(pair<U, T>& p) noexcept;
template <class T, class U>
constexpr const T& get(const pair<U, T>& p) noexcept;
Requires: T and U are distinct types. Otherwise, the program is ill-formed.
Returns: get<1>(p);
template <class T, class U>
constexpr T&& get(pair<U, T>&& p) noexcept;
Requires: T and U are distinct types. Otherwise, the program is ill-formed.
Returns: get<1>(std::move(p));
struct piecewise_construct_t { };
constexpr piecewise_construct_t piecewise_construct{};
The struct piecewise_construct_t is an empty structure type used as a unique type to disambiguate constructor and function overloading. Specifically, pair has a constructor with piecewise_construct_t as the first argument, immediately followed by two tuple ([tuple]) arguments used for piecewise construction of the elements of the pair object.