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).
std::pair<int, std::string> p{7, "seven"}; auto [number, word] = p;
Try it
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.
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
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_elementand provideget<I>(member or ADL).std::pair,std::tupleandstd::arrayuse the third route. - Names refer to the hidden object, not to declared variables.
decltype(name)gives the member's type, and theauto&form lets you modify the original. Preferconst 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 usestd::tiewithstd::ignorefor 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 declaredconstexprand cannot be a function parameter. It can appear in a range-forand inif/switchinitializers. - 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_localon the declaration.
Related
- auto, Range-based for, Brace initialization
- References, Initialization
- Lessons: pair and tuple, map, auto