Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Types and Language Concepts

Structured bindings

Reference for C++17 structured bindings: unpacking pairs, tuples, arrays and structs with auto [a, b], reference bindings, const, and the tuple-like protocol.

A structured binding declaration introduces several names at once, each bound to one element or member of a single object. Written auto [x, y] = expr;, it unpacks a std::pair, a std::tuple, a C array, or a plain struct whose non-static data members are all public. It was added in C++17.

The names are not independent variables. The compiler creates one hidden object from expr and the names refer to its parts. auto copies the whole object, auto& binds to it by reference, and const auto& binds read-only. The most common use is iterating over a std::map as for (const auto& [key, value] : m).

C++
std::pair<int, std::string> p{7, "seven"};
auto [number, word] = p;

Try it

C++ Pairs, tuples, arrays and structs

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++ Copy versus reference, and your own types

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++
attr(optional) cv-auto ref-qualifier(optional) [ id1, id2, ... ] = expression;
attr(optional) cv-auto ref-qualifier(optional) [ id1, id2, ... ] { expression };
attr(optional) cv-auto ref-qualifier(optional) [ id1, id2, ... ] ( expression );
Part Description
cv-auto auto, const auto, volatile auto. The type is deduced; you cannot name a type instead of auto.
ref-qualifier Optional & or &&. Without it the hidden object is a copy.
[id1, id2, ...] One name per element or member. The count must match exactly.
expression An array, a class with all-public non-static members (all in the same class), or a tuple-like type.

Returns: nothing; it declares names. The hidden object is destroyed at the end of the enclosing scope.

Errors: a wrong number of names is a compile error. Binding a type with private members, or members spread across base and derived classes, fails to compile.

Usage notes

  • Three kinds of source. Arrays (one name per element), classes with public non-static members, and tuple-like types that specialize std::tuple_size, std::tuple_element and provide get<I> (member or ADL). std::pair, std::tuple and std::array use the third route.
  • Names refer to the hidden object, not to declared variables. decltype(name) gives the member's type, and the auto& form lets you modify the original. Prefer const auto& for read-only loops over large elements.
  • Cannot skip elements. You must name every element. Mark names you do not use with [[maybe_unused]] to silence warnings, or use std::tie with std::ignore for plain assignment. C++26 standardizes _ as a placeholder name; do not rely on it yet.
  • No nesting. auto [a, [b, c]] = ... is not allowed. Bind first, then unpack.
  • Lambda capture. Capturing a structured binding in a lambda is only allowed since C++20. In C++17 mode copy the value into a normal variable first.
  • Not constexpr, and not a parameter. A binding declaration cannot be declared constexpr and cannot be a function parameter. It can appear in a range-for and in if/switch initializers.
  • Return multiple values. Returning a small struct or a tuple and unpacking it with a binding reads better than output parameters.
  • Version notes: added in C++17; C++20 added lambda capture and allowed static/thread_local on the declaration.