# Operator overloading

> An overloaded operator is an ordinary function with a special name that an operator expression calls. Arity, precedence and associativity never change, but evaluation guarantees can, and a few operators must be members.

- **Source:** C++ Atlas (https://cppatlas.com/topics/operator-overloading)
- **Track:** Expressions and functions
- **Estimated reading time:** 12 minutes
- **ISO C++ clauses:** [over.oper] (https://eel.is/c++draft/over.oper), [over.match.oper] (https://eel.is/c++draft/over.match.oper), [over.call] (https://eel.is/c++draft/over.call), [over.sub] (https://eel.is/c++draft/over.sub), [over.ref] (https://eel.is/c++draft/over.ref), [over.inc] (https://eel.is/c++draft/over.inc), [over.literal] (https://eel.is/c++draft/over.literal), [lex.ext] (https://eel.is/c++draft/lex.ext), [expr.log.and] (https://eel.is/c++draft/expr.log.and), [expr.comma] (https://eel.is/c++draft/expr.comma)
- **cppreference links:** [Operator overloading](https://en.cppreference.com/w/cpp/language/operators), [User-defined literals](https://en.cppreference.com/w/cpp/language/user_literal), [Member access operators](https://en.cppreference.com/w/cpp/language/operator_member_access), [Increment/decrement operators](https://en.cppreference.com/w/cpp/language/operator_incdec), [Logical operators](https://en.cppreference.com/w/cpp/language/operator_logical)
- **Prerequisites:** overload-resolution, name-lookup-and-adl, value-categories

## The one idea

An overloaded operator is a function. When at least one operand of an operator expression has class or enumeration type, the compiler gathers candidate functions named `operator@`, adds the built-in candidates, and runs ordinary overload resolution. Whatever wins is called like any other function, with the operands as arguments.

Everything that surprises people follows from that. The grammar does not change, so precedence, associativity and the number of operands are fixed by the token you chose, not by your function. But the *evaluation* rules of the built-in operator do not come along: a function call evaluates all of its arguments before the body runs, which is why an overloaded `&&` cannot short-circuit.

> **Mental model.** `a + b` is spelled like arithmetic and parsed like arithmetic, then dispatched like `operator+(a, b)` or `a.operator+(b)`. The parse belongs to the language; the meaning belongs to your function.

Candidate gathering and ranking are the subject of overload-resolution; comparison operators, including the rewriting that C++20 introduced, are covered in three-way-comparison. This topic is about which operator functions you may declare, where they must live, and how each special form behaves.

## What can be overloaded, and what must be a member

Almost every operator can be overloaded, including `->*`, the comma, `co_await`, `new` and `delete`, and conversion functions. A handful cannot: scope resolution `::`, member access `.`, pointer-to-member access `.*`, the conditional operator `?:`, and the keyword operators `sizeof`, `alignof`, `typeid` and `noexcept`. You cannot invent new operator tokens, and you cannot change how many operands an operator takes.

A non-member operator function needs at least one parameter whose type is a class, an enumeration, or a reference to one. That rule protects the built-in meaning of `1 + 2`.

```cpp
// int operator+(int, int);   // ill-formed: no class or enumeration parameter
enum class Flags { a = 1, b = 2 };
constexpr Flags operator|(Flags x, Flags y) {   // OK: enumeration operands
  return Flags(int(x) | int(y));
}
```

Four operators must be member functions: assignment `=`, function call `()`, subscript `[]`, and class member access `->`. The usual explanation for assignment is that every class already has an implicitly declared copy assignment operator, and a free function competing with it would be inconsistent. The other three are tied to the object they are applied to. C++23 relaxed one detail: `operator()` and `operator[]` may now be *static* member functions, which removes the hidden `this` parameter for stateless function objects.

> **Standardese.** [over.oper] says an operator function shall be a member function or have at least one parameter of class or enumeration type, and that operator functions cannot have default arguments except where the specific subclause allows it. [over.call] and, since C++23, [over.sub] are the two subclauses that allow them.

## Member or non-member: the symmetry argument

A member operator treats its left operand as the implicit object argument, and the implicit object argument never undergoes user-defined conversions. So a member `operator+` accepts conversions on the right but not on the left, and `2 + v` fails where `v + 2` works.

```cpp
struct Money {
  long cents;
  Money(long c) : cents(c) {}                  // implicit conversion from long
  Money operator+(const Money& o) const { return cents + o.cents; }
};

void demo(Money m) {
  Money a = m + 5;     // OK: 5 converts to Money for the parameter
  // Money b = 5 + m;  // ill-formed: 5 is not converted to the object argument
  (void)a;
}
```

The usual fix is a non-member, and the idiomatic non-member is a *hidden friend*: a `friend` function defined inside the class. It has the access a member would have, both operands get the same conversions, and because it is only found by argument-dependent lookup, it does not pollute overload sets for unrelated types.

```cpp
class Money {
  long cents_;
public:
  Money(long c) : cents_(c) {}
  friend Money operator+(Money a, Money b) { return a.cents_ + b.cents_; }
};

Money total(Money m) { return 5 + m; }   // OK: symmetric
```

The rule of thumb: operators that modify their left operand (`+=`, `<<=`, `=`, prefix `++`) are members; symmetric binary operators (`+`, `==`, `<=>`) are hidden friends or non-members; stream insertion `operator<<` cannot be a member of your class because the left operand is the stream.

## Calls, subscripts and arrows

`operator()` is the one operator with arbitrary arity and default arguments, which is what makes function objects and lambdas possible. Since C++23 it can be `static`, and the lambdas topic shows the matching `static` lambda syntax.

Since C++23, `operator[]` also takes any number of parameters, including zero, and may have default arguments. That is multidimensional subscripting, the access syntax `std::mdspan` uses.

```cpp
#include <cstddef>

struct Grid {
  int cells[4][4]{};
  int& operator[](std::size_t r, std::size_t c) { return cells[r][c]; }  // C++23
  static int operator()(int a, int b) { return a * b; }                // C++23
};

int demo() {
  Grid g;
  g[1, 2] = 5;              // calls operator[](1, 2)
  return g[1, 2] + Grid{}(2, 3);
}
```

To make room for that syntax, a comma expression directly inside square brackets was deprecated in C++20, and in C++23 the built-in subscript requires exactly one expression, so `arr[1, 2]` on a plain array is ill-formed. Clang rejects it; GCC still accepts it with a warning and treats it as the old comma expression, which is an extension.

`operator->` is unique because it is applied again to whatever it returns. The expression `x->m` becomes `(x.operator->())->m`, and if that result is itself a class object, its `operator->` is called, and so on until a raw pointer appears. This drill-down is what lets a smart pointer or a locking proxy return another proxy.

```cpp
#include <cstdio>

struct Raw   { int x = 42; };
struct Inner { Raw r;   Raw*   operator->() { std::puts("Inner"); return &r; } };
struct Outer { Inner i; Inner& operator->() { std::puts("Outer"); return i; } };

int read() { Outer o; return o->x; }   // prints Outer, then Inner; returns 42
```

`operator->*` gets no such treatment; it is an ordinary binary operator.

## Increment, decrement, and the dummy int

Prefix and postfix forms share a token, so the language tells them apart with a dummy parameter. `operator++()` is prefix; `operator++(int)` is postfix. When you write `x++`, the postfix function is called with the argument `0`. An explicit call `x.operator++(5)` passes 5, which nobody should rely on.

```cpp
struct Counter {
  int n = 0;
  Counter& operator++() { ++n; return *this; }               // prefix: return self
  Counter  operator++(int) { Counter old = *this; ++*this; return old; }  // postfix: copy
};
```

The conventional signatures follow the built-in operators: prefix returns an lvalue reference, postfix returns the old value by value. That copy is why prefix increment is the habit for iterators. Nothing in the language enforces these return types; they are convention.

## Operators that lose their built-in guarantees

Built-in `&&` and `||` evaluate the left operand first and skip the right one when the result is already known. Built-in comma evaluates left, discards it, then evaluates right. An overloaded version is a function call, so both operands are always evaluated.

```cpp
#include <cstdio>

struct B { bool v; };
B lhs() { std::puts("lhs"); return {false}; }
B rhs() { std::puts("rhs"); return {true}; }
bool operator&&(B a, B b) { return a.v && b.v; }

bool test() { return lhs() && rhs(); }   // prints lhs, then rhs: no short-circuit
```

C++17 recovered one piece. [over.match.oper] says that when an operator expression calls an overloaded operator, the operands are sequenced in the order prescribed for the built-in operator. So the left operand of an overloaded `&&`, `||` or comma is sequenced before the right one. The same rule makes overloaded `<<`, `>>` and subscript evaluate left to right, and overloaded assignment evaluate its right operand first. Before C++17 the order was unspecified. Short-circuiting is still gone, and it cannot be brought back.

> **Pitfall.** Overloading `&&`, `||` or the comma operator for a type that will appear in conditions silently changes code that looks like a guard, such as `p && p->ok()`. Expression-template libraries do it deliberately; ordinary types should not.

Unary `&` can also be overloaded, which is why generic code takes addresses with `std::addressof` rather than `&x`.

`operator new` and `operator delete` are overloadable too, but they are allocation functions, not operators applied to operands: a `new` expression calls them to obtain storage and then constructs the object itself. Their replacement and class-specific forms belong to dynamic-allocation-new-and-delete.

## User-defined literals

A literal operator gives a suffix meaning: `operator""_km` lets you write `12.5_km`. Suffixes that do not begin with an underscore are reserved for the standard library, as in `"abc"s` and `10ms`. C++23 deprecated the old spelling with a space between the quotes and the suffix, `operator"" _km`; in that form the suffix is a separate identifier, so a suffix such as `_Km` collides with the reserved-identifier rules.

The compiler chooses the operator from the kind of literal, and the permitted parameter lists are fixed:

- integer literal: `(unsigned long long)`, else the raw form `(const char*)`, else a numeric literal operator template `template <char...>`;
- floating literal: `(long double)`, else the raw form, else the template;
- string literal: `(const char*, std::size_t)`, or since C++20 a template whose parameter is a class-type non-type template parameter;
- character literal: `(char)` or the corresponding `char8_t`, `char16_t`, `char32_t` or `wchar_t` overload.

There is no conversion between these: if you only declare the `long double` form, `12_km` is ill-formed, because an integer literal never looks for it.

```cpp
constexpr long double operator""_km(long double v) { return v * 1000; }
constexpr long double operator""_km(unsigned long long v) { return v * 1000.0L; }

static_assert(12_km == 12000);    // needs the unsigned long long overload
static_assert(1.5_km == 1500);    // uses the long double overload
```

Literal operators are found by ordinary unqualified lookup, which is why the standard library puts its own in inline namespaces such as `std::literals::chrono_literals` that you bring in with a `using` directive.

## What to remember

- An overloaded operator is a function chosen by overload resolution; precedence, associativity and arity never change.
- `::`, `.`, `.*`, `?:`, `sizeof`, `alignof`, `typeid` and `noexcept` cannot be overloaded; `->*`, comma and `co_await` can.
- A non-member operator needs a class or enumeration parameter; `=`, `()`, `[]` and `->` must be members.
- C++23 allows `static operator()` and `static operator[]`, and multi-parameter `operator[]` with default arguments.
- Member operators do not convert their left operand; hidden friends give symmetric conversions and ADL-only visibility.
- `operator->` is reapplied to its result until a raw pointer appears; `operator->*` is not.
- Postfix `++` is `operator++(int)` and receives `0`.
- Overloaded `&&`, `||` and comma always evaluate both operands; since C++17 the left one is sequenced first.
- A literal operator only matches its own literal kind; `12_km` needs an integer or raw form.

## Concept Map Outline

- **Operator overloading:** An operator expression on class or enum operands calls a function chosen by overload resolution.
  - **What can be overloaded:** Nearly every operator, but never its precedence, associativity or arity.
    - **Not overloadable:** ::, ., .*, ?:, sizeof, alignof, typeid and noexcept.
    - **Overloadable surprises:** ->*, the comma, co_await, new, delete and conversion functions can all be overloaded.
    - **Class or enum operand:** A non-member operator needs a parameter of class or enumeration type, so int + int stays built-in.
  - **Member or non-member:** Some operators must be members; symmetric ones are better as non-members.
    - **Must be members:** =, (), [] and -> can only be member functions.
    - **Left operand:** A member never converts its left operand, so 2 + v fails when only v + 2 is a member.
    - **Hidden friends:** Friends defined in the class get symmetric conversions and are found only by ADL.
  - **Call, subscript, arrow:** The three object-bound forms with special rules.
    - **operator():** Any arity and default arguments; may be static since C++23.
    - **Multidimensional []:** Since C++23 operator[] takes any number of parameters, may be static, and may have defaults.
    - **Comma in brackets:** Built-in a[1, 2] is ill-formed in C++23; GCC still accepts it with a warning.
    - **-> drill-down:** x->m applies operator-> repeatedly until a raw pointer results.
  - **Increment and decrement:** Prefix and postfix share a token and differ by a dummy parameter.
    - **Dummy int:** operator++(int) is postfix; x++ calls it with the argument 0.
    - **Return conventions:** Prefix returns *this by reference, postfix returns the old value by copy.
  - **Lost guarantees:** Overloads are function calls, so built-in evaluation rules do not all survive.
    - **No short-circuit:** Overloaded &&, || and comma always evaluate both operands.
    - **C++17 sequencing:** Operands of an overloaded operator follow the built-in operator's sequencing order.
    - **Unary &:** Can be overloaded, so generic code uses std::addressof.
    - **new and delete:** Allocation functions that supply storage; the new expression still constructs the object.
  - **User-defined literals:** operator""_suffix gives a literal suffix a meaning.
    - **Underscore suffixes:** Suffixes without a leading underscore are reserved for the standard library.
    - **Fixed parameter lists:** Integer literals want unsigned long long, floating ones long double, else raw const char* or a template.
    - **No conversions:** With only a long double operator, 12_km is ill-formed.
    - **Spaced form deprecated:** C++23 deprecates operator"" _x with a space before the suffix.

## Standardese Quiz Questions

### Question 1 [warmup] ([over.oper], [over.ass])

Which of these operators can only be overloaded as a member function?

A. `operator+`
B. `operator<<`
C. `operator=`
D. `operator==`
E. `operator!`

**Answer (C):** `operator=`

**Why:** Assignment, function call, subscript and `->` must be member functions; every class already has an implicitly declared copy assignment operator, and a free `operator=` is rejected outright. The others may be members or non-members. `operator<<` is tempting because it is usually a non-member, but that is a convention forced by the stream being the left operand, not a rule in either direction.

### Question 2 [warmup] ([over.match.oper], [over.match.funcs])

Is this program well-formed?

```cpp
struct V {
  int x;
  V operator+(int n) const { return {x + n}; }
};

int main() {
  V v{1};
  V w = 2 + v;
  (void)w;
}
```

A. Well-formed: addition is commutative, so the compiler swaps the operands
B. Ill-formed: no `operator+` accepts an `int` on the left and a `V` on the right
C. Well-formed: `2` is converted to `V` and the member is called on it
D. Well-formed only since C++20, which adds reversed candidates for `+`

**Answer (B):** Ill-formed: no `operator+` accepts an `int` on the left and a `V` on the right

**Why:** A member `operator+` makes the left operand the implicit object argument, so it only matches `V + int`. The compiler never swaps the operands of `+`; C++20 reversed candidates exist only for `==` and the relational operators via `<=>`. Converting `2` to `V` is not possible here, and user-defined conversions are never applied to the implicit object argument anyway.

### Question 3 [warmup] ([over.inc])

What does this program print?

```cpp
#include <cstdio>

struct C {
  int n = 0;
  C& operator++() { ++n; return *this; }
  C operator++(int k) {
    std::printf("k=%d\n", k);
    C old = *this;
    ++n;
    return old;
  }
};

int main() {
  C c;
  c++;
  c.operator++(5);
  std::printf("%d\n", c.n);
}
```

A. `k=1`, `k=5`, `2`
B. `k=0`, `2` only; an explicit call to the postfix form is ill-formed
C. `k=5`, `1`; `c++` calls the prefix overload
D. `k=0`, `k=5`, `2`

**Answer (D):** `k=0`, `k=5`, `2`

**Why:** The `int` parameter only distinguishes postfix from prefix. When the postfix form is invoked through `c++`, the standard says it is called with the argument zero. Calling `operator++` by name is an ordinary member function call, so you may pass any `int`, here 5. Each call increments `n` once, so the final value is 2.

### Question 4 [tricky] ([over.match.oper], [expr.log.and], [expr.call])

In C++23, what does this program print?

```cpp
#include <cstdio>

struct B { bool v; };
B f() { std::puts("f"); return {false}; }
B g() { std::puts("g"); return {true}; }
bool operator&&(B a, B b) { std::puts("&&"); return a.v && b.v; }

int main() {
  bool r = f() && g();
  std::printf("%d\n", r);
}
```

A. `f`, `g`, `&&`, `0`
B. `f`, `0`: `g()` is skipped because the left operand is false
C. `f`, `g`, `&&`, `0`, but `f` and `g` may appear in either order
D. `g`, `f`, `&&`, `0`: function arguments are evaluated right to left

**Answer (A):** `f`, `g`, `&&`, `0`

**Why:** An overloaded `&&` is a function call, and both arguments are evaluated before the body runs, so there is no short-circuit. Since C++17, [over.match.oper] sequences the operands of an overloaded operator in the order prescribed for the built-in one, so `f()` is evaluated before `g()`. The third option describes the pre-C++17 rule, when the order was unspecified.

### Question 5 [tricky] ([over.ref], [over.match.oper])

What does this program print?

```cpp
#include <cstdio>

struct Raw { int x = 42; };
struct Inner {
  Raw r;
  Raw* operator->() { std::puts("Inner->"); return &r; }
};
struct Outer {
  Inner i;
  Inner& operator->() { std::puts("Outer->"); return i; }
};

int main() {
  Outer o;
  std::printf("%d\n", o->x);
}
```

A. Nothing: ill-formed, because `operator->` must return a pointer
B. `Outer->`, then `42`
C. `Outer->`, `Inner->`, then `42`
D. Nothing: ill-formed, because `Inner` has no member `x`

**Answer (C):** `Outer->`, `Inner->`, then `42`

**Why:** `o->x` is interpreted as `(o.operator->())->x`. The result is an `Inner` lvalue, which is a class type, so `->` is applied to it again, calling `Inner::operator->`, which yields a `Raw*`, and the built-in `->` finishes the job. `operator->` may return any class type that itself supports `->`; only the final step must produce a pointer.

### Question 6 [tricky] ([lex.ext], [over.literal])

Is this program well-formed?

```cpp
long double operator""_km(long double x) { return x * 1000; }

int main() {
  auto d = 12_km;
  (void)d;
}
```

A. Well-formed: `12` is converted to `long double` and `d` is 12000
B. Ill-formed: an integer literal never selects the `long double` literal operator
C. Well-formed, but `d` has type `unsigned long long`
D. Ill-formed: literal operators must be declared `constexpr`

**Answer (B):** Ill-formed: an integer literal never selects the `long double` literal operator

**Why:** The literal operator is chosen from the kind of literal, with no conversions. For the integer literal `12_km`, lookup tries `operator""_km(unsigned long long)`, then the raw form taking `const char*`, then a numeric literal operator template; none exists, so the program is ill-formed. Writing `12.0_km` or adding an `unsigned long long` overload fixes it. `constexpr` is optional.

### Question 7 [standardese] ([over.oper])

Which of these operators cannot be overloaded?

A. `->*`
B. `,` (comma)
C. `co_await`
D. `.*`
E. `&&`

**Answer (D):** `.*`

**Why:** The pointer-to-member operator `.*` is on the short list of operators that cannot be overloaded, with `::`, `.` and `?:`. Its sibling `->*` can be overloaded, as an ordinary binary operator with no drill-down. The comma, `co_await` and `&&` are all overloadable, although overloading the comma or `&&` loses the built-in short-circuit behaviour.

### Question 8 [standardese] ([over.call], [over.sub], [over.oper])

In C++23, what does `main` return?

```cpp
struct Grid {
  static int operator()(int a, int b) { return a * b; }
  int operator[](int i = 7) const { return i; }
};

int main() {
  return Grid{}(3, 4) + Grid{}[];
}
```

A. 19
B. Ill-formed: `operator()` cannot be a static member function
C. Ill-formed: `operator[]` cannot have a default argument
D. Ill-formed: a subscript expression needs at least one operand

**Answer (A):** 19

**Why:** C++23 (P1169 and P2589) allows `operator()` and `operator[]` to be static member functions, and P2128 lets `operator[]` take any number of parameters, including zero, with default arguments. So `Grid{}(3, 4)` is 12 and `Grid{}[]` uses the default 7, giving 19. Each of the other options was true in C++20.
