std::tuple

Class template std::tuple is a fixed-size collection of heterogeneous values. It is a generalization of std::pair.

# Declarations

template< class... Types >
class tuple;

(since C++11)

# Template parameters

• Types...: the element types stored in the tuple. An empty parameter pack is allowed, so std::tuple<> is a valid type.

# Semantics

• A tuple stores each element directly as part of the tuple object itself.
• The number of elements, their types, and their order are all part of the tuple type.
• Access is tuple-like rather than name-based: elements are selected by index with get or, when types are unique, by type.
• tuple is the general-purpose heterogeneous product type in the standard library; std::pair is the specialized two-element case.

# Member functions

# Non-member functions

# Helper concepts

# Helper classes

# Helper specializations

• enable_nonlocking_formatter_optimization<std::tuple<Ts...>> is specialized in C++23 so tuple formatting can participate in optimized std::print/std::println implementations when every element type enables it.

# Deduction guides

The class has deduction guides so direct construction can infer the tuple element types from constructor arguments.

# Notes

Since the “shape” of a tuple – its size, the types of its elements, and the ordering of those types – are part of its type signature, they must all be available at compile time and can only depend on other compile-time information. This means that many conditional operations on tuples – in particular, conditional prepend/append and filter – are only possible if the conditions can be evaluated at compile time. For example, given a std::tuple<int, double, int>, it is possible to filter on types – e.g. returning a std::tuple<int, int> – but not to filter on whether or not each element is positive (which would have a different type signature depending on runtime values of the tuple), unless all the elements were themselves constexpr.

As a workaround, one can work with tuples of std::optional, but there is still no way to adjust the size based on runtime information.

Until N4387 (applied as a defect report for C++11), a function could not return a tuple using copy-list-initialization.

# Feature-test note

Tuple’s type-level API expands over time mainly through helper traits, formatting support, and tuple-like interoperability. The core product-type semantics are stable from C++11 onward.

# Example

#include <iostream>
#include <stdexcept>
#include <string>
#include <tuple>
 
std::tuple<double, char, std::string> get_student(int id)
{
    switch (id)
    {
        case 0: return {3.8, 'A', "Lisa Simpson"};
        case 1: return {2.9, 'C', "Milhouse Van Houten"};
        case 2: return {1.7, 'D', "Ralph Wiggum"};
        case 3: return {0.6, 'F', "Bart Simpson"};
    }
 
    throw std::invalid_argument("id");
}
 
int main()
{
    const auto student0 = get_student(0);
    std::cout << "ID: 0, "
              << "GPA: " << std::get<0>(student0) << ", "
              << "grade: " << std::get<1>(student0) << ", "
              << "name: " << std::get<2>(student0) << '\n';
 
    const auto student1 = get_student(1);
    std::cout << "ID: 1, "
              << "GPA: " << std::get<double>(student1) << ", "
              << "grade: " << std::get<char>(student1) << ", "
              << "name: " << std::get<std::string>(student1) << '\n';
 
    double gpa2;
    char grade2;
    std::string name2;
    std::tie(gpa2, grade2, name2) = get_student(2);
    std::cout << "ID: 2, "
              << "GPA: " << gpa2 << ", "
              << "grade: " << grade2 << ", "
              << "name: " << name2 << '\n';
 
    // C++17 structured binding:
    const auto [gpa3, grade3, name3] = get_student(3);
    std::cout << "ID: 3, "
              << "GPA: " << gpa3 << ", "
              << "grade: " << grade3 << ", "
              << "name: " << name3 << '\n';
}

# Defect reports

# References

• C++23 standard (ISO/IEC 14882:2024): 22.4 Tuples [tuple]
• C++20 standard (ISO/IEC 14882:2020): 20.5 Tuples [tuple]
• C++17 standard (ISO/IEC 14882:2017): 23.5 Tuples [tuple]
• C++14 standard (ISO/IEC 14882:2014): 20.4 Tuples [tuple]
• C++11 standard (ISO/IEC 14882:2011): 20.4 Tuples [tuple]

# See also

• std::pair
• std::tie