Implicit conversion sequences (C++ only)

The following are the three categories of conversion sequences in order from best to worst:

• Standard conversion sequences
• User-defined conversion sequences
• Ellipsis conversion sequences

Note: Two standard conversion sequences or two user-defined conversion sequences might have different ranks.

Standard conversion sequences are categorized in one of three ranks. The ranks are listed in order from highest to lowest:

• Exact match: This rank includes the following conversions:
  • Identity conversions
  • Lvalue-to-rvalue conversions
  • Array-to-pointer conversions
  • Qualification conversions
• Promotion: This rank includes integral and floating point promotions.
• Conversion: This rank includes the following conversions:
  • Integral and floating-point conversions
  • Floating-integral conversions
  • Pointer conversions
  • Pointer-to-member conversions
  • Boolean conversions

A user-defined conversion sequence consists of the following:

• A standard conversion sequence
• A user-defined conversion
• A second standard conversion sequence

Suppose S1 and S2 are two standard conversion sequences. The compiler checks whether S1 and S2 satisfy the following conditions in sequence. If one of the conditions is satisfied, S1 is a better standard conversion sequence than S2.

1. S2 involves a qualification conversion, but S1 does not involve qualification conversions. See Example 1.
2. The rank of S1 is higher than the rank of S2. See Example 2.
3. Both S1 and S2 involve qualification conversions. T1 is the target type of S1, and T2 of S2. T2 is more cv-qualified than T1. See Example 3.
4. S1 and S2 are reference bindings to an rvalue, and neither of them refers to the implicit object parameter of a nonstatic member function. S1 binds an rvalue reference and S2 binds an lvalue reference. See Example 4.
5. S1 and S2 are reference bindings. S1 binds an lvalue reference to a function lvalue, and S2 binds an rvalue reference to a function lvalue. See Example 5.
6. S1 and S2 are reference bindings. T1 is the target type referred by S1, and T2 by S2. T1 and T2 differ only in top-level cv-qualifiers where T2 is more cv-qualified than T1. See Example 6.

If two standard conversion sequences S1 and S2 have the same rank, S1 is a better standard conversion sequence than S2 if one of the following conditions is satisfied:

• S1 converts a pointer, a pointer to member, or a null pointer, and S2 does not. See Example 7.
• Class A is a parent class of class B. S1 is a conversion from B* to A*, and S2 is a conversion from B* to void*; or S1 is a conversion from A* to void*, and S2 is a conversion from B* to void*. See Example 8.
• Class A is a parent class of class B, and class B is a parent class of class C. One of the following conditions is satisfied:
  • S1 is a conversion from C* to B*, and S2 is a conversion from C* to A*.
  • S1 binds an expression of type C to a reference of type B&, and S2 binds an expression of type C to a reference of type A&.
  • S1 is a conversion from A::* to B::*, and S2 is a conversion from A::* to C::*.
  • S1 is a conversion from C to B, and S2 is a conversion from C to A.
  • S1 is a conversion from B* to A*, and S2 is a conversion from C* to A*. See Example 9.
  • S1 binds an expression of type B to type A&, and S2 binds an expression of type C to type A&.
  • S1 is a conversion from B::* to C::*, and S2 is a conversion from A::* to C::*.
  • S1 is a conversion from B to A, and S2 is a conversion from C to A.

Example 1

void f(int*);        // #1 function
void f(const int*);  // #2 function

void test() {
   // The compiler calls #1 function
   f(static_cast<int*>(0));  
}

In this example, for the call of f(static_cast<int*>(0)), the standard conversion sequence S1 of the f(int*) function is from int* to int*. The standard conversion sequence S2 of the f(const int*) function is from int* to const int*. S2 involves a qualification conversion, but S1 does not, so S1 is a better standard conversion sequence than S2.

Example 2

struct A { };
struct B : A { };

void f(const B*);  // #1 function
void f(A*);        // #2 function

void test() {
   // The compiler calls #1 function 
   f(static_cast<B*>(0));  
}

struct A1 *g(int);    // #3 function
struct A2 *g(short);  // #4 function

void test2() {
  // The compiler calls #4 function
  A2* a2 = g(static_cast<short>(0));  
  
  // The compiler calls #3 function
  A1* a1 = g('\0');
} 

In this example, for the call of f(static_cast<B*>(0)), the standard conversion sequence of the f(const B*) function is an exact match, and the standard conversion sequence of the f(A*) function is a conversion. The rank of exact match is higher than that of conversion, so f(const B*) is chosen by overload resolution. Similarly, for the call of g(static_cast<short>(0)), the standard conversion sequence of the g(short) function is an exact match, and the standard conversion sequence of the g(int) function is a promotion. The g(short) function is called because the rank of exact match is higher than that of promotion. For the call of g('\0'), the standard conversion sequence of the g(short) function is a conversion, and the standard conversion sequence of the g(int) function is a promotion, g(int) is called in this case because the rank of promotion is higher than that of conversion.

Example 3

struct A { };
struct B : A { };
void g(const A*);           // #1 function
void g(const volatile A*);  // #2 function
void test2() {
   // The compiler calls #1 function
   g(static_cast<B*>(0));  
}

In this example, for the call of g(static_cast<B*>(0)), the standard conversion sequence S1 of the g(const A*) function is from B* to const A*. The standard conversion sequence S2 of the g(const volatile A*) function is from B* to const volatile A*. Both S1 and S2 involve qualification conversions, and const volatile A* is more cv-qualified than const A*, so S1 is a better standard conversion sequence than S2.

Example 4

double f1();
int g(const double&&);  // #1 function
int g(const double&);   // #2 function

// The compiler calls #1 function
int i = g(f1());

struct A {
   int operator+(int);
};

int operator+(A &&, int);

A &&f2(); 
 
void test() {   
   f2() + 0;  // error 
}     

In this example, for the call of g(f1()), the standard conversion sequence of the g(const double&) function binds an lvalue reference, and the standard conversion sequence for g(const double&&) binds an rvalue reference. Neither of these two standard conversion sequences refers to the implicit object parameter of a nonstatic member function. The g(const double&&) function is called because its standard conversion sequence is a better one. For the expression f2() + 0, the class member candidate involves a reference binding of the implicit object parameter of a nonstatic member function and hence cannot be ordered with respect to the namespace scope candidate.

Example 5

double f();
int g(double(&&)());  // #1 function
int g(double(&)());   // #2 function

// The compiler calls #2 function
int i = g(f)

In this example, for the call of g(f), the standard conversion sequence of the g(double(&)()) function binds an lvalue reference to a function lvalue, and the standard conversion sequence of the g(double(&&)()) function binds an rvalue reference to a function lvalue. The g(double(&)()) function is called because its standard conversion sequence is a better one.

Example 6

void f(A&);        // #1 function
void f(const A&);  // #2 function
void test() {
   A a; 
   // The compiler calls #1 function  
   f(a);  
}

In this example, for the call of f(a), the standard conversion sequence S1 of the f(A&) function binds an lvalue reference A& to a, and the standard conversion sequence S2 of the f(const A&) function binds a const lvalue reference const A& to a. Because const A and A are the same except for top-level cv-qualifers, and const A is more cv-qualified than A, S1 is a better standard conversion sequence than S2.

Example 7

void f(void*);  // #1 function
void f(bool);   // #2 function
void test() {
   // The compiler calls #1 function 
   f(static_cast<int*>(0));  
}

In this example, for the call of f(static_cast<int*>(0)), the standard conversion sequence S1 of the f(void*) function is from int* to void*, and the standard conversion sequence S2 of the f(bool) function is from int* to bool. S1 and S2 have the same rank. However, because S1 does not convert a pointer, a pointer to member, or a null pointer to a bool, and S2 converts a pointer to a bool, S1 is a better standard conversion sequence than S2.

Example 8

//
void f(void*);      // #1 function
void f(struct A*);  // #2 function
struct A { };
struct B : A { };
void test() {
  // The compiler calls #2 function
  f(static_cast<B*>(0)); 
} 

In this example, for the call of f(static_cast<B*>(0)), the standard conversion sequence of the f(void*) function is from B* to void*, and the standard conversion sequence of the f(struct A*) is from B* to A*. The f(struct A*) is called because its standard conversion sequence is a better one.

Example 9

void f(struct A *);
struct A { };
struct B : A { };
struct C : B { };
struct S {
   operator B*();
   operator C*();
}
void test() { 
   // calls S::operator B*()  
   f(S()); 
}

In this example, for the call of f(S()), the standard conversion sequence is from S() to A*, and the structure S has two conversion operators. The operator function operator B* () is called, because the conversion from B* to A* is better than from C* to A*.

Suppose U1 and U2 are two user-defined conversion sequences. U1 and U2 use the same user-defined conversion function, constructor, or aggregate initialization. U1 is a better user-defined conversion sequence than U2 if the second standard conversion sequence of U1 is better than that of U2. See Example 10:

Example 10

void f(void*);  // #1 function
void f(bool);   // #2 function
struct A {   
   operator int*();
}
void test() {
   // The compiler calls #1 function
   f(A());  
}

In this example, for the call of f(A()), the user-defined conversion sequence U1 of the f(void*) function is from A to void*. The user-defined conversion sequence U2 of the f(bool) function is from A to bool. U1 and U2 use the same user-defined conversion from A to int*. The standard conversion sequence from int* to void* is better than the standard conversion sequence from int* to bool, so U1 is a better user-defined conversion sequence than U2.