function template overloading

Question

Can anybody summarize the idea of function template overloading? What matters, template parameter or function parameter? What about the return value?

For example, given a function template

template<typename X, typename Y> void func(X x, Y y) {} 

what's the overloaded function template?

1) template<typename X> void func(X x, int y) {} 2) template<typename X, typename Y> X func(X x, Y y) {} 3) template<class X, class Y, class Z> void func(X x, Y y, Z z) {} 

Answer 1

Of that list only the second introduces ambiguity, because functions - regardless of whether they are templates - can't be overloaded based on return type.

You can use the other two:

template<typename X> void func(X x, int y); 

will be used if the second argument of the call is an int, e.g func("string", 10);

template<class X, class Y, class Z> void func(X x, Y y, Z z); 

will be used if you call func with three arguments.

---

I don't understand why some other answers mentions that template functions and function overloading doesn't mix. They certainly do, and there are special rules how the function to call is selected.

14.5.5

A function template can be overloaded with other function templates and with normal (non-template) functions. A normal function is not related to a function template (i.e., it is never considered to be a specialization), even if it has the same name and type as a potentially generated function template specialization.)

A non-templated (or "less templated") overload is preferred to templates, e.g

template <class T> void foo(T); void foo(int);  foo(10); //calls void foo(int) foo(10u); //calls void foo(T) with T = unsigned 

Your first overload with one non-template parameter also falls under this rule.

Given choice between several templates, more specialized matches are preferred:

template <class T> void foo(T); template <class T> void foo(T*);  int i; int* p; int arr[10];  foo(i);  //calls first foo(p);   //calls second foo(arr); //calls second: array decays to pointer 

You can find a more formal description of all the rules in the same chapter of the standard (Function templates)

---

And finally there are some situations where two or more overloads would be ambiguous:

template <class T> void foo(T, int); template <class T> void foo(int, T);  foo(1, 2); 

Here the call is ambiguous, because both candidates are equally specialized.

You can disambiguate such situations with the use of (for example) boost::disable_if. For example, we can specify that when T = int, then the second overload shouldn't be included as an overload candidate:

#include <boost/utility/enable_if.hpp> #include <boost/type_traits/is_same.hpp> template <class T> void foo(T x, int i);  template <class T> typename boost::disable_if<boost::is_same<int, T> >::type foo(int i, T x);  foo(1, 2); //calls the first 

Here the library produces a "substitution failure" in the return type of the second overload, if T = int, removing it from the set of overload candidates.

In practice you should rarely run into situations like that.

Answer 2

There are two separate things here: function templating and function overloading. Any two distinct template declarations are likely to be overloads of each other, so your question doesn't quite make sense as stated. (The three "overloads" you give do not build upon the first template, rather you have four overloads to the same function name.) The real issue is, given some overloads and a call, how to call the desired overload?

First, the return type doesn't participate in the overloading process whether or not there is a template involved. So #2 will never play well with #1.

Second, the rules for function template overload resolution are different from the more commonly used class template specialization rules. Both essentially solve the same problem, but

• the rules for class templates are simpler and more powerful, allowing for example recursion, and (member) functions differing only by return type
• the rules for function templates allow the compiler to figure the template arguments from the function argument types

You might be able to solve your particular problem with function template overloads, but you may have trouble fixing any bug that arises as the rules are longer and fewer people are familiar with their intricacies. I was unaware after a few years of template hacking that subtle function template overloading was even possible. In libraries such as Boost and GCC's STL, an alternative approach is ubiquitous. Use a templated wrapper class:

template< typename X, typename Y > struct functor {     void operator()( X x, Y y ); }; template< typename X > // partial specialization:  struct functor< X, int > { // alternative to overloading for classes     void operator()( X x, int y ); }; 

Now you sacrifice the implicit instantiation syntax (with no angle brackets). If you want to get that back, you need another function

template< typename X, typename Y > void func( X x, Y y ) {     return functor< X, Y >()( x, y ); } 

I'd be interested to hear whether function overloading can do anything (besides deduction) that class [partial] specialization can't…

And then, of course, your overload #3 will never face ambiguity because it has a different number of arguments than any other overload.