What are template deduction guides and when should we use them?

Question

The C++17 standard introduces "template deduction guides". I gather they're something to do with the new template argument deduction for constructors introduced in this version of the standard, but I haven't yet seen a simple, FAQ-style explanation of what they are and what they're for.

• What are template deduction guides in C++17?

• Why (and when) do we need them?

• How do I declare them?

Solution

Template deduction guides are patterns associated with a template class that tell the compiler how to translate a set of constructor arguments (and their types) into template parameters for the class.

The simplest example is that of std::vector and its constructor that takes an iterator pair.

template<typename Iterator>
void func(Iterator first, Iterator last)
{
  vector v(first, last);
}

The compiler needs to figure out what vector<T>'s T type will be. We know what the answer is; T should be typename std::iterator_traits<Iterator>::value_type. But how do we tell the compiler without having to type vector<typename std::iterator_traits<Iterator>::value_type>?

You use a deduction guide:

template<typename Iterator> vector(Iterator b, Iterator e) -> 
    vector<typename std::iterator_traits<Iterator>::value_type>;

This tells the compiler that, when you call a vector constructor matching that pattern, it will deduce the vector specialization using the code on the right of ->.

You need guides when the deduction of the type from the arguments is not based on the type of one of those arguments. Initializing a vector from an initializer_list explicitly uses the vector's T, so it doesn't need a guide.

The left side doesn't necessarily specify an actual constructor. The way it works is that, if you use template constructor deduction on a type, it matches the arguments you pass against all deduction guides (actual constructors of the primary template provide implicit guides). If there is a match, it uses that to determine which template arguments to provide to the type.

But once that deduction is done, once the compiler figures out the template parameters for the type, initialization for the object of that type proceeds as if none of that happened. That is, the deduction guide selected does not have to match the constructor selected.

This also means that you can use guides with aggregates and aggregate initialization:

template<typename T>
struct Thingy
{
  T t;
};

Thingy(const char *) -> Thingy<std::string>;

Thingy thing{"A String"}; //thing.t is a `std::string`.

So deduction guides are only used to figure out the type being initialized. The actual process of initialization works exactly as it did before, once that determination has been made.

Comments

[doug]

en.cppreference.com/w/cpp/language/class_template_deduction

[Quuxplusone]

In particular, I'd be interested to know whether any deduction guides are actually provided by the C++17 STL (e.g. for std::pair or std::tuple). What's the complete list of "deducible" standard template types as of C++17?

[Cubbi]

@Quuxplusone en.cppreference.com/w/cpp/utility/pair/deduction_guides and en.cppreference.com/w/cpp/utility/tuple/deduction_guides

[Jean-Simon Brochu]

I'd be interested to know if any compiler supports this. I tried gcc, clang and vc++. rextester.com/DHPHC32332 Nevermind, I found it works only with gc++ 8.1 C++17 and 2a g++ -std=c++17 -O2 -Wall -pedantic -pthread main.cpp && ./a.out

[T.C.]

Hmm, it just occurred to me that even with the guide, vector v{first, last}; won't do the right thing :(

[Arne Vogel]

@T.C. … unless the right thing is making a vector of iterators. And std::string{32,'*'}[0] == ' ' (for ASCII). But this has all been true since C++11.

[gnzlbg]

what happens with the allocator vector parameter ? what would happend if the allocator vector parameter wouldn't have a default argument? (you cannot deduce it from InputIterator)

[user541686]

@NicolBolas: Would you mind explaining the details of how implicit and explicit deduction guides can work in the context of partially or fully specialized classes (whose constructors clearly need don't have to have parameter types matching those of the primary template)? It's hard to find information on this through a quick search.

[Nicol Bolas]

@Mehrdad: The only caveat where specialization matters is that implicit guides are only generated from the primary template's constructors, not from specializations. Beyond that, specialization is irrelevant to the rules of class deduction. But since this question is about explicit deduction guides, that's kind of off-topic.

[user541686]

@NicolBolas: I see. It's not clear to me that the question is about explicit deduction guides at all... I think it's helpful if you just include what you literally wrote in this comment.