operator overloading
Customizes the C++ operators for operands of userdefined types.
Contents 
[edit] Syntax
Overloaded operators are functions with special function names:
operator op

(1)  
operator type

(2)  
operator new operator new []

(3)  
operator delete operator delete []

(4)  
operator "" suffixidentifier

(5)  (since C++11)  
operator co_await

(6)  (since C++20)  
op    any of the following operators:+  * / % ^ &  ~ ! = < > += = *= /= %= ^= &= = << >> >>= <<= == != <= >= <=> (since C++20) &&  ++  , >* > ( ) [ ] 
[edit] Overloaded operators
When an operator appears in an expression, and at least one of its operands has a class type or an enumeration type, then overload resolution is used to determine the userdefined function to be called among all the functions whose signatures match the following:
Expression  As member function  As nonmember function  Example 

@a  (a).operator@ ( )  operator@ (a)  !std::cin calls std::cin.operator!() 
a@b  (a).operator@ (b)  operator@ (a, b)  std::cout << 42 calls std::cout.operator<<(42) 
a=b  (a).operator= (b)  cannot be nonmember  Given std::string s;, s = "abc"; calls s.operator=("abc") 
a(b...)  (a).operator()(b...)  cannot be nonmember  Given std::random_device r;, auto n = r(); calls r.operator()() 
a[b]  (a).operator[](b)  cannot be nonmember  Given std::map<int, int> m;, m[1] = 2; calls m.operator[](1) 
a>  (a).operator> ( )  cannot be nonmember  Given std::unique_ptr<S> p;, p>bar() calls p.operator>() 
a@  (a).operator@ (0)  operator@ (a, 0)  Given std::vector<int>::iterator i;, i++ calls i.operator++(0) 
in this table, 
In addition, for comparison operators ==, !=, <, >, <=, >=, <=>, overload resolution also considers the rewritten candidates generated from operator== or operator<=>. 
(since C++20) 
Note: for overloading co_await
, (since C++20)userdefined conversion functions, userdefined literals, allocation and deallocation see their respective articles.
Overloaded operators (but not the builtin operators) can be called using function notation:
std::string str = "Hello, "; str.operator+=("world"); // same as str += "world"; operator<<(operator<<(std::cout, str) , '\n'); // same as std::cout << str << '\n'; // (since C++17) except for sequencing
[edit] Restrictions
 The operators
::
(scope resolution),.
(member access),.*
(member access through pointer to member), and?:
(ternary conditional) cannot be overloaded.  New operators such as
**
,<>
, or&
cannot be created.  The overloads of operators
&&
and
lose shortcircuit evaluation.  The overload of operator
>
must either return a raw pointer, or return an object (by reference or by value) for which operator>
is in turn overloaded.  It is not possible to change the precedence, grouping, or number of operands of operators.

(until C++17) 
[edit] Canonical implementations
Other than the restrictions above, the language puts no other constraints on what the overloaded operators do, or on the return type (it does not participate in overload resolution), but in general, overloaded operators are expected to behave as similar as possible to the builtin operators: operator+ is expected to add, rather than multiply its arguments, operator= is expected to assign, etc. The related operators are expected to behave similarly (operator+ and operator+= do the same additionlike operation). The return types are limited by the expressions in which the operator is expected to be used: for example, assignment operators return by reference to make it possible to write a = b = c = d, because the builtin operators allow that.
Commonly overloaded operators have the following typical, canonical forms:^{[1]}
[edit] Assignment operator
The assignment operator (operator=) has special properties: see copy assignment and move assignment for details.
The canonical copyassignment operator is expected to perform no action on selfassignment, and to return the lhs by reference:
// assume the object holds reusable storage, such as a heapallocated buffer mArray T& operator=(const T& other) // copy assignment { if (this != &other) { // selfassignment check expected if (other.size != size) { // storage cannot be reused delete[] mArray; // destroy storage in this size = 0; mArray = nullptr; // preserve invariants in case next line throws mArray = new int[other.size]; // create storage in this size = other.size; } std::copy(other.mArray, other.mArray + other.size, mArray); } return *this; }
The canonical move assignment is expected to leave the movedfrom object in valid state (that is, a state with class invariants intact), and either do nothing or at least leave the object in a valid state on selfassignment, and return the lhs by reference to nonconst, and be noexcept:
T& operator=(T&& other) noexcept // move assignment { if(this != &other) { // noop on selfmoveassignment (delete[]/size=0 also ok) delete[] mArray; // delete this storage mArray = std::exchange(other.mArray, nullptr); // leave movedfrom in valid state size = std::exchange(other.size, 0); } return *this; }
In those situations where copy assignment cannot benefit from resource reuse (it does not manage a heapallocated array and does not have a (possibly transitive) member that does, such as a member std::vector or std::string), there is a popular convenient shorthand: the copyandswap assignment operator, which takes its parameter by value (thus working as both copy and moveassignment depending on the value category of the argument), swaps with the parameter, and lets the destructor clean it up.
This form automatically provides strong exception guarantee, but prohibits resource reuse.
[edit] Stream extraction and insertion
The overloads of operator>>
and operator<<
that take a std::istream& or std::ostream& as the left hand argument are known as insertion and extraction operators. Since they take the userdefined type as the right argument (b
in a@b), they must be implemented as nonmembers.
std::ostream& operator<<(std::ostream& os, const T& obj) { // write obj to stream return os; } std::istream& operator>>(std::istream& is, T& obj) { // read obj from stream if( /* T could not be constructed */ ) is.setstate(std::ios::failbit); return is; }
These operators are sometimes implemented as friend functions.
[edit] Function call operator
When a userdefined class overloads the function call operator, operator(), it becomes a FunctionObject type.
An object of such a type can be used in a functioncalllike expression:
// An object of this type represents a linear function of one variable a*x + b. struct Linear { double a, b; double operator()(double x) const { return a*x + b; } }; int main() { Linear f{2, 1}; // Represents function 2x + 1. Linear g{1, 0}; // Represents function x. // f and g are objects that can be used like a function. double f_0 = f(0); double f_1 = f(1); double g_0 = g(0); }
The following are two alternatives to such an approach that don't use overloading but have disadvantages. 1. Using global variables:
double a, b; // Bad: Global variables. double linear(double x) { return a*x + b; } int main() { a = 2; b = 1; double f_0 = linear(0); double f_1 = linear(1); // Bad: Need to reassign the parameters to be able to calculate a different function: a = 1; b = 0; double g_0 = linear(0); }
2. Using additional parameters:
double linear(double a, double b, double x) { return a*x + b; } int main() { double f_0 = linear(2, 1, 0); // Bad: Have to repeat the same parameters again: double f_1 = linear(2, 1, 1); double g_0 = linear(1, 0, 0); }
Many standard algorithms, from std::sort to std::accumulate accept FunctionObjects to customize behavior. There are no particularly notable canonical forms of operator(), but to illustrate the usage
struct Sum { int sum; Sum() : sum(0) { } void operator()(int n) { sum += n; } }; Sum s = std::for_each(v.begin(), v.end(), Sum());
See also lambdas.
[edit] Increment and decrement
When the postfix increment and decrement appear in an expression, the corresponding userdefined function (operator++ or operator) is called with an integer argument 0
. Typically, it is implemented as T operator++(int), where the argument is ignored. The postfix increment and decrement operator is usually implemented in terms of the prefix version:
struct X { X& operator++() { // actual increment takes place here return *this; } X operator++(int) { X tmp(*this); // copy operator++(); // preincrement return tmp; // return old value } };
Although canonical form of preincrement/predecrement returns a reference, as with any operator overload, the return type is userdefined; for example the overloads of these operators for std::atomic return by value.
[edit] Binary arithmetic operators
Binary operators are typically implemented as nonmembers to maintain symmetry (for example, when adding a complex number and an integer, if operator+
is a member function of the complex type, then only complex+integer would compile, and not integer+complex). Since for every binary arithmetic operator there exists a corresponding compound assignment operator, canonical forms of binary operators are implemented in terms of their compound assignments:
class X { public: X& operator+=(const X& rhs) // compound assignment (does not need to be a member, { // but often is, to modify the private members) /* addition of rhs to *this takes place here */ return *this; // return the result by reference } // friends defined inside class body are inline and are hidden from nonADL lookup friend X operator+(X lhs, // passing lhs by value helps optimize chained a+b+c const X& rhs) // otherwise, both parameters may be const references { lhs += rhs; // reuse compound assignment return lhs; // return the result by value (uses move constructor) } };
[edit] Relational operators
Standard algorithms such as std::sort and containers such as std::set expect operator< to be defined, by default, for the userprovided types, and expect it to implement strict weak ordering (thus satisfying the Compare requirements). An idiomatic way to implement strict weak ordering for a structure is to use lexicographical comparison provided by std::tie:
struct Record { std::string name; unsigned int floor; double weight; friend bool operator<(const Record& l, const Record& r) { return std::tie(l.name, l.floor, l.weight) < std::tie(r.name, r.floor, r.weight); // keep the same order } };
Typically, once operator< is provided, the other relational operators are implemented in terms of operator<.
inline bool operator< (const X& lhs, const X& rhs){ /* do actual comparison */ } inline bool operator> (const X& lhs, const X& rhs){ return rhs < lhs; } inline bool operator<=(const X& lhs, const X& rhs){ return !(lhs > rhs); } inline bool operator>=(const X& lhs, const X& rhs){ return !(lhs < rhs); }
Likewise, the inequality operator is typically implemented in terms of operator==:
inline bool operator==(const X& lhs, const X& rhs){ /* do actual comparison */ } inline bool operator!=(const X& lhs, const X& rhs){ return !(lhs == rhs); }
When threeway comparison (such as std::memcmp or std::string::compare) is provided, all six relational operators may be expressed through that:
inline bool operator==(const X& lhs, const X& rhs){ return cmp(lhs,rhs) == 0; } inline bool operator!=(const X& lhs, const X& rhs){ return cmp(lhs,rhs) != 0; } inline bool operator< (const X& lhs, const X& rhs){ return cmp(lhs,rhs) < 0; } inline bool operator> (const X& lhs, const X& rhs){ return cmp(lhs,rhs) > 0; } inline bool operator<=(const X& lhs, const X& rhs){ return cmp(lhs,rhs) <= 0; } inline bool operator>=(const X& lhs, const X& rhs){ return cmp(lhs,rhs) >= 0; }
The inequality operator is automatically generated by the compiler if operator== is defined. Likewise, the four relational operators are automatically generated by the compiler if the threeway comparison operator operator<=> is defined. operator== and operator<=>, in turn, are generated by the compiler if operator<=> is defined as defaulted: struct Record { std::string name; unsigned int floor; double weight; auto operator<=>(const Record&) = default; }; // records can now be compared with ==, !=, <, <=, >, and >= See default comparisons for details. 
(since C++20) 
[edit] Array subscript operator
Userdefined classes that provide arraylike access that allows both reading and writing typically define two overloads for operator[]: const and nonconst variants:
struct T { value_t& operator[](std::size_t idx) { return mVector[idx]; } const value_t& operator[](std::size_t idx) const { return mVector[idx]; } };
If the value type is known to be a builtin type, the const variant should return by value.
Where direct access to the elements of the container is not wanted or not possible or distinguishing between lvalue c[i] = v; and rvalue v = c[i]; usage, operator[] may return a proxy. see for example std::bitset::operator[].
To provide multidimensional array access semantics, e.g. to implement a 3D array access a[i][j][k] = x;, operator[] has to return a reference to a 2D plane, which has to have its own operator[] which returns a reference to a 1D row, which has to have operator[] which returns a reference to the element. To avoid this complexity, some libraries opt for overloading operator() instead, so that 3D access expressions have the Fortranlike syntax a(i, j, k) = x;
[edit] Bitwise arithmetic operators
Userdefined classes and enumerations that implement the requirements of BitmaskType are required to overload the bitwise arithmetic operators operator&, operator, operator^, operator~, operator&=, operator=, and operator^=, and may optionally overload the shift operators operator<< operator>>, operator>>=, and operator<<=. The canonical implementations usually follow the pattern for binary arithmetic operators described above.
[edit] Boolean negation operator
The operator operator! is commonly overloaded by the userdefined classes that are intended to be used in boolean contexts. Such classes also provide a userdefined conversion function to boolean type (see std::basic_ios for the standard library example), and the expected behavior of operator! is to return the value opposite of operator bool. 
(until C++11) 
Since the builtin operator ! performs contextual conversion to 
(since C++11) 
[edit] Rarely overloaded operators
The following operators are rarely overloaded:
 The addressof operator, operator&. If the unary & is applied to an lvalue of incomplete type and the complete type declares an overloaded operator&, the behavior is undefined (until C++11) it is unspecified whether the operator has the builtin meaning or the operator function is called (since C++11). Because this operator may be overloaded, generic libraries use std::addressof to obtain addresses of objects of userdefined types. The best known example of a canonical overloaded operator& is the Microsoft class CComPtr. An example of this operator's use in EDSL can be found in boost.spirit.
 The boolean logic operators, operator&& and operator. Unlike the builtin versions, the overloads cannot implement shortcircuit evaluation. Also unlike the builtin versions, they do not sequence their left operand before the right one. (until C++17) In the standard library, these operators are only overloaded for std::valarray.
 The comma operator, operator,. Unlike the builtin version, the overloads do not sequence their left operand before the right one. (until C++17) Because this operator may be overloaded, generic libraries use expressions such as a,void(),b instead of a,b to sequence execution of expressions of userdefined types. The boost library uses
operator,
in boost.assign, boost.spirit, and other libraries. The database access library SOCI also overloadsoperator,
.  The member access through pointer to member operator>*. There are no specific downsides to overloading this operator, but it is rarely used in practice. It was suggested that it could be part of smart pointer interface, and in fact is used in that capacity by actors in boost.phoenix. It is more common in EDSLs such as cpp.react.
[edit] Example
#include <iostream> class Fraction { int gcd(int a, int b) { return b == 0 ? a : gcd(b, a % b); } int n, d; public: Fraction(int n, int d = 1) : n(n/gcd(n, d)), d(d/gcd(n, d)) { } int num() const { return n; } int den() const { return d; } Fraction& operator*=(const Fraction& rhs) { int new_n = n * rhs.n/gcd(n * rhs.n, d * rhs.d); d = d * rhs.d/gcd(n * rhs.n, d * rhs.d); n = new_n; return *this; } }; std::ostream& operator<<(std::ostream& out, const Fraction& f) { return out << f.num() << '/' << f.den() ; } bool operator==(const Fraction& lhs, const Fraction& rhs) { return lhs.num() == rhs.num() && lhs.den() == rhs.den(); } bool operator!=(const Fraction& lhs, const Fraction& rhs) { return !(lhs == rhs); } Fraction operator*(Fraction lhs, const Fraction& rhs) { return lhs *= rhs; } int main() { Fraction f1(3, 8), f2(1, 2), f3(10, 2); std::cout << f1 << " * " << f2 << " = " << f1 * f2 << '\n' << f2 << " * " << f3 << " = " << f2 * f3 << '\n' << 2 << " * " << f1 << " = " << 2 * f1 << '\n'; }
Output:
3/8 * 1/2 = 3/16 1/2 * 5/1 = 5/2 2 * 3/8 = 3/4
[edit] Defect reports
The following behaviorchanging defect reports were applied retroactively to previously published C++ standards.
DR  Applied to  Behavior as published  Correct behavior 

CWG 1458  C++11  taking address of incomplete type that overloads addressof was undefined behavior  the behavior is only unspecified 
[edit] See Also
Common operators  

assignment  increment decrement 
arithmetic  logical  comparison  member access 
other 
a = b 
++a 
+a 
!a 
a == b 
a[b] 
a(...) 
Special operators  
static_cast converts one type to another related type 
[edit] References
 ↑ Operator Overloading on StackOverflow C++ FAQ