C++ Reference ยท Types and Language Concepts
Overload resolution in C++
Concept page on C++ overload resolution: candidate and viable functions, conversion ranks, templates versus non-templates, ambiguity and tie-breakers.
When several functions share a name, the compiler must decide which one a call invokes. This is overload resolution. It happens at compile time, looks only at the static types and value categories of the arguments, and ignores the return type and the body of the functions.
The process has three steps. First, name lookup (including ADL) collects the candidate functions. Second, the compiler discards candidates that cannot take the given number or kinds of arguments, leaving the viable functions. Third, it ranks the viable functions by how good the conversion of each argument is and picks the best one. If there is no single best function, the call is ill-formed (ambiguous).
void show(int); void show(double); show(3); // show(int): exact match show(3.0f); // show(double): float -> double is a promotion
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
The next example shows how templates, references and const take part, and what the tie-breakers decide.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
The ranking
For each argument, the implicit conversion sequence to the parameter type falls in one of these ranks, best first:
- Exact match: identical types, lvalue-to-rvalue conversion, array-to-pointer or function-to-pointer decay, adding
const/volatilequalification at the top level of a reference. - Promotion:
char,short,booltoint;floattodouble; unscoped enum to its promoted integer type. - Conversion: any other standard conversion:
inttodouble,doubletoint,inttolong, derived pointer to base pointer, pointer tobool. - User-defined conversion: through a converting constructor or conversion operator.
- Ellipsis: passing to
...is the worst match.
A function is better than another if, for every argument, its conversion is not worse, and for at least one argument it is better. If neither function is better, the tie-breakers apply in this order:
- a non-template beats a template specialization;
- a more specialized template beats a less specialized one (partial ordering);
- for template functions, a function with a satisfied constraint that is more constrained beats a less constrained one (C++20 concepts);
- binding an rvalue to
T&&beatsconst T&, andT&to a non-constlvalue beatsconst T&.
Among viable functions with equal conversions, still no winner means a diagnostic such as "call of overloaded 'take(int)' is ambiguous".
An ambiguous call, which is an error and therefore shown read-only:
void take(long); void take(double); take(5); // error: both int -> long and int -> double are conversions take(5L); // fine: exact match
Usage notes
- Ambiguity is the common failure. With
void take(long); void take(double);, the calltake(5)convertsinttolongandinttodouble, two conversions of the same rank, so the call does not compile. Cast the argument (take(5L)) or add anintoverload. - The return type never participates. You cannot overload on return type alone.
constmember functions overload on the implicit object: aconstobject only sees theconstoverload, a non-constobject prefers the non-constone.- Default arguments count as overloads of a sort:
void f(int, int = 0)andvoid f(int)together makef(1)ambiguous. - Brace initialization of a parameter,
f({1, 2}), uses list-initialization rules and prefersstd::initializer_listconstructors, which can be surprising. - Name hiding: a function declared in an inner scope hides outer functions of the same name, so they never become candidates. A
usingdeclaration brings them back. - Narrowing conversions are not a rank-based problem in overload resolution, but they make list-initialization of the chosen function's argument ill-formed.
- Deleted functions take part:
void f(double) = delete;is chosen and then rejected, which is a way to forbid an unwanted implicit conversion. See= defaultand= delete.