Namespaces
Variants
Views
Actions

std::tuple

From cppreference.com
< cpp‎ | utility
 
 
Utilities library
Language support
Type support (basic types, RTTI)
Library feature-test macros (C++20)
Dynamic memory management
Program utilities
Coroutine support (C++20)
Variadic functions
Debugging support
(C++26)
Three-way comparison
(C++20)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
General utilities
Date and time
Function objects
Formatting library (C++20)
(C++11)
Relational operators (deprecated in C++20)
Integer comparison functions
(C++20)(C++20)(C++20)   
(C++20)
Swap and type operations
(C++14)
(C++11)
(C++11)
(C++11)
(C++17)
Common vocabulary types
tuple
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++23)
Elementary string conversions
(C++17)
(C++17)

 
 
Defined in header <tuple>
template< class... Types >
class tuple;
(since C++11)

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

If std::is_trivially_destructible<Ti>::value is true for every Ti in Types, the destructor of std::tuple is trivial.

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

Contents

[edit] Template parameters

Types... - the types of the elements that the tuple stores. Empty list is supported.

[edit] Member functions

constructs a new tuple
(public member function) [edit]
assigns the contents of one tuple to another
(public member function) [edit]
swaps the contents of two tuples
(public member function) [edit]

[edit] Non-member functions

creates a tuple object of the type defined by the argument types
(function template) [edit]
(C++11)
creates a tuple of lvalue references or unpacks a tuple into individual objects
(function template) [edit]
creates a tuple of forwarding references
(function template) [edit]
(C++11)
creates a tuple by concatenating any number of tuples
(function template) [edit]
tuple accesses specified element
(function template) [edit]
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20)
lexicographically compares the values in the tuple
(function template) [edit]
specializes the std::swap algorithm
(function template) [edit]

[edit] Helper concepts

specifies that a type implemented the tuple protocol
(std::get, std::tuple_element, std::tuple_size)
(exposition-only concept*)[edit]

[edit] Helper classes

obtains the size of tuple at compile time
(class template specialization) [edit]
obtains the type of the specified element
(class template specialization) [edit]
specializes the std::uses_allocator type trait
(class template specialization) [edit]
determines the common reference type of a tuple and a tuple-like type
(class template specialization) [edit]
determines the common type of a tuple and a tuple-like type
(class template specialization) [edit]
formatting support for pair and tuple
(class template specialization) [edit]
(C++11)
placeholder to skip an element when unpacking a tuple using tie
(constant) [edit]

[edit] Deduction guides (since C++17)

[edit] 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:

std::tuple<int, int> foo_tuple()
{
    return {1, -1};  // Error until N4387
    return std::tuple<int, int>{1, -1}; // Always works
    return std::make_tuple(1, -1); // Always works
}

[edit] 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';
}

Output:

ID: 0, GPA: 3.8, grade: A, name: Lisa Simpson
ID: 1, GPA: 2.9, grade: C, name: Milhouse Van Houten
ID: 2, GPA: 1.7, grade: D, name: Ralph Wiggum
ID: 3, GPA: 0.6, grade: F, name: Bart Simpson

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 2796 C++11 triviality of the destructor of std::tuple was unspecified specified
LWG 3990 C++11 a program could declare an explicit or
partial specialization of std::tuple
the program is ill-formed in this
case (no diagnostic required)

[edit] References

  • C++23 standard (ISO/IEC 14882:2023):
  • 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]

[edit] See also

implements binary tuple, i.e. a pair of values
(class template) [edit]