20 General utilities library [utilities]

20.4 Pairs [pairs]

20.4.1 In general [pairs.general]

The library provides a template for heterogeneous pairs of values.

The library also provides a matching function template to simplify their construction and several templates that provide access to pair objects as if they were tuple objects (see [tuple.helper] and [tuple.elem]).

20.4.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, class U2>
      constexpr explicit(see below) pair(U1&& x, U2&& y);
    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... Args1, class... Args2>
      constexpr pair(piecewise_construct_t,
                     tuple<Args1...> first_args, tuple<Args2...> second_args);

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

    constexpr void swap(pair& p) 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 satisfy the requirements for a constexpr function.

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<first_type> is true and
(5.2)
is_default_constructible_v<second_type> is true.

Effects: Value-initializes first and second.

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

[ Note

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

— end note

]

🔗

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

Constraints:

(8.1)
is_copy_constructible_v<first_type> is true and
(8.2)
is_copy_constructible_v<second_type> is true.

Effects: Initializes first with x and second with y.

Remarks: The expression inside explicit is equivalent to:

!is_convertible_v<const first_type&, first_type> ||
  !is_convertible_v<const second_type&, second_type>

🔗

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

Constraints:

(11.1)
is_constructible_v<first_type, U1> is true and
(11.2)
is_constructible_v<second_type, 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, first_type> || !is_convertible_v<U2, second_type>

🔗

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

Constraints:

(14.1)
is_constructible_v<first_type, const U1&> is true and
(14.2)
is_constructible_v<second_type, const U2&> is true.

Effects: Initializes members from the corresponding members of the argument.

Remarks: The expression inside explicit is equivalent to:

!is_convertible_v<const U1&, first_type> || !is_convertible_v<const U2&, second_type>

🔗

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

Constraints:

(17.1)
is_constructible_v<first_type, U1> is true and
(17.2)
is_constructible_v<second_type, U2> is true.

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

Remarks: The expression inside explicit is equivalent to:

!is_convertible_v<U1, first_type> || !is_convertible_v<U2, second_type>

🔗

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

Mandates:

(20.1)
is_constructible_v<first_type, Args1...> is true and
(20.2)
is_constructible_v<second_type, 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<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.

🔗

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

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

Remarks: This operator is defined as deleted unless is_copy_assignable_v<first_type> is true and is_copy_assignable_v<second_type> is true.

Returns: *this.

🔗

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

Constraints:

(25.1)
is_assignable_v<first_type&, const U1&> is true and
(25.2)
is_assignable_v<second_type&, 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:

(28.1)
is_move_assignable_v<first_type> is true and
(28.2)
is_move_assignable_v<second_type> 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.

Remarks: The expression inside noexcept is equivalent to:

is_nothrow_move_assignable_v<T1> && is_nothrow_move_assignable_v<T2>

🔗

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

Constraints:

(32.1)
is_assignable_v<first_type&, U1> is true and
(32.2)
is_assignable_v<second_type&, U2> is true.

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

std::forward<U2>(p.second).

Returns: *this.

🔗

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

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 expression inside noexcept is equivalent to:

is_nothrow_swappable_v<first_type> && is_nothrow_swappable_v<second_type>

20.4.3 Specialized algorithms [pairs.spec]

🔗

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 common_comparison_category_t<synth-three-way-result<T1>,
                                         synth-three-way-result<T2>>
    operator<=>(const pair<T1, T2>& x, const pair<T1, T2>& y);

Effects: Equivalent to:

if (auto c = synth-three-way(x.first, y.first); c != 0) return c;
return synth-three-way(x.second, y.second);

🔗

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

Constraints: is_swappable_v<T1> is true and is_swappable_v<T2> is true.

Effects: Equivalent to x.swap(y).

🔗

template<class T1, class T2>
  constexpr pair<unwrap_ref_decay_t<T1>, unwrap_ref_decay_t<T2>> make_pair(T1&& x, T2&& y);

Returns:

pair<unwrap_ref_decay_t<T1>,
     unwrap_ref_decay_t<T2>>(std::forward<T1>(x), std::forward<T2>(y))

[ 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

]

20.4.4 Tuple-like access to pair [pair.astuple]

🔗

template<class T1, class T2>
  struct tuple_size<pair<T1, T2>> : integral_constant<size_t, 2> { };

🔗

template<size_t I, class T1, class T2>
  struct tuple_element<I, pair<T1, T2>> {
    using type = see below ;
  };

Mandates:

I < 2

Type: The type T1 if I is 0, otherwise 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;
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;

Mandates:

I < 2

Returns:

(4.1)
If I is 0, returns a reference to p.first.
(4.2)
If I is 1, returns a reference to p.second.

🔗

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

Mandates: T1 and T2 are distinct types.

Returns: A reference to p.first.

🔗

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

Mandates: T1 and T2 are distinct types.

Returns: A reference to p.second.

20.4.5 Piecewise construction [pair.piecewise]

🔗

struct piecewise_construct_t {
  explicit piecewise_construct_t() = default;
};
inline constexpr piecewise_construct_t piecewise_construct{};

The struct piecewise_construct_t is an empty class 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 arguments used for piecewise construction of the elements of the pair object.