Operator Overloading

C# supports operator overloading. Operators allow for a more concise notation of operations. They should not be overused - we use them mainly when it is intuitive and does not raise doubts, e.g., for our own numeric types. An operator should do what we would expect it to do.

Example

Operators are defined as public, static members of a type. The method name must be the operation symbol preceded by the operator keyword. Depending on the operation, the method takes one or two parameters.

public struct Complex
{
    public double Real { get; }
    public double Imaginary { get; }
    
    public Complex(double real, double imaginary)
    {
        Real = real;
        Imaginary = imaginary;
    }
    
    public static Complex operator +(Complex a, Complex b)
    {
        return new Complex(a.Real + b.Real, a.Imaginary + b.Imaginary);
    }

    public static Complex operator -(Complex a, Complex b)
    {
        return new Complex(a.Real - b.Real, a.Imaginary - b.Imaginary);
    }

    public static Complex operator -(Complex a)
    {
        return new Complex(-a.Real, -a.Imaginary);
    }
    
    public static Complex operator *(Complex a, Complex b)
    {
        return new Complex(
            a.Real * b.Real - a.Imaginary * b.Imaginary,
            a.Real * b.Imaginary + a.Imaginary * b.Real
        );
    }

    public static bool operator ==(Complex a, Complex b)
    {
        return a.Real == b.Real && a.Imaginary == b.Imaginary;
    }

    public static bool operator !=(Complex a, Complex b)
    {
        return !(a == b);
    }
    
    public override bool Equals(object? obj)
    {
        return obj is Complex complex && complex == this;
    }

    public override int GetHashCode()
    {
        return HashCode.Combine(Real, Imaginary);
    }
}
  • Some operators must be implemented in pairs: == and !=, < and >, <= and >=, true and false
  • Compound assignment operators (e.g., +=, /=) are implicitly overloaded by overloading their corresponding non-compound operators. Since C# 14, they can also be defined explicitly.
  • When overloading the == operator, you should also override the Equals and GetHashCode methods, otherwise the compiler will issue a warning.
  • It is also worth implementing the IEquatable<T> and IComparable<T> interfaces. In .NET 7 (C# 11) and newer, when overloading arithmetic operators, it is worth considering the implementation of generic interfaces, e.g., IAdditionOperators<TSelf, TOther, TResult>, IMultiplyOperators<TSelf, TOther, TResult>, etc. This will allow us to later constrain the generic type, and it is also a form of code documentation.

Compound Assignment Operators (C# 14)

Before C# 14, x += y was always evaluated as x = x + y. For mutable types storing a lot of data (e.g., vectors or matrices), this means allocating a new object and copying the data on every +=. Since C# 14, a type can define compound assignment operators (+=, -=, *=, …) and the ++ and -- operators as instance methods that modify the object in place. Such an operator must be public, must not be static, and returns void; a compound assignment operator takes one parameter (the right-hand side), while ++ and -- take none.

public class Vector
{
    private readonly double[] _data;

    public Vector(int size) => _data = new double[size];

    public double this[int i]
    {
        get => _data[i];
        set => _data[i] = value;
    }

    public static Vector operator +(Vector a, Vector b)
    {
        var result = new Vector(a._data.Length);
        for (int i = 0; i < a._data.Length; i++)
            result._data[i] = a._data[i] + b._data[i];
        return result;
    }

    public void operator +=(Vector other)
    {
        for (int i = 0; i < _data.Length; i++)
            _data[i] += other._data[i];
    }

    public void operator ++()
    {
        for (int i = 0; i < _data.Length; i++)
            _data[i]++;
    }
}
var v = new Vector(3);
var w = new Vector(3);
w[0] = 1;
var sum = v + w; // static operator +: allocates a new Vector
v += w;          // instance operator +=: modifies v in place
v++;             // instance operator ++
Console.WriteLine($"{v[0]} {v[1]} {sum[0]}"); // 2 1 1
// var old = v++; // error: the instance ++ cannot be used when the result of x++ is used

If a type does not define a compound assignment operator, the compiler still evaluates x += y as x = x + y. The instance ++ is not used when the result of a postfix x++ is used (e.g., y = x++), because the value from before the increment is needed - in that case a static operator ++ is required.

Since C# 14, operators can also be declared in extension blocks, which allows adding operators to types we do not control - see Extension Methods.

Operator Inheritance

Operators are static members, so they are not polymorphic: they cannot be virtual or overridden, and the operator is selected at compile time based on the static types of the operands (an operator declared in a base class also works for objects of derived classes). Since C# 11, operators can be declared in interfaces as static abstract or static virtual - implementing types then must (or, for static virtual, may) provide their own implementation, and the operator can be used through a generic type parameter constrained by the interface.

public interface IIncrementable<TSelf> where TSelf : IIncrementable<TSelf>
{
    public static abstract TSelf operator ++(TSelf self);
}

Generic Math (C# 11)

Static abstract operators in interfaces are the basis of generic math (.NET 7+). Built-in numeric types implement generic interfaces such as INumber<TSelf> (namespace System.Numerics), which provides arithmetic and comparison operators as well as members such as T.Zero and T.One. Thanks to that, a single generic method can work with any numeric type - something that in C++ is typically done with templates:

using System.Numerics;

static T Sum<T>(IEnumerable<T> values) where T : INumber<T>
{
    T result = T.Zero;
    foreach (T value in values)
        result += value;
    return result;
}

Console.WriteLine(Sum([1, 2, 3]));    // 6
Console.WriteLine(Sum([1.5, 2.5]));   // 4
Console.WriteLine(Sum([0.1m, 0.2m])); // 0.3

Checked Operators (C# 11)

Since C# 11, a type can define a separate version of an operator for the checked context, e.g., one that throws an OverflowException on overflow. It can be declared for the ++, --, unary -, binary +, -, *, / operators and for explicit conversions, and always requires the regular version of the same operator, which is used in the unchecked context (the default):

public readonly struct Money(int cents)
{
    public int Cents { get; } = cents;

    public static Money operator +(Money a, Money b) => new(a.Cents + b.Cents);
    public static Money operator checked +(Money a, Money b) => new(checked(a.Cents + b.Cents));
}
var max = new Money(int.MaxValue);
var one = new Money(1);
Console.WriteLine(unchecked(max + one).Cents); // -2147483648
Console.WriteLine(checked(max + one).Cents);   // OverflowException

Defining Conversions

You can define your own conversions for a type, both explicit and implicit.

  • Implicit conversions should always be safe, not cause loss of information, and not throw exceptions.
  • Explicit conversions may fail (e.g., by throwing an exception) or may cause loss of information - they should require a conscious decision from the programmer (using a cast).
public struct Complex
{
    public double Real { get; }
    public double Imaginary { get; }
    
    public Complex(double real, double imaginary)
    {
        Real = real;
        Imaginary = imaginary;
    }
    
    public static implicit operator Complex(double d)
    {
        return new Complex(d, 0.0);
    }
    
    public static explicit operator double(Complex c)
    {
        return c.Real;
    }
}

Usage:

Complex c = new Complex(3.0, 4.0);
double d = (double)c; // explicit conversion
c = 5.0;              // implicit conversion