13 Overloading [over]

Not all function declarations can be overloaded. Those that cannot be overloaded are specified here. A program is ill-formed if it contains two such non-overloadable declarations in the same scope. [ Note: This restriction applies to explicit declarations in a scope, and between such declarations and declarations made through a using-declaration ([namespace.udecl]). It does not apply to sets of functions fabricated as a result of name lookup (e.g., because of using-directives) or overload resolution (e.g., for operator functions).  — end note ]

Certain function declarations cannot be overloaded:

• (2.1)

  Function declarations that differ only in the return type cannot be overloaded.

• (2.2)

  Member function declarations with the same name and the same parameter-type-list cannot be overloaded if any of them is a static member function declaration ([class.static]). Likewise, member function template declarations with the same name, the same parameter-type-list, and the same template parameter lists cannot be overloaded if any of them is a static member function template declaration. The types of the implicit object parameters constructed for the member functions for the purpose of overload resolution ([over.match.funcs]) are not considered when comparing parameter-type-lists for enforcement of this rule. In contrast, if there is no static member function declaration among a set of member function declarations with the same name and the same parameter-type-list, then these member function declarations can be overloaded if they differ in the type of their implicit object parameter. [ Example: the following illustrates this distinction:

  class X {
    static void f();
    void f();                     // ill-formed
    void f() const;               // ill-formed
    void f() const volatile;      // ill-formed
    void g();
    void g() const;               // OK: no static g
    void g() const volatile;      // OK: no static g
  };
  

   — end example ]

• (2.3)

  Member function declarations with the same name and the same parameter-type-list as well as member function template declarations with the same name, the same parameter-type-list, and the same template parameter lists cannot be overloaded if any of them, but not all, have a ref-qualifier ([dcl.fct]). [ Example:

  class Y {
    void h() &;
    void h() const &;             // OK
    void h() &&;                  // OK, all declarations have a ref-qualifier
    void i() &;
    void i() const;               // ill-formed, prior declaration of i
                                  // has a ref-qualifier
  };
  

   — end example ]

[ Note: As specified in [dcl.fct], function declarations that have equivalent parameter declarations declare the same function and therefore cannot be overloaded:

• (3.1)

  Parameter declarations that differ only in the use of equivalent typedef “types” are equivalent. A typedef is not a separate type, but only a synonym for another type ([dcl.typedef]). [ Example:

  typedef int Int;
  
  void f(int i);
  void f(Int i);                  // OK: redeclaration of f(int)
  void f(int i) { /* ... */ }
  void f(Int i) { /* ... */ }    // error: redefinition of f(int)
  
  

   — end example ]

  Enumerations, on the other hand, are distinct types and can be used to distinguish overloaded function declarations. [ Example:

  enum E { a };
  
  void f(int i) { /* ... */ }
  void f(E i)   { /* ... */ }
  

   — end example ]

• (3.2)

  Parameter declarations that differ only in a pointer * versus an array [] are equivalent. That is, the array declaration is adjusted to become a pointer declaration ([dcl.fct]). Only the second and subsequent array dimensions are significant in parameter types ([dcl.array]). [ Example:

  int f(char*);
  int f(char[]);                  // same as f(char*);
  int f(char[7]);                 // same as f(char*);
  int f(char[9]);                 // same as f(char*);
  
  int g(char(*)[10]);
  int g(char[5][10]);             // same as g(char(*)[10]);
  int g(char[7][10]);             // same as g(char(*)[10]);
  int g(char(*)[20]);             // different from g(char(*)[10]);
  

   — end example ]

• (3.3)

  Parameter declarations that differ only in that one is a function type and the other is a pointer to the same function type are equivalent. That is, the function type is adjusted to become a pointer to function type ([dcl.fct]). [ Example:

  void h(int());
  void h(int (*)());              // redeclaration of h(int())
  void h(int x()) { }             // definition of h(int())
  void h(int (*x)()) { }          // ill-formed: redefinition of h(int())
  

   — end example ]

• (3.4)

  Parameter declarations that differ only in the presence or absence of const and/or volatile are equivalent. That is, the const and volatile type-specifiers for each parameter type are ignored when determining which function is being declared, defined, or called. [ Example:

  typedef const int cInt;
  
  int f (int);
  int f (const int);              // redeclaration of f(int)
  int f (int) { /* ... */ }      // definition of f(int)
  int f (cInt) { /* ... */ }     // error: redefinition of f(int)
  

   — end example ]

  Only the const and volatile type-specifiers at the outermost level of the parameter type specification are ignored in this fashion; const and volatile type-specifiers buried within a parameter type specification are significant and can be used to distinguish overloaded function declarations.124 In particular, for any type T, “pointer to T,” “pointer to const T,” and “pointer to volatile T” are considered distinct parameter types, as are “reference to T,” “reference to const T,” and “reference to volatile T.”

• (3.5)

  Two parameter declarations that differ only in their default arguments are equivalent. [ Example: consider the following:

  void f (int i, int j);
  void f (int i, int j = 99);     // OK: redeclaration of f(int, int)
  void f (int i = 88, int j);     // OK: redeclaration of f(int, int)
  void f ();                      // OK: overloaded declaration of f
  
  void prog () {
      f (1, 2);                   // OK: call f(int, int)
      f (1);                      // OK: call f(int, int)
      f ();                       // Error: f(int, int) or f()?
  }
  

   — end example ]  — end note ]

Two function declarations of the same name refer to the same function if they are in the same scope and have equivalent parameter declarations ([over.load]). A function member of a derived class is not in the same scope as a function member of the same name in a base class. [ Example:

struct B {
  int f(int);
};

struct D : B {
  int f(const char*);
};

Here D::f(const char*) hides B::f(int) rather than overloading it.

void h(D* pd) {
  pd->f(1);                     // error:
                                // D::f(const char*) hides B::f(int)
  pd->B::f(1);                  // OK
  pd->f("Ben");                 // OK, calls D::f
}

 — end example ]

A locally declared function is not in the same scope as a function in a containing scope. [ Example:

void f(const char*);
void g() {
  extern void f(int);
  f("asdf");                    // error: f(int) hides f(const char*)
                                // so there is no f(const char*) in this scope
}

void caller () {
  extern void callee(int, int);
  {
    extern void callee(int);    // hides callee(int, int)
    callee(88, 99);             // error: only callee(int) in scope
  }
}

 — end example ]

Different versions of an overloaded member function can be given different access rules. [ Example:

class buffer {
private:
    char* p;
    int size;
protected:
    buffer(int s, char* store) { size = s; p = store; }
public:
    buffer(int s) { p = new char[size = s]; }
};

 — end example ]

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 candidate functions 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 implicit object parameter, and certain other properties of the candidate function. [ 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 ]

Overload resolution selects the function to call in seven distinct contexts within the language:

• (2.1)

  invocation of a function named in the function call syntax ([over.call.func]);

• (2.2)

  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 ([over.call.object]);

• (2.3)

  invocation of the operator referenced in an expression ([over.match.oper]);

• (2.4)

  invocation of a constructor for direct-initialization ([dcl.init]) of a class object ([over.match.ctor]);

• (2.5)

  invocation of a user-defined conversion for copy-initialization ([dcl.init]) of a class object ([over.match.copy]);

• (2.6)

  invocation of a conversion function for initialization of an object of a nonclass type from an expression of class type ([over.match.conv]); and

• (2.7)

  invocation of a conversion function for conversion to a glvalue or class prvalue to which a reference ([dcl.init.ref]) will be directly bound ([over.match.ref]).

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:

• (2.8)

  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 viable functions ([over.match.viable]).

• (2.9)

  Then the best viable function is selected based on the implicit conversion sequences ([over.best.ics]) needed to match each argument to the corresponding parameter of each viable function.

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 (Clause [class.access]) in the context in which it is used, the program is ill-formed.

A use of an overloaded function name without arguments is resolved in certain contexts to a function, a pointer to function or a pointer to member function for a specific function from the overload set. A function template name is considered to name a set of overloaded functions in such contexts. The function selected is the one whose type is identical to the function type of the target type required in the context. [ Note: That is, the class of which the function is a member is ignored when matching a pointer-to-member-function type.  — end note ] The target can be

• (1.1)

  an object or reference being initialized ([dcl.init], [dcl.init.ref]),

• (1.2)

  the left side of an assignment ([expr.ass]),

• (1.3)

  a parameter of a function ([expr.call]),

• (1.4)

  a parameter of a user-defined operator ([over.oper]),

• (1.5)

  the return value of a function, operator function, or conversion ([stmt.return]),

• (1.6)

  an explicit type conversion ([expr.type.conv], [expr.static.cast], [expr.cast]), or

• (1.7)

  a non-type template-parameter ([temp.arg.nontype]).

The overloaded function name can be preceded by the & operator. An overloaded function name shall not be used without arguments in contexts other than those listed. [ Note: Any redundant set of parentheses surrounding the overloaded function name is ignored ([expr.prim]).  — end note ]

If the name is a function template, template argument deduction is done ([temp.deduct.funcaddr]), and if the argument deduction succeeds, the resulting template argument list is used to generate a single function template specialization, which is added to the set of overloaded functions considered. [ Note: As described in [temp.arg.explicit], if deduction fails and the function template name is followed by an explicit template argument list, the template-id is then examined to see whether it identifies a single function template specialization. If it does, the template-id is considered to be an lvalue for that function template specialization. The target type is not used in that determination.  — end note ]

Non-member functions and static member functions match targets of type “pointer-to-function” or “reference-to-function.” Nonstatic member functions match targets of type “pointer-to-member-function”. If a non-static member function is selected, the reference to the overloaded function name is required to have the form of a pointer to member as described in [expr.unary.op].

If more than one function is selected, any function template specializations in the set are eliminated if the set also contains a non-template function, and any given function template specialization F1 is eliminated if the set contains a second function template specialization whose function template is more specialized than the function template of F1 according to the partial ordering rules of [temp.func.order]. After such eliminations, if any, there shall remain exactly one selected function.

[ Example:

int f(double);
int f(int);
int (*pfd)(double) = &f;        // selects f(double)
int (*pfi)(int) = &f;           // selects f(int)
int (*pfe)(...) = &f;           // error: type mismatch
int (&rfi)(int) = f;            // selects f(int)
int (&rfd)(double) = f;         // selects f(double)
void g() {
  (int (*)(int))&f;             // cast expression as selector
}

The initialization of pfe is ill-formed because no f() with type int(...) has been declared, and not because of any ambiguity. For another example,

struct X {
  int f(int);
  static int f(long);
};

int (X::*p1)(int)  = &X::f;     // OK
int    (*p2)(int)  = &X::f;     // error: mismatch
int    (*p3)(long) = &X::f;     // OK
int (X::*p4)(long) = &X::f;     // error: mismatch
int (X::*p5)(int)  = &(X::f);   // error: wrong syntax for
                                // pointer to member
int    (*p6)(long) = &(X::f);   // OK

 — end example ]

[ Note: If f() and g() are both overloaded functions, the cross product of possibilities must be considered to resolve f(&g), or the equivalent expression f(g).  — end note ]

[ Note: There are no standard conversions (Clause [conv]) of one pointer-to-function type into another. In particular, even if B is a public base of D, we have

D* f();
B* (*p1)() = &f;                // error

void g(D*);
void (*p2)(B*) = &g;            // error

 — end note ]

A function declaration having one of the following operator-function-ids as its name declares an operator function. A function template declaration having one of the following operator-function-ids as its name declares an operator function template. A specialization of an operator function template is also an operator function. An operator function is said to implement the operator named in its operator-function-id.

operator-function-id:
    operator operator

operator: one of
	new	delete	new[]	delete[]
	+	-	*	/	%	^	&	|	~
	!	=	<	>	+=	-=	*=	/=	%=
	^=	&=	|=	<<	>>	>>=	<<=	==	!=
	<=	>=	&&	||	++	--	,	->*	->
	( )	[ ]

[ Note: The last two operators are function call ([expr.call]) and subscripting ([expr.sub]). The operators new[], delete[], (), and [] are formed from more than one token.  — end note ]

Both the unary and binary forms of

+    -    *     &

can be overloaded.

The following operators cannot be overloaded:

.    .*   ::    ?:

nor can the preprocessing symbols # and ## (Clause [cpp]).

Operator functions are usually not called directly; instead they are invoked to evaluate the operators they implement ([over.unary] – [over.inc]). They can be explicitly called, however, using the operator-function-id as the name of the function in the function call syntax ([expr.call]). [ Example:

complex z = a.operator+(b);     // complex z = a+b;
void* p = operator new(sizeof(int)*n);

 — end example ]

The allocation and deallocation functions, operator new, operator new[], operator delete and operator delete, are described completely in [basic.stc.dynamic]. The attributes and restrictions found in the rest of this subclause do not apply to them unless explicitly stated in [basic.stc.dynamic].

An operator function shall either be a non-static member function or be a non-member function and have at least one parameter whose type is a class, a reference to a class, an enumeration, or a reference to an enumeration. It is not possible to change the precedence, grouping, or number of operands of operators. The meaning of the operators =, (unary) &, and , (comma), predefined for each type, can be changed for specific class and enumeration types by defining operator functions that implement these operators. Operator functions are inherited in the same manner as other base class functions.

The identities among certain predefined operators applied to basic types (for example, ++a ≡ a+=1) need not hold for operator functions. Some predefined operators, such as +=, require an operand to be an lvalue when applied to basic types; this is not required by operator functions.

An operator function cannot have default arguments ([dcl.fct.default]), except where explicitly stated below. Operator functions cannot have more or fewer parameters than the number required for the corresponding operator, as described in the rest of this subclause.

Operators not mentioned explicitly in subclauses [over.ass] through [over.inc] act as ordinary unary and binary operators obeying the rules of [over.unary] or [over.binary].

The candidate operator functions that represent the built-in operators defined in Clause [expr] are specified in this subclause. These candidate functions participate in the operator overload resolution process as described in [over.match.oper] and are used for no other purpose. [ Note: Because built-in operators take only operands with non-class type, and operator overload resolution occurs only when an operand expression originally has class or enumeration type, operator overload resolution can resolve to a built-in operator only when an operand has a class type that has a user-defined conversion to a non-class type appropriate for the operator, or when an operand has an enumeration type that can be converted to a type appropriate for the operator. Also note that some of the candidate operator functions given in this subclause are more permissive than the built-in operators themselves. As described in [over.match.oper], after a built-in operator is selected by overload resolution the expression is subject to the requirements for the built-in operator given in Clause [expr], and therefore to any additional semantic constraints given there. If there is a user-written candidate with the same name and parameter types as a built-in candidate operator function, the built-in operator function is hidden and is not included in the set of candidate functions.  — end note ]

In this subclause, the term promoted integral type is used to refer to those integral types which are preserved by integral promotion (including e.g. int and long but excluding e.g. char). Similarly, the term promoted arithmetic type refers to floating types plus promoted integral types. [ Note: In all cases where a promoted integral type or promoted arithmetic type is required, an operand of enumeration type will be acceptable by way of the integral promotions.  — end note ]

For every pair (T, VQ), where T is an arithmetic type, and VQ is either volatile or empty, there exist candidate operator functions of the form

VQ T& operator++(VQ T&);
T operator++(VQ T&, int);

For every pair (T, VQ), where T is an arithmetic type other than bool, and VQ is either volatile or empty, there exist candidate operator functions of the form

VQ T& operator--(VQ T&);
T operator--(VQ T&, int);

For every pair (T, VQ), where T is a cv-qualified or cv-unqualified object type, and VQ is either volatile or empty, there exist candidate operator functions of the form

T*VQ& operator++(T*VQ&);
T*VQ& operator--(T*VQ&);
T*    operator++(T*VQ&, int);
T*    operator--(T*VQ&, int);

For every cv-qualified or cv-unqualified object type T, there exist candidate operator functions of the form

T&    operator*(T*);

For every function type T that does not have cv-qualifiers or a ref-qualifier, there exist candidate operator functions of the form

T&    operator*(T*);

For every type T there exist candidate operator functions of the form

T*    operator+(T*);

For every promoted arithmetic type T, there exist candidate operator functions of the form

T operator+(T);
T operator-(T);

For every promoted integral type T, there exist candidate operator functions of the form

T operator~(T);

For every quintuple (C1, C2, T, CV1, CV2), where C2 is a class type, C1 is the same type as C2 or is a derived class of C2, T is an object type or a function type, and CV1 and CV2 are cv-qualifier-seqs, there exist candidate operator functions of the form

CV12 T& operator->*(CV1 C1*, CV2 T C2::*);

where CV12 is the union of CV1 and CV2.

For every pair of promoted arithmetic types L and R, there exist candidate operator functions of the form

LR      operator*(L, R);
LR      operator/(L, R);
LR      operator+(L, R);
LR      operator-(L, R);
bool    operator<(L, R);
bool    operator>(L, R);
bool    operator<=(L, R);
bool    operator>=(L, R);
bool    operator==(L, R);
bool    operator!=(L, R);

where LR is the result of the usual arithmetic conversions between types L and R.

For every cv-qualified or cv-unqualified object type T there exist candidate operator functions of the form

T*      operator+(T*, std::ptrdiff_t);
T&      operator[](T*, std::ptrdiff_t);
T*      operator-(T*, std::ptrdiff_t);
T*      operator+(std::ptrdiff_t, T*);
T&      operator[](std::ptrdiff_t, T*);

For every T, where T is a pointer to object type, there exist candidate operator functions of the form

std::ptrdiff_t   operator-(T, T);

For every T, where T is an enumeration type, a pointer type, or std::nullptr_t, there exist candidate operator functions of the form

bool    operator<(T, T);
bool    operator>(T, T);
bool    operator<=(T, T);
bool    operator>=(T, T);
bool    operator==(T, T);
bool    operator!=(T, T);

For every pointer to member type T there exist candidate operator functions of the form

bool    operator==(T, T);
bool    operator!=(T, T);

For every pair of promoted integral types L and R, there exist candidate operator functions of the form

LR      operator%(L, R);
LR      operator&(L, R);
LR      operator^(L, R);
LR      operator|(L, R);
L       operator<<(L, R);
L       operator>>(L, R);

where LR is the result of the usual arithmetic conversions between types L and R.

For every triple (L, VQ, R), where L is an arithmetic type, VQ is either volatile or empty, and R is a promoted arithmetic type, there exist candidate operator functions of the form

VQ L&   operator=(VQ L&, R);
VQ L&   operator*=(VQ L&, R);
VQ L&   operator/=(VQ L&, R);
VQ L&   operator+=(VQ L&, R);
VQ L&   operator-=(VQ L&, R);

For every pair (T, VQ), where T is any type and VQ is either volatile or empty, there exist candidate operator functions of the form

T*VQ&   operator=(T*VQ&, T*);

For every pair (T, VQ), where T is an enumeration or pointer to member type and VQ is either volatile or empty, there exist candidate operator functions of the form

VQ T&   operator=(VQ T&, T);

For every pair (T, VQ), where T is a cv-qualified or cv-unqualified object type and VQ is either volatile or empty, there exist candidate operator functions of the form

T*VQ&   operator+=(T*VQ&, std::ptrdiff_t);
T*VQ&   operator-=(T*VQ&, std::ptrdiff_t);

For every triple (L, VQ, R), where L is an integral type, VQ is either volatile or empty, and R is a promoted integral type, there exist candidate operator functions of the form

VQ L&   operator%=(VQ L&, R);
VQ L&   operator<<=(VQ L&, R);
VQ L&   operator>>=(VQ L&, R);
VQ L&   operator&=(VQ L&, R);
VQ L&   operator^=(VQ L&, R);
VQ L&   operator|=(VQ L&, R);

There also exist candidate operator functions of the form

bool    operator!(bool);
bool    operator&&(bool, bool);
bool    operator||(bool, bool);

For every pair of promoted arithmetic types L and R, there exist candidate operator functions of the form

LR      operator?:(bool, L, R);

where LR is the result of the usual arithmetic conversions between types L and R. [ Note: As with all these descriptions of candidate functions, this declaration serves only to describe the built-in operator for purposes of overload resolution. The operator “?:” cannot be overloaded.  — end note ]

For every type T, where T is a pointer, pointer-to-member, or scoped enumeration type, there exist candidate operator functions of the form

T       operator?:(bool, T, T);