Skip to content
Tutorials Center
My learning

Topics

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).

C++
void show(int);
void show(double);
show(3);        // show(int): exact match
show(3.0f);     // show(double): float -> double is a promotion

Try it

C++ Ranking conversions

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.

C++ Templates, references and const

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:

  1. Exact match: identical types, lvalue-to-rvalue conversion, array-to-pointer or function-to-pointer decay, adding const/volatile qualification at the top level of a reference.
  2. Promotion: char, short, bool to int; float to double; unscoped enum to its promoted integer type.
  3. Conversion: any other standard conversion: int to double, double to int, int to long, derived pointer to base pointer, pointer to bool.
  4. User-defined conversion: through a converting constructor or conversion operator.
  5. 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&& beats const T&, and T& to a non-const lvalue beats const 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:

C++
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 call take(5) converts int to long and int to double, two conversions of the same rank, so the call does not compile. Cast the argument (take(5L)) or add an int overload.
  • The return type never participates. You cannot overload on return type alone.
  • const member functions overload on the implicit object: a const object only sees the const overload, a non-const object prefers the non-const one.
  • Default arguments count as overloads of a sort: void f(int, int = 0) and void f(int) together make f(1) ambiguous.
  • Brace initialization of a parameter, f({1, 2}), uses list-initialization rules and prefers std::initializer_list constructors, 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 using declaration 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 = default and = delete.