cpp/language/overload resolution

In order to compile a function call, the compiler must first perform, which, for functions, may involve , and for function templates may be followed by.

If the name refers to more than one entity, it is said to be overloaded, 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 of.
 * 2) Trimming the set to only.
 * 3) Analyzing the set to determine the single  (this may involve ).

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

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

Candidate functions
Before overload resolution begins, the functions selected by name lookup and template argument deduction are combined to form the set of candidate functions. The exact details depend on the context in which overload resolution takes place:

Call to a named function
If in a   names a set of overloaded functions and/or function templates (but not callable objects), the following rules are followed:
 * If the expression has the form  or  (where A has class type cv T), then  is  as a member function of . 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 type cv T.
 * If the expression is a, the name is  following normal rules for function calls (which may involve ). The function declarations found by this lookup are (due to the way lookup works) either:
 * a) 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)
 * b) all member functions of some class, in which case, if is in scope and is a pointer to  or to a derived class of ,  is used as the implied object argument. Otherwise (if  is not in scope or does not point to ), a fake object of type  is used as the implied object argument, and if overload resolution subsequently selects a non-static member function, the program is ill-formed.

Call to a class object
If in a   has class type cv, then
 * The function-call operators of T are obtained by ordinary of the name  in the context of the expression, and every declaration found is added to the set of candidate functions.
 * For each non-explicit in  or in a base of  (unless hidden), whose cv-qualifiers are the same or greater than 's cv-qualifiers, and where the conversion function converts to:
 * pointer-to-function
 * reference-to-pointer-to-function
 * reference-to-function
 * then a surrogate 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 argument (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).

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, both and  participate in overload resolution, with the set of candidate functions selected as follows:

For a unary operator whose argument has type  (after removing cv-qualifications), or binary operator  whose left operand has type  and right operand of type  (after removing cv-qualifications), the following sets of candidate functions are prepared: @1@ member candidates: if is a complete class or a class currently being defined, the set of member candidates is the result of  of. In all other cases, the set of member candidates is empty. @2@ non-member candidates: For the operators where permits non-member forms, all declarations found by  of  in the context of the expression (which may involve ), except that member function declarations are ignored and do not prevent the lookup from continuing into the next enclosing scope. If both operands of a binary operator or the only operand of a unary operator has enumeration type, the only functions from the lookup set that become non-member candidates are the ones whose parameter has that enumeration type (or reference to that enumeration type) @3@ built-in candidates: For, the unary , and , the set of built-in candidates is empty. For other operators built-in candidates are the ones listed in as long as all operands can be implicitly converted to their parameters. If any built-in candidate has the same parameter list as a non-member candidate that is not a function template specialization, it is not added to the list of built-in candidates. When the built-in assignment operators are considered, the conversions from their left-hand arguments are restricted: user-defined conversions are not considered.

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 for, where the second operand is not an argument for the function call (see ).

If the overload resolution selects a built-in candidate, the 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:

For, the unary , and , if there are no viable functions (see below) in the set of candidate functions, then the operator is reinterpreted as a built-in.

Initialization by constructor
When an object of class type is or  outside a  context, the candidate functions are all constructors of the class being initialized. The argument list is the expression list of the initializer.

When an object of class type is copy-initialized from an object of the same or derived class type, or default-initialized in a copy-initialization context, the candidate functions are all s of the class being initialized. The argument list is the expression of the initializer.

Copy-initialization by conversion
If of an object of class type requires that a user-defined conversion is called to convert the initializer expression of type cv  to the type cv  of the object being initialized, the following functions are candidate functions:
 * all s of
 * the non-explicit conversion functions from and its base classes (unless hidden) to  or class derived from  or a reference to such. If this copy-initialization is part of the direct-initialization sequence of cv  (initializing a reference to be bound to the first parameter of a constructor that takes a reference to cv ), 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.

Non-class initialization by conversion
When initialization of an object of non-class type cv1 requires a  to convert from an initializer expression of class type cv, the following functions are candidates:
 * the non-explicit user-defined conversion functions of and its base classes (unless hidden) that produce type  or a type convertible to  by a, or a reference to such type. cv qualifiers on the returned type are ignored for the purpose of selecting candidate functions.
 * if this is, the explicit user-defined conversion functions of and its base classes (unless hidden) that produce type  or a type convertible to  by a , 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.

Reference initialization by conversion
During, where the reference to cv1 is bound to the lvalue or rvalue result of a conversion from the initializer expression from the class type cv2 , the following functions are selected for the candidate set:
 * the non-explicit user-defined conversion functions of and its base classes (unless hidden) to the type
 * (when initializing lvalue reference or rvalue reference to function) lvalue reference to cv2
 * (when initializing rvalue reference or lvalue reference to function) cv2 or rvalue reference to cv2
 * where cv2 T2 is reference-compatible with cv1 T


 * for direct initialization, the explicit user-defined conversion functions are also considered if T2 is the same type as T or can be converted to type T 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.

List-initialization
When an object of non-aggregate class type is, two-phase overload resolution takes place.
 * at phase 1, the candidate functions are all initializer-list constructors of 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 of 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 and 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).

Additional rules for function template candidates
If name lookup produces a function template, 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 (see ).

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.

See for further detail.

Additional rules for constructor candidates
Inherited copy and move constructors are not included in the list of candidate functions when constructing a derived class object.

Additional rules for member function candidates
If any candidate function is a (static or non-static), 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 the implied object argument.

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

The user-defined conversion functions are considered to be members of the implied object argument for the purpose of determining the type of the implicit 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 the ''implicit object parameter''.

For the static member functions, the implicit object parameter is considered to match any object: its type is not examined and no conversion sequence is attempted for it.

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

@1@ user-defined conversions cannot be applied to the implicit object parameter

@2@ rvalues can be bound to non-const implicit object parameter and do not affect the ranking of the implicit conversions.

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 of viable functions

To be included in the set of viable functions, the candidate function must satisfy the following: @1@ If there are arguments, the candidate function that has exactly  parameters is viable @2@ If the candidate function has less than parameters, but has an, it is viable. @3@ If the candidate function has more than parameters and the 'st parameter and all parameters that follow have default arguments, it is viable. For the rest of overload resolution, the parameter list is truncated at M.

@5@ For every argument there must be at least one implicit conversion sequence that converts it to the corresponding parameter. @6@ If any parameter has reference type, reference binding is accounted for at this step: if an rvalue argument corresponds to non-const lvalue reference parameter or an lvalue argument corresponds to rvalue reference parameter, the function is not viable.

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 class ,

Best viable function
For each pair of viable function and, the implicit conversion sequences from the -th argument to -th parameter are ranked to determine which one is better (except the first argument, the implicit object argument for static member functions has no effect on the ranking)

is determined to be a better function than if implicit conversions for all arguments of F1 are not worse than the implicit conversions for all arguments of F2, and @1@ there is at least one argument of F1 whose implicit conversion is better than the corresponding implicit conversion for that argument of F2 @2@ or, if not that, (only in context of non-class initialization by conversion), the standard conversion sequence from the return type of F1 to the type being initialized is better than the standard conversion sequence from the return type of F2

@4@ or, if not that, F1 is a non-template function while F2 is a template specialization @5@ or, if not that, F1 and F2 are both template specializations and F1 is more specialized according to the

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.

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.

Ranking of implicit conversion sequences
The argument-parameter implicit conversion sequences considered by overload resolution correspond to s used in (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.

Each is assigned one of three ranks: @1@ Exact match: no conversion required, lvalue-to-rvalue conversion, qualification conversion, user-defined conversion of class type to the same class @2@ Promotion: integral promotion, floating-point promotion @3@ Conversion: integral conversion, floating-point conversion, floating-integral conversion, pointer conversion, pointer-to-member conversion, boolean conversion, user-defined conversion of a derived class to its base

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

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

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

@1@ A standard conversion sequence is always better than a user-defined conversion sequence or an ellipsis conversion sequence. @2@ A user-defined conversion sequence is always better than an sequence @3@ A standard conversion sequence is better than a standard conversion sequence  if
 * @a@ is a subsequence of, excluding lvalue transformations. The identity conversion sequence is considered a subsequence of any other conversion
 * @b@ Or, if not that, the rank of is better than the rank of
 * @c@ or, if not that, both and  are binding to a reference parameter to something other than the implicit object parameter of a ref-qualified member function, and  binds an rvalue reference to an rvalue while  binds an lvalue reference to an rvalue


 * @d@ or, if not that, both and  are binding to a reference parameter and  binds an lvalue reference to function while  binds an rvalue reference to function.


 * @e@ or, if not that, both and  are binding to a reference parameters only different in top-level cv-qualification, and 's type is less cv-qualified than 's.


 * @f@ Or, if not that, S1 and S2 only differ in qualification conversion, and

@4@ A user-defined conversion sequence is better than a user-defined conversion sequence  if they call the same constructor/user-defined conversion function or initialize the same class with aggregate-initialization, and in either case the second standard conversion sequence in  is better than the second standard conversion sequence in

@5@ A list-initialization sequence is better than list-initialization sequence  if  initializes an std parameter, while  does not.

If two conversion sequences are indistinguishable because they have the same rank, the following additional rules apply: @1@ Conversion that does not involve pointer to or pointer-to-member to  is better than the one that does.

@4@ Conversion that converts pointer-to-derived to pointer-to-base is better than the conversion of pointer-to-derived to pointer-to-, and conversion of pointer-to-base to is better than pointer-to-derived to. @5@ If is derived (directly or indirectly) from, and  is derived (directly or indirectly) from
 * @a@ to  is better than  to
 * @b@ to  or  is better than  to  or
 * @c@ to  is better than  to
 * @d@ to  is better than  to
 * @e@ to  is better than  to
 * @f@ to  or  is better than  to  or
 * @g@ to  is better than  to
 * @h@ to  is better than  to

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:

Implicit conversion sequence in list-initialization
In, the argument is a , 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 aggregate 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 is, and there is a non-narrowing implicit conversion from every element of the initializer list to , 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.


 * 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) to  is the one used.


 * Otherwise, if the parameter type is a non-aggregate class type, 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 considering, 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.


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


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


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