Tuples and std::tuple

A std::tuple is a generalization of std::pair that allows storing a collection of objects of different types. While a pair is limited to two elements, a tuple can contain any number of elements. This makes tuples a flexible way to group related values.

Tuples are heterogeneous containers, meaning each element can have a different type. This is in contrast to homogeneous containers like arrays and lists where all elements have the same type.

Tuples are commonly used to return multiple values from a function, store related attributes of an object, or pass multiple arguments to a function. They provide a convenient way to work with small, fixed-size collections of diverse values.

Creating Tuples

The std::tuple class template is available from the <tuple> header. Once included, we can then create a tuple in the usual ways. We pass the types of the objects we’ll be storing as template arguments, and their values as constructor arguments:

1#include <tuple>
2
3std::tuple<int, float, bool> MyTuple{
4  42, 3.14f, true
5};

When initializing the tuple with values, we can omit the template types, allowing the compiler to deduce them using class template argument deduction (CTAD)

1#include <tuple>
2
3std::tuple MyTuple{42, 3.14f, true};

The std::make_tuple() function also allows tuples to be constructed with deduced types:

1#include <tuple>
2
3void HandleTuple(
4  std::tuple<int, float, bool> Object){
5  // ...
6}
7
8int main(){
9  HandleTuple(std::make_tuple(42, 3.14f, true));
10}

This function was introduced to make construction require less syntax, but is less relevant now that CTAD provides the same convenience as a native feature of the language.

Member Access

Access to objects within a std::tuple is typically done through the std::get template function. We pass the index as a template argument, and the tuple as a function argument:

1#include <tuple>
2#include <iostream>
3
4int main(){
5  std::tuple MyTuple{42, 3.14f, true};
6
7  std::cout << std::get<0>(MyTuple) << ", ";
8  std::cout << std::get<1>(MyTuple) << ", ";
9  std::cout << std::get<2>(MyTuple);
10}

142, 3.14, 1

The std::get function returns the element by reference, allowing it to be updated:

1#include <tuple>
2#include <iostream>
3
4int main(){
5  std::tuple MyTuple{42, 3.14f, true};
6
7  std::cout << "First element: "
8    << std::get<0>(MyTuple);
9
10  std::get<0>(MyTuple) = 5;
11
12  std::cout << "\nNew first element: "
13    << std::get<0>(MyTuple);
14}

1First element: 42
2New first element: 5

We can also pass a type as the template argument to std::get. This retrieves the element within the tuple that has that type:

1#include <iostream>
2#include <tuple>
3
4int main() {
5  std::tuple MyTuple{42, 3.14f, true};
6
7  std::cout << "Float: "
8    << std::get<float>(MyTuple);  
9}

1Float: 3.14

This assumes the tuple has exactly one element of that type. If this is not the case, we will get a compilation error:

1#include <iostream>
2#include <tuple>
3
4int main() {
5  // A std::tuple<float, int, float, bool>:
6  std::tuple MyTuple{9.8f, 42, 3.14f, true};
7
8  std::cout << "Float: "
9    << std::get<float>(MyTuple);  
10}

1error: static_assert failed: 'duplicate type T in get<T>(tuple)'

Structured Binding

Similar to pairs, we can unpack tuple objects to dedicated variables using structured binding:

1#include <tuple>
2#include <iostream>
3
4int main(){
5  std::tuple MyTuple{42, 3.14, "Hello"};
6
7  auto [a, b, c]{MyTuple};
8
9  std::cout << a << ", " << b << ", " << c;
10}

142, 3.14, Hello

std::tie()

When the variables we want to use have already been declared, we can use std::tie() to update them. Here, we reuse our a, b, and c variables to store new values:

1#include <tuple>
2#include <iostream>
3
4int main(){
5  using std::cout, std::tuple;
6
7  tuple MyTuple{42, 3.14, true};
8  auto [a, b, c]{MyTuple};
9  cout << a << ", " << b << ", " << c;
10
11  tuple AnotherTuple{100, 9.8, false};
12  std::tie(a, b, c) = AnotherTuple;
13  cout << '\n' << a << ", " << b << ", " << c;
14}

142, 3.14, 1
2100, 9.8, 0

std::ignore

When using std::tie(), we can pass std::ignore in any position to skip over that element in the tuple. Below, we skip over the middle element, only updating a and c:

1#include <tuple>
2#include <iostream>
3
4int main(){
5  using std::cout, std::tuple, std::ignore;
6
7  tuple MyTuple{42, 3.14, true};
8  auto [a, b, c]{MyTuple};
9  cout << a << ", " << b << ", " << c;
10
11  tuple AnotherTuple{100, 9.8, false};
12  std::tie(a, ignore, c) = AnotherTuple;
13  cout << '\n' << a << ", " << b << ", " << c;
14}

142, 3.14, 1
2100, 3.14, 0

Tuple Type Traits

The <tuple> header includes two type traits that can help us when working with std::tuple containers at compile time. We covered type traits in detail earlier in the course:

Type Traits: Compile-Time Type Analysis

Learn how to use type traits to perform compile-time type analysis, enable conditional compilation, and enforce type requirements in templates.

Tuple Size using std::tuple_size

Similar to std::array, tuples have a fixed, static size, specified at compile time. We can get the size of a tuple by passing its type to the std::tuple_size type trait. Usually, this is done using the shorthand std::tuple_size_v syntax:

1#include <tuple>
2#include <iostream>
3
4template <typename T>
5void HandleTuple(T Tuple){
6  std::cout << "Tuple size: "
7    << std::tuple_size_v<T>;
8}
9
10int main(){
11  HandleTuple(std::tuple{42, 3.14, true});
12}

1Tuple size: 3

Tuple Element Type using std::tuple_element

The std::tuple_element type trait allows us to determine the subtypes our tuple is storing. It receives two template parameters: the zero-based index of the position we’re querying within the tuple, and the tuple type.

Below, we get the type of the first element (index 0) of our tuple using the shorthand syntax std::tuple_element_t. We then compare it to the int type using std::is_same_v:

1#include <tuple>
2#include <iostream>
3
4template <typename T>
5void HandleTuple(T Tuple){
6  if constexpr (std::is_same_v<
7    std::tuple_element_t<0, T>, int>) {
8    std::cout <<
9      "The first element is an integer";
10  }
11}
12
13int main(){
14  HandleTuple(std::tuple{42, 3.14, true});
15}

1The first element is an integer

Tuple Concatenation

Tuples are not designed to be resized at run time, but we can create a new tuple by concatenating two or more tuples together using the std::tuple_cat() function:

1#include <tuple>
2#include <iostream>
3
4int main(){
5  std::tuple Original{42, 3.14, true};
6  std::tuple Additions{9.8f, "Hello"};
7
8  auto Combined{
9    std::tuple_cat(Original, Additions)};
10
11  std::cout << "Combined Tuple Size: "
12    << std::tuple_size_v<decltype(Combined)>;
13
14  std::cout << "\nLast element: "
15    << std::get<4>(Combined);
16}

1Combined Tuple Size: 5
2Last element: Hello

Tuple Iteration

The standard library’s implementation of a tuple is quite basic, with very limited capabilities. The type does not provide any assistance with iteration.

Additionally, the C++ language itself has limited support for iteration over heterogeneous collections in general. That will be addressed in future language versions, with a feature tentatively called expansion statements.

Until then, if we need that capability, we must do a little more work. If our project relies heavily on tuples, we could introduce a third-party library with a more robust implementation.

The following is an example using Boost.Hana in conjunction with a lambda expression. We cover lambda expressions in detail in our later chapter on functions:

1#include <iostream>
2#include <boost/hana.hpp>
3namespace hana = boost::hana;
4
5int main(){
6  hana::tuple Tuple{42, 3.14, true};
7
8  hana::for_each(Tuple, [](auto Object){
9    std::cout << Object << ", ";
10  });
11}

142, 3.14, 1,

The following is an example of iterating over a tuple using only the standard library. It is also using more advanced functional concepts that we cover in the later chapter:

1#include <tuple>
2#include <iostream>
3
4void Log(auto Object){
5  std::cout << Object << ", ";
6}
7
8int main(){
9  std::tuple MyTuple{42, 3.14f, true};
10
11  std::apply([](auto... Objects){
12    (Log(Objects), ...);
13  }, MyTuple);
14}

142, 3.14, 1,

Summary

In this lesson, we covered tuples and std::tuple, which provide a way to store and work with small collections of diverse objects. The key takeaways include:

• std::tuple is a container that stores objects of different types
• Tuples are a generalization of pairs, allowing any number of elements
• Tuples are heterogeneous containers, with each element potentially having a different type
• Tuples can be created by specifying the types and values, or using std::make_tuple()
• Elements are accessed using std::get<index>() or std::get<type>()
• Structured bindings and std::tie() allow unpacking tuples into individual variables
• std::tuple_size and std::tuple_element are type traits for querying tuple properties
• Tuples can be concatenated using std::tuple_cat()

Next Lesson

Introduction to Queues and std::queue

Learn the fundamentals and applications of queues with the std::queue container.

ContinueView Course