# Structured bindings

> A structured binding declaration creates one hidden variable from the initializer and then introduces names that refer into it. The specifiers you write apply to the hidden variable, and the names are aliases, not new variables.

- **Source:** C++ Atlas (https://cppatlas.com/topics/structured-bindings)
- **Track:** Expressions and functions
- **Estimated reading time:** 12 minutes
- **ISO C++ clauses:** [dcl.struct.bind] (https://eel.is/c++draft/dcl.struct.bind), [dcl.type.decltype] (https://eel.is/c++draft/dcl.type.decltype), [expr.prim.lambda.capture] (https://eel.is/c++draft/expr.prim.lambda.capture), [class.temporary] (https://eel.is/c++draft/class.temporary), [tuple.helper] (https://eel.is/c++draft/tuple.helper)
- **cppreference links:** [Structured binding declaration](https://en.cppreference.com/w/cpp/language/structured_binding), [std::tuple_size](https://en.cppreference.com/w/cpp/utility/tuple_size), [std::tuple_element](https://en.cppreference.com/w/cpp/utility/tuple_element)
- **Prerequisites:** type-deduction-auto-decltype, reference-binding-and-temporaries, value-categories

## The one idea

`auto [a, b] = expr;` looks like it declares two variables. It declares one. The compiler invents a variable, which the standard calls `e`, initializes it from `expr` exactly as `auto e = expr;` would, and then makes `a` and `b` names for parts of `e`.

Every rule follows from that picture. The `auto`, `const`, `&` or `&&` you write decide the type of `e`, not of `a` and `b`. Copying happens once, when `e` is initialized, or not at all if `e` is a reference. And `a` and `b` are not objects in their own right: they are names that the compiler resolves to subobjects of `e`, or, for tuple-like types, to references initialized from `get`.

```text
auto& [k, v] = entry;

    entry ----------------+
                          |   e is declared as  auto& e = entry;
    e (hidden, auto&) ----+
      .first  <-- k       k and v name members of e,
      .second <-- v       so they name members of entry
```

> **Mental model.** Rewrite `cv auto ref [names...] = expr;` as `cv auto ref e = expr;` and then read each name as "the i-th part of `e`". Any question about copies, constness or lifetime is a question about `e`.

## What the specifiers apply to

Because the declaration of `e` is formed from your specifiers and initializer, the familiar `auto` deduction rules apply to it, and they explain the common forms:

- `auto [a, b] = p;` copies `p` into `e`. Writing to `a` changes the copy.
- `auto& [a, b] = p;` makes `e` an lvalue reference to `p`. Writing to `a` changes `p`. It does not compile if `p` is a prvalue, because a non-const lvalue reference cannot bind to it.
- `const auto& [a, b] = make();` makes `e` a reference to const bound to the temporary; the names are read-only.
- `auto&& [a, b] = expr;` makes `e` a forwarding reference: it binds to anything without copying.

```cpp
#include <utility>

std::pair<int, int> make() { return {1, 2}; }

void demo() {
  std::pair<int, int> p{1, 2};
  auto  [a, b] = p;     a = 10;   // p.first is still 1: e is a copy
  auto& [c, d] = p;     c = 10;   // p.first is now 10: e refers to p
  // auto& [x, y] = make();       // ill-formed: lvalue reference to a prvalue
  const auto& [x, y] = make();    // OK: e binds to the temporary
  (void)b; (void)d; (void)x; (void)y;
}
```

The one exception to "`e` is declared exactly like `auto e = expr`" is a plain array with no reference qualifier: `e` becomes an array of the same type, and its elements are copied from the source elements one by one. Ordinary `auto` would have decayed the array to a pointer.

## Three ways to bind

Which protocol is used depends only on `E`, the type of `e` with references removed, and the checks happen in this order.

**Arrays.** If `E` is an array type, the names refer to its elements, and their number must equal the array bound.

**Tuple-like types.** Otherwise, if `std::tuple_size<E>` is a complete type with a member named `value`, the tuple protocol is used. The number of names must equal `std::tuple_size<E>::value`. For each index `i`, the compiler introduces a hidden variable of type "reference to `std::tuple_element<i, E>::type`", initialized from `e.get<i>()` if `E` has a member function template `get` whose first template parameter is a non-type parameter, and from `get<i>(e)` found by argument-dependent lookup otherwise. The name then refers to the object that reference is bound to. This is how `std::pair`, `std::tuple` and `std::array` decompose.

**Data members.** Otherwise, `E` must be a non-union class whose non-static data members are all direct members of `E` or all members of the same unambiguous base class, with no anonymous unions. The names refer to the members in declaration order, and the number of names must match. Since C++20 the members only need to be accessible at the point of the declaration, so a friend or member function can decompose a class with private data.

```cpp
class Point {
  int x_ = 1, y_ = 2;
  friend int sum(const Point& p) { auto [x, y] = p; return x + y; }  // OK since C++20
};

// auto [x, y] = Point{};   // ill-formed outside the class: x_ and y_ are private
```

> **Pitfall.** Specializing `std::tuple_size` for a type switches it to the tuple protocol even if it is an aggregate whose members would otherwise bind directly. A half-finished specialization, with `tuple_size` but no working `get`, turns a working declaration into a compile error.

## Names, not variables

A structured binding is an alias, and the language treats it differently from a variable in several observable ways.

**`decltype`.** Applied to an unparenthesized binding, `decltype` gives its *referenced type*, not the type of a reference. For arrays that is the element type, for data members it is the member's declared type with `e`'s cv-qualification added, and for the tuple protocol it is `std::tuple_element<i, E>::type`. So `auto& [a, b] = p;` for a `std::pair<int, int>` gives `decltype(a)` equal to `int`, not `int&`. Parenthesize it, as `decltype((a))`, and you get the expression rule: `a` is an lvalue, so `int&`.

**References inside the element type.** For `std::tie(x, y)`, the element types are `int&`, so the bindings refer to `x` and `y` themselves, even with plain `auto`. The object that `auto` creates is a tuple of references, not a copy of the referenced ints.

```cpp
#include <tuple>

void demo() {
  int x = 1, y = 2;
  auto [a, b] = std::tie(x, y);   // e is a std::tuple<int&, int&>
  a = 10;                          // x is now 10
  (void)b;
}
```

**Bit-fields.** A binding can name a bit-field, which no reference can, because the binding is not a reference. `auto& [flags] = s;` followed by `flags = 2;` writes the bit-field `s.flags`.

**Lambda capture.** In C++17 a structured binding could not be captured by a lambda at all, because it is not a variable. C++20 allows capturing bindings both by copy and by reference, although a binding that names a bit-field still cannot be captured by reference. GCC already accepted such captures in C++17 mode as an extension, while older Clang releases rejected them in every mode.

```cpp
#include <utility>

int demo() {
  auto [a, b] = std::pair{1, 2};
  return [a, &b] { return a + b; }();   // OK since C++20
}
```

C++20 also allowed the `static` and `thread_local` specifiers on a structured binding declaration. `constexpr`, `inline` and `extern` were still not permitted in C++23.

## Lifetime through bindings

Lifetime extension works through `e`. When `e` is a reference bound directly to a temporary, as in `const auto& [a, b] = make();` or `auto&& [a, b] = make();`, the temporary lives as long as `e`, which is the end of the enclosing scope. The names never dangle in that case.

```cpp
#include <cstdio>
#include <utility>

struct Noisy { ~Noisy() { std::puts("~Noisy"); } };
std::pair<Noisy, int> make() { return {}; }

void demo() {
  {
    const auto& [n, i] = make();
    std::puts("body");        // prints before ~Noisy: the pair is still alive
    (void)n; (void)i;
  }                           // ~Noisy here, when e goes out of scope
}
```

The usual limits of lifetime extension still apply. If the initializer is a function call that returns a reference into a temporary, such as a member function that returns `*this` by reference called on a prvalue, then `e` binds to the returned reference, no temporary is bound directly, and the bindings dangle at the end of the full-expression. The rules are the subject of reference-binding-and-temporaries.

## Writing a tuple-like type

To opt a type into the tuple protocol, specialize `std::tuple_size` and `std::tuple_element`, and provide `get<I>` either as a member function template or as a free function template that argument-dependent lookup can find. Free `get` must be in the type's own namespace; a `get` declared elsewhere and visible only through ordinary lookup is not considered.

```cpp
#include <cstddef>
#include <utility>

namespace geo {
struct Pt { int x, y; };
template <std::size_t I> int get(const Pt& p) { return I == 0 ? p.x : p.y; }
}

template <> struct std::tuple_size<geo::Pt> : std::integral_constant<std::size_t, 2> {};
template <std::size_t I> struct std::tuple_element<I, geo::Pt> { using type = int; };

int demo() { auto [a, b] = geo::Pt{3, 4}; return a * b; }   // 12, via geo::get
```

The hidden variable is passed to `get` as an lvalue when `e` is an lvalue reference and as an xvalue otherwise, so a `get` overload set that distinguishes `&` and `&&` can move elements out of a by-value `e`. `std::tuple_element` should be specialized for the unqualified type; the standard library provides the partial specializations for `const E` that make `const auto [a, b]` work.

> **Standardese.** [dcl.struct.bind] says the member `get` is used when class member access lookup for `get` in `E` finds at least one function template whose first template parameter is a non-type parameter. Otherwise `get<i>(e)` is used with `get` looked up by argument-dependent lookup only.

## C++26 additions

C++26 extends the syntax in four ways. GCC 16 implements all of them in `-std=c++26` mode.

- **Attributes on individual bindings** (P0609): `auto [a, b [[maybe_unused]]] = f();`.
- **Structured binding as a condition** (P0963): `if (auto [ok, value] = parse(s))`. The condition is `e` contextually converted to `bool`, and that test is performed before the bindings are initialized, so a tuple-like type's `get` is not called before the check.
- **Binding packs** (P1061): one name may be preceded by `...` to introduce a pack, as in `auto [head, ...tail] = t;`. A pack may only be introduced inside a template, and it can be empty.
- **`constexpr` and `constinit`** (P2686) are now allowed on the declaration, subject to the usual constant-initialization rules.

```cpp
#include <tuple>

template <class T>
int sum_all(const T& t) {
  auto [...xs] = t;          // C++26: xs is a pack of all the elements
  return (0 + ... + xs);
}

int demo() { return sum_all(std::tuple{1, 2, 3}); }   // 6
```

The placeholder name `_`, which can be repeated in one declaration since C++26, also works in structured bindings and is described with the other C++26 language changes.

## What to remember

- A structured binding declaration declares one hidden variable `e`; the names refer into it.
- `auto`, `const`, `&` and `&&` apply to `e`. `auto` copies, `auto&` aliases an lvalue, `const auto&` and `auto&&` bind anything.
- The protocol is chosen in order: array, then tuple-like if `std::tuple_size<E>` is complete, then public or accessible data members.
- The tuple protocol prefers a member `get` template and otherwise uses ADL-only `get<i>(e)`.
- `decltype(name)` gives the referenced type, such as `int` for a `std::pair<int, int>` binding even with `auto&`.
- `auto [a, b] = std::tie(x, y);` still aliases `x` and `y`.
- Bindings can name bit-fields and, since C++20, can be captured by lambdas.
- A reference `e` bound directly to a temporary extends its lifetime; a reference returned from a function does not.
- C++26 adds per-binding attributes, bindings as conditions, packs inside templates, and `constexpr`.

## Concept Map Outline

- **Structured bindings:** One hidden variable e is initialized from the expression; the names refer into it.
  - **The hidden variable e:** Specifiers and ref-qualifiers you write declare e, not the names.
    - **auto:** e is a copy of the initializer, so writes through the names do not reach the source.
    - **auto&:** e aliases an lvalue; it cannot bind to a prvalue.
    - **const auto& and auto&&:** e binds to anything, including temporaries, without copying.
    - **Array exception:** Without a reference, an array initializer is copied element by element into an array e.
  - **Three protocols:** Chosen in order from E, the type of e without references.
    - **Array:** Names refer to elements; their count must equal the bound.
    - **Tuple-like:** Used whenever std::tuple_size<E> is complete with a value member.
    - **Data members:** All non-static members, accessible at the declaration since C++20, in one class.
  - **Names, not variables:** A binding is an alias with its own rules.
    - **decltype:** Gives the referenced type: int for a pair<int, int> binding even with auto&.
    - **std::tie:** Element types are references, so plain auto still aliases the tied variables.
    - **Bit-fields:** A binding can name a bit-field, which no reference can.
    - **Lambda capture:** Forbidden in C++17, allowed in C++20; bit-field bindings cannot be captured by reference.
    - **Specifiers:** static and thread_local since C++20; constexpr only from C++26; never inline.
  - **Lifetime:** Extension works through e, not through the names.
    - **Direct binding extends:** const auto& [a, b] = make(); keeps the temporary alive to scope end.
    - **Returned references dangle:** If the initializer returns a reference into a temporary, nothing is extended.
  - **Tuple protocol:** Specialize tuple_size and tuple_element and provide get.
    - **Member get first:** Used if member lookup finds a get template whose first parameter is a non-type parameter.
    - **ADL-only free get:** Otherwise get<i>(e) is found only by argument-dependent lookup.
    - **Value category of e:** e is passed as an lvalue if it is an lvalue reference, else as an xvalue.
  - **C++26 additions:** Implemented by GCC 16 in -std=c++26 mode.
    - **Per-binding attributes:** auto [a, b [[maybe_unused]]] = f(); attaches an attribute to one name.
    - **As a condition:** if (auto [ok, v] = f()) tests e as bool before the bindings are initialized.
    - **Binding packs:** auto [h, ...t] = x; introduces a possibly empty pack, only inside templates.

## Standardese Quiz Questions

### Question 1 [warmup] ([dcl.struct.bind])

What does this program print?

```cpp
#include <cstdio>
#include <utility>

struct S { int v = 1; };

int main() {
  std::pair<S, int> p;
  auto [a, b] = p;
  a.v = 5;
  std::printf("%d\n", p.first.v);
  auto& [c, d] = p;
  c.v = 7;
  std::printf("%d\n", p.first.v);
}
```

A. `5`, then `7`
B. `1`, then `7`
C. `1`, then `1`
D. `5`, then `5`

**Answer (B):** `1`, then `7`

**Why:** `auto [a, b] = p;` declares a hidden variable `auto e = p;`, which is a copy, and `a` names `e.first`, so the write does not reach `p`. With `auto&`, the hidden variable is a reference to `p`, so `c` names `p.first` and the second write is visible. The first option assumes bindings always alias the initializer, which is only true when the hidden variable is a reference.

### Question 2 [warmup] ([dcl.struct.bind], [dcl.init.ref])

Is this program well-formed?

```cpp
#include <utility>

std::pair<int, int> make() { return {1, 2}; }

int main() {
  auto& [a, b] = make();
  return a + b;
}
```

A. Well-formed: structured bindings always extend the lifetime of the initializer
B. Well-formed, but `a` and `b` dangle after the declaration
C. Ill-formed: the hidden variable is a non-const lvalue reference initialized from a prvalue
D. Ill-formed: structured bindings cannot have a reference qualifier

**Answer (C):** Ill-formed: the hidden variable is a non-const lvalue reference initialized from a prvalue

**Why:** The declaration introduces `auto& e = make();`, and a non-const lvalue reference cannot bind to a prvalue, so the program is ill-formed. Lifetime extension would apply if the binding were allowed, which is why `const auto&` and `auto&&` work. Reference qualifiers on structured bindings are perfectly legal.

### Question 3 [warmup] ([dcl.struct.bind], [class.access])

Is this program well-formed?

```cpp
class P {
  int x = 1;
public:
  int y = 2;
};

int main() {
  auto [a, b] = P{};
  return a + b;
}
```

A. Ill-formed: `x` is not accessible in `main`
B. Well-formed: only public members are bound, so `a` is `y`
C. Ill-formed, but only because `P` is not an aggregate
D. Well-formed: structured bindings ignore access control

**Answer (A):** Ill-formed: `x` is not accessible in `main`

**Why:** With no `std::tuple_size` specialization, the names bind to all non-static data members of `P` in declaration order, and every one of them must be accessible at the point of the declaration. `x` is private and `main` is not a friend, so the program is ill-formed. Private members are not skipped, and aggregate status is irrelevant: binding to members does not use aggregate initialization.

### Question 4 [tricky] ([dcl.type.decltype], [dcl.struct.bind])

What is `decltype(a)` after this declaration?

```cpp
#include <utility>

std::pair<int, int> p{1, 2};
auto& [a, b] = p;
```

A. `int&`
B. `const int&`
C. `int&&`
D. `int`

**Answer (D):** `int`

**Why:** `std::pair` uses the tuple protocol, and `decltype` of an unparenthesized structured binding is its referenced type, `std::tuple_element<0, std::pair<int, int>>::type`, which is `int`. The `&` makes the hidden variable a reference, but it does not change the referenced type. `int&` is what `decltype((a))` gives, because the parenthesized form uses the rule for lvalue expressions.

### Question 5 [tricky] ([dcl.struct.bind], [tuple.creation])

What does this program print?

```cpp
#include <cstdio>
#include <tuple>

int main() {
  int x = 1, y = 2;
  auto [a, b] = std::tie(x, y);
  a = 10;
  std::printf("%d %d\n", x, y);
}
```

A. `1 2`: plain `auto` copies, so `a` is independent
B. `10 2`
C. Nothing: ill-formed, because `std::tie` returns a prvalue
D. Nothing: undefined behavior, because the tuple is a destroyed temporary

**Answer (B):** `10 2`

**Why:** `std::tie(x, y)` returns `std::tuple<int&, int&>`, and `auto` makes the hidden variable a tuple of that type. It holds references to `x` and `y`, so `std::tuple_element<0, E>::type` is `int&` and `a` refers to `x` itself. `auto` produces a new tuple, not new ints, and since the hidden variable is an object rather than a reference to the temporary, nothing dangles.

### Question 6 [tricky] ([class.temporary], [dcl.struct.bind])

What does this program print?

```cpp
#include <cstdio>
#include <utility>

struct Noisy { ~Noisy() { std::puts("~Noisy"); } };
std::pair<Noisy, int> make() { return {}; }

int main() {
  {
    const auto& [n, i] = make();
    std::puts("body");
    (void)n; (void)i;
  }
  std::puts("after");
}
```

A. `~Noisy`, `body`, `after`: the temporary dies at the end of the declaration
B. `body`, `after`, `~Noisy`
C. `body`, `~Noisy`, `after`
D. Undefined behavior: `n` and `i` refer into a destroyed temporary

**Answer (C):** `body`, `~Noisy`, `after`

**Why:** The hidden variable is `const auto& e = make();`, a reference bound directly to the prvalue, so the temporary pair has its lifetime extended to that of `e`, the end of the inner block. `body` is printed while the pair is alive, then `~Noisy` at the closing brace, then `after`. The first and last options assume the bindings themselves would need to extend the lifetime; they do not, because `e` already does.

### Question 7 [standardese] ([dcl.struct.bind], [tuple.helper])

Both a member `get` and a free `get` exist. What does this program print?

```cpp
#include <cstddef>
#include <cstdio>
#include <utility>

namespace geo {
struct Pt {
  int x, y;
  template <std::size_t I> int get() const { std::puts("member"); return I == 0 ? x : y; }
};
template <std::size_t I> int get(const Pt& p) { std::puts("free"); return I == 0 ? p.x : p.y; }
}

template <> struct std::tuple_size<geo::Pt> : std::integral_constant<std::size_t, 2> {};
template <std::size_t I> struct std::tuple_element<I, geo::Pt> { using type = int; };

int main() {
  auto [a, b] = geo::Pt{3, 4};
  std::printf("%d %d\n", a, b);
}
```

A. `free`, `free`, `3 4`
B. Ill-formed: the call to `get` is ambiguous
C. `3 4` only: `Pt` is an aggregate, so its data members are bound directly
D. `member`, `member`, `3 4`

**Answer (D):** `member`, `member`, `3 4`

**Why:** Because `std::tuple_size<geo::Pt>` is complete, the tuple protocol is used, not direct member binding. [dcl.struct.bind] then uses `e.get<i>()` whenever member lookup for `get` finds a function template whose first template parameter is a non-type parameter, and only otherwise falls back to `get<i>(e)` found by argument-dependent lookup. The two are never put into one overload set, so there is no ambiguity, and the member is called once per binding.

### Question 8 [standardese] ([dcl.struct.bind])

In C++23, which of these structured binding declarations at block scope is well-formed?

A. `constexpr auto [a, b] = std::pair{1, 2};`
B. `static auto [a, b] = std::pair{1, 2};`
C. `inline auto [a, b] = std::pair{1, 2};`
D. `extern auto [a, b] = std::pair{1, 2};`

**Answer (B):** `static auto [a, b] = std::pair{1, 2};`

**Why:** C++20 allowed the storage class specifiers `static` and `thread_local` on structured binding declarations, alongside `auto` and cv-qualifiers. `constexpr` was not permitted until C++26 (P2686); GCC accepts it in C++23 mode only as an extension with a warning, and Clang rejects it. `inline` and `extern` are not allowed in any version.
