23 General utilities library [utilities]

Effects: Value-initializes each element.

Remarks: This constructor shall not participate in overload resolution unless is_­default_­constructible_­v<${\text{T}}_i$> is true for all i. [ Note: This behavior can be implemented by a constructor template with default template arguments.  — end note ] The constructor is explicit if and only if ${\text{T}}_i$ is not implicitly default-constructible for at least one i. [ Note: This behavior can be implemented with a trait that checks whether a const ${\text{T}}_i$& can be initialized with {}.  — end note ]

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

Remarks: This constructor shall not participate in overload resolution unless sizeof...(Types) >= 1 and is_­copy_­constructible_­v<${\text{T}}_i$> is true for all i. The constructor is explicit if and only if is_­convertible_­v<const ${\text{T}}_i$&, ${\text{T}}_i$> is false for at least one i.

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

Remarks: This constructor shall not participate in overload resolution unless sizeof...(Types) == sizeof...(UTypes) and sizeof...(Types) >= 1 and is_­constructible_­v<${\text{T}}_i$, ${\text{U}}_i$&&> is true for all i. The constructor is explicit if and only if is_­convertible_­v<${\text{U}}_i$&&, ${\text{T}}_i$> is false for at least one i.

Requires: is_­copy_­constructible_­v<${\text{T}}_i$> is true for all i.

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

Requires: is_­move_­constructible_­v<${\text{T}}_i$> is true for all i.

Effects: For all i, initializes the $i^{\text{th}}$ element of *this with std​::​forward<${\text{T}}_i$>(get<i>(u)).

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

Remarks: This constructor shall not participate in overload resolution unless

• (16.1)

  sizeof...(Types) == sizeof...(UTypes) and

• (16.2)

  is_­constructible_­v<${\text{T}}_i$, const ${\text{U}}_i$&> is true for all i, and

• (16.3)

  sizeof...(Types) != 1, or (when Types... expands to T and UTypes... expands to U)
  !is_­convertible_­v<const tuple<U>&, T> && !is_­constructible_­v<T, const tuple<U>&>
  && !is_­same_­v<T, U> is true.

The constructor is explicit if and only if is_­convertible_­v<const ${\text{U}}_i$&, ${\text{T}}_i$> is false for at least one i.

Effects: For all i, initializes the $i^{\text{th}}$ element of *this with std​::​forward<${\text{U}}_i$>(get<i>(u)).

Remarks: This constructor shall not participate in overload resolution unless

• (18.1)

  sizeof...(Types) == sizeof...(UTypes), and

• (18.2)

  is_­constructible_­v<${\text{T}}_i$, ${\text{U}}_i$&&> is true for all i, and

• (18.3)

  sizeof...(Types) != 1, or (when Types... expands to T and UTypes... expands to U)
  !is_­convertible_­v<tuple<U>, T> && !is_­constructible_­v<T, tuple<U>> &&
  !is_­same_­v<T, U> is true.

The constructor is explicit if and only if is_­convertible_­v<${\text{U}}_i$&&, ${\text{T}}_i$> is false for at least one i.

Effects: Initializes the first element with u.first and the second element with u.second.

Remarks: This constructor shall not participate in overload resolution unless sizeof...(Types) == 2, is_­constructible_­v<${\text{T}}_0$, const U1&> is true and is_­constructible_­v<${\text{T}}_1$, const U2&> is true.

The constructor is explicit if and only if is_­convertible_­v<const U1&, ${\text{T}}_0$> is false or is_­convertible_­v<const U2&, ${\text{T}}_1$> is false.

Effects: Initializes the first element with std​::​forward<U1>(u.first) and the second element with std​::​forward<U2>(u.second).

Remarks: This constructor shall not participate in overload resolution unless sizeof...(Types) == 2, is_­constructible_­v<${\text{T}}_0$, U1&&> is true and is_­constructible_­v<${\text{T}}_1$, U2&&> is true.

The constructor is explicit if and only if is_­convertible_­v<U1&&, ${\text{T}}_0$> is false or is_­convertible_­v<U2&&, ${\text{T}}_1$> is false.

Requires: Alloc shall meet the requirements for an Allocator.

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

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

Remarks: This operator shall be defined as deleted unless is_­copy_­assignable_­v<${\text{T}}_i$> is true for all i.

Returns: *this.

Effects: For all i, assigns std​::​forward<${\text{T}}_i$>(get<i>(u)) to get<i>(*this).

Remarks: This operator shall be defined as deleted unless is_­move_­assignable_­v<${\text{T}}_i$> is true for all i.

Remarks: The expression inside noexcept is equivalent to the logical and of the following expressions:

is_nothrow_move_assignable_v<$T_i$>

where $T_i$ is the $i^{\text{th}}$ type in Types.

Returns: *this.

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

Remarks: This operator shall not participate in overload resolution unless sizeof...(Types) == sizeof...(UTypes) and is_­assignable_­v<${\text{T}}_i$&, const ${\text{U}}_i$&> is true for all i.

Returns: *this.

Effects: For all i, assigns std​::​forward<${\text{U}}_i$>(get<i>(u)) to get<i>(*this).

Remarks: This operator shall not participate in overload resolution unless is_­assignable_­v<${\text{T}}_i$&, ${\text{U}}_i$&&> == true for all i and sizeof...(Types) == sizeof...(UTypes).

Returns: *this.

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

Remarks: This operator shall not participate in overload resolution unless sizeof...(Types) == 2 and is_­assignable_­v<${\text{T}}_0$&, const U1&> is true for the first type ${\text{T}}_0$ in Types and is_­assignable_­v<${\text{T}}_1$&, const U2&> is true for the second type ${\text{T}}_1$ in Types.

Returns: *this.

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.

Remarks: This operator shall not participate in overload resolution unless sizeof...(Types) == 2 and is_­assignable_­v<${\text{T}}_0$&, U1&&> is true for the first type ${\text{T}}_0$ in Types and is_­assignable_­v<${\text{T}}_1$&, U2&&> is true for the second type ${\text{T}}_1$ in Types.

Returns: *this.

Requires: Each element in *this shall be swappable with ([swappable.requirements]) the corresponding element in rhs.

Effects: Calls swap for each element in *this and its corresponding element in rhs.

Remarks: The expression inside noexcept is equivalent to the logical and of the following expressions:

is_nothrow_swappable_v<$T_i$>

where $T_i$ is the $i^{\text{th}}$ type in Types.

Throws: Nothing unless one of the element-wise swap calls throws an exception.

The pack VTypes is defined as follows. Let U${}_i$ be decay_­t<T${}_i$> for each T${}_i$ in TTypes. If U${}_i$ is a specialization of reference_­wrapper, then V${}_i$ in VTypes is U${}_i$​::​type&, otherwise V${}_i$ is U${}_i$.

Returns: tuple<VTypes...>(std​::​forward<TTypes>(t)...).

[ Example:

int i; float j;
make_tuple(1, ref(i), cref(j))

creates a tuple of type tuple<int, int&, const float&>.  — end example ]

Effects: Constructs a tuple of references to the arguments in 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).

Returns: tuple<TTypes&&...>(std​::​forward<TTypes>(t)...).

Returns: tuple<TTypes&...>(t...). When an argument in t is ignore, assigning any value to the corresponding tuple element has no effect.

[ Example: tie functions allow one to create tuples that unpack tuples into variables. ignore can be used for elements that are not needed:

int i; std::string s;
tie(i, ignore, s) = make_tuple(42, 3.14, "C++");
// i == 42, s == "C++"

 — end example ]

In the following paragraphs, let ${\text{T}}_i$ be the $i^{\text{th}}$ type in Tuples, ${\text{U}}_i$ be remove_­reference_­t<T${}_i$>, and ${\text{tp}}_i$ be the $i^{\text{th}}$ parameter in the function parameter pack tpls, where all indexing is zero-based.

Requires: For all i, ${\text{U}}_i$ shall be the type ${\text{cv}}_i$ tuple<${\text{Args}}_i$...>, where ${\text{cv}}_i$ is the (possibly empty) $i^{\text{th}}$ cv-qualifier-seq and ${\text{Args}}_i$ is the parameter pack representing the element types in ${\text{U}}_i$. Let ${\text{A}}_{ik}$ be the $k^{\text{th}}$ type in ${\text{Args}}_i$. For all ${\text{A}}_{ik}$ the following requirements shall be satisfied:

• (10.1)

  If ${\text{T}}_i$ is deduced as an lvalue reference type, then is_­constructible_­v<${\text{A}}_{ik}$, $c{v}_i{\text{A}}_{ik}$&> == true, otherwise

• (10.2)

  is_­constructible_­v<${\text{A}}_{ik}$, $c{v}_i{\text{A}}_{ik}$&&> == true.

Remarks: The types in CTypes shall be equal to the ordered sequence of the extended types ${\text{Args}}_0$..., ${\text{Args}}_1$..., …, ${\text{Args}}_{n-1}$..., where n is equal to sizeof...(Tuples). Let ${\text{e}}_i$... be the $i^{\text{th}}$ ordered sequence of tuple elements of the resulting tuple object corresponding to the type sequence ${\text{Args}}_i$.

Returns: A tuple object constructed by initializing the ${k_i}^{\text{th}}$ type element ${\text{e}}_{ik}$ in ${\text{e}}_i$... with

get<$k_i$>(std::forward<${\text{T}}_i$>(${\text{tp}}_i$))

for each valid $k_i$ and each group ${\text{e}}_i$ in order.

[ Note: An implementation may support additional types in the parameter pack Tuples that support the tuple-like protocol, such as pair and array.  — end note ]

Effects: Given the exposition-only function:

template <class F, class Tuple, size_t... I>
constexpr decltype(auto)
    apply_impl(F&& f, Tuple&& t, index_sequence<I...>) {                // exposition only
  return INVOKE(std::forward<F>(f), std::get<I>(std::forward<Tuple>(t))...);
}

Equivalent to:

return apply_impl(std::forward<F>(f), std::forward<Tuple>(t),
                  make_index_sequence<tuple_size_v<decay_t<Tuple>>>{});

Effects: Given the exposition-only function:

template <class T, class Tuple, size_t... I>
constexpr T make_from_tuple_impl(Tuple&& t, index_sequence<I...>) {     // exposition only
  return T(get<I>(std::forward<Tuple>(t))...);
}

Equivalent to:

return make_from_tuple_impl<T>(forward<Tuple>(t),
                               make_index_sequence<tuple_size_v<decay_t<Tuple>>>{});

[ Note: The type of T must be supplied as an explicit template parameter, as it cannot be deduced from the argument list.  — end note ]

Remarks: All specializations of tuple_­size shall meet the UnaryTypeTrait requirements with a base characteristic of integral_­constant<size_­t, N> for some N.

Requires: I < sizeof...(Types). The program is ill-formed if I is out of bounds.

Type: TI is the type of the Ith element of Types, where indexing is zero-based.

Let TS denote tuple_­size<T> of the cv-unqualified type T. If the expression TS​::​value is well-formed when treated as an unevaluated operand, then each of the three templates shall meet the UnaryTypeTrait requirements with a base characteristic of

integral_constant<size_t, TS::value>

Otherwise, they shall have no member value.

Access checking is performed as if in a context unrelated to TS and T. Only the validity of the immediate context of the expression is considered. [ Note: The compilation of the expression can result in side effects such as the instantiation of class template specializations and function template specializations, the generation of implicitly-defined functions, and so on. Such side effects are not in the “immediate context” and can result in the program being ill-formed.  — end note ]

In addition to being available via inclusion of the <tuple> header, the three templates are available when either of the headers <array> or <utility> are included.

Let TE denote tuple_­element_­t<I, T> of the cv-unqualified type T. Then each of the three templates shall meet the TransformationTrait requirements with a member typedef type that names the following type:

• (7.1)

  for the first specialization, add_­const_­t<TE>,

• (7.2)

  for the second specialization, add_­volatile_­t<TE>, and

• (7.3)

  for the third specialization, add_­cv_­t<TE>.

In addition to being available via inclusion of the <tuple> header, the three templates are available when either of the headers <array> or <utility> are included.

Requires: I < sizeof...(Types). The program is ill-formed if I is out of bounds.

Returns: A reference to the Ith element of t, where indexing is zero-based.

[ Note A: If a T in Types is some reference type X&, the return type is X&, not X&&. However, if the element type is a non-reference type T, the return type is T&&.  — end note ]

[ Note B: Constness is shallow. If a T in Types is some reference type X&, the return type is X&, not const X&. However, if the element type is a non-reference type T, the return type is const T&. This is consistent with how constness is defined to work for member variables of reference type.  — end note ]

Requires: The type T occurs exactly once in Types.... Otherwise, the program is ill-formed.

Returns: A reference to the element of t corresponding to the type T in Types....

[ Example:

  const tuple<int, const int, double, double> t(1, 2, 3.4, 5.6);
  const int& i1 = get<int>(t);        // OK. Not ambiguous. i1 == 1
  const int& i2 = get<const int>(t);  // OK. Not ambiguous. i2 == 2
  const double& d = get<double>(t);   // ERROR. ill-formed

 — end example ]

Requires: For all i, where 0 <= i and i < sizeof...(TTypes), get<i>(t) == get<i>(u) is a valid expression returning a type that is convertible to bool. sizeof...(TTypes) == sizeof...(UTypes).

Returns: true if get<i>(t) == get<i>(u) for all i, otherwise false. For any two zero-length tuples e and f, e == f returns true.

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 false.

Requires: For all i, where 0 <= i and i < sizeof...(TTypes), both get<i>(t) < get<i>(u) and get<i>(u) < get<i>(t) are valid expressions returning types that are convertible to bool. sizeof...(TTypes) == sizeof...(UTypes).

Returns: The result of a lexicographical comparison between t and u. The result is defined as: (bool)(get<0>(t) < get<0>(u)) || (!(bool)(get<0>(u) < get<0>(t)) && t${}_{tail}$ < u${}_{tail}$), where r${}_{tail}$ for some tuple r is a tuple containing all but the first element of r. For any two zero-length tuples e and f, e < f returns false.

Returns: !(t == u).

Returns: u < t.

Returns: !(u < t).

Returns: !(t < u).

Requires: Alloc shall be an Allocator.

[ Note: Specialization of this trait informs other library components that tuple can be constructed with an allocator, even though it does not have a nested allocator_­type.  — end note ]

Remarks: This function shall not participate in overload resolution unless is_­swappable_­v<${\text{T}}_i$> is true for all i, where $0\le i<\text{sizeof...(Types)}$. The expression inside noexcept is equivalent to:

noexcept(x.swap(y))

Effects: As if by x.swap(y).