%!TEX root = std.tex

\rSec0[over]{Overloading}%

\indextext{overloading|(}

\gramSec[gram.over]{Overloading}

\rSec1[over.pre]{Preamble}

\pnum

\indextext{overloaded function|see{overloading}}%

\indextext{function!overloaded|see{overloading}}%

\begin{note}

Each of two or more entities with the same name in the same scope,

which must be functions or function templates,

is commonly called an ``overload''.

\end{note}

\pnum

When a function is designated in a call, which function

declaration is being referenced and the validity of the call

are determined by comparing the types

of the arguments at the point of use with the types of the parameters

in the declarations in the overload set.

This function selection process is called

\defn{overload resolution} and is defined in~\ref{over.match}.

\begin{note}

Overload sets are formed by \grammarterm{id-expression}s

naming functions and function templates and

by \grammarterm{splice-expression}s designating entities of the same kinds.

\end{note}

\begin{example}

\indextext{overloading!example of}%

\begin{codeblock}

double abs(double);

int abs(int);

abs(1); // calls \tcode{abs(int);}

abs(1.0); // calls \tcode{abs(double);}

\end{codeblock}

\end{example}

\rSec1[over.match]{Overload resolution}%

\rSec2[over.match.general]{General}%

\indextext{overloading!resolution|(}%

\indextext{resolution|see{overloading, resolution}}%

\indextext{ambiguity!overloaded function}

\pnum

Overload resolution is a mechanism for selecting the best

function to call given a list of expressions that are to be the

arguments of the call and a set of

\defnx{candidate functions}{candidate}

that can

be called based on the context of the call.

The selection

criteria for the best function are the number of arguments, how

well the arguments match the parameter-type-list of the

candidate function,

how well (for non-static member functions) the object

matches the object parameter,

and certain other properties of the candidate function.

\begin{note}

The function selected by overload resolution is not

guaranteed to be appropriate for the context.

Other restrictions,

such as the accessibility of the function, can make its use in

the calling context ill-formed.

\end{note}

\pnum

\indextext{overloading!resolution!contexts}%

Overload resolution selects the function to call in seven distinct

contexts within the language:

\begin{itemize}

\item

invocation of a function named in the function call syntax\iref{over.call.func};

\item

invocation of a function call operator, a pointer-to-function

conversion function, a reference-to-pointer-to-function conversion

function, or a reference-to-function

conversion function on a class object named in the function

call syntax\iref{over.call.object};

\item

invocation of the operator referenced in an expression\iref{over.match.oper};

\item

invocation of a constructor for default- or direct-initialization\iref{dcl.init}

of a class object\iref{over.match.ctor};

\item

invocation of a user-defined conversion for

copy-initialization\iref{dcl.init} of a class object\iref{over.match.copy};

\item

invocation of a conversion function for initialization of an object of a

non-class type from an expression of class type\iref{over.match.conv}; and

\item

invocation of a conversion function for conversion

in which a reference\iref{dcl.init.ref}

will be directly bound\iref{over.match.ref}.

\end{itemize}

Each of these contexts defines the set of candidate functions and

the list of arguments in its own unique way.

But, once the

candidate functions and argument lists have been identified, the

selection of the best function is the same in all cases:

\begin{itemize}

\item

First, a subset of the candidate functions (those that have

the proper number of arguments and meet certain other

conditions) is selected to form a set of

\indextext{function!viable}%

viable functions\iref{over.match.viable}.

\item

Then the best viable function is selected based on the

implicit conversion sequences\iref{over.best.ics} needed to

match each argument to the corresponding parameter of each

viable function.

\end{itemize}

\pnum

If a best viable function exists and is unique, overload

resolution succeeds and produces it as the result.

Otherwise

overload resolution fails and the invocation is ill-formed.

When overload resolution succeeds,

and the best viable function is not accessible\iref{class.access} in the context

in which it is used,

the program is ill-formed.

\pnum

Overload resolution results in a \defnadj{usable}{candidate}

if overload resolution succeeds and

the selected candidate

is either not a function\iref{over.built}, or

is a function that is not deleted and

is accessible from the context

in which overload resolution was performed.

\rSec2[over.match.funcs]{Candidate functions and argument lists}%

\rSec3[over.match.funcs.general]{General}%

\indextext{overloading!candidate functions|(}%

\indextext{overloading!argument lists|(}

\pnum

The subclauses of~\ref{over.match.funcs} describe

the set of candidate functions and the argument list submitted to

overload resolution in each context in which

overload resolution is used.

The source transformations and constructions defined

in these subclauses are only for the purpose of describing the

overload resolution process.

An implementation is not required

to use such transformations and constructions.

\pnum

\indextext{member function!overload resolution and}%

\indextext{function!overload resolution and}%

The set of candidate functions can contain both member and non-member

functions to be resolved against the same argument list.

If a member function is

\begin{itemize}

\item

an implicit object member function that is not a constructor, or

\item

a static member function and

the argument list includes an implied object argument,

\end{itemize}

it is considered to have an extra first parameter,

called the \defnadj{implicit}{object parameter},

which represents the object for which the member function has been called.

\pnum

Similarly, when appropriate, the context can construct an

argument list that contains an

\defn{implied object argument}

as the first argument in the list to denote

the object to be operated on.

\pnum

For implicit object member functions, the type of the implicit object

parameter is

\begin{itemize}

\item ``lvalue reference to \cv{}~\tcode{X}'' for functions declared

without a \grammarterm{ref-qualifier} or with the

\tcode{\&} \grammarterm{ref-qualifier}

\item ``rvalue reference to \cv{}~\tcode{X}'' for functions declared with the

\tcode{\&\&} \grammarterm{ref-qualifier}

\end{itemize}

where

\tcode{X}

is the class of which the function is a direct member and

\cv{}

is the cv-qualification on the

member function declaration.

\begin{example}

For a

\keyword{const}

member

function of class

\tcode{X},

the extra parameter is assumed to have type

``lvalue reference to

\tcode{const X}''.

\end{example}

For conversion functions that are implicit object member functions,

the function is considered to be a member of the

class of the implied object argument for the purpose of defining the

type of the implicit object parameter.

For non-conversion functions that are implicit object member functions

nominated by a \grammarterm{using-declaration}

in a derived class, the function is

considered to be a member of the derived class for the purpose of defining

the type of the implicit object parameter.

For static member functions, the implicit object parameter is considered

to match any object (since if the function is selected, the object is

discarded).

\begin{note}

No actual type is established for the implicit object parameter

of a static member function, and no attempt will be made to determine a

conversion sequence for that parameter\iref{over.match.best}.

\end{note}

\pnum

\indextext{implied object argument!implicit conversion sequences}%

During overload resolution, the implied object argument is

indistinguishable from other arguments.

The implicit object

parameter, however, retains its identity since

no user-defined conversions can be applied to achieve a type

match with it.

\indextext{implied object argument!non-static member function and}%

For implicit object member functions declared without a \grammarterm{ref-qualifier},

even if the implicit object parameter is not const-qualified,

an rvalue can be bound to the parameter

as long as in all other respects the argument can be

converted to the type of the implicit object parameter.

\begin{note}

The fact that such an argument is an rvalue does not

affect the ranking of implicit conversion sequences\iref{over.ics.rank}.

\end{note}

\pnum

Because other than in list-initialization only one user-defined conversion

is allowed

in an

implicit conversion sequence, special rules apply when selecting

the best user-defined conversion\iref{over.match.best,over.best.ics}.

\begin{example}

\begin{codeblock}

class T {

public:

T();

};

class C : T {

public:

C(int);

};

T a = 1; // error: no viable conversion (\tcode{T(C(1))} not considered)

\end{codeblock}

\end{example}

\pnum

In each case where conversion functions of a class \tcode{S} are considered

for initializing an object or reference of type \tcode{T},

the candidate functions include the result of a search

for the \grammarterm{conversion-function-id} \tcode{\keyword{operator} T}

in \tcode{S}.

\begin{note}

This search can find a specialization of

a conversion function template\iref{basic.lookup}.

\end{note}

Each such case also defines sets of \defnadj{permissible}{types}

for explicit and non-explicit conversion functions;

each (non-template) conversion function

that

\begin{itemize}

\item is a non-hidden member of \tcode{S},

\item yields a permissible type, and,

\item for the former set, is non-explicit

\end{itemize}

is also a candidate function.

If initializing an object, for any permissible type \cv{} \tcode{U}, any

\cvqual{cv2} \tcode{U}, \cvqual{cv2} \tcode{U\&}, or \cvqual{cv2} \tcode{U\&\&}

is also a permissible type.

If the set of permissible types for explicit conversion functions is empty,

any candidates that are explicit are discarded.

\pnum

In each case where a candidate is a function template, candidate

function template specializations

are generated using template argument deduction\iref{temp.over,temp.deduct}.

If a constructor template or conversion function template

has an \grammarterm{explicit-specifier}

whose \grammarterm{constant-expression} is value-dependent\iref{temp.dep},

template argument deduction is performed first and then,

if the context admits only candidates that

are not explicit and the generated specialization is explicit\iref{dcl.fct.spec},

it will be removed from the candidate set.

Those candidates are then handled as candidate

functions in the usual way.

\begin{footnote}

The process of argument deduction fully

determines the parameter types of

the

function template specializations,

i.e., the parameters of

function template specializations

contain

no template parameter types.

Therefore, except where specified otherwise,

function template specializations

and non-template functions\iref{dcl.fct} are treated equivalently

for the remainder of overload resolution.

\end{footnote}

A given name can refer to, or a conversion can consider,

one or more function templates as well as a set of non-template functions.

In such a case, the

candidate functions generated from each function template are combined

with the set of non-template candidate functions.

\pnum

A

defaulted move special member function\iref{class.copy.ctor,class.copy.assign}

that is defined as deleted

is excluded from the set of candidate functions in all contexts.

A constructor inherited from class type \tcode{C}\iref{class.inhctor.init}

that has a first parameter of type ``reference to \cvqual{cv1} \tcode{P}''

(including such a constructor instantiated from a template)

is excluded from the set of candidate functions

when constructing an object of type \cvqual{cv2} \tcode{D}

if the argument list has exactly one argument and

\tcode{C} is reference-related to \tcode{P} and

\tcode{P} is reference-related to \tcode{D}.

\begin{example}

\begin{codeblock}

struct A {

A(); // \#1

A(A &&); // \#2

template<typename T> A(T &&); // \#3

};

struct B : A {

using A::A;

B(const B &); // \#4

B(B &&) = default; // \#5, implicitly deleted

struct X { X(X &&) = delete; } x;

};

extern B b1;

B b2 = static_cast<B&&>(b1); // calls \#4: \#1 is not viable, \#2, \#3, and \#5 are not candidates

struct C { operator B&&(); };

B b3 = C(); // calls \#4

\end{codeblock}

\end{example}

\rSec3[over.match.call]{Function call syntax}%

\rSec4[over.match.call.general]{General}%

\indextext{overloading!resolution!function call syntax|(}

\pnum

In a function call\iref{expr.call}

\begin{ncsimplebnf}

postfix-expression \terminal{(} \opt{expression-list} \terminal{)}

\end{ncsimplebnf}

if the \grammarterm{postfix-expression} names at least one function or

function template,

overload resolution is applied as specified in \ref{over.call.func}.

If the \grammarterm{postfix-expression} denotes an object of class type, overload

resolution is applied as specified in \ref{over.call.object}.

\pnum

If the \grammarterm{postfix-expression} is the address of an overload set,

overload resolution is applied using that set as described above.

\begin{note}

No implied object argument is added in this case.

\end{note}

If the function selected by overload resolution is

an implicit object member function,

the program is ill-formed.

\begin{note}

The resolution of the address of an

overload set in other contexts is described in \ref{over.over}.

\end{note}

\rSec4[over.call.func]{Call to designated function}

\pnum

Of interest in~\ref{over.call.func} are only those function calls

in which the \grammarterm{postfix-expression} ultimately contains

an \grammarterm{id-expression} or \grammarterm{splice-expression}

that designates one or more functions.

Such a

\grammarterm{postfix-expression},

perhaps nested arbitrarily deep in

parentheses, has one of the following forms:

\begin{ncbnf}

postfix-expression:\br

postfix-expression \terminal{.} id-expression\br

postfix-expression \terminal{.} splice-expression\br

postfix-expression \terminal{->} id-expression\br

postfix-expression \terminal{->} splice-expression\br

id-expression\br

splice-expression

\end{ncbnf}

These represent two syntactic subcategories of function calls:

qualified function calls and unqualified function calls.

\pnum

In qualified function calls,

the function is designated by

an \grammarterm{id-expression} or \grammarterm{splice-expression} $E$

preceded by an \tcode{->} or \tcode{.} operator.

Since the

construct

\tcode{A->B}

is generally equivalent to

\tcode{(*A).B},

the rest of

\ref{over} assumes, without loss of generality, that all member

function calls have been normalized to the form that uses an

object and the

\tcode{.}

operator.

Furthermore, \ref{over} assumes that

the

\grammarterm{postfix-expression}

that is the left operand of the

\tcode{.}

operator

has type ``\cv{}~\tcode{T}''

where

\tcode{T}

denotes a class.

\begin{footnote}

Note that cv-qualifiers on the type of objects are

significant in overload

resolution for

both glvalue and class prvalue objects.

\end{footnote}

The set of candidate functions either

is the set found by name lookup\iref{class.member.lookup}

if $E$ is an \grammarterm{id-expression} or

is the set determined as specified in~\ref{expr.prim.splice}

if $E$ is a \grammarterm{splice-expression}.

The argument list is the

\grammarterm{expression-list}

in the call augmented by the addition of the left operand of

the

\tcode{.}

operator in the normalized member function call as the

implied object argument\iref{over.match.funcs}.

\pnum

In unqualified function calls, the function is designated by

an \grammarterm{id-expression} or a \grammarterm{splice-expression} $E$.

The set of candidate functions either

is the set found by name lookup\iref{basic.lookup}

if $E$ is an \grammarterm{id-expression} or

is the set determined as specified in~\ref{expr.prim.splice}

if $E$ is a \grammarterm{splice-expression}.

The set of candidate functions

consists either entirely of non-member functions or entirely of

member functions of some class

\tcode{T}.

In the former case or

if $E$ is either a \grammarterm{splice-expression} or

the address of an overload set,

the argument list is

the same as the

\grammarterm{expression-list}

in the call.

Otherwise, the argument list is the

\grammarterm{expression-list}

in the call augmented by the addition of an implied object

argument as in a qualified function call.

If the current class is, or is derived from, \tcode{T}, and the keyword

\keyword{this}\iref{expr.prim.this} refers to it,

\begin{itemize}

\item

if the unqualified function call

appears in a precondition assertion of a constructor

or a postcondition assertion of a destructor

and overload resolution selects a non-static member function,

the call is ill-formed;

\item

otherwise,

the implied object argument is

\tcode{(*\keyword{this})}.

\end{itemize}

Otherwise,

\begin{itemize}

\item

if overload resolution selects a non-static member function,

the call is ill-formed;

\item

otherwise,

a contrived object of type

\tcode{T}

becomes the implied object argument.

\begin{footnote}

An implied object argument is contrived to

correspond to the implicit object

parameter attributed to member functions during overload resolution.

It is not

used in

the call to the selected function.

Since the member functions all have the

same implicit

object parameter, the contrived object will not be the cause to select or

reject a

function.

\end{footnote}

\end{itemize}

\begin{example}

\begin{codeblock}

struct C {

bool a();

void b() {

a(); // OK, \tcode{(*this).a()}

}

void c(this const C&); // \#1

void c() &; // \#2

static void c(int = 0); // \#3

void d() {

c(); // error: ambiguous between \#2 and \#3

(C::c)(); // error: as above

(&(C::c))(); // error: cannot resolve address of overloaded \tcode{this->C::c}\iref{over.over}

(&C::c)(C{}); // selects \#1

(&C::c)(*this); // error: selects \#2, and is ill-formed\iref{over.match.call.general}

(&C::c)(); // selects \#3

}

void f(this const C&);

void g() const {

f(); // OK, \tcode{(*this).f()}

f(*this); // error: no viable candidate for \tcode{(*this).f(*this)}

this->f(); // OK

}

static void h() {

f(); // error: contrived object argument, but overload resolution

// picked a non-static member function

f(C{}); // error: no viable candidate

C{}.f(); // OK

}

void k(this int);

operator int() const;

void m(this const C& c) {

c.k(); // OK

}

C()

pre(a()) // error: implied \keyword{this} in constructor precondition

pre(this->a()) // OK

post(a()); // OK

~C()

pre(a()) // OK

post(a()) // error: implied \keyword{this} in destructor postcondition

post(this->a()); // OK

};

\end{codeblock}

\end{example}

\rSec4[over.call.object]{Call to object of class type}

\pnum

If the \grammarterm{postfix-expression} \tcode{E}

in the function call syntax evaluates

to a class object of type ``\cv{}~\tcode{T}'',

then the set of candidate functions

includes at least the function call operators of \tcode{T}.

The function call operators of \tcode{T}

are the results of a search for the name \tcode{\keyword{operator}()}

in the scope of \tcode{T}.

\pnum

In addition, for each non-explicit conversion function declared in \tcode{T} of the

form

\begin{ncsimplebnf}

\keyword{operator} conversion-type-id \terminal{(\,)} \opt{cv-qualifier-seq} \opt{ref-qualifier} \opt{noexcept-specifier} \opt{attribute-specifier-seq} \terminal{;}

\end{ncsimplebnf}

where the optional

\grammarterm{cv-qualifier-seq}

is the same cv-qualification as, or a greater cv-qualification than,

\cv{},

and where

\grammarterm{conversion-type-id}

denotes the type ``pointer to function

of ($\tcode{P}_1, \dotsc, \tcode{P}_n$) returning \tcode{R}'',

or the type ``reference to pointer to function

of ($\tcode{P}_1, \dotsc, \tcode{P}_n$) returning \tcode{R}'',

or the type

``reference to function of ($\tcode{P}_1, \dotsc, \tcode{P}_n$)

returning \tcode{R}'', a \defn{surrogate call function} with the unique name

\placeholder{call-function}

and having a declaration of the form

\begin{ncbnf}

\terminal{R} \placeholder{call-function} \terminal{(} conversion-type-id \ %

\terminal{F, P$_1$ a$_1$, $\dotsc$, P$_n$ a$_n$);}

\end{ncbnf}

is also considered as a candidate function.

\begin{note}

If a surrogate call function is selected by overload resolution,

the behavior is as described in~\ref{over.call}.

\end{note}

Similarly, surrogate

call functions are added to the set of candidate functions for

each non-explicit conversion function declared in a base class of

\tcode{T}

provided the function is not hidden within

\tcode{T}

by another

intervening declaration.

\begin{footnote}

Note that this construction can yield

candidate call functions that cannot be

differentiated one from the other by overload resolution because they have

identical

declarations or differ only in their return type.

The call will be ambiguous

if overload

resolution cannot select a match to the call that is uniquely better than such

undifferentiable functions.

\end{footnote}

\pnum

The argument list submitted to overload resolution consists of

the argument expressions present in the function call syntax

preceded by the implied object argument

\tcode{(E)}.

\begin{note}

When comparing the

call against the function call operators, the implied object

argument is compared against the object parameter of the

function call operator.

When comparing the call against a

surrogate call function, the implied object argument is compared

against the first parameter of the surrogate call function.

\end{note}

\begin{example}

\begin{codeblock}

int f1(int);

int f2(float);

typedef int (*fp1)(int);

typedef int (*fp2)(float);

struct A {

operator fp1() { return f1; }

operator fp2() { return f2; }

} a;

int i = a(1); // calls \tcode{f1} via pointer returned from conversion function

\end{codeblock}

\end{example}

\indextext{overloading!resolution!function call syntax|)}

\rSec3[over.match.oper]{Operators in expressions}%

\indextext{overloading!resolution!operators}

\pnum

If no operand of an operator in an expression has a type that is a class

or an enumeration, the operator is assumed to be a built-in operator

and interpreted according to \ref{expr.compound}.

\begin{note}

Because

\tcode{.},

\tcode{.*},

and

\tcode{::}

cannot be overloaded,

these operators are always built-in operators interpreted according to

\ref{expr.compound}.

\tcode{?:}

cannot be overloaded, but the rules in this subclause are used to determine

the conversions to be applied to the second and third operands when they

have class or enumeration type\iref{expr.cond}.

\end{note}

\begin{example}

\begin{codeblock}

struct String {

String (const String&);

String (const char*);

operator const char* ();

};

String operator + (const String&, const String&);

void f() {

const char* p= "one" + "two"; // error: cannot add two pointers; overloaded \tcode{\keyword{operator}+} not considered

// because neither operand has class or enumeration type

int I = 1 + 1; // always evaluates to \tcode{2} even if class or enumeration types exist

// that would perform the operation.

}

\end{codeblock}

\end{example}

\pnum

If either operand has a type that is a class or an enumeration, a

user-defined operator function can be declared that implements

this operator or a user-defined conversion can be necessary to

convert the operand to a type that is appropriate for a built-in

operator.

In this case, overload resolution is used to determine

which operator function or built-in operator is to be invoked to implement the

operator.

Therefore, the operator notation is first transformed

to the equivalent function-call notation as summarized in

\tref{over.match.oper}

(where \tcode{@} denotes one of the operators covered in the specified subclause).

However, the operands are sequenced in the order prescribed

for the built-in operator\iref{expr.compound}.

\begin{floattable}{Relationship between operator and function call notation}{over.match.oper}

{l|l|l|l}

\topline

\hdstyle{Subclause} & \hdstyle{Expression} & \hdstyle{As member function} & \hdstyle{As non-member function} \\ \capsep

\ref{over.unary} & \tcode{@a} & \tcode{(a).\keyword{operator}@ (\,)} & \tcode{\keyword{operator}@(a)} \\

\ref{over.binary} & \tcode{a@b} & \tcode{(a).\keyword{operator}@ (b)} & \tcode{\keyword{operator}@(a, b)} \\

\ref{over.assign} & \tcode{a=b} & \tcode{(a).\keyword{operator}= (b)} & \\

\ref{over.sub} & \tcode{a[b]} & \tcode{(a).\keyword{operator}[](b)} & \\

\ref{over.ref} & \tcode{a->} & \tcode{(a).\keyword{operator}->(\,)} & \\

\ref{over.inc} & \tcode{a@} & \tcode{(a).\keyword{operator}@ (0)} & \tcode{\keyword{operator}@(a, 0)} \\

\end{floattable}

\pnum

For a unary operator \tcode{@}

with an operand of type \cvqual{cv1} \tcode{T1},

and for a binary operator \tcode{@}

with a left operand of type \cvqual{cv1} \tcode{T1}

and a right operand of type \cvqual{cv2} \tcode{T2},

four sets of candidate functions, designated

\defnx{member candidates}{member candidate},

\defnx{non-member candidates}{non-member candidate},

\defnx{built-in candidates}{built-in candidate},

and

\defnx{rewritten candidates}{rewritten candidate},

are constructed as follows:

\begin{itemize}

\item

If \tcode{T1} is a complete class type or a class currently being defined,

the set of member candidates is the result of a search for

\tcode{\keyword{operator}@} in the scope of \tcode{T1};

otherwise, the set of member candidates is empty.

\item

For the operators \tcode{=}, \tcode{[]}, or \tcode{->},

the set of non-member candidates is empty;

otherwise, it includes the result of unqualified lookup for

\tcode{\keyword{operator}@}

in the rewritten function call\iref{basic.lookup.unqual,basic.lookup.argdep},

ignoring all member functions.

However, if no operand has a class type, only those non-member

functions in the lookup set that have a first parameter of type

\tcode{T1}

or ``reference to \cv{}~\tcode{T1}'',

when

\tcode{T1}

is an enumeration type,

or (if there is a right operand) a second parameter of type

\tcode{T2}

or ``reference to \cv{}~\tcode{T2}'',

when

\tcode{T2}

is an enumeration type,

are candidate functions.

\item

For the operator

\tcode{,},

the unary operator

\tcode{\&},

or the operator

\tcode{->},

the built-in candidates set is empty.

For all other operators, the built-in candidates include all

of the candidate operator functions defined in~\ref{over.built} that,

compared to the given operator,

\begin{itemize}

\item

have the same operator name, and

\item

accept the same number of operands, and

\item

accept operand types to which the given operand or

operands can be converted according to \ref{over.best.ics}, and

\item

do not have the same parameter-type-list as any non-member candidate

or rewritten non-member candidate

that is not a function template specialization.

\end{itemize}

\item

The rewritten candidate set is determined as follows:

\begin{itemize}

\item

For the relational\iref{expr.rel} operators,

the rewritten candidates include

all non-rewritten candidates

for the expression \tcode{x <=> y}.

\item

For the

relational\iref{expr.rel} and

three-way comparison\iref{expr.spaceship}

operators,

the rewritten candidates also include

a synthesized candidate,

with the order of the two parameters reversed,

for each non-rewritten candidate

for the expression

\tcode{y <=> x}.

\item

For the \tcode{!=} operator\iref{expr.eq},

the rewritten candidates

include all non-rewritten candidates

for the expression \tcode{x == y}

that are rewrite targets with first operand \tcode{x} (see below).

\item

For the equality operators,

the rewritten candidates also include a synthesized candidate,

with the order of the two parameters reversed,

for each non-rewritten candidate

for the expression \tcode{y == x}

that is a rewrite target with first operand \tcode{y}.

\item

For all other operators, the rewritten candidate set is empty.

\end{itemize}

\begin{note}

A candidate synthesized from a member candidate has its

object parameter as the second parameter, thus implicit conversions

are considered for the first, but not for the second, parameter.

\end{note}

\end{itemize}

\pnum

A non-template function or function template \tcode{F} named \tcode{\keyword{operator}==}

is a rewrite target with first operand \tcode{o}

unless a search for the name \tcode{\keyword{operator}!=} in the scope $S$

from the instantiation context of the operator expression

finds a function or function template

that would correspond\iref{basic.scope.scope} to \tcode{F}

if its name were \tcode{\keyword{operator}==},

where $S$ is the scope of the class type of \tcode{o}

if \tcode{F} is a class member, and

the namespace scope of which \tcode{F} is a member otherwise.

A function template specialization named \tcode{\keyword{operator}==} is a rewrite target

if its function template is a rewrite target.

\begin{example}

\begin{codeblock}

struct A {};

template<typename T> bool operator==(A, T); // \#1

bool a1 = 0 == A(); // OK, calls reversed \#1

template<typename T> bool operator!=(A, T);

bool a2 = 0 == A(); // error, \#1 is not a rewrite target

struct B {

bool operator==(const B&); // \#2

};

struct C : B {

C();

C(B);

bool operator!=(const B&); // \#3

};

bool c1 = B() == C(); // OK, calls \#2; reversed \#2 is not a candidate

// because search for \tcode{\keyword{operator}!=} in \tcode{C} finds \#3

bool c2 = C() == B(); // error: ambiguous between \#2 found when searching \tcode{C} and

// reversed \#2 found when searching \tcode{B}

struct D {};

template<typename T> bool operator==(D, T); // \#4

inline namespace N {

template<typename T> bool operator!=(D, T); // \#5

}

bool d1 = 0 == D(); // OK, calls reversed \#4; \#5 does not forbid \#4 as a rewrite target

\end{codeblock}

\end{example}

\pnum

For the first parameter of the built-in assignment operators,

only standard conversion sequences\iref{over.ics.scs} are considered.

\pnum

For all other operators, no such restrictions apply.

\pnum

The set of candidate functions for overload resolution

for some operator \tcode{@}

is the

union of

the member candidates,

the non-member candidates,

the built-in candidates,

and the rewritten candidates

for that operator \tcode{@}.

\pnum

The argument list contains all of the

operands of the operator.

The best function from the set of candidate functions is selected

according to~\ref{over.match.viable}

and~\ref{over.match.best}.

\begin{footnote}

If the set of candidate functions is empty,

overload resolution is unsuccessful.

\end{footnote}

\begin{example}

\begin{codeblock}

struct A {

operator int();

};

A operator+(const A&, const A&);

void m() {

A a, b;

a + b; // \tcode{\keyword{operator}+(a, b)} chosen over \tcode{int(a) + int(b)}

}

\end{codeblock}

\end{example}

\pnum

If a rewritten \tcode{\keyword{operator}<=>} candidate

is selected by overload resolution

for an operator \tcode{@},

\tcode{x @ y}

is interpreted as

\tcode{0 @ (y <=> x)}

if the selected candidate is a synthesized candidate

with reversed order of parameters,

or \tcode{(x <=> y) @ 0} otherwise,

using the selected rewritten \tcode{\keyword{operator}<=>} candidate.

Rewritten candidates for the operator \tcode{@}

are not considered in the context of the resulting expression.

\pnum

If a rewritten \tcode{\keyword{operator}==} candidate

is selected by overload resolution

for an operator \tcode{@},

its return type shall be \cv{} \tcode{bool}, and

\tcode{x @ y} is interpreted as:

\begin{itemize}

\item

if \tcode{@} is \tcode{!=}

and the selected candidate is a synthesized candidate

with reversed order of parameters,

\tcode{!(y == x)},

\item

otherwise, if \tcode{@} is \tcode{!=},

\tcode{!(x == y)},

\item

otherwise (when \tcode{@} is \tcode{==}),

\tcode{y == x},

\end{itemize}

in each case using the selected rewritten \tcode{\keyword{operator}==} candidate.

\pnum

If a built-in candidate is selected by overload resolution, the

operands of class type are converted to the types of the corresponding parameters

of the selected operation function, except that the second standard conversion

sequence of a user-defined conversion sequence\iref{over.ics.user} is not applied.

Then the operator is treated as the corresponding

built-in operator and interpreted according to \ref{expr.compound}.

\begin{example}

\begin{codeblock}

struct X {

operator double();

};

struct Y {

operator int*();

};

int *a = Y() + 100.0; // error: pointer arithmetic requires integral operand

int *b = Y() + X(); // error: pointer arithmetic requires integral operand

\end{codeblock}

\end{example}

\pnum

The second operand of operator

\tcode{->}

is ignored in selecting an

\tcode{\keyword{operator}->}

function, and is not an argument when the

\tcode{\keyword{operator}->}

function is called.

When

\tcode{\keyword{operator}->}

returns, the operator

\tcode{->}

is applied to the value returned, with the original second

operand.

\begin{footnote}

If the value returned by the

\tcode{\keyword{operator}->}

function has class type, this can result in selecting and calling another

\tcode{\keyword{operator}->}

function.

The process repeats until an

\tcode{\keyword{operator}->}