In order to compile a function call, the compiler must first performname lookup, which, for functions, may involveargument-dependent lookup, and for function templates may be followed bytemplate argument deduction.

If the name refers to more than one entity, it is said to beoverloaded, and the compiler must determine which overload to call. In simple terms, the overload whose parameters match the arguments most closely is the one that is called.

In detail, overload resolution proceeds through the following steps:

1. Building the set ofcandidate functions.
2. Trimming the set to onlyviable functions.
3. Analyzing the set to determine the singlebest viable function (this may involveranking of implicit conversion sequences).

void f(long);void f(float); f(0L);// calls f(long)f(0);// error: ambiguous overload

Besides function calls, overloaded function names may appear in several additional contexts, where different rules apply: seeAddress of an overloaded function.

If a function cannot be selected by overload resolution, it cannot be used (e.g. it is atemplated entity with a failedconstraint).

[edit]Candidate functions

Before overload resolution begins, the functions selected by name lookup and template argument deduction are combined to form the set ofcandidate functions. The exact details depend on the context in which overload resolution will take place.

[edit]Call to a named function

IfE in afunction call expressionE(args) names a set of overloaded functions and/or function templates (but not callable objects), the following rules are followed:

• If the expressionE has the formPA->B orA.B (whereA has class typecvT), thenB islooked up as a member function ofT. The function declarations found by that lookup are the candidate functions. The argument list for the purpose of overload resolution has the implied object argument of typecvT.
• If the expressionE is aprimary expression, the name islooked up following normal rules for function calls (which may involveADL). The function declarations found by this lookup are (due to the way lookup works) either:

• all non-member functions (in which case the argument list for the purpose of overload resolution is exactly the argument list used in the function call expression)
• all member functions of some classT, in which case, ifthis is in scope and is a pointer toT or to a derived class ofT,*this is used as the implied object argument. Otherwise (ifthis is not in scope or does not point toT), a fake object of typeT is used as the implied object argument, and if overload resolution subsequently selects a non-static member function, the program is ill-formed.

[edit]Call to a class object

IfE in afunction call expressionE(args) has class typecvT, then

• The function-call operators ofT are obtained by ordinarylookup of the nameoperator() in the context of the expression(E).operator(), and every declaration found is added to the set of candidate functions.
• For each non-explicituser-defined conversion function inT or in a base ofT (unless hidden), whose cv-qualifiers are the same or greater thanT's cv-qualifiers, and where the conversion function converts to:

• pointer-to-function
• reference-to-pointer-to-function
• reference-to-function

then asurrogate call function with a unique name whose first parameter is the result of the conversion, the remaining parameters are the parameter list accepted by the result of the conversion, and the return type is the return type of the result of the conversion, is added to the set of candidate functions. If this surrogate function is selected by the subsequent overload resolution, then the user-defined conversion function will be called and then the result of the conversion will be called.

In any case, the argument list for the purpose of overload resolution is the argument list of the function call expression preceded by the implied object argumentE (when matching against the surrogate function, the user-defined conversion will automatically convert the implied object argument to the first argument of the surrogate function).

int f1(int);int f2(float); struct A{using fp1=int(*)(int);    operator fp1(){return f1;}// conversion function to pointer to functionusing fp2=int(*)(float);    operator fp2(){return f2;}// conversion function to pointer to function} a; int i= a(1);// calls f1 via pointer returned from conversion function

[edit]Call to an overloaded operator

If at least one of the arguments to an operator in an expression has a class type or an enumeration type, bothbuiltin operators anduser-defined operator overloads participate in overload resolution, with the set of candidate functions selected as follows:

For a unary operator@ whose argument has typeT1 (after removing cv-qualifications), or binary operator@ whose left operand has typeT1 and right operand of typeT2 (after removing cv-qualifications), the following sets of candidate functions are prepared:

The set of candidate functions to be submitted for overload resolution is a union of the sets above. The argument list for the purpose of overload resolution consists of the operands of the operator except foroperator->, where the second operand is not an argument for the function call (seemember access operator).

struct A{    operatorint();// user-defined conversion};A operator+(const A&,const A&);// non-member user-defined operator void m(){    A a, b;    a+ b;// member-candidates: none// non-member candidates: operator+(a, b)// built-in candidates: int(a) + int(b)// overload resolution chooses operator+(a, b)}

If the overload resolution selects a built-in candidate, theuser-defined conversion sequence from an operand of class type is not allowed to have a second standard conversion sequence: the user-defined conversion function must give the expected operand type directly:

struct Y{ operatorint*();};// Y is convertible to int*int*a= Y()+100.0;// error: no operator+ between pointer and double

Foroperator,, the unaryoperator&, andoperator->, if there are no viable functions (see below) in the set of candidate functions, then the operator is reinterpreted as a built-in.

[edit]Initialization by constructor

When an object of class type isdirect-initialized ordefault-initialized (including default-initialization in the context ofcopy-list-initialization)(since C++11), the candidate functions are all constructors of the class being initialized. The argument list is the expression list of the initializer.

Otherwise, the candidate functions are allconverting constructors of the class being initialized. The argument list is the expression of the initializer.

[edit]Copy-initialization by conversion

Ifcopy-initialization of an object of class type requires that a user-defined conversion is called to convert the initializer expression of typecvS to the typecvT of the object being initialized, the following functions are candidate functions:

• allconverting constructors ofT
• the non-explicit conversion functions fromS and its base classes (unless hidden) toT or class derived fromT or a reference to such. If this copy-initialization is part of the direct-initialization sequence ofcvT (initializing a reference to be bound to the first parameter of a constructor that takes a reference tocvT), then explicit conversion functions are also considered.

Either way, the argument list for the purpose of overload resolution consists of a single argument which is the initializer expression, which will be compared against the first argument of the constructor or against the implicit object argument of the conversion function.

[edit]Non-class initialization by conversion

When initialization of an object of non-class typecv1T requires auser-defined conversion function to convert from an initializer expression of class typecvS, the following functions are candidates:

• the non-explicit user-defined conversion functions ofS and its base classes (unless hidden) that produce typeT or a type convertible toT by astandard conversion sequence, or a reference to such type. cv-qualifiers on the returned type are ignored for the purpose of selecting candidate functions.
• if this isdirect-initialization, the explicit user-defined conversion functions ofS and its base classes (unless hidden) that produce typeT or a type convertible toT by aqualification conversion, or a reference to such type, are also considered.

Either way, the argument list for the purpose of overload resolution consists of a single argument which is the initializer expression, which will be compared against the implicit object argument of the conversion function.

[edit]Reference initialization by conversion

Duringreference initialization, where the reference tocv1T is bound to the lvalue or rvalue result of a conversion from the initializer expression from the class typecv2S, the following functions are selected for the candidate set:

• The non-explicit user-defined conversion functions ofS and its base classes (unless hidden) to the type

• (when converting to an lvalue) lvalue reference tocv2T2
• (when converting to an rvalue or an lvalue of function type)cv2T2 or rvalue reference tocv2T2

wherecv2T2 isreference-compatible withcv1T.

• For direct initialization, the explicit user-defined conversion functions are also considered ifT2 is the same type asT or can be converted to typeT with a qualification conversion.

Either way, the argument list for the purpose of overload resolution consists of a single argument which is the initializer expression, which will be compared against the implicit object argument of the conversion function.

[edit]List-initialization

When an object of non-aggregate class typeT islist-initialized, two-phase overload resolution takes place.

• at phase 1, the candidate functions are all initializer-list constructors ofT and the argument list for the purpose of overload resolution consists of a single initializer list argument
• if overload resolution fails at phase 1, phase 2 is entered, where the candidate functions are all constructors ofT and the argument list for the purpose of overload resolution consists of the individual elements of the initializer list.

If the initializer list is empty andT has a default constructor, phase 1 is skipped.

In copy-list-initialization, if phase 2 selects an explicit constructor, the initialization is ill-formed (as opposed to all over copy-initializations where explicit constructors are not even considered).

[edit]Additional rules for function template candidates

If name lookup found a function template,template argument deduction and checking of any explicit template arguments are performed to find the template argument values (if any) that can be used in this case:

• If both succeeds, the template arguments are used to synthesize declarations of the corresponding function template specializations, which are added to the candidate set, and such specializations are treated just like non-template functions except where specified otherwise in the tie-breaker rules below.
• If argument deduction fails or the synthesized function template specialization would be ill-formed, no such function is added to the candidate set (seeSFINAE).

If a name refers to one or more function templates and also to a set of overloaded non-template functions, those functions and the specializations generated from the templates are all candidates.

Seefunction template overloading for further detail.

[edit]Additional rules for constructor candidates

[edit]Additional rules for member function candidates

If any candidate function is amember function (static or non-static) that does not have anexplicit object parameter(since C++23), but not a constructor, it is treated as if it has an extra parameter (implicit object parameter) which represents the object for which they are called and appears before the first of the actual parameters.

Similarly, the object on which a member function is being called is prepended to the argument list as theimplied object argument.

For member functions of classX, the type of the implicit object parameter is affected by cv-qualifications and ref-qualifications of the member function as described inmember functions.

The user-defined conversion functions are considered to be members of theimplied object argument for the purpose of determining the type of theimplicit object parameter.

The member functions introduced by a using-declaration into a derived class are considered to be members of the derived class for the purpose of defining the type of theimplicitobject parameter.

For the rest of overload resolution, theimplied object argument is indistinguishable from other arguments, but the following special rules apply to theimplicit object parameter:

struct B{void f(int);};struct A{ operator B&();}; A a;a.B::f(1);// Error: user-defined conversions cannot be applied// to the implicit object parameterstatic_cast<B&>(a).f(1);// OK

[edit]Viable functions

Given the set of candidate functions, constructed as described above, the next step of overload resolution is examining arguments and parameters to reduce the set to the set ofviable functions

To be included in the set of viable functions, the candidate function must satisfy the following:

User-defined conversions (both converting constructors and user-defined conversion functions) are prohibited from taking part in implicit conversion sequence where it would make it possible to apply more than one user-defined conversion. Specifically, they are not considered if the target of the conversion is the first parameter of a constructor or the implicit object parameter of a user-defined conversion function, and that constructor/user-defined conversion is a candidate for

• copy-initialization of a class by user-defined conversion,
• initialization of a non-class type by a conversion function,
• initialization by conversion function for direct reference binding,
• initialization by constructor during the second (direct-initialization) step of classcopy-initialization,

struct A{ A(int);};struct B{ B(A);}; B b{{0}};// list-initialization of B // candidates: B(const B&), B(B&&), B(A)// {0} -> B&& not viable: would have to call B(A)// {0} -> const B&: not viable: would have to bind to rvalue, would have to call B(A)// {0} -> A viable. Calls A(int): user-defined conversion to A is not banned

[edit]Best viable function

For each pair of viable functionF1 andF2, the implicit conversion sequences from thei^th argument toi^th parameter are ranked to determine which one is better (except the first argument, theimplicit object argument for static member functions has no effect on the ranking)

F1 is determined to be a better function thanF2 if implicit conversions for all arguments ofF1 arenot worse than the implicit conversions for all arguments of F2, and

template<typename T=int>struct S{constexprvoid f();// #1constexprvoid f(this S&) requirestrue;// #2}; void test(){    S<> s;    s.f();// calls #2}

struct A{    A(int=0);}; struct B: A{using A::A;     B();}; B b;// OK, B::B()

template<class T>struct A{using value_type= T;    A(value_type);// #1    A(const A&);// #2    A(T, T,int);// #3 template<class U>    A(int, T, U);// #4};// #5 is A(A), the copy deduction candidate A x(1,2,3);// uses #3, generated from a non-template constructor template<class T>A(T)-> A<T>;// #6, less specialized than #5 A a(42);// uses #6 to deduce A<int> and #1 to initializeA b= a;// uses #5 to deduce A<int> and #2 to initialize template<class T>A(A<T>)-> A<A<T>>;// #7, as specialized as #5A b2= a;// uses #7 to deduce A<A<int>> and #1 to initialize

These pair-wise comparisons are applied to all viable functions. If exactly one viable function is better than all others, overload resolution succeeds and this function is called. Otherwise, compilation fails.

void Fcn(constint*,short);// overload #1void Fcn(int*,int);// overload #2 int i;short s=0; void f(){    Fcn(&i,1L);// 1st argument: &i -> int* is better than &i -> const int*// 2nd argument: 1L -> short and 1L -> int are equivalent// calls Fcn(int*, int)     Fcn(&i,'c');// 1st argument: &i -> int* is better than &i -> const int*// 2nd argument: 'c' -> int is better than 'c' -> short// calls Fcn(int*, int)     Fcn(&i, s);// 1st argument: &i -> int* is better than &i -> const int*// 2nd argument: s -> short is better than s -> int// no winner, compilation error}

If the best viable function resolves to a function for which multiple declarations were found, and if any two of these declarations inhabit different scopes and specify a default argument that made the function viable, the program is ill-formed.

namespace A{extern"C"void f(int=5);} namespace B{extern"C"void f(int=5);} using A::f;using B::f; void use(){    f(3);// OK, default argument was not used for viability    f();// error: found default argument twice}

[edit]Ranking of implicit conversion sequences

The argument-parameter implicit conversion sequences considered by overload resolution correspond toimplicit conversions used incopy initialization (for non-reference parameters), except that when considering conversion to the implicit object parameter or to the left-hand side of assignment operator, conversions that create temporary objects are not considered.When the parameter is the implicit object parameter of a static member function, the implicit conversion sequence is a standard conversion sequence that is neither better nor worse than any other standard conversion sequence.(since C++23)

Eachtype of standard conversion sequence is assigned one of three ranks:

The rank of the standard conversion sequence is the worst of the ranks of the standard conversions it holds (there may be up tothree conversions)

Binding of a reference parameter directly to the argument expression is either identity or a derived-to-base conversion:

struct Base{};struct Derived: Base{} d; int f(Base&);// overload #1int f(Derived&);// overload #2 int i= f(d);// d -> Derived& has rank Exact Match// d -> Base& has rank Conversion// calls f(Derived&)

Since ranking of conversion sequences operates with types and value categories only, abit field can bind to a reference argument for the purpose of ranking, but if that function gets selected, it will be ill-formed.

int i;int f1(); int g(constint&);// overload #1int g(constint&&);// overload #2 int j= g(i);// lvalue int -> const int& is the only valid conversionint k= g(f1());// rvalue int -> const int&& better than rvalue int -> const int&

int f(void(&)());// overload #1int f(void(&&)());// overload #2 void g();int i1= f(g);// calls #1

int f(constint*);int f(int*); int i;int j= f(&i);// &i -> int* is better than &i -> const int*, calls f(int*)

int f(constint&);// overload #1int f(int&);// overload #2 (both references) int g(constint&);// overload #1int g(int);// overload #2 int i;int j= f(i);// lvalue i -> int& is better than lvalue int -> const int&// calls f(int&)int k= g(i);// lvalue i -> const int& ranks Exact Match// lvalue i -> rvalue int ranks Exact Match// ambiguous overload: compilation error

struct Z{}; struct A{    operator Z&();    operatorconst Z&();// overload #1}; struct B{    operator Z();    operatorconst Z&&();// overload #2}; const Z& r1= A();// OK, uses #1const Z&& r2= B();// OK, uses #2

struct A{    operatorshort();// user-defined conversion function} a; int f(int);// overload #1int f(float);// overload #2 int i= f(a);// A -> short, followed by short -> int (rank Promotion)// A -> short, followed by short -> float (rank Conversion)// calls f(int)

void f1(int);// #1void f1(std::initializer_list<long>);// #2void g1(){ f1({42});}// chooses #2 void f2(std::pair<constchar*,constchar*>);// #3void f2(std::initializer_list<std::string>);// #4void g2(){ f2({"foo","bar"});}// chooses #4

void f(int(&&)[]);// overload #1void f(double(&&)[]);// overload #2void f(int(&&)[2]);// overload #3 f({1});// #1: Better than #2 due to conversion, better than #3 due to boundsf({1.0});// #2: double -> double is better than double -> intf({1.0,2.0});// #2: double -> double is better than double -> intf({1,2});// #3: -> int[2] is better than -> int[],//     and int -> int is better than int -> double

If two conversion sequences are indistinguishable because they have the same rank, the following additional rules apply:

enum num:char{ one='0'};std::cout<< num::one;// '0', not 48

int f(std::float32_t);int f(std::float64_t);int f(longlong); float x;std::float16_t y; int i= f(x);// calls f(std::float32_t) on implementations where// float and std::float32_t have equal conversion ranksint j= f(y);// error: ambiguous, no equal conversion rank

Ambiguous conversion sequences are ranked as user-defined conversion sequences because multiple conversion sequences for an argument can exist only if they involve different user-defined conversions:

class B; class A{ A(B&);};// converting constructorclass B{ operator A();};// user-defined conversion functionclass C{ C(B&);};// converting constructor void f(A){}// overload #1void f(C){}// overload #2 B b;f(b);// B -> A via ctor or B -> A via function (ambiguous conversion)// b -> C via ctor (user-defined conversion)// the conversions for overload #1 and for overload #2// are indistinguishable; compilation fails

[edit]Implicit conversion sequence in list-initialization

Inlist initialization, the argument is abraced-init-list, which isn't an expression, so the implicit conversion sequence into the parameter type for the purpose of overload resolution is decided by the following special rules:

• If the parameter type is some aggregateX and the initializer list consists of exactly one element of same or derived class (possibly cv-qualified), the implicit conversion sequence is the one required to convert the element to the parameter type.
• Otherwise, if the parameter type is a reference to character array and the initializer list has a single element that is an appropriately-typed string literal, the implicit conversion sequence is the identity conversion.
• Otherwise, if the parameter type isstd::initializer_list<X>, and there is a non-narrowing implicit conversion from every element of the initializer list toX, the implicit conversion sequence for the purpose of overload resolution is the worst conversion necessary. If the braced-init-list is empty, the conversion sequence is the identity conversion.

struct A{    A(std::initializer_list<double>);// #1    A(std::initializer_list<complex<double>>);// #2    A(std::initializer_list<std::string>);// #3};A a{1.0,2.0};// selects #1 (rvalue double -> double: identity conv) void g(A);g({"foo","bar"});// selects #3 (lvalue const char[4] -> std::string: user-def conv)

• Otherwise, if the parameter type is “array of N T” (this only happens for references to arrays), the initializer list must have N or less elements, and the worst implicit conversion necessary to convert every element of the list (or the empty pair of braces{} if the list is shorter than N) toT is the one used.

typedefint IA[3]; void h(const IA&);void g(int(&&)[]); h({1,2,3});// int->int identity conversiong({1,2,3});// same as above since C++20

• Otherwise, if the parameter type is a non-aggregate class typeX, overload resolution picks the constructor C of X to initialize from the argument initializer list

• If C is not an initializer-list constructor and the initializer list has a single element of possibly cv-qualified X, the implicit conversion sequence has Exact Match rank. If the initializer list has a single element of possibly cv-qualified type derived from X, the implicit conversion sequence has Conversion rank. (note the difference from aggregates: aggregates initialize directly from single-element init lists before consideringaggregate initialization, non-aggregates consider initializer_list constructors before any other constructors)
• otherwise, the implicit conversion sequence is a user-defined conversion sequence with the second standard conversion sequence an identity conversion.

If multiple constructors are viable but none is better than the others, the implicit conversion sequence is the ambiguous conversion sequence.

struct A{ A(std::initializer_list<int>);};void f(A); struct B{ B(int,double);};void g(B); g({'a','b'});// calls g(B(int, double)), user-defined conversion// g({1.0, 1,0}); // error: double->int is narrowing, not allowed in list-init void f(B);// f({'a', 'b'}); // f(A) and f(B) both user-defined conversions

• Otherwise, if the parameter type is an aggregate which can be initialized from the initializer list according byaggregate initialization, the implicit conversion sequence is a user-defined conversion sequence with the second standard conversion sequence an identity conversion.

struct A{int m1;double m2;}; void f(A);f({'a','b'});// calls f(A(int, double)), user-defined conversion

• Otherwise, if the parameter is a reference, reference initialization rules apply

struct A{int m1;double m2;}; void f(const A&);f({'a','b'});// temporary created, f(A(int, double)) called. User-defined conversion

• Otherwise, if the parameter type is not a class and the initializer list has one element, the implicit conversion sequence is the one required to convert the element to the parameter type
• Otherwise, if the parameter type is not a class type and if the initializer list has no elements, the implicit conversion sequence is the identity conversion.

struct A{int x, y;};struct B{int y, x;}; void f(A a,int);// #1void f(B b, ...);// #2void g(A a);// #3void g(B b);// #4 void h(){    f({.x=1, .y=2},0);// OK; calls #1    f({.y=2, .x=1},0);// error: selects #1, initialization of a fails// due to non-matching member order    g({.x=1, .y=2});// error: ambiguous between #3 and #4}

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

1. ↑The type of the of the first parameter of a built-in assignment operator is “lvalue reference to possibly volatile-qualifiedT”. References of this type cannot bound to a temporary.

[edit]References

[edit]See also

• Name lookup
• Argument-dependent lookup
• Template argument deduction
• SFINAE

• In other languages

• Deutsch
• Español
• 日本語
• Русский
• 中文