std::tuple

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_v<Types> && ...) is true, the destructor of tuple is trivial.

(since C++17)

Template parameters

Types...

-

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

Member functions

(constructor)	constructs a new `tuple` (public member function)
operator=	assigns the contents of one `tuple` to another (public member function)
swap	swaps the contents of two `tuple`s (public member function)

Non-member functions

make_tuple	creates a `tuple` object of the type defined by the argument types (function template)
tie	creates a `tuple` of lvalue references or unpacks a tuple into individual objects (function template)
forward_as_tuple	creates a `tuple` of rvalue references (function template)
tuple_cat	creates a `tuple` by concatenating any number of tuples (function template)
std::get(std::tuple)	tuple accesses specified element (function template)
operator==operator!=operator<operator<=operator>operator>=	lexicographically compares the values in the tuple (function template)
std::swap(std::tuple) (C++11)	specializes the std::swap algorithm (function template)

Helper classes

tuple_size	obtains the size of `tuple` at compile time (class template specialization)
tuple_element	obtains the type of the specified element (class template specialization)
std::uses_allocator<std::tuple> (C++11)	specializes the std::uses_allocator type trait (class template specialization)
ignore	placeholder to skip an element when unpacking a `tuple` using `tie` (constant)

Notes

Until C++17, a function could not return a tuple using list-initialization:

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

Example

Run this code

#include <tuple>
#include <iostream>
#include <string>
#include <stdexcept>
 
std::tuple<double, char, std::string> get_student(int id)
{
    if (id == 0) return std::make_tuple(3.8, 'A', "Lisa Simpson");
    if (id == 1) return std::make_tuple(2.9, 'C', "Milhouse Van Houten");
    if (id == 2) return std::make_tuple(1.7, 'D', "Ralph Wiggum");
    throw std::invalid_argument("id");
}
 
int main()
{
    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';
 
    double gpa1;
    char grade1;
    std::string name1;
    std::tie(gpa1, grade1, name1) = get_student(1);
    std::cout << "ID: 1, "
              << "GPA: " << gpa1 << ", "
              << "grade: " << grade1 << ", "
              << "name: " << name1 << '\n';
}

Output:

ID: 0, GPA: 3.8, grade: A, name: Lisa Simpson
ID: 1, GPA: 2.9, grade: C, name: Milhouse Van Houten

References

C++11 standard (ISO/IEC 14882:2011):

20.4 Tuples [tuple]

Language
Standard library headers
Concepts
Utilities library
Strings library
Containers library
Algorithms library
Iterators library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Filesystem library (C++17)
Technical Specifications

Type support (basic types, RTTI, type traits)
Dynamic memory management
Error handling
Program utilities
Variadic functions
Date and time
Function objects
initializer_list (C++11)
bitset
hash (C++11)
Relational operators
rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>=
`optional`, `any` and `variant` (C++17)
optional
any
variant
in_placein_place_typein_place_indexin_place_tin_place_type_tin_place_index_t
Pairs and tuples
pair
tuple (C++11)
apply (C++17)
make_from_tuple (C++17)
piecewise_construct_t (C++11)
piecewise_construct (C++11)
integer_sequence (C++14)
Swap, forward and move
swap
exchange (C++14)
forward (C++11)
move (C++11)
move_if_noexcept (C++11)
Elementary string conversions
to_chars (C++17)
from_chars (C++17)
chars_format (C++17)
Type operations
declval (C++11)
as_const (C++17)