22 General utilities library [utilities]

22.3 Pairs [pairs]

22.3.2 Class template pair [pairs.pair]

namespace std { template<class T1, class T2> struct pair { using first_type = T1; using second_type = T2; T1 first; T2 second; pair(const pair&) = default; pair(pair&&) = default; constexpr explicit(see below) pair(); constexpr explicit(see below) pair(const T1& x, const T2& y); template<class U1 = T1, class U2 = T2> constexpr explicit(see below) pair(U1&& x, U2&& y); template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>& p); template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>& p); template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>&& p); template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>&& p); template<pair-like P> constexpr explicit(see below) pair(P&& p); template<class... Args1, class... Args2> constexpr pair(piecewise_construct_t, tuple<Args1...> first_args, tuple<Args2...> second_args); constexpr pair& operator=(const pair& p); constexpr const pair& operator=(const pair& p) const; template<class U1, class U2> constexpr pair& operator=(const pair<U1, U2>& p); template<class U1, class U2> constexpr const pair& operator=(const pair<U1, U2>& p) const; constexpr pair& operator=(pair&& p) noexcept(see below); constexpr const pair& operator=(pair&& p) const; template<class U1, class U2> constexpr pair& operator=(pair<U1, U2>&& p); template<class U1, class U2> constexpr const pair& operator=(pair<U1, U2>&& p) const; template<pair-like P> constexpr pair& operator=(P&& p); template<pair-like P> constexpr const pair& operator=(P&& p) const; constexpr void swap(pair& p) noexcept(see below); constexpr void swap(const pair& p) const noexcept(see below); }; template<class T1, class T2> pair(T1, T2) -> pair<T1, T2>; }

Constructors and member functions of pair do 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 is a constexpr function if and only if all required element-wise initializations for move and copy, respectively, would be constexpr-suitable ([dcl.constexpr]).

If (is_trivially_destructible_v<T1> && is_trivially_destructible_v<T2>) is true, then the destructor of pair is trivial.

pair<T, U> is a structural type ([temp.param]) if T and U are both structural types.

Two values p1 and p2 of type pair<T, U> are template-argument-equivalent ([temp.type]) if and only if p1.first and p2.first are template-argument-equivalent and p1.second and p2.second are template-argument-equivalent.

🔗

constexpr explicit(see below) pair();

Constraints:

(5.1)
is_default_constructible_v<T1> is true and
(5.2)
is_default_constructible_v<T2> is true.

Effects: Value-initializes first and second.

Remarks: The expression inside explicit evaluates to true if and only if either T1 or T2 is not implicitly default-constructible.

[Note 1:

This behavior can be implemented with a trait that checks whether a const T1& or a const T2& can be initialized with {}.

— end note]

🔗

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

Constraints:

(8.1)
is_copy_constructible_v<T1> is true and
(8.2)
is_copy_constructible_v<T2> is true.

Effects: Initializes first with x and second with y.

Remarks: The expression inside explicit is equivalent to: !is_convertible_v<const T1&, T1> || !is_convertible_v<const T2&, T2>

🔗

template<class U1 = T1, class U2 = T2> constexpr explicit(see below) pair(U1&& x, U2&& y);

Constraints:

(11.1)
is_constructible_v<T1, U1> is true and
(11.2)
is_constructible_v<T2, U2> is true.

Effects: Initializes first with std::forward<U1>(x) and second with std::forward<U2>(y).

Remarks: The expression inside explicit is equivalent to: !is_convertible_v<U1, T1> || !is_convertible_v<U2, T2>

This constructor is defined as deleted if reference_constructs_from_temporary_v<first_type, U1&&> is true or reference_constructs_from_temporary_v<second_type, U2&&> is true.

🔗

template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>& p);
template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>& p);
template<class U1, class U2> constexpr explicit(see below) pair(pair<U1, U2>&& p);
template<class U1, class U2> constexpr explicit(see below) pair(const pair<U1, U2>&& p);
template<pair-like P> constexpr explicit(see below) pair(P&& p);

Let FWD(u) be static_cast<decltype(u)>(u).

Constraints:

(15.1)
For the last overload, remove_cvref_t is not a specialization of ranges::subrange,
(15.2)
is_constructible_v<T1, decltype(get<0>(FWD(p)))> is true, and
(15.3)
is_constructible_v<T2, decltype(get<1>(FWD(p)))> is true.

Effects: Initializes first with get<0>(FWD(p)) and second with get<1>(FWD(p)).

Remarks: The expression inside explicit is equivalent to: !is_convertible_v<decltype(get<0>(FWD(p))), T1> || !is_convertible_v<decltype(get<1>(FWD(p))), T2>

The constructor is defined as deleted if reference_constructs_from_temporary_v<first_type, decltype(get<0>(FWD(p)))> || reference_constructs_from_temporary_v<second_type, decltype(get<1>(FWD(p)))> is true.

🔗

template<class... Args1, class... Args2>
  constexpr pair(piecewise_construct_t,
                 tuple<Args1...> first_args, tuple<Args2...> second_args);

Mandates:

(18.1)
is_constructible_v<T1, Args1...> is true and
(18.2)
is_constructible_v<T2, Args2...> is true.

Effects: 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(x).)

This form of construction, whereby constructor arguments for first and second are each provided in a separate tuple object, is called piecewise construction.

[Note 2:

If a data member of pair is of reference type and its initialization binds it to a temporary object, the program is ill-formed ([class.base.init]).

— end note]

🔗

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

Effects: Assigns p.first to first and p.second to second.

Returns: *this.

Remarks: This operator is defined as deleted unless is_copy_assignable_v<T1> is true and is_copy_assignable_v<T2> is true.

🔗

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

Constraints:

(23.1)
is_copy_assignable_v<const T1> is true and
(23.2)
is_copy_assignable_v<const T2> is true.

Effects: Assigns p.first to first and p.second to second.

Returns: *this.

🔗

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

Constraints:

(26.1)
is_assignable_v<T1&, const U1&> is true and
(26.2)
is_assignable_v<T2&, const U2&> is true.

Effects: Assigns p.first to first and p.second to second.

Returns: *this.

🔗

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

Constraints:

(29.1)
is_assignable_v<const T1&, const U1&> is true, and
(29.2)
is_assignable_v<const T2&, const U2&> is true.

Effects: Assigns p.first to first and p.second to second.

Returns: *this.

🔗

constexpr pair& operator=(pair&& p) noexcept(see below);

Constraints:

(32.1)
is_move_assignable_v<T1> is true and
(32.2)
is_move_assignable_v<T2> is true.

Effects: Assigns std::forward<T1>(p.first) to first and std::forward<T2>(p.second) to second.

Returns: *this.

Remarks: The exception specification is equivalent to: is_nothrow_move_assignable_v<T1> && is_nothrow_move_assignable_v<T2>

🔗

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

Constraints:

(36.1)
is_assignable_v<const T1&, T1> is true and
(36.2)
is_assignable_v<const T2&, T2> is true.

Effects: Assigns std::forward<T1>(p.first) to first and std::forward<T2>(p.second) to second.

Returns: *this.

🔗

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

Constraints:

(39.1)
is_assignable_v<T1&, U1> is true and
(39.2)
is_assignable_v<T2&, U2> is true.

Effects: Assigns std::forward<U1>(p.first) first and std::forward<U2>(p.second) to second.

Returns: *this.

🔗

template<pair-like P> constexpr pair& operator=(P&& p);

Constraints:

(42.1)
different-from<P, pair> ([range.utility.helpers]) is true,
(42.2)
remove_cvref_t is not a specialization of ranges::subrange,
(42.3)
is_assignable_v<T1&, decltype(get<0>(std::forward(p)))> is true, and
(42.4)
is_assignable_v<T2&, decltype(get<1>(std::forward(p)))> is true.

Effects: Assigns get<0>(std::forward(p)) to first and get<1>(std::forward(p)) to second.

Returns: *this.

🔗

template<pair-like P> constexpr const pair& operator=(P&& p) const;

Constraints:

(45.1)
different-from<P, pair> ([range.utility.helpers]) is true,
(45.2)
remove_cvref_t is not a specialization of ranges::subrange,
(45.3)
is_assignable_v<const T1&, decltype(get<0>(std::forward(p)))> is true, and
(45.4)
is_assignable_v<const T2&, decltype(get<1>(std::forward(p)))> is true.

Effects: Assigns get<0>(std::forward(p)) to first and get<1>(std::forward(p)) to second.

Returns: *this.

🔗

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

Constraints:

(48.1)
is_assignable_v<const T1&, U1> is true, and
(48.2)
is_assignable_v<const T2&, U2> is true.

Effects: Assigns std::forward<U1>(p.first) to first and std::forward<U2>(u.second) to second.

Returns: *this.

🔗

constexpr void swap(pair& p) noexcept(see below);
constexpr void swap(const pair& p) const noexcept(see below);

Mandates:

(51.1)
For the first overload, is_swappable_v<T1> is true and is_swappable_v<T2> is true.
(51.2)
For the second overload, is_swappable_v<const T1> is true and is_swappable_v<const T2> is true.

Preconditions: first is swappable with ([swappable.requirements]) p.first and second is swappable with p.second.

Effects: Swaps first with p.first and second with p.second.

Remarks: The exception specification is equivalent to:

(54.1)
is_nothrow_swappable_v<T1> && is_nothrow_swappable_v<T2> for the first overload, and
(54.2)
is_nothrow_swappable_v<const T1> && is_nothrow_swappable_v<const T2> for the second overload.