{"id":20937,"date":"2018-10-11T14:33:39","date_gmt":"2018-10-11T14:33:39","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/vcblog\/?p=20937"},"modified":"2019-02-18T17:47:38","modified_gmt":"2019-02-18T17:47:38","slug":"how-to-use-class-template-argument-deduction","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/how-to-use-class-template-argument-deduction\/","title":{"rendered":"How to Use Class Template Argument Deduction"},"content":{"rendered":"

Class Template Argument Deduction (CTAD) is a C++17 Core Language feature that reduces code verbosity. C++17’s Standard Library also supports CTAD, so after upgrading your toolset, you can take advantage of this new feature when using STL types like std::pair and std::vector. Class templates in other libraries and your own code will partially benefit from CTAD automatically, but sometimes they’ll need a bit of new code (deduction guides) to fully benefit. Fortunately, both using CTAD and providing deduction guides is pretty easy, despite template metaprogramming’s fearsome reputation!\n<\/span><\/p>\n

CTAD support is available in VS 2017 15.7 and later with the \/std:c++17 and \/std:c++latest<\/a> compiler options.\n<\/span><\/p>\n

Template Argument Deduction\n<\/strong><\/span><\/p>\n

C++98 through C++14 performed template argument deduction for function templates. Given a function template like template <typename RanIt> void sort(RanIt first, RanIt last);<\/code>, you can and should sort a std::vector<int><\/code> without explicitly specifying that RanIt<\/code> is std::vector<int>::iterator<\/code>. When the compiler sees sort(v.begin(), v.end());<\/code>, it knows what the types of v.begin()<\/code> and v.end()<\/code> are, so it can determine what RanIt<\/code> should be. The process of determining template arguments for template parameters (by comparing the types of function arguments to function parameters, according to rules in the Standard) is known as template argument deduction, which makes function templates far more usable than they would otherwise be.\n<\/span><\/p>\n

However, class templates didn’t benefit from these rules. If you wanted to construct a std::pair<\/code> from two int<\/code>s, you had to say std::pair<int, int> p(11, 22);<\/code>, despite the fact that the compiler already knows that the types of 11<\/code> and 22<\/code> are int<\/code>. The workaround for this limitation was to use function template argument deduction: std::make_pair(11, 22)<\/code> returns std::pair<int, int><\/code>. Like most workarounds, this is problematic for a few reasons: defining such helper functions often involves template metaprogramming (std::make_pair()<\/code> needs to perform perfect forwarding and decay, among other things), compiler throughput is reduced (as the front-end has to instantiate the helper, and the back-end has to optimize it away), debugging is more annoying (as you have to step through helper functions), and there’s still a verbosity cost (the extra make_<\/code> prefix, and if you want a local variable instead of a temporary, you need to say auto<\/code>).\n<\/span><\/p>\n

Hello, CTAD World\n<\/strong><\/span><\/p>\n

C++17 extends template argument deduction to the construction of an object given only the name of a class template. Now, you can say std::pair(11, 22)<\/code> and this is equivalent to std::pair<int, int>(11, 22)<\/code>. Here’s a full example, with a C++17 terse static_assert<\/code> verifying that the declared type of p<\/code> is the same as std::pair<int, const char *><\/code>:<\/span><\/p>\n

C:\\Temp>type meow.cpp\r\n#include <type_traits>\r\n#include <utility>\r\nint main() {\r\n    std::pair p(1729, \"taxicab\");\r\n    static_assert(std::is_same_v<decltype(p), std::pair<int, const char *>>);\r\n}\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 meow.cpp\r\nmeow.cpp\r\nC:\\Temp><\/pre>\n
CTAD works with parentheses and braces, and named variables and nameless temporaries.\n<\/span><\/p>\n
Another Example: array and greater<\/strong><\/span><\/p>\n
C:\\Temp>type arr.cpp\r\n#include <algorithm>\r\n#include <array>\r\n#include <functional>\r\n#include <iostream>\r\n#include <string_view>\r\n#include <type_traits>\r\nusing namespace std;\r\nint main() {\r\n    array arr = { \"lion\"sv, \"direwolf\"sv, \"stag\"sv, \"dragon\"sv };\r\n    static_assert(is_same_v<decltype(arr), array<string_view, 4>>);\r\n    sort(arr.begin(), arr.end(), greater{});\r\n    cout << arr.size() << \": \";\r\n    for (const auto& e : arr) {\r\n        cout << e << \" \";\r\n    }\r\n    cout << \"\\n\";\r\n}\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 arr.cpp && arr\r\narr.cpp\r\n4: stag lion dragon direwolf<\/pre>\n
This demonstrates a couple of neat things. First, CTAD for std::array<\/code> deduces both its element type and its size. Second, CTAD works with default template arguments; greater{}<\/code> constructs an object of type greater<void><\/code> because it’s declared as template <typename T = void> struct greater;<\/code>.\n<\/span><\/p>\n
CTAD for Your Own Types<\/strong><\/span><\/p>\n
C:\\Temp>type mypair.cpp\r\n#include <type_traits>\r\ntemplate <typename A, typename B> struct MyPair {\r\n    MyPair() { }\r\n    MyPair(const A&, const B&) { }\r\n};\r\nint main() {\r\n    MyPair mp{11, 22};\r\n    static_assert(std::is_same_v<decltype(mp), MyPair<int, int>>);\r\n}\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 mypair.cpp\r\nmypair.cpp\r\nC:\\Temp><\/pre>\n
In this case, CTAD automatically works for MyPair<\/code>. What happens is that the compiler sees that a MyPair<\/code> is being constructed, so it runs template argument deduction for MyPair<\/code>‘s constructors. Given the signature (const A&, const B&<\/code>) and the arguments of type int<\/code>, A<\/code> and B<\/code> are deduced to be int<\/code>, and those template arguments are used for the class and the constructor.\n<\/span><\/p>\n
However, MyPair{}<\/code> would emit a compiler error. That’s because the compiler would attempt to deduce A<\/code> and B<\/code>, but there are no constructor arguments and no default template arguments, so it can’t guess whether you want MyPair<int, int><\/code> or MyPair<Starship, Captain><\/code>.\n<\/span><\/p>\n
Deduction Guides\n<\/strong><\/span><\/p>\n
In general, CTAD automatically works when class templates have constructors whose signatures mention all of the class template parameters (like MyPair<\/code> above). However, sometimes constructors themselves are templated, which breaks the connection that CTAD relies on. In those cases, the author of the class template can provide “deduction guides” that tell the compiler how to deduce class template arguments from constructor arguments.<\/span><\/p>\n
C:\\Temp>type guides.cpp\r\n#include <iterator>\r\n#include <type_traits>\r\ntemplate <typename T> struct MyVec {\r\n    template <typename Iter> MyVec(Iter, Iter) { }\r\n};\r\ntemplate <typename Iter> MyVec(Iter, Iter) -> MyVec<typename std::iterator_traits<Iter>::value_type>;\r\ntemplate <typename A, typename B> struct MyAdvancedPair {\r\n    template <typename T, typename U> MyAdvancedPair(T&&, U&&) { }\r\n};\r\ntemplate <typename X, typename Y> MyAdvancedPair(X, Y) -> MyAdvancedPair<X, Y>;\r\nint main() {\r\n    int * ptr = nullptr;\r\n    MyVec v(ptr, ptr);\r\n    static_assert(std::is_same_v<decltype(v), MyVec<int>>);\r\n    MyAdvancedPair adv(1729, \"taxicab\");\r\n    static_assert(std::is_same_v<decltype(adv), MyAdvancedPair<int, const char *>>);\r\n}\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 guides.cpp\r\nguides.cpp\r\nC:\\Temp><\/pre>\n
Here are two of the most common cases for deduction guides in the STL: iterators and perfect forwarding. MyVec<\/code> resembles a std::vector<\/code> in that it’s templated on an element type T<\/code>, but it’s constructible from an iterator type Iter<\/code>. Calling the range constructor provides the type information we want, but the compiler can’t possibly realize the relationship between Iter<\/code> and T<\/code>. That’s where the deduction guide helps. After the class template definition, the syntax template <typename Iter> MyVec(Iter, Iter) -> MyVec<typename std::iterator_traits<Iter>::value_type>;<\/code> tells the compiler “when you’re running CTAD for MyVec<\/code>, attempt to perform template argument deduction for the signature MyVec(Iter, Iter)<\/code>. If that succeeds, the type you want to construct is MyVec<typename std::iterator_traits<Iter>::value_type><\/code>. That essentially dereferences the iterator type to get the element type we want.\n<\/span><\/p>\n
The other case is perfect forwarding, where MyAdvancedPair<\/code> has a perfect forwarding constructor like std::pair<\/code> does. Again, the compiler sees that A<\/code> and B<\/code> versus T<\/code> and U<\/code> are different types, and it doesn’t know the relationship between them. In this case, the transformation we need to apply is different: we want decay<\/code> (if you’re unfamiliar with decay<\/code>, you can skip this). Interestingly, we don’t need decay_t<\/code>, although we could use that type trait if we wanted extra verbosity. Instead, the deduction guide template <typename X, typename Y> MyAdvancedPair(X, Y) -> MyAdvancedPair<X, Y>;<\/code> is sufficient. This tells the compiler “when you’re running CTAD for MyAdvancedPair<\/code>, attempt to perform template argument deduction for the signature MyAdvancedPair(X, Y)<\/code>, as if it were taking arguments by value. Such deduction performs decay. If it succeeds, the type you want to construct is MyAdvancedPair<X, Y><\/code>.”\n<\/span><\/p>\n
This demonstrates a critical fact about CTAD and deduction guides. CTAD looks at a class template’s constructors, plus its deduction guides, in order to determine the type to construct. That deduction either succeeds (determining a unique type) or fails. Once the type to construct has been chosen, overload resolution to determine which constructor to call happens normally. CTAD doesn’t affect how the constructor is called.<\/strong> For MyAdvancedPair<\/code> (and std::pair<\/code>), the deduction guide’s signature (taking arguments by value, notionally) affects the type chosen by CTAD. Afterwards, overload resolution chooses the perfect forwarding constructor, which takes its arguments by perfect forwarding, exactly as if the class type had been written with explicit template arguments.\n<\/span><\/p>\n
CTAD and deduction guides are also non-intrusive. Adding deduction guides for a class template doesn’t affect existing code, which previously was required to provide explicit template arguments. That’s why we were able to add deduction guides for many STL types without breaking a single line of user code.\n<\/span><\/p>\n
Enforcement\n<\/strong><\/span><\/p>\n
In rare cases, you might want deduction guides to reject certain code. Here’s how std::array<\/code> does it:<\/span><\/p>\n
C:\\Temp>type enforce.cpp\r\n#include <stddef.h>\r\n#include <type_traits>\r\ntemplate <typename T, size_t N> struct MyArray {\r\n    T m_array[N];\r\n};\r\ntemplate <typename First, typename... Rest> struct EnforceSame {\r\n    static_assert(std::conjunction_v<std::is_same<First, Rest>...>);\r\n    using type = First;\r\n};\r\ntemplate <typename First, typename... Rest> MyArray(First, Rest...)\r\n    -> MyArray<typename EnforceSame<First, Rest...>::type, 1 + sizeof...(Rest)>;\r\nint main() {\r\n    MyArray a = { 11, 22, 33 };\r\n    static_assert(std::is_same_v<decltype(a), MyArray<int, 3>>);\r\n}\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 enforce.cpp\r\nenforce.cpp\r\nC:\\Temp><\/pre>\n
Like std::array<\/code>, MyArray<\/code> is an aggregate with no actual constructors, but CTAD still works for these class templates via deduction guides. MyArray<\/code>‘s guide performs template argument deduction for MyArray(First, Rest...)<\/code>, enforcing all of the types to be the same, and determining the array’s size from how many arguments there are.\n<\/span><\/p>\n
Similar techniques could be used to make CTAD entirely ill-formed for certain constructors, or all constructors. The STL itself hasn’t needed to do that explicitly, though. (There are only two classes where CTAD would be undesirable: unique_ptr<\/code> and shared_ptr<\/code>. C++17 supports both unique_ptrs<\/code> and shared_ptrs<\/code> to arrays, but both new T<\/code> and new T[N]<\/code> return T *<\/code>. Therefore, there’s insufficient information to safely deduce the type of a unique_ptr<\/code> or shared_ptr<\/code> being constructed from a raw pointer. As it happens, this is automatically blocked in the STL due to unique_ptr<\/code>‘s support for fancy pointers and shared_ptr<\/code>‘s support for type erasure, both of which change the constructor signatures in ways that prevent CTAD from working.)\n<\/span><\/p>\n
Corner Cases for Experts: Non-Deduced Contexts\n<\/strong><\/span><\/p>\n
Here are some advanced examples that aren’t meant to be imitated; instead, they’re meant to illustrate how CTAD works in complicated scenarios.\n<\/span><\/p>\n
Programmers who write function templates eventually learn about “non-deduced contexts”. For example, a function template taking typename Identity<T>::type<\/code> can’t deduce T<\/code> from that function argument. Now that CTAD exists, non-deduced contexts affect the constructors of class templates too.<\/span><\/p>\n
C:\\Temp>type corner1.cpp\r\ntemplate <typename X> struct Identity {\r\n    using type = X;\r\n};\r\ntemplate <typename T> struct Corner1 {\r\n    Corner1(typename Identity<T>::type, int) { }\r\n};\r\nint main() {\r\n    Corner1 corner1(3.14, 1729);\r\n}\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 corner1.cpp\r\ncorner1.cpp\r\ncorner1.cpp(10): error C2672: 'Corner1': no matching overloaded function found\r\ncorner1.cpp(10): error C2783: 'Corner1<T> Corner1(Identity<X>::type,int)': could not deduce template argument for 'T'\r\ncorner1.cpp(6): note: see declaration of 'Corner1'\r\ncorner1.cpp(10): error C2641: cannot deduce template argument for 'Corner1'\r\ncorner1.cpp(10): error C2514: 'Corner1': class has no constructors\r\ncorner1.cpp(5): note: see declaration of 'Corner1'<\/pre>\n
In corner1.cpp, typename Identity<T>::type<\/code> prevents the compiler from deducing that T<\/code> should be double<\/code>.\n<\/span><\/p>\n
Here’s a case where some but not all constructors mention T<\/code> in a non-deduced context:<\/span><\/p>\n
C:\\Temp>type corner2.cpp\r\ntemplate <typename X> struct Identity {\r\n    using type = X;\r\n};\r\ntemplate <typename T> struct Corner2 {\r\n    Corner2(T, long) { }\r\n    Corner2(typename Identity<T>::type, unsigned long) { }\r\n};\r\nint main() {\r\n    Corner2 corner2(3.14, 1729);\r\n}\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 corner2.cpp\r\ncorner2.cpp\r\ncorner2.cpp(11): error C2668: 'Corner2<double>::Corner2': ambiguous call to overloaded function\r\ncorner2.cpp(7): note: could be 'Corner2<double>::Corner2(double,unsigned long)'\r\ncorner2.cpp(6): note: or       'Corner2<double>::Corner2(T,long)'\r\n        with\r\n        [\r\n            T=double\r\n        ]\r\ncorner2.cpp(11): note: while trying to match the argument list '(double, int)'<\/pre>\n
In corner2.cpp, CTAD succeeds but constructor overload resolution fails. CTAD ignores the constructor taking (typename Identity<T>::type, unsigned long)<\/code> due to the non-deduced context, so CTAD uses only (T, long)<\/code> for deduction. Like any function template, comparing the parameters (T, long)<\/code> to the argument types double, int<\/code> deduces T<\/code> to be double<\/code>. (int is convertible to long<\/code>, which is sufficient for template argument deduction; it doesn’t demand an exact match there.) After CTAD has determined that Corner2<double><\/code> should be constructed, constructor overload resolution considers both signatures (double, long)<\/code> and (double, unsigned long)<\/code> after substitution, and those are ambiguous for the argument types double, int<\/code> (because int<\/code> is convertible to both long<\/code> and unsigned long<\/code>, and the Standard doesn’t prefer either conversion).\n<\/span><\/p>\n
Corner Cases for Experts: Deduction Guides Are Preferred<\/strong><\/span><\/p>\n
C:\\Temp>type corner3.cpp\r\n#include <type_traits>\r\ntemplate <typename T> struct Corner3 {\r\n    Corner3(T) { }\r\n    template <typename U> Corner3(U) { }\r\n};\r\n#ifdef WITH_GUIDE\r\n    template <typename X> Corner3(X) -> Corner3<X *>;\r\n#endif\r\nint main() {\r\n    Corner3 corner3(1729);\r\n#ifdef WITH_GUIDE\r\n    static_assert(std::is_same_v<decltype(corner3), Corner3<int *>>);\r\n#else\r\n    static_assert(std::is_same_v<decltype(corner3), Corner3<int>>);\r\n#endif\r\n}\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 corner3.cpp\r\ncorner3.cpp\r\nC:\\Temp>cl \/EHsc \/nologo \/W4 \/std:c++17 \/DWITH_GUIDE corner3.cpp\r\ncorner3.cpp\r\nC:\\Temp><\/pre>\n
CTAD works by performing template argument deduction and overload resolution for a set of deduction candidates (hypothetical function templates) that are generated from the class template’s constructors and deduction guides. In particular, this follows the usual rules for overload resolution with only a couple of additions. Overload resolution still prefers things that are more specialized (N4713 16.3.3 [over.match.best]\/1.7). When things are equally specialized, there’s a new tiebreaker: deduction guides are preferred (\/1.12).\n<\/span><\/p>\n
In corner3.cpp, without a deduction guide, the Corner3(T)<\/code> constructor is used for CTAD (whereas Corner3(U)<\/code> isn’t used for CTAD because it doesn’t mention T), and Corner3<int><\/code> is constructed. When the deduction guide is added, the signatures Corner3(T)<\/code> and Corner3(X)<\/code> are equally specialized, so paragraph \/1.12 steps in and prefers the deduction guide. This says to construct Corner3<int *><\/code> (which then calls Corner3(U)<\/code> with U = int<\/code>).\n<\/span><\/p>\n
Reporting Bugs\n<\/strong><\/span><\/p>\n
Please let us know what you think about VS. You can report bugs via the IDE’s Report A Problem and also via the web: go to the VS Developer Community<\/a> and click on the C++ tab.<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"
Class Template Argument Deduction (CTAD) is a C++17 Core Language feature that reduces code verbosity. C++17’s Standard Library also supports CTAD, so after upgrading your toolset, you can take advantage of this new feature when using STL types like std::pair and std::vector. Class templates in other libraries and your own code will partially benefit from […]<\/p>\n","protected":false},"author":266,"featured_media":35994,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[512],"tags":[],"class_list":["post-20937","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-general-cpp-series"],"acf":[],"blog_post_summary":"
Class Template Argument Deduction (CTAD) is a C++17 Core Language feature that reduces code verbosity. C++17’s Standard Library also supports CTAD, so after upgrading your toolset, you can take advantage of this new feature when using STL types like std::pair and std::vector. Class templates in other libraries and your own code will partially benefit from […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/20937","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/266"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=20937"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/20937\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/35994"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=20937"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=20937"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=20937"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}