22 General utilities library [utilities]

namespace std { template<class. Types> class tuple { public: / [tuple.cnstr], tuple construction constexpr explicit(see below) tuple(); constexpr explicit(see below) tuple(const Types&.) / only if sizeof...(Types) >= 1 noexcept(see below); template<class. UTypes> constexpr explicit(see below) tuple(UTypes&&.) / only if sizeof...(Types) >= 1 noexcept(see below); tuple(const tuple&) = default; tuple(tuple&&) = default; template<class. UTypes> constexpr explicit(see below) tuple(tuple<UTypes..>&); template<class. UTypes> constexpr explicit(see below) tuple(const tuple<UTypes..>&); template<class. UTypes> constexpr explicit(see below) tuple(tuple<UTypes..>&); template<class. UTypes> constexpr explicit(see below) tuple(const tuple<UTypes..>&); template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>&); / only if sizeof...(Types) == 2 template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>&); / only if sizeof...(Types) == 2 template<class U1, class U2> constexpr explicit(see below) tuple(pair<U1, U2>&); / only if sizeof...(Types) == 2 template<class U1, class U2> constexpr explicit(see below) tuple(const pair<U1, U2>&); / only if sizeof...(Types) == 2 template<tuple-like UTuple> constexpr explicit(see below) tuple(UTuple&&); / allocator-extended constructors template<class Alloc> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a); template<class Alloc> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const Types&.); template<class Alloc, class. UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, UTypes&&.); template<class Alloc> constexpr tuple(allocator_arg_t, const Alloc& a, const tuple&); template<class Alloc> constexpr tuple(allocator_arg_t, const Alloc& a, tuple&&); template<class Alloc, class. UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, tuple<UTypes..>&); template<class Alloc, class. UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes..>&); template<class Alloc, class. UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, tuple<UTypes..>&); template<class Alloc, class. UTypes> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes..>&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&); template<class Alloc, class U1, class U2> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&); template<class Alloc, tuple-like UTuple> constexpr explicit(see below) tuple(allocator_arg_t, const Alloc& a, UTuple&&); / [tuple.assign], tuple assignment constexpr tuple& operator=(const tuple&); constexpr const tuple& operator=(const tuple&) const; constexpr tuple& operator=(tuple&&) noexcept(see below); constexpr const tuple& operator=(tuple&&) const; template<class. UTypes> constexpr tuple& operator=(const tuple<UTypes..>&); template<class. UTypes> constexpr const tuple& operator=(const tuple<UTypes..>&) const; template<class. UTypes> constexpr tuple& operator=(tuple<UTypes..>&); template<class. UTypes> constexpr const tuple& operator=(tuple<UTypes..>&) const; template<class U1, class U2> constexpr tuple& operator=(const pair<U1, U2>&); / only if sizeof...(Types) == 2 template<class U1, class U2> constexpr const tuple& operator=(const pair<U1, U2>&) const; / only if sizeof...(Types) == 2 template<class U1, class U2> constexpr tuple& operator=(pair<U1, U2>&); / only if sizeof...(Types) == 2 template<class U1, class U2> constexpr const tuple& operator=(pair<U1, U2>&) const; / only if sizeof...(Types) == 2 template<tuple-like UTuple> constexpr tuple& operator=(UTuple&&); template<tuple-like UTuple> constexpr const tuple& operator=(UTuple&&) const; / [tuple.swap], tuple swap constexpr void swap(tuple&) noexcept(see below); constexpr void swap(const tuple&) const noexcept(see below); }; template<class. UTypes> tuple(UTypes..) -> tuple<UTypes..>; template<class T1, class T2> tuple(pair<T1, T2>) -> tuple<T1, T2>; template<class Alloc, class. UTypes> tuple(allocator_arg_t, Alloc, UTypes..) -> tuple<UTypes..>; template<class Alloc, class T1, class T2> tuple(allocator_arg_t, Alloc, pair<T1, T2>) -> tuple<T1, T2>; template<class Alloc, class. UTypes> tuple(allocator_arg_t, Alloc, tuple<UTypes..>) -> tuple<UTypes..>; }

If a program declares an explicit or partial specialization of tuple, the program is ill-formed, no diagnostic required.

22.4.4.2 Construction [tuple.cnstr]

In the descriptions that follow, let i be in the range [0, sizeof.(Types)) in order,

T {i be the {i th type in Types, and U {i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}_{i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}}^{th type in Types, and U {i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}_{i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}}}_{i be the {i th type in Types, and U {i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}_{i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}}^{th type in Types, and U {i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}_{i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}}}

For each tuple constructor, an exception is thrown only if the construction of one of the types in Types throws an exception.

The defaulted move and copy constructor, respectively, of tuple is a constexpr function if and only if all required element-wise initializations for move and copy, respectively, would be constexpr-suitable ([dcl.constexpr]).

The defaulted move and copy constructor of tuple<> are constexpr functions.

If is_trivially_destructible_v<

T {i > is true for all T {i, then the destructor of tuple is trivial .}_{i, then the destructor of tuple is trivial .}}_{i >}

The default constructor of tuple<> is trivial.

🔗

constexpr explicit(see below) tuple();

Remarks: The expression inside explicit evaluates to true if and only if

T {i is not copy-list-initializable from an empty list for at least one i .}_{i is not copy-list-initializable from an empty list for at least one i .}

[Note 1:

This behavior can be implemented with a trait that checks whether a const

T {i & can be initialized with {} .}_{i &}

— end note]

🔗

constexpr explicit(see below) tuple(const Types&.)
  noexcept(is_nothrow_copy_constructible_v<Types> && ..);

Constraints: sizeof.(Types) ≥ 1 and is_copy_constructible_v<

T {i > is true for all i .}_{i >}

Effects: Initializes each element with the value of the corresponding parameter.

Remarks: The expression inside explicit is equivalent to: !conjunction_v<is_convertible<const Types&, Types>.>

🔗

template<class. UTypes> constexpr explicit(see below) tuple(UTypes&&. u)
  noexcept(is_nothrow_constructible_v<Types, UTypes> && ..);

Let disambiguating-constraint be:

(12.1)
negation<is_same<remove_cvref_t< $U {0 >, tuple > > if sizeof . (Types) is 1;}_{0 >, tuple > >}$
(12.2)
otherwise, bool_constant<!is_same_v<remove_cvref_t< $U {0 >, allocator_arg_t > | | is_- same_v < remove_cvref_t < T {0 >, allocator_arg_t > > if sizeof . (Types) is 2 or 3;}_{0 >, allocator_arg_t > >}}_{0 >, allocator_arg_t > | | is_- same_v < remove_cvref_t < T {0 >, allocator_arg_t > > if sizeof . (Types) is 2 or 3;}_{0 >, allocator_arg_t > >}}$
(12.3)
otherwise, true_type.

Constraints:

(13.1)
sizeof.(Types) equals sizeof.(UTypes),
(13.2)
sizeof.(Types) ≥ 1, and
(13.3)
conjunction_v<disambiguating-constraint, is_constructible<Types, UTypes>.> is
true.

Effects: Initializes the elements in the tuple with the corresponding value in std::forward<UTypes>(u).

Remarks: The expression inside explicit is equivalent to: !conjunction_v<is_convertible<UTypes, Types>.>

This constructor is defined as deleted if (reference_constructs_from_temporary_v<Types, UTypes&&> || ..) is true.

🔗

tuple(const tuple& u) = default;

Effects: Initializes each element of *this with the corresponding element of u.

🔗

tuple(tuple&& u) = default;

Effects: For all i, initializes the

{i th element of * this with std ​::​ forward < T {i > (get < i > (u)) .}_{i > (get < i > (u))}}^{th element of * this with std ​::​ forward < T {i > (get < i > (u)) .}_{i > (get < i > (u))}}

🔗

template<class. UTypes> constexpr explicit(see below) tuple(tuple<UTypes..>& u);
template<class. UTypes> constexpr explicit(see below) tuple(const tuple<UTypes..>& u);
template<class. UTypes> constexpr explicit(see below) tuple(tuple<UTypes..>& u);
template<class. UTypes> constexpr explicit(see below) tuple(const tuple<UTypes..>& u);

Constraints:

(21.1)
sizeof.(Types) equals sizeof.(UTypes), and
(21.2)
(is_constructible_v<Types, decltype(get(FWD(u))> && ..) is true, and
(21.3)
either sizeof.(Types) is not 1, or (when Types.. expands to T and UTypes.. expands to U) is_convertible_v<decltype(u), T>, is_constructible_v<T, decltype(u)>, and is_same_v<T, U> are all false.

Effects: For all i, initializes the

{i th element of * this with get < i > (FWD (u)) .}^{th element of * this with get < i > (FWD (u)) .}

Remarks: The expression inside explicit is equivalent to: !(is_convertible_v<decltype(get(FWD(u)), Types> && ..)

The constructor is defined as deleted if (reference_constructs_from_temporary_v<Types, decltype(get(FWD(u))> || ..) is true.

🔗

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

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

Remarks: The expression inside explicit is equivalent to: !is_convertible_v<decltype(get<0>(FWD(u)),

T {0 > | |! is_convertible_v < decltype (get < 1 > (FWD (u)), T {1 >}_{1 >}}_{0 > | |! is_convertible_v < decltype (get < 1 > (FWD (u)), T {1 >}_{1 >}}

The constructor is defined as deleted if reference_constructs_from_temporary_v<

T {0, decltype (get < 0 > (FWD (u)) > | | reference_constructs_from_temporary_v < T {1, decltype (get < 1 > (FWD (u)) > is true .}_{1, decltype (get < 1 > (FWD (u)) >}}_{0, decltype (get < 0 > (FWD (u)) > | | reference_constructs_from_temporary_v < T {1, decltype (get < 1 > (FWD (u)) > is true .}_{1, decltype (get < 1 > (FWD (u)) >}}

🔗

template<tuple-like UTuple>
  constexpr explicit(see below) tuple(UTuple&& u);

Constraints:

(29.1)
different-from<UTuple, tuple> ([range.utility.helpers]) is true,
(29.2)
remove_cvref_t<UTuple> is not a specialization of ranges::subrange,
(29.3)
sizeof.(Types) equals tuple_size_v<remove_cvref_t<UTuple>>,
(29.4)
(is_constructible_v<Types, decltype(get(std::forward<UTuple>(u))> && ..) is true, and
(29.5)
either sizeof.(Types) is not 1, or (when Types.. expands to T) is_convertible_v<UTuple, T> and is_constructible_v<T, UTuple> are both false.

Effects: For all i, initializes the

{i th element of * this with get < i > (std ​::​ forward < UTuple > (u)) .}^{th element of * this with get < i > (std ​::​ forward < UTuple > (u)) .}

Remarks: The expression inside explicit is equivalent to: !(is_convertible_v<decltype(get(std::forward<UTuple>(u)), Types> && ..)

The constructor is defined as deleted if (reference_constructs_from_temporary_v<Types, decltype(get(std::forward<UTuple>(u))> || ..) is true.

🔗

template<class Alloc>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a);
template<class Alloc>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, const Types&.);
template<class Alloc, class. UTypes>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, UTypes&&.);
template<class Alloc>
  constexpr tuple(allocator_arg_t, const Alloc& a, const tuple&);
template<class Alloc>
  constexpr tuple(allocator_arg_t, const Alloc& a, tuple&&);
template<class Alloc, class. UTypes>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, tuple<UTypes..>&);
template<class Alloc, class. UTypes>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes..>&);
template<class Alloc, class. UTypes>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, tuple<UTypes..>&);
template<class Alloc, class. UTypes>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, const tuple<UTypes..>&);
template<class Alloc, class U1, class U2>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&);
template<class Alloc, class U1, class U2>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
template<class Alloc, class U1, class U2>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, pair<U1, U2>&);
template<class Alloc, class U1, class U2>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, const pair<U1, U2>&);
template<class Alloc, tuple-like UTuple>
  constexpr explicit(see below)
    tuple(allocator_arg_t, const Alloc& a, UTuple&&);

Preconditions: Alloc meets the Cpp17Allocator requirements ([allocator.requirements.general]).

Effects: Equivalent to the preceding constructors except that each element is constructed with uses-allocator construction .

22.4.4.3 Assignment [tuple.assign]

For each tuple assignment operator, an exception is thrown only if the assignment of one of the types in Types throws an exception.

In the function descriptions that follow, let i be in the range [0, sizeof.(Types)) in order,

T {i be the {i th type in Types, and U {i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}_{i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}}^{th type in Types, and U {i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}_{i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}}}_{i be the {i th type in Types, and U {i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}_{i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}}^{th type in Types, and U {i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}_{i be the {i th type in a template parameter pack named UTypes, where indexing is zero-based .}^{th type in a template parameter pack named UTypes, where indexing is zero-based .}}}}

🔗

constexpr tuple& operator=(const tuple& u);

Effects: Assigns each element of u to the corresponding element of *this.

Remarks: This operator is defined as deleted unless is_copy_assignable_v<

T {i > is true for all i .}_{i >}

🔗

constexpr const tuple& operator=(const tuple& u) const;

Returns: *this.

🔗

constexpr tuple& operator=(tuple&& u) noexcept(see below);

Effects: For all i, assigns std::forward<

T {i > (get < i > (u)) to get < i > (* this) .}_{i > (get < i > (u))}

Remarks: The exception specification is equivalent to the logical and of the following expressions: is_nothrow_move_assignable_v<

{T i > where {T i is the {i th type in Types .}^{th type in Types .}}_{i is the {i th type in Types .}^{th type in Types .}}}_{i >}

🔗

constexpr const tuple& operator=(tuple&& u) const;

Effects: For all i, assigns std::forward<T

{i > (get < i > (u)) to get < i > (* this) .}_{i > (get < i > (u))}

Returns: *this.

🔗

template<class. UTypes> constexpr tuple& operator=(const tuple<UTypes..>& u);

Effects: Assigns each element of u to the corresponding element of *this.

Returns: *this.

🔗

template<class. UTypes> constexpr const tuple& operator=(const tuple<UTypes..>& u) const;

Returns: *this.

🔗

template<class. UTypes> constexpr tuple& operator=(tuple<UTypes..>& u);

Effects: For all i, assigns std::forward<

U {i > (get < i > (u)) to get < i > (* this) .}_{i > (get < i > (u))}

Returns: *this.

🔗

template<class. UTypes> constexpr const tuple& operator=(tuple<UTypes..>& u) const;

Effects: For all i, assigns std::forward<U

{i > (get < i > (u)) to get < i > (* this) .}_{i > (get < i > (u))}

Returns: *this.

🔗

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

Effects: Assigns u.first to the first element of *this and u.second to the second element of *this.

Returns: *this.

🔗

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

Effects: Assigns u.first to the first element and u.second to the second element.

Returns: *this.

🔗

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

Effects: Assigns std::forward<U1>(u.first) to the first element of *this and

std::forward<U2>(u.second) to the second element of *this.

Returns: *this.

🔗

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

Returns: *this.

🔗

template<tuple-like UTuple>
  constexpr tuple& operator=(UTuple&& u);

Constraints:

(39.1)
different-from<UTuple, tuple> ([range.utility.helpers]) is true,
(39.2)
remove_cvref_t<UTuple> is not a specialization of ranges::subrange,
(39.3)
sizeof.(Types) equals tuple_size_v<remove_cvref_t<UTuple>>, and
(39.4)
is_assignable_v< $T {i &, decltype (get (std :: forward < UTuple > (u)) > is true for all i .}_{i &, decltype (get (std :: forward < UTuple > (u)) >}$

Effects: For all i, assigns get(std::forward<UTuple>(u)) to get(*this).

Returns: *this.

🔗

template<tuple-like UTuple>
  constexpr const tuple& operator=(UTuple&& u) const;

Constraints:

(42.1)
different-from<UTuple, tuple> ([range.utility.helpers]) is true,
(42.2)
remove_cvref_t<UTuple> is not a specialization of ranges::subrange,
(42.3)
sizeof.(Types) equals tuple_size_v<remove_cvref_t<UTuple>>, and
(42.4)
is_assignable_v<const $T {i &, decltype (get (std :: forward < UTuple > (u)) > is true for all i .}_{i &, decltype (get (std :: forward < UTuple > (u)) >}$

Effects: For all i, assigns get(std::forward<UTuple>(u)) to get(*this).

Returns: *this.

22.4.4.4 swap [tuple.swap]

🔗

constexpr void swap(tuple& rhs) noexcept(see below);
constexpr void swap(const tuple& rhs) const noexcept(see below);

Mandates:

(2.1)
For the first overload, (is_swappable_v<Types> && ..) is true.
(2.2)
For the second overload, (is_swappable_v<const Types> && ..) is true.

Remarks: The exception specification is equivalent to

(6.1)
(is_nothrow_swappable_v<Types> && ..) for the first overload and
(6.2)
(is_nothrow_swappable_v<const Types> && ..) for the second overload.

22 General utilities library [utilities]

22.4 Tuples [tuple]

22.4.4 Class template tuple [tuple.tuple]

22.4.4.1 General [tuple.tuple.general]

22.4.4.2 Construction [tuple.cnstr]

22.4.4.3 Assignment [tuple.assign]

22.4.4.4 swap [tuple.swap]

22.4.4.1 General [tuple.tuple.general]

22.4.4.2 Construction [tuple.cnstr]

22.4.4.3 Assignment [tuple.assign]

22.4.4.4 swap [tuple.swap]