Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Containers

C++ std::tuple class

Reference for std::tuple: fixed collections of mixed types with get, tie, make_tuple, tuple_cat, apply, structured bindings and lexicographic comparison.

std::tuple<Ts...> (header <tuple>) generalizes std::pair to any number of values of any types. The number and types of elements are part of the type and fixed at compile time. Elements have no names: you reach them by position with std::get<I> or by unpacking the tuple with a structured binding.

Tuples shine in generic code: they hold a pack of arguments, return several results from a function template, give a lexicographic comparison for free, and carry data through std::apply. For ordinary application code with meaningful fields, prefer a named struct.

C++
#include <tuple>

std::tuple<int, std::string, double> row{1, "pen", 0.99};

Try it

C++ Creating and unpacking tuples

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Comparison, tuple_cat and apply

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
template<class... Types> class tuple;

constexpr tuple(const Types&... elems);
template<class... Us> constexpr tuple(Us&&... elems);

template<std::size_t I, class... Ts> constexpr auto& get(tuple<Ts...>& t) noexcept;
template<class T, class... Ts>       constexpr T&    get(tuple<Ts...>& t) noexcept;
Name Description
Types Element types, in order. A reference type makes a reference element.
elems Values used to initialize the elements. Default construction value-initializes every element.
I Zero-based index, a compile-time constant. An index past the last element does not compile.
T Element type, usable only when it occurs exactly once in the tuple.

Helpers: std::make_tuple (decays arguments, unwraps reference_wrapper), std::tie (tuple of lvalue references, used for assignment and comparison), std::forward_as_tuple (forwarding references), std::tuple_cat, std::apply, std::make_from_tuple, std::tuple_size, std::tuple_element, std::ignore.

Returns: get returns a reference to the element (an rvalue reference for a moved tuple). tuple_cat returns a new tuple of the combined element types.

Errors: all errors are compile-time: out-of-range index, get<T> with a duplicated or missing type, or comparing tuples whose elements are not comparable.

Usage notes

  • Comparison is lexicographic element by element (==, <, <=> since C++20), which makes tuples a quick sort key: std::tie(a.year, a.name) < std::tie(b.year, b.name).
  • Structured bindings work on tuples (auto [a, b, c] = t;) and are the readable way to unpack. Use auto& to bind to the tuple's elements instead of copies.
  • std::tie for assignment: std::tie(x, y) = f(); unpacks into existing variables; std::ignore skips an element.
  • Reference elements: std::tuple<int&> stores a reference, so the tuple must not outlive the variable it refers to. std::forward_as_tuple results are dangerous to store for the same reason.
  • Index with a constant, not a run-time value; there is no t[i]. Iterating a tuple needs std::apply with a fold expression, std::index_sequence, or a recursive template.
  • Compile-time cost: large tuples (dozens of elements) and heavy use of tuple_cat slow compilation noticeably.
  • Empty tuple std::tuple<> is valid and has size 1 or more bytes in practice.
  • std::pair interoperates: a pair converts to a two-element tuple, and tuple_cat accepts pairs.