root/trunk/docsrc/operatoroverloading.dd

Ddoc

$(SPEC_S Operator Overloading,

$(V2
    $(P Operator overloading is accomplished by rewriting operators whose
    operands are class or struct objects into calls to specially named
    member functions. No additional syntax is used.
    )

    $(UL
    $(LI $(LINK2 #Unary, Unary Operator Overloading))
    $(LI $(LINK2 #Cast, Cast Operator Overloading))
    $(LI $(LINK2 #Binary, Binary Operator Overloading))
    $(LI $(LINK2 #equals, Overloading == and !=))
    $(LI $(LINK2 #compare, Overloading < <=, > and >=))
    $(LI $(LINK2 #FunctionCall, Function Call Operator Overloading))
    $(LI $(LINK2 #Assignment, Assignment Operator Overloading))
    $(LI $(LINK2 #OpAssign, Op Assignment Operator Overloading))
    $(LI $(LINK2 #Array, Index Operator Overloading))
    $(LI $(LINK2 #Slice, Slice Operator Overloading))
    $(LI $(LINK2 #Dispatch, Forwarding))
    )

<h2><a name="Unary">Unary Operator Overloading</a></h2>

    $(TABLE2 Overloadable Unary Operators,

    $(TR $(TH$(I op)) $(TH$(I rewrite)) )

    $(TR
    $(TD -$(I e))
    $(TD $(CODE $(I e).opUnary!("-")()))
    )

    $(TR
    $(TD +$(I e))
    $(TD $(CODE $(I e).opUnary!("+")()))
    )

    $(TR
    $(TD ~$(I e))
    $(TD $(CODE $(I e).opUnary!("~")()))
    )

    $(TR
    $(TD *$(I e))
    $(TD $(CODE $(I e).opUnary!("*")()))
    )

    $(TR
    $(TD ++$(I e))
    $(TD $(CODE $(I e).opUnary!("++")()))
    )

    $(TR
    $(TD --$(I e))
    $(TD $(CODE $(I e).opUnary!("--")()))
    )

    )

    $(P 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;
    }
}

int foo(S s) {
    return -s;
}
---

<h3>Postincrement $(I e)++ and Postdecrement $(I e)-- Operators</h3>

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

    $(TABLE2 Postfix Operator Rewrites,

    $(TR $(TH$(I op)) $(TH$(I rewrite)) )

    $(TR
    $(TD $(I e)--)
    $(TD $(CODE (auto t = e, --$(I e), t)))
    )

    $(TR
    $(TD $(I e)++)
    $(TD $(CODE (auto t = e, ++$(I e), t)))
    )
    )

<h3>Overloading Index Unary Operators</h3>

    $(TABLE2 Overloadable Index Unary Operators,

    $(TR $(TH$(I op)) $(TH$(I rewrite)) )

    $(TR
    $(TD $(CODE -$(I a)[$(ARGUMENTS)]))
    $(TD $(CODE $(I a).opIndexUnary!("-")($(ARGUMENTS))))
    )

    $(TR
    $(TD $(CODE +$(I a)[$(ARGUMENTS)]))
    $(TD $(CODE $(I a).opIndexUnary!("+")($(ARGUMENTS))))
    )

    $(TR
    $(TD $(CODE ~$(I a)[$(ARGUMENTS)]))
    $(TD $(CODE $(I a).opIndexUnary!("~")($(ARGUMENTS))))
    )

    $(TR
    $(TD $(CODE *$(I a)[$(ARGUMENTS)]))
    $(TD $(CODE $(I a).opIndexUnary!("*")($(ARGUMENTS))))
    )

    $(TR
    $(TD $(CODE ++$(I a)[$(ARGUMENTS)]))
    $(TD $(CODE $(I a).opIndexUnary!("++")($(ARGUMENTS))))
    )

    $(TR
    $(TD $(CODE --$(I a)[$(ARGUMENTS)]))
    $(TD $(CODE $(I a).opIndexUnary!("--")($(ARGUMENTS))))
    )

    )

<h3>Overloading Slice Unary Operators</h3>

    $(TABLE2 Overloadable Slice Unary Operators,

    $(TR $(TH$(I op)) $(TH$(I rewrite)) )

    $(TR
    $(TD $(CODE -$(I a)[$(SLICE)]))
    $(TD $(CODE $(I a).opSliceUnary!("-")($(SLICE2))))
    )

    $(TR
    $(TD $(CODE +$(I a)[$(SLICE)]))
    $(TD $(CODE $(I a).opSliceUnary!("+")($(SLICE2))))
    )

    $(TR
    $(TD $(CODE ~$(I a)[$(SLICE)]))
    $(TD $(CODE $(I a).opSliceUnary!("~")($(SLICE2))))
    )

    $(TR
    $(TD $(CODE *$(I a)[$(SLICE)]))
    $(TD $(CODE $(I a).opSliceUnary!("*")($(SLICE2))))
    )

    $(TR
    $(TD $(CODE ++$(I a)[$(SLICE)]))
    $(TD $(CODE $(I a).opSliceUnary!("++")($(SLICE2))))
    )

    $(TR
    $(TD $(CODE --$(I a)[$(SLICE)]))
    $(TD $(CODE $(I a).opSliceUnary!("--")($(SLICE2))))
    )

    $(TR
    $(TD $(CODE -$(I a)[ ]))
    $(TD $(CODE $(I a).opSliceUnary!("-")()))
    )

    $(TR
    $(TD $(CODE +$(I a)[ ]))
    $(TD $(CODE $(I a).opSliceUnary!("+")()))
    )

    $(TR
    $(TD $(CODE ~$(I a)[ ]))
    $(TD $(CODE $(I a).opSliceUnary!("~")()))
    )

    $(TR
    $(TD $(CODE *$(I a)[ ]))
    $(TD $(CODE $(I a).opSliceUnary!("*")()))
    )

    $(TR
    $(TD $(CODE ++$(I a)[ ]))
    $(TD $(CODE $(I a).opSliceUnary!("++")()))
    )

    $(TR
    $(TD $(CODE --$(I a)[ ]))
    $(TD $(CODE $(I a).opSliceUnary!("--")()))
    )
    )

<h2><a name="Cast">Cast Operator Overloading</a></h2>

    $(TABLE2 Cast Operators,

    $(TR $(TH$(I op)) $(TH$(I rewrite)) )

    $(TR
    $(TD cast($(I type))$(I e))
    $(TD $(CODE $(I e).opCast!($(I type))()))
    )

    )


<h3>Boolean Operations</h3>

    $(P 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, these are covered by a rewrite to:
    )
---
opCast!(bool)(e)
---

    $(P So,)

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

    $(P etc., whenever a bool result is expected. 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.
    )

<h2><a name="Binary">Binary Operator Overloading</a></h2>

    $(P The following binary operators are overloadable:)

    $(TABLE2 Overloadable Binary Operators,

    $(TR $(TD +) $(TD -) $(TD *) $(TD /) $(TD %) $(TD ^^) $(TD &amp;) )
    $(TR $(TD |) $(TD ^) $(TD &lt;&lt;) $(TD &gt;&gt;) $(TD &gt;&gt;&gt;) $(TD ~) $(TD in) )

    )

    $(P The expression:)
---
a $(I op) b
---
    $(P is rewritten as both:)
---
a.opBinary!("$(I op)")(b)
b.opBinaryRight!("$(I op)")(a)
---

    $(P and the one with the $(SINGLEQUOTE better) match is selected.
    It is an error for both to equally match.
    )

<h2><a name="equals">Overloading == and !=</a></h2>

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

    $(P Given $(CODE a == b) :)

$(OL
    $(LI If a and b are both class objects, then the expression is rewritten as:
---
.object.opEquals(a, b)
---
    and that function is implemented as:
---
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);
}
---
    )
    $(LI Otherwise the expressions $(CODE a.opEquals(b)) and
    $(CODE b.opEquals(a)) are tried. If both resolve to the same opEquals
    function, then the expression is rewritten to be $(CODE a.opEquals(b)).
    )
    $(LI If one is a better match then the other, or one compiles and the other
    does not, the one is selected.)
    $(LI Otherwise, an error results.)
)

    $(P If overridding Object.opEquals() for classes, the class member function
    signature should look like:)
---
class C {
    override bool opEquals(Object o) { ... }
}
---

    $(P If structs declare an opEquals member function, it should follow the following
    form:)
---
struct S {
    int opEquals(ref const S s) { ... }
}
---

<h2><a name="compare">Overloading &lt; &lt;=, &gt; and &gt;=</a></h2>

    $(P Comparison operations are rewritten as follows:)

    $(TABLE2 Overloadable Unary Operators,
    $(TR $(TH comparison) $(TH rewrite 1) $(TH rewrite 2) )

    $(TR $(TD $(CODE a &lt; b)) $(TD $(CODE a.opCmp(b) &lt; 0)) $(TD $(CODE b.opCmp(a) &gt; 0)))
    $(TR $(TD $(CODE a &lt;= b)) $(TD $(CODE a.opCmp(b) &lt;= 0)) $(TD $(CODE b.opCmp(a) &gt;= 0)))
    $(TR $(TD $(CODE a &gt; b)) $(TD $(CODE a.opCmp(b) &gt; 0)) $(TD $(CODE b.opCmp(a) &lt; 0)))
    $(TR $(TD $(CODE a &gt;= b)) $(TD $(CODE a.opCmp(b) &gt;= 0)) $(TD $(CODE b.opCmp(a) &lt;= 0)))
    )

    $(P 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.
    )

    $(P If overriding Object.opCmp() for classes, the class member function
    signature should look like:)
---
class C {
    override int opCmp(Object o) { ... }
}
---

    $(P If structs declare an opCmp member function, it should follow the following
    form:)
---
struct S {
    int opCmp(ref const S s) { ... }
}
---

<h2><a name="FunctionCall">Function Call Operator Overloading $(I f)()</a></h2>

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

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

void test()
{   F f;
    int i;

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

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

<h2><a name="Assignment">Assignment Operator Overloading</a></h2>

    $(P The assignment operator $(CODE =) can be overloaded if the
    lvalue is a struct aggregate, and $(CODE opAssign)
    is a member function of that aggregate.)

    $(P The assignment operator cannot be overloaded for rvalues
    that can be implicitly cast to the lvalue type.
    Furthermore, the following parameter signatures for $(CODE opAssign)
    are not allowed:)

---
opAssign(...)
opAssign(T)
opAssign(T, ...)
opAssign(T ...)
opAssign(T, U = defaultValue, etc.)
---

    $(P where $(I T) is the same type as the aggregate type $(I A),
    is implicitly
    convertible to $(I A), or if $(I A) is a struct and $(I T)
    is a pointer to a type that is
    implicitly convertible to $(I A).
    )

<h3>Index Assignment Operator Overloading</h2>

    $(P 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 $(CODE a[$(ARGUMENTS)] = c) are rewritten
    as $(CODE a.opIndexAssign(c, $(ARGUMENTS))).
    )

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

void test()
{   A a;

    a$(B [)i,3$(B ]) = 7;       // same as a.opIndexAssign(7,i,3);
}
-------

<h3>Slice Assignment Operator Overloading</h2>

    $(P If the left hand side of an assignment is a slice operation
    on a struct or class instance,
    it can be overloaded by providing an opSliceAssign member function.
    Expressions of the form $(CODE a[$(SLICE)] = c) are rewritten
    as $(CODE a.opSliceAssign(c, $(SLICE2))), and
    $(CODE a[] = c) as $(CODE a.opSliceAssign(c)).
    )

-------
struct A
{
    int $(B opSliceAssign)(int v);            // overloads a[] = v
    int $(B opSliceAssign)(int v, size_t x, size_t y); // overloads a[i .. j] = v
}

void test()
{   A a;
    int v;

    a$(B []) = v;       // same as a.opSliceAssign(v);
    a$(B [)3..4$(B ]) = v;  // same as a.opSliceAssign(v,3,4);
}
-------

<h2><a name="OpAssign">Op Assignment Operator Overloading</a></h2>

    $(P The following op assignment operators are overloadable:)

    $(TABLE2 Overloadable Op Assignment Operators,

    $(TR $(TD +=) $(TD -=) $(TD *=) $(TD /=) $(TD %=) $(TD ^^=) $(TD &amp;=) )
    $(TR $(TD |=) $(TD ^=) $(TD &lt;&lt;=) $(TD &gt;&gt;=) $(TD &gt;&gt;&gt;=) $(TD ~=) $(TD &nbsp;) )

    )

    $(P The expression:)
---
a $(I op)= b
---

    $(P is rewritten as:)

---
a.opOpAssign!("$(I op)")(b)
---

<h3>Index Op Assignment Operator Overloading</h3>

    $(P If the left hand side of an $(I op)= is an index expression on
    a struct or class instance and opIndexOpAssign is a member:)

---
a[$(ARGUMENTS)] $(I op)= c
---

    $(P it is rewritten as:)

---
a.opIndexOpAssign!("$(I op)")(c, $(ARGUMENTS))
---

<h3>Slice Op Assignment Operator Overloading</h3>

    $(P If the left hand side of an $(I op)= is a slice expression on
    a struct or class instance and opSliceOpAssign is a member:)

---
a[$(SLICE)] $(I op)= c
---

    $(P it is rewritten as:)

---
a.opSliceOpAssign!("$(I op)")(c, $(SLICE2))
---

    $(P and)

---
a[] $(I op)= c
---

    $(P it is rewritten as:)

---
a.opSliceOpAssign!("$(I op)")(c)
---

<h2><a name="Array">Index Operator Overloading</a></h2>

    $(P The array index operator, $(CODE a[$(ARGUMENTS)]), can be overloaded by
    declaring a function named $(B opIndex) with one
    or more parameters.
    )

-------
struct A
{
    int $(B opIndex)(size_t i1, size_t i2, size_t i3);
}

void test()
{   A a;
    int i;

    i = a$(B [)5,6,7$(B ]); // same as i = a.opIndex(5,6,7);
}
-------

    $(P In this way a struct or class object can behave as if it
    were an array.
    )

    $(P If an index expression can be rewritten using opIndexAssign or opIndexOpAssign,
    those are preferred over opIndex.
    )


<h2><a name="Slice">Slice Operator Overloading</a></h2>

    $(P Overloading the slicing operator means overloading expressions
    like $(CODE a[]) and $(CODE a[$(SLICE)]).
    This can be done by declaring a member function named $(B opSlice).
    )

-------
class A
{
    int $(B opSlice)();               // overloads a[]
    int $(B opSlice)(size_t x, size_t y);         // overloads a[i .. j]
}

void test()
{   A a = new A();
    int i;
    int v;

    i = a$(B []);       // same as i = a.opSlice();
    i = a$(B [)3..4$(B ]);  // same as i = a.opSlice(3,4);
}
-------

    $(P If a slice expression can be rewritten using opSliceAssign or opSliceOpAssign,
    those are preferred over opSlice.
    )

<h2><a name="Dispatch">Forwarding</a></h2>

    $(P Member names not found in a class or struct can be forwarded
    to a template function named $(CODE opDispatch) for resolution.
    )

---
import std.stdio;

struct S
{
    void opDispatch(string s, T)(T i)
    {
    writefln("S.opDispatch('%s', %s)", s, i);
    }
}

class C
{
    void opDispatch(string s)(int i)
    {
    writefln("C.opDispatch('%s', %s)", s, i);
    }
}

struct D
{
    template opDispatch(string s)
    {
    enum int opDispatch = 8;
    }
}

void main()
{
    S s;
    s.opDispatch!("hello")(7);
    s.foo(7);

    auto c = new C();
    c.foo(8);

    D d;
    writefln("d.foo = %s", d.foo);
    assert(d.foo == 8);
}
---
)

$(V1
    $(P Overloading is accomplished by interpreting specially named
    struct and class member functions as being implementations of unary and
    binary operators. No additional syntax is used.
    )

    $(UL
    $(LI $(LINK2 #Unary, Unary Operator Overloading))
    $(LI $(LINK2 #Binary, Binary Operator Overloading))
    $(LI $(LINK2 #FunctionCall, Function Call Operator Overloading))
    $(LI $(LINK2 #Array, Array Operator Overloading))
    $(LI $(LINK2 #Assignment, Assignment Operator Overloading))
$(V2
    $(DOT $(LI $(LINK2 #Dot, Forwarding)))
)
    $(LI $(LINK2 #Future, Future Directions))
    )

<h2><a name="Unary">Unary Operator Overloading</a></h2>


    $(TABLE2 Overloadable Unary Operators,

    $(TR $(TH$(I op)) $(TH$(I opfunc)) )

    $(TR
    $(TD -$(I e))
    $(TD $(CODE opNeg))
    )

    $(TR
    $(TD +$(I e))
    $(TD $(CODE opPos))
    )

    $(TR
    $(TD ~$(I e))
    $(TD $(CODE opCom))
    )

    $(TR
    $(TD $(I e)++)
    $(TD $(CODE opPostInc))
    )

    $(TR
    $(TD $(I e)--)
    $(TD $(CODE opPostDec))
    )

    $(TR
    $(TD cast($(I type))$(I e))
    $(TD $(CODE opCast))
    )

    )


    $(P Given a unary
    overloadable operator $(I op) and its corresponding
    class or struct member
    function name $(I opfunc), the syntax:
    )

---
$(I op) a
---

    $(P where $(I a) is a class or struct object reference,
    is interpreted as if it was written as:
    )
---
a.$(I opfunc)()
---

<h3>Overloading ++$(I e) and --$(I e)</h3>

    $(P Since ++$(I e) is defined to be semantically equivalent
    to ($(I e) += 1), the expression ++$(I e) is rewritten
    as ($(I e) += 1), and then checking for operator overloading
    is done. The situation is analogous for --$(I e).
    )

<h3>Examples</h3>

    $(OL 
    $(LI
-------
class A { int $(B opNeg)(); }
A a;
-a; // equivalent to a.opNeg();
-------
    )
    $(LI
-------
class A { int $(B opNeg)(int i); }
A a;
-a; // equivalent to a.opNeg(), which is an error
-------
    )
    )

<h3>Overloading cast($(I type))$(I e)</h3>

    $(P The member function $(I e).$(B opCast()) is called,
    and the return value of $(B opCast()) is implicitly converted
    to $(I type). Since functions cannot be overloaded based on
    return value, there can be only one $(B opCast) per struct or
    class.
    Overloading the cast operator does not affect implicit casts, it
    only applies to explicit casts.
    )

-------
struct A
{
    int $(B opCast)() { return 28; }
}

void test()
{
    A a;

    long i = cast(long)a;   // i is set to 28L
    void* p = cast(void*)a; // error, cannot implicitly
                // convert int to void*
    int j = a;          // error, cannot implicitly convert
                // A to int
}
-------

<h2><a name="Binary">Binary Operator Overloading</a></h2>


    $(TABLE2 Overloadable Binary Operators,

    $(TR $(TH $(I op))
    $(TH commutative?)
    $(TH $(I opfunc))
    $(TH $(I opfunc_r))
    )

    $(TR $(TD +) $(TD yes) $(TD $(CODE opAdd)) $(TD $(CODE opAdd_r)))

    $(TR $(TD -) $(TD no) $(TD $(CODE opSub)) $(TD $(CODE opSub_r)))

    $(TR $(TD *) $(TD yes) $(TD $(CODE opMul)) $(TD $(CODE opMul_r)))

    $(TR $(TD /) $(TD no) $(TD $(CODE opDiv)) $(TD $(CODE opDiv_r)))

    $(TR $(TD %) $(TD no) $(TD $(CODE opMod)) $(TD $(CODE opMod_r)))

    $(TR $(TD &) $(TD yes) $(TD $(CODE opAnd)) $(TD $(CODE opAnd_r)))

    $(TR $(TD |) $(TD yes) $(TD $(CODE opOr)) $(TD $(CODE opOr_r)))

    $(TR $(TD ^) $(TD yes) $(TD $(CODE opXor)) $(TD $(CODE opXor_r)))

    $(TR $(TD &lt;&lt;) $(TD no) $(TD $(CODE opShl)) $(TD $(CODE opShl_r)))

    $(TR $(TD &gt;&gt;) $(TD no) $(TD $(CODE opShr)) $(TD $(CODE opShr_r)))

    $(TR $(TD &gt;&gt;&gt;) $(TD no) $(TD $(CODE opUShr)) $(TD $(CODE opUShr_r)))

    $(TR $(TD ~) $(TD no) $(TD $(CODE opCat)) $(TD $(CODE opCat_r)))

    $(TR $(TD ==) $(TD yes) $(TD $(CODE opEquals)) $(TD  -))

    $(TR $(TD !=) $(TD yes) $(TD $(CODE opEquals)) $(TD  -))

    $(TR $(TD &lt;) $(TD yes) $(TD $(CODE opCmp)) $(TD  -))

    $(TR $(TD &lt;=) $(TD yes) $(TD $(CODE opCmp)) $(TD  -))

    $(TR $(TD &gt;) $(TD yes) $(TD $(CODE opCmp)) $(TD  -))

    $(TR $(TD &gt;=) $(TD yes) $(TD $(CODE opCmp)) $(TD  -))

    $(TR $(TD =) $(TD no ) $(TD $(CODE opAssign)) $(TD -) )

    $(TR $(TD +=) $(TD no) $(TD $(CODE opAddAssign)) $(TD  -))

    $(TR $(TD -=) $(TD no) $(TD $(CODE opSubAssign)) $(TD  -))

    $(TR $(TD *=) $(TD no) $(TD $(CODE opMulAssign)) $(TD  -))

    $(TR $(TD /=) $(TD no) $(TD $(CODE opDivAssign)) $(TD  -))

    $(TR $(TD %=) $(TD no) $(TD $(CODE opModAssign)) $(TD  -))

    $(TR $(TD &=) $(TD no) $(TD $(CODE opAndAssign)) $(TD  -))

    $(TR $(TD |=) $(TD no) $(TD $(CODE opOrAssign)) $(TD  -))

    $(TR $(TD ^=) $(TD no) $(TD $(CODE opXorAssign)) $(TD  -))

    $(TR $(TD &lt;&lt;=) $(TD no) $(TD $(CODE opShlAssign)) $(TD  -))

    $(TR $(TD &gt;&gt;=) $(TD no) $(TD $(CODE opShrAssign)) $(TD  -))

    $(TR $(TD &gt;&gt;&gt;=) $(TD no) $(TD $(CODE opUShrAssign)) $(TD  -))

    $(TR $(TD ~=) $(TD no) $(TD $(CODE opCatAssign)) $(TD  -))

    $(TR $(TD in ) $(TD no ) $(TD $(CODE opIn) ) $(TD $(CODE opIn_r) ))

    )

    $(P Given a binary
    overloadable operator $(I op) and its corresponding
    class or struct member
    function name $(I opfunc) and $(I opfunc_r),
    and the syntax:
    )

---
a $(I op) b
---

    the following sequence of rules is applied, in order, to determine
    which form is used:

    $(OL 
    $(LI The expression is rewritten as both:
---
a.$(I opfunc)(b)
b.$(I opfunc_r)(a)
---
    If any $(I a.opfunc) or $(I b.opfunc_r) functions exist,
    then overloading is applied
    across all of them and the best match is used. If either exist,
    and there is no argument match, then it is an error.
    )

    $(LI If the operator is commutative, then the following
    forms are tried:
---
a.$(I opfunc_r)(b)
b.$(I opfunc)(a)
---
    )

    $(LI If $(I a) or $(I b) is a struct or class object reference,
    it is an error.
    )
    )

<h4>Examples</h4>

    $(OL 
    $(LI

-------
class A { int $(B opAdd)(int i); }
A a;
a + 1;  // equivalent to a.opAdd(1)
1 + a;  // equivalent to a.opAdd(1)
-------
    )
    $(LI

-------
class B { int $(B opDiv_r)(int i); }
B b;
1 / b;  // equivalent to b.opDiv_r(1)
-------
    )
    $(LI
-------
class A { int $(B opAdd)(int i); }
class B { int $(B opAdd_r)(A a); }
A a;
B b;
a + 1;  // equivalent to a.opAdd(1)
a + b;  // equivalent to b.opAdd_r(a)
b + a;  // equivalent to b.opAdd_r(a)
-------
    )
    $(LI
-------
class A { int $(B opAdd)(B b);  int $(B opAdd_r)(B b); }
class B { }
A a;
B b;
a + b;  // equivalent to a.opAdd(b)
b + a;  // equivalent to a.opAdd_r(b)
-------
    )
    $(LI
-------
class A { int $(B opAdd)(B b);  int $(B opAdd_r)(B b); }
class B { int $(B opAdd_r)(A a); }
A a;
B b;
a + b;  // ambiguous: a.opAdd(b) or b.opAdd_r(a)
b + a;  // equivalent to a.opAdd_r(b)
-------
    )
    )

<h3>Overloading == and !=</h3>

    $(P Both operators use the $(CODE $(B opEquals)()) function.
    The expression
    $(CODE (a == b)) is rewritten as $(CODE a.$(B opEquals)(b)),
    and $(CODE (a != b)) is rewritten as $(CODE !a.$(B opEquals)(b)).
    )

    $(P The member function $(CODE $(B opEquals)()) is defined as part of
    Object as:
    )

-------
$(V1 int)$(V2 bool) $(B opEquals)(Object o);
-------

    $(P so that every class object has a default $(CODE $(B opEquals)()).
    But every class definition which will be using == or != should
    expect to need to override opEquals. The parameter to the overriding
    function must be of type $(CODE Object), not the type for the class.
    )

    $(P Structs and unions (hereafter just called structs) can
    provide a member function:
    )

-------
$(V1 int)$(V2 bool) $(B opEquals)(S s)
-------
    $(P or:)
-------
$(V1 int)$(V2 bool) $(B opEquals)(S* s)
-------

    $(P where $(CODE S) is the struct name, to define how equality is
    determined.)

    $(P If a struct has no $(B opEquals) function declared for it,
    a bit compare of the contents of the two structs is done to
    determine equality or inequality.
    )

    $(P $(B Note:) Comparing a reference to a class object against $(B null)
    should be done as:
    )
-------
if (a is null)
-------
    $(P and not as:)
-------
if (a == null)
-------
    $(P The latter is converted to:)
-------
if (a.$(B opEquals)(null))
-------
    $(P which will fail if $(CODE $(B opEquals)()) is a virtual function.)

<h3>Overloading &lt;, &lt;=, &gt; and &gt;=</h3>

    $(P These comparison operators all use the $(CODE $(B opCmp)()) function.
    The expression
    $(CODE (a $(I op) b)) is rewritten as $(CODE (a.$(B opCmp)(b) $(I op) 0)).
    The commutative operation is rewritten as $(CODE (0 $(I op) b.$(B opCmp)(a)))
    )

    $(P The member function $(CODE $(B opCmp)()) is defined as part of Object
    as:
    )

-------
int $(B opCmp)(Object o);
-------

    $(P so that every class object has a $(CODE $(B opCmp)()).
    )

    $(P $(CODE $(B opCmp)) for structs works analogously to
    $(CODE $(B opEquals)) for structs:
    )
-------
struct Pair
{
    int a, b;
    int $(B opCmp)(Pair rhs)
    {
        if (a!=rhs.a) return a-rhs.a;
        return b-rhs.b;
    }
}
-------

    $(P If a struct has no $(CODE $(B opCmp)()) function declared for it,
    attempting
    to compare two structs is an error.
    )

<h4>Rationale</h4>

    $(P The reason for having both $(CODE $(B opEquals)) and
    $(CODE $(B opCmp)) is that:)

    $(UL
    $(LI Testing for equality can sometimes be a much more efficient
    operation than testing for less or greater than.)
    $(LI Having an $(CODE $(B opCmp)) defined in $(CODE Object)
    makes it possible to
    make associative arrays work generically for classes.)
    $(LI For some objects, testing for less or greater makes no sense.
    This is why $(CODE Object.$(B opCmp)) throws a runtime error.
    $(CODE $(B opCmp)) must be overridden in each class for which comparison
    makes sense.)
    )

    $(P The parameter to $(B opEquals) and $(B opCmp)
    for class definitions must
    be of type $(CODE Object), rather than the type of the particular class,
    in order to override the $(CODE Object.$(B opEquals)) and
    $(CODE Object.$(B opCmp))
    functions properly.
    )

<h2><a name="FunctionCall">Function Call Operator Overloading $(I f)()</a></h2>

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

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

void test()
{   F f;
    int i;

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

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

<h2><a name="Array">Array Operator Overloading</a></h2>

<h3>Overloading Indexing $(I a)[$(I i)]</h3>

    $(P The array index operator, [], can be overloaded by
    declaring a function named $(B opIndex) with one
    or more parameters.
    Assignment to an array can be overloaded with a function
    named $(B opIndexAssign) with two or more parameters.
    The first parameter is the rvalue of the assignment expression.
    )

-------
struct A
{
    int $(B opIndex)(size_t i1, size_t i2, size_t i3);
    int $(B opIndexAssign)(int value, size_t i1, size_t i2);
}

void test()
{   A a;
    int i;

    i = a$(B [)5,6,7$(B ]); // same as i = a.opIndex(5,6,7);
    a$(B [)i,3$(B ]) = 7;       // same as a.opIndexAssign(7,i,3);
}
-------

    $(P In this way a struct or class object can behave as if it
    were an array.
    )

$(V1
    $(P $(B Note:) Array index overloading currently does not
    work for the lvalue of an $(I op)=, ++, or -- operator.
    )
)
$(V2
    $(P $(B Note:) To use array index overloading
    with the $(I op)=, ++, or -- operators,
    have the opIndex function return a reference type.
    This reference is then used as the lvalue for those operators.
    )
)

<h3>Overloading Slicing $(I a)[] and $(I a)[$(I i) .. $(I j)]</h3>

    $(P Overloading the slicing operator means overloading expressions
    like $(CODE a[]) and $(CODE a[i .. j]).
    This can be done by declaring a function named $(B opSlice).
    Assignment to a slice can be done by declaring $(B opSliceAssign).
    )

-------
class A
{
    int $(B opSlice)();               // overloads a[]
    int $(B opSlice)(size_t x, size_t y);         // overloads a[i .. j]

    int $(B opSliceAssign)(int v);            // overloads a[] = v
    int $(B opSliceAssign)(int v, size_t x, size_t y); // overloads a[i .. j] = v
}

void test()
{   A a = new A();
    int i;
    int v;

    i = a$(B []);       // same as i = a.opSlice();
    i = a$(B [)3..4$(B ]);  // same as i = a.opSlice(3,4);

    a$(B []) = v;       // same as a.opSliceAssign(v);
    a$(B [)3..4$(B ]) = v;  // same as a.opSliceAssign(v,3,4);
}
-------

<h2><a name="Assignment">Assignment Operator Overloading</a></h2>

    $(P The assignment operator $(CODE =) can be overloaded if the
    lvalue is a struct $(V1 or class) aggregate, and $(CODE opAssign)
    is a member function of that aggregate.)

    $(P The assignment operator cannot be overloaded for rvalues
    that can be implicitly cast to the lvalue type.
    Furthermore, the following parameter signatures for $(CODE opAssign)
    are not allowed:)

---
opAssign(...)
opAssign(T)
opAssign(T, ...)
opAssign(T ...)
opAssign(T, U = defaultValue, etc.)
---

    $(P where $(I T) is the same type as the aggregate type $(I A),
    is implicitly
    convertible to $(I A), or if $(I A) is a struct and $(I T)
    is a pointer to a type that is
    implicitly convertible to $(I A).
    )

$(V2
$(DOT
<h2><a name="Dot">Forwarding</a></h2>

    $(P Providing a struct or class member function $(CODE opDot) enables
    the forwarding
    of any names not found in the struct's scope to be forwarded
    to the return type of the $(CODE opDot) function. In other words:
    )

---
struct T {
  ...
  S opDot() { ... }
}
T t;
...
t.m
---

    $(P is rewritten as:)

---
t.opDot().m
---

    $(P if m does not exist as a member of the struct T.)

    $(P The members .sizeof, .init, .offsetof, .alignof, .mangleof
    and .stringof are not forwarded to $(CODE opDot).)

---
struct S {
    int a, b, c;
}

struct T {
    S s;
    int b = 7;

    S* opDot() {
        return &s;    // forwards to member s
    }
}

void main() {
    T t;
    t.a = 4;
    t.b = 5;
    t.c = 6;
    assert(t.a == 4);
    assert(t.b == 5);    // T.b overrides S.b
    assert(t.c == 6);
    assert(t.s.b == 0);
    assert(t.sizeof == 4*4); // sizeof T, not sizeof S
}
---
)
)

<h2><a name="Future">Future Directions</a></h2>

    $(P The operators $(CODE ! && || ?:) and a few others will
    likely never be overloadable.
    )
)
)

Macros:
    TITLE=Operator Overloading
    WIKI=OperatorOverloading
    SUB=<sub>$0</sub>
    ARGUMENTS=$(I b)$(SUB 1), $(I b)$(SUB 2), ... $(I b)$(SUB n)
    SLICE=$(I i)..$(I j)
    SLICE2=$(I i), $(I j)
    FOO=