Unary Operator Overloading

For example, in order to overload the - (negation) operator for struct S, and no other operator:

struct S
{
    int m;

    int opUnary(string s)() if (s == "-")
    {
        return -m;
    }
}

void main()
{
    S s = {2};
    assert(-s == -2);
}

Note: <em>opUnary</em> above can also be declared using a template parameter specialization:

int opUnary(string s : "-")()

Postincrement e++ and Postdecrement e-- Operators

These are not directly overloadable, but instead are rewritten in terms of the ++e and --e prefix operators:

Overloading Index Unary Operators

Indexing can be overloaded. A unary operation on an index expression can also be overloaded independently. This works for multidimensional indexing.

struct S
{
    private int[] a;

    void opIndexUnary(string s: "++")(size_t i) { ++a[i]; }
}

S s = {[4]};
+s[0];
assert(s.a[0] == 5);

Overloading Slice Unary Operators

Slicing can be overloaded. A unary operation on a slice can also be overloaded independently. opIndexUnary is defined either with no function arguments for a full slice, or with two arguments for the start and end indices of the slice.

struct S
{
    private int[] a;

    void opIndexUnary(string s: "--")() { --a[]; }
}

S s = {[1, 2]};

Note: For backward compatibility, if the above rewrites fail to compile and opSliceUnary is defined, then the rewrites a.opSliceUnary!(op)(i, j) and a.opSliceUnary!(op) are tried instead, respectively.

Cast Operator Overloading

To define how one type can be cast to another, define the opCast template method, which is used as follows:

Note that opCast is only ever used with an explicit cast expression, except in the case of boolean operations (see next section).

struct S
{
    void* mem;

    bool opCast(T)()
    if (is(T == bool)) => mem !is null;
}

S s = S(new int);
auto b = cast(bool) s;
assert(b);
//b = s; // error

If the return type of opCast differs from the <em>type</em> parameter of the cast, then the result is implicitly converted to <em>type</em>.

Boolean Operations

Notably absent from the list of overloaded unary operators is the ! logical negation operator. More obscurely absent is a unary operator to convert to a bool result. Instead, for structs these are covered by a rewrite to:

opCast!(bool)(e)

So,

if (e)   =>  if (e.opCast!(bool))
if (!e)  =>  if (!e.opCast!(bool))

and similarly for other boolean conditional expressions and logical operators used on the struct instance.

This only happens, however, for instances of structs. Class references are converted to bool by checking to see if the class reference is null or not.

Binary Operator Overloading

The following binary operators are overloadable:

The expression:

a op b

is rewritten as one of:

a.opBinary!("op")(b)
b.opBinaryRight!("op")(a)

and the one with the 'better' match is selected. It is an error for both to equally match. Example:

struct S
{
    int[] data;

    // this ~ rhs
    int[] opBinary(string op : "~")(int rhs)
    {
        return data ~ rhs;
    }
    // lhs ~ this
    int[] opBinaryRight(string op : "~")(int lhs)
    {
        return lhs ~ data;
    }
}

void main()
{
    auto s = S([2,3]);
    assert(s ~ 4 == [2,3,4]); // opBinary
    assert(1 ~ s == [1,2,3]); // opBinaryRight
}

Operator overloading for a number of operators can be done at the same time. For example, if only the + or - operators are supported:

T opBinary(string op)(T rhs)
{
    static if (op == "+") return data + rhs.data;
    else static if (op == "-") return data - rhs.data;
    else static assert(0, "Operator "~op~" not implemented");
}

To do them all en masse:

T opBinary(string op)(T rhs)
{
    return mixin("data "~op~" rhs.data");
}

Note that opIn and opIn_r have been deprecated in favor of opBinary!"in" and opBinaryRight!"in" respectively.

Overloading the Comparison Operators

D allows overloading of the comparison operators ==, !=, &lt;, &lt;=, &gt;=, &gt; via two functions, opEquals and opCmp.

The equality and inequality operators are treated separately from comparison operators because while practically all user-defined types can be compared for equality, only a subset of types have a meaningful ordering. For example, while it makes sense to determine if two RGB color vectors are equal, it is not meaningful to say that one color is greater than another, because colors do not have an ordering. Thus, one would define opEquals for a Color type, but not opCmp.

Furthermore, even with orderable types, the order relation may not be linear. For example, one may define an ordering on sets via the subset relation, such that x &lt; y is true if x is a (strict) subset of y. If x and y are disjoint sets, then neither x &lt; y nor y &lt; x holds, but that does not imply that x == y. Thus, it is insufficient to determine equality purely based on opCmp alone. For this reason, opCmp is only used for the inequality operators &lt;, &lt;=, &gt;=, and &gt;. The equality operators == and != always employ opEquals instead.

Therefore, it is the programmer's responsibility to ensure that opCmp and opEquals are consistent with each other. If opEquals is not specified, the compiler provides a default version that does member-wise comparison. If this suffices, one may define only opCmp to customize the behaviour of the inequality operators. But if not, then a custom version of opEquals should be defined as well, in order to preserve consistent semantics between the two kinds of comparison operators.

Finally, if the user-defined type is to be used as a key in the built-in associative arrays, then the programmer must ensure that the semantics of opEquals and toHash are consistent. If not, the associative array may not work in the expected manner.

Overloading == and !=

Expressions of the form a != b are rewritten as !(a == b).

Given a == b :

1. .object.opEquals(a, b)

   bool opEquals(Object a, Object b)
   {
       if (a is b) return true;
       if (a is null || b is null) return false;
       if (typeid(a) == typeid(b)) return a.opEquals(b);
       return a.opEquals(b) && b.opEquals(a);
   }

   If a and b are both class objects, then the expression is rewritten as: and that function is implemented as:
2. Otherwise the expressions a.opEquals(b) and b.opEquals(a) are tried. If both resolve to the same opEquals function, then the expression is rewritten to be a.opEquals(b).
3. If one is a better match than the other, or one compiles and the other does not, the first is selected.
4. Otherwise, an error results.

If overriding Object.opEquals() for classes, the class member function signature should look like:

class C
{
    override bool opEquals(Object o) { ... }
}

If structs declare an opEquals member function for the identity comparison, it could have several forms, such as:

struct S
{
    // lhs should be mutable object
    bool opEquals(const S s) { ... }        // for r-values (e.g. temporaries)
    bool opEquals(ref const S s) { ... }    // for l-values (e.g. variables)

    // both hand side can be const object
    bool opEquals(const S s) const { ... }  // for r-values (e.g. temporaries)
}

Alternatively, declare a single templated opEquals function with an auto ref parameter:

struct S
{
    // for l-values and r-values,
    // with converting both hand side implicitly to const
    bool opEquals()(auto ref const S s) const { ... }
}

Overloading &lt;

Comparison operations are rewritten as follows:

Both rewrites are tried. If only one compiles, that one is taken. If they both resolve to the same function, the first rewrite is done. If they resolve to different functions, the best matching one is used. If they both match the same, but are different functions, an ambiguity error results.

struct B
{
    int opCmp(int)         { return -1; }
    int opCmp(ref const S) { return -1; }
    int opCmp(ref const C) { return -1; }
}

struct S
{
    int opCmp(ref const S) { return 1; }
    int opCmp(ref B)       { return 0; }
}

struct C
{
    int opCmp(ref const B) { return 0; }
}

void main()
{
    S s;
    const S cs;
    B b;
    C c;
    assert(s > s);      // s.opCmp(s) > 0
    assert(!(s < b));   // s.opCmp(b) > 0  - S.opCmp(ref B) is exact match
    assert(!(b < s));   // s.opCmp(b) < 0  - S.opCmp(ref B) is exact match
    assert(b < cs);     // b.opCmp(s) < 0  - B.opCmp(ref const S) is  exact match
    static assert(!__traits(compiles, b < c)); // both C.opCmp and B.opcmp match exactly
}

If overriding Object.opCmp() for classes, the class member function signature should look like:

class C
{
    override int opCmp(Object o) { ... }
}

If structs declare an opCmp member function, it should have the following form:

struct S
{
    int opCmp(ref const S s) const { ... }
}

Note that opCmp is only used for the inequality operators; expressions like a == b always uses opEquals. If opCmp is defined but opEquals isn't, the compiler will supply a default version of opEquals that performs member-wise comparison. If this member-wise comparison is not consistent with the user-defined opCmp, then it is up to the programmer to supply an appropriate version of opEquals. Otherwise, inequalities like a &lt;= b will behave inconsistently with equalities like a == b.

struct S
{
    int i, j;
    int opCmp(ref const S s) const { return (i > s.i) - (i < s.i); } // ignore j
}

S a = {2, 3};
S b = {2, 1};
S c = {3, 0};
assert(a < c);
assert(a <= b);
assert(!(a < b)); // opCmp ignores j
assert(a != b);   // generated opEquals tests both i and j members

Function Call Operator Overloading

The function call operator, (), can be overloaded by declaring a function named opCall:

struct F
{
    int opCall();
    int opCall(int x, int y, int z);
}

void test()
{
    F f;
    int i;

    i = f();      // same as i = f.opCall();
    i = f(3,4,5); // same as i = f.opCall(3,4,5);
}

In this way a struct or class object can behave as if it were a function.

Note that merely declaring opCall automatically disables struct literal syntax. To avoid the limitation, declare a constructor so that it takes priority over opCall in Type(...) syntax.

struct Multiplier
{
    int factor;
    this(int num) { factor = num; }
    int opCall(int value) { return value * factor; }
}

void main()
{
    Multiplier m = Multiplier(10);  // invoke constructor
    assert(m.factor == 10);
    int result = m(5);              // invoke opCall
    assert(result == 50);
}

Static opCall

static opCall also works as expected for a function call operator with type names.

struct Double
{
    static int opCall(int x) { return x * 2; }
}
void test()
{
    int i = Double(2);
    assert(i == 4);
}

Mixing struct constructors and static opCall is not allowed.

struct S
{
    this(int i) {}
    static S opCall()  // disallowed due to constructor
    {
        return S.init;
    }
}

Note: static opCall can be used to simulate struct constructors with no arguments, but this is not recommended practice. Instead, the preferred solution is to use a factory function to create struct instances.

Assignment Operator Overloading

The assignment operator = can be overloaded if the left hand side is a struct aggregate, and opAssign is a member function of that aggregate.

For struct types, operator overloading for the identity assignment is allowed.

struct S
{
    // identity assignment, allowed.
    void opAssign(S rhs);

    // not identity assignment, also allowed.
    void opAssign(int);
}
S s;
s = S();      // Rewritten to s.opAssign(S());
s = 1;        // Rewritten to s.opAssign(1);

However for class types, identity assignment is not allowed. All class types have reference semantics, so identity assignment by default rebinds the left-hand-side to the argument at the right, and this is not overridable.

class C
{
    // If X is the same type as C or the type which is
    // implicitly convertible to C, then opAssign would
    // accept identity assignment, which is disallowed.
    // C opAssign(...);
    // C opAssign(X);
    // C opAssign(X, ...);
    // C opAssign(X ...);
    // C opAssign(X, U = defaultValue, etc.);

    // not an identity assignment - allowed
    void opAssign(int);
}
C c = new C();
c = new C();  // Rebinding referencee
c = 1;        // Rewritten to c.opAssign(1);

Index Assignment Operator Overloading

If the left hand side of an assignment is an index operation on a struct or class instance, it can be overloaded by providing an opIndexAssign member function. Expressions of the form a[b₁, b₂, ... b_n] = c are rewritten as a.opIndexAssign(c, b₁, b₂, ... b_n).

struct A
{
    int opIndexAssign(int value, size_t i1, size_t i2);
}

void test()
{
    A a;
    a[i,3] = 7;  // same as a.opIndexAssign(7,i,3);
}

Slice Assignment Operator Overloading

If the left hand side of an assignment is a slice operation on a struct or class instance, it can be overloaded by implementing an opIndexAssign member function that takes the return value of the opSlice function as parameter(s). Expressions of the form a[i..j] = c are rewritten as a.opIndexAssign(c, a.opSlice!0(i, j)), and a[] = c as a.opIndexAssign(c).

See [#array-ops|Array Indexing and Slicing Operators Overloading] for more details.

struct A
{
    int opIndexAssign(int v);  // overloads a[] = v
    int opIndexAssign(int v, size_t[2] slice);  // overloads a[i .. j] = v
    size_t[2] opSlice(size_t dim)(size_t i, size_t j);  // overloads i .. j
}

void test()
{
    A a;
    int v;

    a[] = v;  // same as a.opIndexAssign(v);
    a[3..4] = v;  // same as a.opIndexAssign(v, a.opSlice!0(3,4));
}

For backward compatibility, if rewriting a[i..j] as a.opIndexAssign(a.opSlice!0(i, j)) fails to compile, the legacy rewrite opSliceAssign(c, i, j) is used instead.

Op Assignment Operator Overloading

The following op assignment operators are overloadable:

The expression:

a op= b

is rewritten as:

a.opOpAssign!("op")(b)