<tuple>

[added with TR1]

forward_as_tuple · get · ignore · make_tuple · swap · tie · tuple · tuple_cat · tuple_element · tuple_size · uses_allocator

operator== · operator!= · operator< · operator<= · operator> · operator>=

Include the C++11 header <tuple> to define a template tuple whose instances hold objects of varying types.

Note: Beginning with C++11, this header makes extensive use of variadic templates, indicated by various uses of ellipsis (...). The descriptions below use variadic notation, but still apply to older compilers, provided the number of parameters in a varying-length list does not exceed ten.

namespace std {
    // TEMPLATE CLASSES
template<class... Types>
    class tuple;

template<size_t Idx, class Ty>
    class tuple_element; // not defined
template<size_t Idx, class... Types>
    class tuple_element<Idx, tuple<Types...> >;
template<size_t Idx, class... Types> [added with C++11]
    class tuple_element<Idx, const tuple<Types...> >;
template<size_t Idx, class... Types> [added with C++11]
    class tuple_element<Idx, volatile tuple<Types...> >;
template<size_t Idx, class... Types> [added with C++11]
    class tuple_element<Idx, const volatile tuple<Types...> >;

template<class Ty>
    class tuple_size; // not defined
template<class... Types>
    class tuple_size<tuple<Types...> >;
template<class... Types> [added with C++11]
    class tuple_size<const tuple<Types...> >;
template<class... Types> [added with C++11]
    class tuple_size<volatile tuple<Types...> >;
template<class... Types> [added with C++11]
    class tuple_size<const volatile tuple<Types...> >;

    // TEMPLATE FUNCTIONS
template<size_t Idx, class... Types>
    constexpr typename tuple_element<Idx, tuple<Types...> >::type&
        get(tuple<Types...>& tpl) noexcept;
template<size_t Idx, class... Types>
    constexpr const typename tuple_element<Idx, tuple<Types...> >::type&
        get(const tuple<Types...>& tpl) noexcept;
template<size_t Idx, class... Types> [added with C++11]
    constexpr typename tuple_element<Idx, tuple<Types...> >::type&&
        get(tuple<Types...>&& tpl) noexcept;

template<class Ty, class... Types> [added with C++14]
    constexpr RI& get(tuple<Types...>& tpl) noexcept;
template<class Ty, class... Types> [added with C++14]
    constexpr const RI& get(const tuple<Types...>& tpl) noexcept;
template<class Ty, class... Types> [added with C++14]
    constexpr RI&& get(tuple<Types...>&& tpl) noexcept;

template<class... Types> [added with C++11]
    tuple<Types&&...>
        forward_as_tuple(Types&&... Args) noexcept;
template<class... Types>
    tuple<Types2...>
        constexpr make_tuple(Types&&...);
template<class... Types>
    tuple<Types&...>
        tie(Types&...) noexcept;

template<class... Tuples> [added with C++11]
    constexpr tuple<Types...>
        tuple_cat(Tuples&&... tpls);

template<class... Types>
    void swap(tuple<Types...>& left,
        tuple<Types...&> right)
            noexcept(noexcept(left.swap(right)));

    // TEMPLATE COMPARISON OPERATORS
template<class... Types1, class... Types2>
    constexpr bool operator==(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);
template<class... Types1, class... Types2>
    constexpr bool operator!=(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);
template<class... Types1, class... Types2>
    constexpr bool operator<(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);
template<class... Types1, class... Types2>
    constexpr bool operator>=(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);
template<class... Types1, class... Types2>
    constexpr bool operator>(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);
template<class... Types1, class... Types2>
    constexpr bool operator<=(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);

    // CONST OBJECTS
const T1 ignore;

        // HELPERS
template<class... Types, class Alloc>
    struct uses_allocator<tuple<Types...>, Alloc>;

    namespace tr1 {
using std::get; using std::ignore; [added with C++11]
using std::make_tuple; using std::ref;
using std::tie; using std::tuple;
using std::tuple_cat; using std::tuple_element;
using std::tuple_size;
    }  // namespace tr1
}  // namespace std

forward_as_tuple

template<class... Types> [added with C++11]
    tuple<Types&&...>
        forward_as_tuple(Types&&... Args) noexcept;

The template function returns tuple<Types&&...>(forward<Types>(Args)...)

get

template<size_t Idx, class... Types>
    constexpr typename tuple_element<Idx, tuple<Types...> >::type&
        get(tuple<Types...>& tpl) noexcept;
template<size_t Idx, class... Types>
    constexpr const typename tuple_element<Idx, tuple<Types...> >::type&
        get(const tuple<Types...>& tpl) noexcept;
template<size_t Idx, class... Types> [added with C++11]
    constexpr typename tuple_element<Idx, tuple<Types...> >::type&&
        get(tuple<Types...>&& tpl) noexcept;

template<class Ty, class... Types> [added with C++14]
    constexpr RI& get(tuple<Types...>& tpl) noexcept;
template<class Ty, class... Types> [added with C++14]
    constexpr const RI& get(const tuple<Types...>& tpl) noexcept;
template<class Ty, class... Types> [added with C++14]
    constexpr RI&& get(tuple<Types...>&& tpl) noexcept;

The first three template functions each return a reference to the value at index Idx in the tuple object tpl.

The remaining functions require that Ty be an element type that differs from all other element types. They each return a reference to the value of the element with type Ty.

ignore

const T1 ignore;

The object has unspecified type T1 and can be assigned anything with no effect. Note that ignore& can make a useful placeholder in a tuple object.

make_tuple

template<class... Types>
    constexpr tuple<Types2...>
        make_tuple(Types&&...);

The template function returns a tuple object constructed from the argument list, where each element type T2i in Types2 is determined from the corresponding Ti in Types as follows:

• If Ti is any const/volatile qualified reference_wrapper<X>, T2i is X&.
• Otherwise, beginning with C++11, T2i is decay<Ti>::type.
• Otherwise, T2i is Ti.

operator==

template<class... Types1, class... Types2>
    constexpr bool operator==(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);

The function returns true only when both tuples are empty, or when get<0>(tpl1) == get<0>(tpl2) && ... for all corresponding elements.

operator!=

template<class... Types1, class... Types2>
    constexpr bool operator!=(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);

The function returns !(tpl1 == tpl2).

operator<

template<class... Types1, class... Types2>
    constexpr bool operator<(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);

The function returns true only when both tuples are not empty and get<0>(tpl1) < get<0>(tpl2) || !(get<0>(tpl2) < get<0>(tpl1)) && ... for all corresponding elements.

operator<=

template<class... Types1, class... Types2>
    constexpr bool operator<=(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);

The function returns !(tpl2 < tpl1).

operator>

template<class... Types1, class... Types2>
    constexpr bool operator>(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);

The function returns tpl2 < tpl1.

operator>=

template<class... Types1, class... Types2>
    constexpr bool operator>=(const tuple<Types1...>& tpl1,
        const tuple<Types2...>& tpl2);

The function returns !(tpl1 < tpl2).

swap

template<class... Types>
    void swap(tuple<Types...>& left,
        tuple<Types...&> right)
            noexcept(noexcept(left.swap(right)));

The function executes left.swap(right).

tie

template<class... Types>
    tuple<Types&...>
        tie(Types&...) noexcept;

The template function returns a tuple object constructed from the argument list, where each element is a reference. Note that a reference to ignore can be assigned anything and will do nothing.

tuple

template<class... Types>
class tuple {
public:
    constexpr tuple();
    explicit tuple(const Types&...);
    template<class... Types2>
        constexpr tuple(const tuple<Types2...>& right);
    template<class U1, class U2>
        constexpr tuple(const pair<U1, U2>& right);

    template<class... Types2>
        constexpr explicit tuple(Types2...&& args); [added with C++11]

    template<class... Types2>
        constexpr tuple(tuple<Types2...>&& right); [added with C++11]
    template<class U1, class U2>
        constexpr tuple(pair<U1, U2>&& right); [added with C++11]

    tuple(const tuple& right) = default; [added with C++11]
    tuple(tuple&& right) = default; [added with C++11]

    template<class Alloc>
        tuple(allocator_arg_t, const Alloc& al); [added with C++11]
    template<class Alloc>
        tuple(allocator_arg_t, const Alloc& al,
            const Types&...); [added with C++11]
    template<class Alloc, class... Types2>
        tuple(allocator_arg_t, const Alloc& al,
            const tuple<Types2...>& right); [added with C++11]
    template<class Alloc, class U1, class U2>
        tuple(allocator_arg_t, const Alloc& al,
            const pair<U1, U2>& right); [added with C++11]

    template<class Alloc, class... Types2>
        tuple(allocator_arg_t, const Alloc& al,
            Types2...&& args); [added with C++11]

    template<class Alloc>
        tuple(allocator_arg_t, const Alloc& al,
            tuple&& right); [added with C++11]
    template<class Alloc, class... Types2>
        tuple(allocator_arg_t, const Alloc& al,
            tuple<Types2...>&& right); [added with C++11]
    template<class Alloc, class U1, class U2>
        tuple(allocator_arg_t, const Alloc& al,
            pair<U1, U2>&& right); [added with C++11]
    template<class Alloc>
        tuple(allocator_arg_t, const Alloc& al,
            const tuple& right); [added with C++11]

    tuple& operator=(const tuple& right);
    template<class... Types2>
        tuple& operator=(const tuple<Types2...>& right);
    template<class U1, class U2>
        tuple& operator=(const pair<U1, U2>& right);

    tuple& operator=(tuple&& right); [added with C++11]
    template<class... Types2>
        tuple& operator=(tuple<Types2...>&& right); [added with C++11]
    template<class U1, class U2>
        tuple& operator=(pair<U1, U2>&& right); [added with C++11]

    void swap(tuple& right)
        noexcept(expr); [added with C++11]
    };

The template class describes an object that stores zero or more objects of types specified by Types. The extent of a tuple instance is the number N of its template arguments. The index of the template argument Ti (counting from zero) and of the corresponding stored value of that type is i.

tuple::operator=

tuple& operator=(const tuple& right);
template<class... Types2>
    tuple& operator=(const tuple<Types2...>& right);
template<class U1, class U2>
    tuple& operator=(const pair<U1, U2>& right);

tuple& operator=(tuple&& right); [added with C++11]
template<class... Types2>
    tuple& operator=(tuple<Types2...>&& right); [added with C++11]
template<class U1, class U2>
    tuple& operator=(pair<U1, U2>&& right); [added with C++11]

The first two member operators assign the elements of right to the corresponding elements of *this. The third member operator assigns right.first to the element at index 0 of *this and right.second to the element at index 1. All three member operators return *this.

The remaining member operators are analogs to earlier ones, but with rvalue references.

tuple::swap

void swap(tuple& right)
    noexcept(expr); [added with C++11]

The member function calls swap for each element of right and the corresponding element of *this.

The noexcept expression expr is true if, for each type Ti in Types... swap(declval<Ti&>(), declval<Ti&>()). is true.

tuple::tuple

tuple();
constexpr explicit tuple(const Types&...);
template<class... Types2>
    constexpr tuple(const tuple<Types2...>& right);
template<class U1, class U2>
    constexpr tuple(const pair<U1, U2>& right);

template<class... Types2>
    constexpr explicit tuple(Types2...&& args); [added with C++11]

template<class... Types2>
    constexpr tuple(tuple<Types2...>&& right); [added with C++11]
template<class U1, class U2>
    constexpr tuple(pair<U1, U2>&& right); [added with C++11]

tuple(const tuple& right) = default;
tuple(tuple&& right) = default; [added with C++11]

template<class Alloc>
    tuple(allocator_arg_t, const Alloc& al); [added with C++11]
template<class Alloc>
    tuple(allocator_arg_t, const Alloc& al,
        const Types&...); [added with C++11]
template<class Alloc, class... Types2>
    tuple(allocator_arg_t, const Alloc& al,
        const tuple<Types2...>& right); [added with C++11]
template<class Alloc, class U1, class U2>
    tuple(allocator_arg_t, const Alloc& al,
        const pair<U1, U2>& right); [added with C++11]

template<class Alloc, class... Types2>
    tuple(allocator_arg_t, const Alloc& al,
        Types2...&& args); [added with C++11]

template<class Alloc>
    tuple(allocator_arg_t, const Alloc& al,
        tuple&& right); [added with C++11]
template<class Alloc, class... Types2>
    tuple(allocator_arg_t, const Alloc& al,
        tuple<Types2...>&& right); [added with C++11]
template<class Alloc, class U1, class U2>
    tuple(allocator_arg_t, const Alloc& al,
        pair<U1, U2>&& right); [added with C++11]
template<class Alloc>
    tuple(allocator_arg_t, const Alloc& al,
        const tuple& right); [added with C++11]

The first constructor constructs an object whose elements are default constructed. The second constructor constructs an object whose elements are copy constructed from the argument list.

The third constructor constructs an object whose elements are copy constructed from the corresponding element of right. The fourth constructor constructs an object whose element at index 0 is copy constructed from right.first and whose element at index 1 is copy constructed from right.second.

The next three constructors are analogs to earlier ones, but with rvalue references.

The remaining constructors construct each of the tuple elements (of type Ti, with optional argument Vi) in one of three ways:

• If uses_allocator<Ti, Alloc> holds false, then the element is constructed with no additional arguments (just the optional argument Vi).
• If uses_allocator<Ti, Alloc> holds true, and is_constructible<Ti, allocator_arg_t, Alloc [, Ti]> holds true, then the optional constructor argument Vi is preceded by the two arguments allocator_arg and al.
• If uses_allocator<Ti, Alloc> holds true and is_constructible<Ti, allocator_arg_t, Alloc [, Ti]> holds false, then the optional constructor argument Vi is followed by al.

tuple_cat

template<class... Tuples> [added with C++11]
    constexpr tuple<Types...>
        tuple_cat(Tuples&&... tpls);

The template function returns an object of type tuple<Types...> whose elements are the concatenation of the elements of the arguments tpls.... Each of the arguments tpls... must be an object of template class tuple or, as a conforming extension, an object of template class array or pair.

tuple_element

template<size_t Idx, class Ty>
    class tuple_element; // not defined
template<size_t Idx, class... Types>
    class tuple_element<Idx, tuple<Types...> >;
template<size_t Idx, class... Types> [added with C++11]
    class tuple_element<Idx, const tuple<Types...> >;
template<size_t Idx, class... Types> [added with C++11]
    class tuple_element<Idx, volatile tuple<Types...> >;
template<size_t Idx, class... Types> [added with C++11]
    class tuple_element<Idx, const volatile tuple<Types...> >;

The template class has a member type type that is a synonym for the cv-qualified type at index Idx of the type tuple<Types...>.

tuple_size

template<class Ty>
    class tuple_size; // not defined
template<class... Types>
    class tuple_size<tuple<Types...> >;
template<class... Types> [added with C++11]
    class tuple_size<const tuple<Types...> >;
template<class... Types> [added with C++11]
    class tuple_size<volatile tuple<Types...> >;
template<class... Types> [added with C++11]
    class tuple_size<const volatile tuple<Types...> >;

The template class has a member const size_t value whose value is the extent of the type tuple<Types...>.

uses_allocator

template<class... Types, class Alloc>
    struct uses_allocator<tuple<Types...>, Alloc>
        : public true_type { };

The specialization always holds true.

See also the Table of Contents and the Index.

Copyright (c) by P.J. Plauger. All rights reserved.