# Class template argument deduction

> Since C++17 you can name a class template without arguments and let the initializer decide them. The compiler turns every constructor and deduction guide into a fictional function template, runs overload resolution against them, and uses the winner's return type; the surprises come from which fictional function wins.

- **Source:** C++ Atlas (https://cppatlas.com/topics/class-template-argument-deduction)
- **Track:** Templates
- **Estimated reading time:** 13 minutes
- **ISO C++ clauses:** [over.match.class.deduct] (https://eel.is/c++draft/over.match.class.deduct), [temp.deduct.guide] (https://eel.is/c++draft/temp.deduct.guide), [dcl.type.class.deduct] (https://eel.is/c++draft/dcl.type.class.deduct), [over.match.best] (https://eel.is/c++draft/over.match.best), [over.match.list] (https://eel.is/c++draft/over.match.list), [temp.deduct.call] (https://eel.is/c++draft/temp.deduct.call), [dcl.init.aggr] (https://eel.is/c++draft/dcl.init.aggr)
- **cppreference links:** [Class template argument deduction (CTAD)](https://en.cppreference.com/w/cpp/language/class_template_argument_deduction), [Deduction guides for std::vector](https://en.cppreference.com/w/cpp/container/vector/deduction_guides), [Deduction guides for std::pair](https://en.cppreference.com/w/cpp/utility/pair/deduction_guides), [Aggregate initialization](https://en.cppreference.com/w/cpp/language/aggregate_initialization)
- **Prerequisites:** template-argument-deduction, initialization-forms, overload-resolution

## The one idea

When a declaration names a class template without an argument list, as in `std::pair p(1, 2.0);`, the compiler has to invent the arguments. It does so with machinery you already know. Every constructor of the primary template, and every deduction guide, becomes a fictional function template whose return type is the class specialization it would produce. The initializer is treated as the argument list of a call to that overload set. Ordinary template argument deduction and overload resolution pick one candidate, and its return type is the type of the variable.

Only then does real initialization happen, using the real constructors of the deduced type. Deduction chooses a type; it does not choose the constructor that runs.

> **Mental model.** CTAD is overload resolution over a set of imaginary factory functions, one per constructor plus one per guide plus a copy candidate. If you can predict which imaginary factory wins, you can predict the type.

## Implicit guides from constructors

For each constructor of the primary template, [over.match.class.deduct] forms a function template whose template parameters are the class's parameters followed by the constructor's own, whose function parameters are the constructor's, and whose return type is the class specialization. Constructors of partial or explicit specializations are not used. If the class declares no constructors, a hypothetical default constructor is used instead, which is how `template <class T = int> struct X {}; X x;` deduces `X<int>`.

```cpp
template <class T>
struct Pt {
  T x, y;
  Pt(T a, T b) : x(a), y(b) {}   // implicit guide: template <class T> Pt(T, T) -> Pt<T>
};

Pt p(1, 2);         // Pt<int>
auto r = Pt(3, 4);  // functional cast: also Pt<int>
// Pt q(1, 2.0);    // error: T deduced as both int and double
```

Because the implicit guides take parameters by the same types as the constructors, they inherit the constructors' deduction behaviour. One rule is deliberately different: a constructor parameter `T&&` where `T` is a class template parameter is not a forwarding reference during CTAD. With `Holder(T&&)` as the only constructor, `Holder h(i);` for an lvalue `i` deduces `T = int` and then fails to bind `int&&` to `i`. The forwarding-references topic explains the rule this exclusion switches off.

## User-defined deduction guides

When constructors do not carry enough information, you write a guide. It looks like a function declaration with a trailing return type and the class template's name in place of a function name. It must be declared in the same scope as the class template, it has no body, and it can be a template or not.

```cpp
#include <iterator>
#include <string>
#include <vector>

template <class T> struct Bag {
  std::vector<T> items;
  template <class It> Bag(It b, It e) : items(b, e) {}  // T is not deducible from It
};
template <class It>
Bag(It, It) -> Bag<typename std::iterator_traits<It>::value_type>;

template <class T> struct Name { T value; Name(T v) : value(v) {} };
Name(const char*) -> Name<std::string>;  // non-template guide

void demo() {
  int a[] = {1, 2, 3};
  Bag b(a, a + 3);  // Bag<int>
  Name n("Ada");    // Name<std::string>, not Name<const char*>
}
```

The standard library uses exactly this: `std::vector` has an iterator-pair guide, and `std::pair` has `pair(T1, T2) -> pair<T1, T2>`. Its parameters are by value, so arguments decay: `std::pair p{1, "hi"}` is `std::pair<int, const char*>`, not a pair holding an array.

A guide is also the repair for the `Holder(T&&)` problem from the previous section. A guide's template parameters are its own, not the class's, so in `template <class U> Holder(U&&) -> Holder<std::remove_cvref_t<U>>;` the parameter is a genuine forwarding reference, and an lvalue `int` deduces `Holder<int>`. The constructor that then runs must still accept an lvalue, so such classes usually pair the guide with a constructor template.

A guide only names the result. If it names a type whose constructors cannot accept the initializer, deduction succeeds and initialization then fails, with an error that points at a constructor rather than at the guide.

> **Standardese.** [over.match.best] adds CTAD-specific tiebreakers that apply only after conversion sequences and partial ordering fail to separate two candidates: a candidate generated from a user-defined guide beats one generated from a constructor, the copy deduction candidate beats other constructor-generated candidates, and one generated from a non-template constructor beats one from a constructor template.

## The copy deduction candidate: copying beats wrapping

Besides constructors and guides, the set always contains a copy deduction candidate, built from a hypothetical constructor `C(C)`: in effect `template <class T> C(C<T>) -> C<T>`. Given an existing `std::vector<int> other`, both of these are candidates for `std::vector v{other};`:

```text
initializer_list ctor:  vector(initializer_list<T>)  ->  T = vector<int>   (wraps)
copy deduction:         vector(vector<T>)            ->  T = int           (copies)
```

List-initialization normally tries initializer-list constructors first, which would make `v` a `std::vector<std::vector<int>>` of one element. C++17, through P0702, added a rule to stop that: when the braced list consists of a single element whose type is a specialization of the class template, or a class derived from one, the initializer-list phase is skipped. The copy deduction candidate then wins, and `v` is a copy.

```cpp
#include <type_traits>
#include <vector>

void demo() {
  std::vector<int> other{1, 2, 3};
  std::vector v{other};         // std::vector<int>: a copy of other
  std::vector w{other, other};  // std::vector<std::vector<int>>: two elements
  static_assert(std::is_same_v<decltype(v), std::vector<int>>);
  static_assert(std::is_same_v<decltype(w), std::vector<std::vector<int>>>);
}
```

The same rule applies to `std::optional o{opt};` and `std::tuple t{tup};`, which copy rather than nest. Generic code that wraps whatever it is given, such as `std::vector v{x};` for an arbitrary `x`, changes meaning when `x` happens to be a vector. Spell the type out in generic code.

> **Pitfall.** Adding one element to a braced list flips the result from "copy" to "container of containers". Code that builds `std::vector{a}` and `std::vector{a, b}` from the same kind of value gets two unrelated element types.

## Braces, parentheses and initializer lists

Apart from the single-element rule, CTAD follows normal initialization: with braces, initializer-list constructors get first claim. That turns an innocent iterator pair into a vector of iterators.

```cpp
#include <string>
#include <type_traits>
#include <vector>

void demo() {
  std::string s = "hello";
  std::vector a(s.begin(), s.end());  // std::vector<char>, five elements
  std::vector b{s.begin(), s.end()};  // std::vector<std::string::iterator>, two elements
  std::vector c(3, 1);                // std::vector<int>{1, 1, 1}
  std::vector d{3, 1};                // std::vector<int>{3, 1}
  static_assert(std::is_same_v<decltype(b), std::vector<std::string::iterator>>);
}
```

`explicit` matters too. Guides generated from `explicit` constructors are explicit, a user-defined guide can be declared `explicit`. In copy-initialization without braces, explicit candidates are not considered at all; in copy-list-initialization they are considered, and choosing one makes the program ill-formed. With `explicit Box(const char*) -> Box<std::string>;`, the direct-initialization `Box a("hi");` gives `Box<std::string>`, but `Box b = "hi";` ignores the guide and deduces `Box<const char*>` from the constructor.

## Aggregates, aliases and inherited constructors

C++20 extended CTAD in two directions, and C++23 in a third.

**Aggregates (C++20).** An aggregate class template has no constructors to generate guides from. For an aggregate, the compiler now forms an aggregate deduction candidate whose parameters are the element types matched to the initializer's elements. It works for braced initialization and for C++20 parenthesized aggregate initialization.

```cpp
template <class T> struct Agg { T a; T b; };

Agg x{1, 2};      // Agg<int> in C++20; ill-formed in C++17 without a guide
Agg y(1, 2);      // also Agg<int>, via parenthesized aggregate initialization
// Agg z{1, 2.0}; // error: T deduced as both int and double
```

`std::array` predates this and keeps its own guide, which requires all elements to have the same type.

**Alias templates (C++20).** Naming an alias template without arguments now deduces too. The compiler takes the guides of the aliased class template, deduces the alias's parameters from each guide's return type, and keeps the guides for which that works. Given `template <class T> using Vec = std::vector<T>;`, the declaration `Vec v{1, 2, 3};` deduces `std::vector<int>`. GCC and Clang both implement this.

**Inherited constructors (C++23).** P2582 makes constructors inherited with a using-declaration contribute guides to the derived class template. Given `template <class T> struct Derived : Base<T> { using Base<T>::Base; };`, the declaration `Derived d(42);` deduces `Derived<int>` from `Base(T)`. GCC implements this from version 14; Clang 21 does not yet, so portable code still needs explicit guides.

## What CTAD will not do

CTAD is all or nothing. `std::pair<int> p{1, 2.0};` is not "deduce the second argument": once an argument list is present, no deduction happens, and a `pair` with one argument is simply wrong. `Foo<> f;` is also not CTAD; it explicitly asks for all defaults. If you want to fix some arguments and deduce others, write a factory function or an alias template that fixes them.

CTAD is also limited to certain declarations. [dcl.type.class.deduct] allows a deduced class type in a variable declaration with an initializer, a functional cast, a `new` expression, and, since C++20, the type of a non-type template parameter. It is not allowed for non-static data members, even with a default member initializer, nor for function parameters or return types.

```cpp
#include <vector>

struct S {
  // std::vector v{1, 2};   // error: no CTAD for non-static data members
  std::vector<int> v{1, 2};
};
```

## What to remember

- CTAD is overload resolution over fictional functions: one per constructor of the primary template, one per guide, plus the copy deduction candidate.
- The winner only chooses the type; the real constructors of that type then perform initialization.
- A class template's `T&&` constructor parameter is not a forwarding reference during CTAD.
- Guides have no body, live in the class template's scope, may be non-templates, and may be `explicit`; `T x = init;` ignores explicit guides, and `T x = {init};` is ill-formed if one wins.
- A braced list with one element of the same template's type copies; `std::vector v{other}` is a copy, `std::vector v{other, other}` nests.
- With braces, initializer-list constructors win, so `std::vector{s.begin(), s.end()}` holds two iterators.
- C++20 added aggregate CTAD and alias template CTAD; C++23 added inherited constructors, which Clang 21 does not implement.
- No partial deduction, and no CTAD for data members or function parameters.

## Concept Map Outline

- **CTAD:** Overload resolution over fictional functions built from constructors and guides picks the class's template arguments.
  - **Implicit guides:** Each constructor of the primary template becomes a function template returning C<T...>.
    - **Primary template only:** Constructors of partial or explicit specializations are never used.
    - **No constructors:** A hypothetical C() is used, so default template arguments can deduce.
    - **T&& is not forwarding:** A class parameter's T&& in a constructor does not forward during CTAD.
    - **Type, not constructor:** The winner chooses the type; real constructors then initialize it.
  - **User-defined guides:** Declarations like Bag(It, It) -> Bag<value_type>, with no body.
    - **Same scope:** A guide must be declared in the scope of its class template.
    - **Non-template guides:** Name(const char*) -> Name<std::string> needs no template head.
    - **By-value decay:** pair(T1, T2) decays arrays, so pair{1, "hi"} holds const char*.
    - **Guides win ties:** After partial ordering, a user guide beats a constructor-generated candidate.
  - **Copy deduction:** A candidate from a hypothetical C(C) is always added to the set.
    - **Single element copies:** A one-element braced list of a C specialization skips the initializer-list phase.
    - **Two elements nest:** std::vector v{other, other} is a vector of vectors.
    - **Generic code trap:** std::vector{x} copies when x is a vector and wraps otherwise.
  - **Braces and explicit:** CTAD follows ordinary initialization rules once the candidates are formed.
    - **Iterator pairs:** std::vector{b, e} holds two iterators; std::vector(b, e) holds the elements.
    - **Explicit guides:** Ignored in T x = init; selecting one in T x = {init} is ill-formed.
  - **Later extensions:** C++20 and C++23 widened where guides come from.
    - **Aggregates (C++20):** An aggregate deduction candidate works with braces and parentheses.
    - **Alias templates (C++20):** The aliased template's guides are adapted to the alias's parameters.
    - **Inherited ctors (C++23):** P2582: using Base<T>::Base contributes guides; GCC 14+, not Clang 21.
  - **Limits:** Where and how much CTAD can deduce.
    - **All or nothing:** pair<int> p{1, 2.0} is an invalid template-id, not partial deduction.
    - **Allowed places:** Variables with initializers, functional casts, new, and C++20 NTTP types.
    - **Not allowed:** Non-static data members, function parameters and return types.

## Standardese Quiz Questions

### Question 1 [warmup] ([over.match.class.deduct], [over.match.list])

What does this program print?

```cpp
#include <cstdio>
#include <vector>

int main() {
  std::vector<int> other{1, 2, 3};
  std::vector v{other};
  std::printf("%zu\n", v.size());
}
```

A. `1`, because `v` is a `std::vector<std::vector<int>>`
B. `3`
C. Nothing: ill-formed, the deduction is ambiguous
D. `0`

**Answer (B):** `3`

**Why:** When a braced list has a single element whose type is a specialization of the class template being deduced, the initializer-list phase is skipped, so the copy deduction candidate `vector(vector<T>) -> vector<T>` wins with `T = int`. `v` is a copy of `other` with three elements. Wrapping was the result before P0702 fixed it for C++17, and it is what you get with two elements, `std::vector v{other, other}`.

### Question 2 [warmup] ([pairs.pair], [temp.deduct.call], [over.match.class.deduct])

What is the type of `p.second`?

```cpp
#include <utility>

std::pair p{1, "hi"};
```

A. `const char[3]`
B. `std::string`
C. `const char (&)[3]`
D. `const char*`

**Answer (D):** `const char*`

**Why:** `std::pair` has the deduction guide `pair(T1, T2) -> pair<T1, T2>`, which takes its parameters by value. Deducing a by-value parameter from an array argument decays it, so `T2` is `const char*` and `p` is `std::pair<int, const char*>`. An array type is tempting because the constructor taking `const T2&` would preserve it, but the guide is what decides the type here.

### Question 3 [warmup] ([dcl.type.class.deduct], [temp.arg])

Is this declaration well-formed?

```cpp
#include <utility>

std::pair<int> p{1, 2.0};
```

A. Ill-formed: `std::pair` needs two template arguments, and CTAD is all or nothing
B. Well-formed: `p` is `std::pair<int, double>`
C. Well-formed: `p` is `std::pair<int, int>`, and 2.0 is narrowed
D. Ill-formed only because of narrowing

**Answer (A):** Ill-formed: `std::pair` needs two template arguments, and CTAD is all or nothing

**Why:** Class template argument deduction happens only when the template name appears with no argument list at all. Once `<int>` is written, the name refers to `std::pair<int>`, which is an invalid template-id because the second parameter has no default. There is no partial deduction; use `std::pair<int, double>`, `std::pair p{1, 2.0}`, or a factory function.

### Question 4 [tricky] ([over.match.class.deduct], [over.match.list], [vector.overview])

What does this program print?

```cpp
#include <cstdio>
#include <string>
#include <vector>

int main() {
  std::string s = "hello";
  std::vector v{s.begin(), s.end()};
  std::vector w(s.begin(), s.end());
  std::printf("%zu %zu\n", v.size(), w.size());
}
```

A. `5 5`
B. `2 2`
C. `2 5`
D. Nothing: `v` is ill-formed because iterators are not characters

**Answer (C):** `2 5`

**Why:** With braces, initializer-list constructors are tried first, so `std::vector(std::initializer_list<T>)` deduces `T = std::string::iterator`, and `v` holds the two iterators. The single-element copy rule does not apply because there are two elements. With parentheses there is no initializer-list phase, and the iterator-pair guide deduces `std::vector<char>` with five characters.

### Question 5 [tricky] ([temp.deduct.call], [over.match.class.deduct])

Is this program well-formed?

```cpp
template <class T>
struct Holder {
  Holder(T&&) {}
};

int main() {
  int i = 0;
  Holder h(i);
}
```

A. Well-formed: `T&&` is a forwarding reference, so `h` is `Holder<int&>`
B. Ill-formed: `T&&` names a class template parameter, so it is not a forwarding reference and cannot bind `i`
C. Well-formed: `h` is `Holder<int>`, initialized from a copy of `i`
D. Ill-formed: a class template cannot be deduced from a reference parameter

**Answer (B):** Ill-formed: `T&&` names a class template parameter, so it is not a forwarding reference and cannot bind `i`

**Why:** The implicit guide is `template <class T> Holder(T&&) -> Holder<T>`, but [temp.deduct.call] excludes a class template parameter from being a forwarding reference during CTAD. So `T` deduces as `int` from the lvalue, the guide's parameter is `int&&`, and it cannot bind to `i`. Without this rule `Holder<int&>` would be deduced, which is the tempting answer and would usually not be what the class author meant. A user-defined guide with its own `template <class U> Holder(U&&)` parameter does forward.

### Question 6 [tricky] ([over.match.class.deduct], [temp.deduct.guide], [over.match.copy])

What is the type of `b`?

```cpp
#include <string>

template <class T> struct Box { Box(T) {} };
explicit Box(const char*) -> Box<std::string>;

Box a("hi");
Box b = "hi";
```

A. `Box<std::string>`, the same as `a`
B. `Box<const char*>`
C. `Box<const char[3]>`
D. Ill-formed: an explicit guide cannot be used in copy-initialization

**Answer (B):** `Box<const char*>`

**Why:** In copy-initialization that is not list-initialization, explicit candidates are not considered, so the guide is ignored for `b`. That leaves the implicit guide from `Box(T)`, which takes `T` by value and decays the array: `Box<const char*>`. For the direct-initialization of `a`, the guide and the constructor's implicit guide match equally well, and the tie goes to the guide, which is both user-defined and a non-template, so `a` is `Box<std::string>`. Only copy-list-initialization, `Box c = {"hi"};`, would be ill-formed, because there an explicit candidate is considered and then rejected.

### Question 7 [standardese] ([over.match.class.deduct], [dcl.init.aggr])

In C++20, which of these declarations are well-formed?

```cpp
template <class T> struct Agg { T a; T b; };

Agg x{1, 2};     // #1
Agg y(1, 2);     // #2
Agg z{1, 2.0};   // #3
```

A. None: an aggregate needs a user-defined deduction guide
B. Only #1
C. All three, with `z` deduced as `Agg<double>`
D. #1 and #2

**Answer (D):** #1 and #2

**Why:** C++20 adds an aggregate deduction candidate formed from the aggregate's element types and the initializer's elements, used for braced and for parenthesized aggregate initialization, so #1 and #2 deduce `Agg<int>`. In #3 the candidate is `template <class T> Agg(T, T)`, and deducing `T` from `int` and `double` conflicts, so deduction fails and #3 is ill-formed; no common type is computed. "None" is the C++17 answer, when aggregates needed explicit guides.

### Question 8 [standardese] ([dcl.type.class.deduct])

Is this class definition well-formed?

```cpp
#include <vector>

struct S {
  std::vector v{1, 2};
};
```

A. Well-formed: `v` is `std::vector<int>`
B. Well-formed: `v` is `std::vector<std::initializer_list<int>>`
C. Ill-formed: a deduced class type cannot be the type of a non-static data member
D. Ill-formed: a default member initializer cannot use braces with CTAD, but `= {1, 2}` would work

**Answer (C):** Ill-formed: a deduced class type cannot be the type of a non-static data member

**Why:** [dcl.type.class.deduct] allows a placeholder for a deduced class type only in an initializing declaration of a variable, a functional cast, a `new` expression, and the type of a non-type template parameter. A non-static data member is none of these, whatever form its default member initializer takes, so you must write `std::vector<int>`. A `static inline` data member is a variable, so CTAD would work there.
