operatoroverloading.dd

Ddoc

$(SPEC_S Operator Overloading,

	$(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 $(RELATIVE_LINK2 Unary, Unary Operator Overloading))
	$(LI $(RELATIVE_LINK2 Cast, Cast Operator Overloading))
	$(LI $(RELATIVE_LINK2 Binary, Binary Operator Overloading))
	$(LI $(RELATIVE_LINK2 equals, Overloading $(D ==) and $(D !=)))
	$(LI $(RELATIVE_LINK2 compare, Overloading $(D <), $(D <)$(D =),
	$(D <), and $(D <)$(D =)))
	$(LI $(RELATIVE_LINK2 FunctionCall, Function Call Operator Overloading))
	$(LI $(RELATIVE_LINK2 Assignment, Assignment Operator Overloading))
	$(LI $(RELATIVE_LINK2 OpAssign, Op Assignment Operator Overloading))
	$(LI $(RELATIVE_LINK2 Array, Index Operator Overloading))
	$(LI $(RELATIVE_LINK2 Slice, Slice Operator Overloading))
	$(LI $(RELATIVE_LINK2 Dollar, Dollar Operator Overloading))
	$(LI $(RELATIVE_LINK2 Dispatch, Forwarding))
	)

$(H2 $(LNAME2 Unary, Unary Operator Overloading))

	$(TABLE2 Overloadable Unary Operators,
	$(THEAD $(I op), $(I rewrite))
	$(TROW
	$(ARGS $(D -)$(I e)),
	$(ARGS $(I e)$(D .opUnary!("-")()))
	)
	$(TROW
	$(ARGS $(D +)$(I e)),
	$(ARGS $(I e)$(D .opUnary!("+")()))
	)
	$(TROW
	$(ARGS $(D ~)$(I e)),
	$(ARGS $(I e)$(D .opUnary!("~")()))
	)

	$(TROW
	$(ARGS $(D *)$(I e)),
	$(ARGS $(I e)$(D .opUnary!("*")()))
	)

	$(TROW
	$(ARGS $(D ++)$(I e)),
	$(ARGS $(I e)$(D .opUnary!("++")()))
	)

	$(TROW
	$(ARGS $(D --)$(I e)),
	$(ARGS $(I e)$(D .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)$(D ++) and Postdecrement $(I e)$(D --) Operators)

	$(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,
	$(THEAD $(I op), $(I rewrite))
	$(TROW
	$(ARGS $(I e)$(D --)),
	$(ARGS $(D $(LPAREN)auto t =) $(I e)$(D , --)$(I e)$(D , t$(RPAREN))))
	$(TROW
	$(ARGS $(I e)$(D ++)),
	$(ARGS $(D $(LPAREN)auto t =) $(I e)$(D , ++)$(I e)$(D , t$(RPAREN))))
	)

$(H3 Overloading Index Unary Operators)

	$(TABLE2 Overloadable Index Unary Operators,
	$(THEAD $(I op), $(I rewrite))
	$(TROW
	$(D -)$(I a)$(D [b1,b2,...,bn]),
	$(ARGS $(I a)$(D .opIndexUnary!("-")$(LPAREN)b1,b2,...,bn$(RPAREN))))
	$(TROW
	$(D +)$(I a)$(D [b1,b2,...,bn]),
	$(I a)$(D .opIndexUnary!("+")$(LPAREN)b1,b2,...,bn$(RPAREN))
	)
	$(TROW
	$(D ~)$(I a)$(D [b1,b2,...,bn]),
	$(I a)$(D .opIndexUnary!("~")$(LPAREN)b1,b2,...,bn$(RPAREN))
	)
	$(TROW
	$(D *)$(I a)$(D [b1,b2,...,bn]),
	$(I a)$(D .opIndexUnary!("*")$(LPAREN)b1,b2,...,bn$(RPAREN))
	)
	$(TROW
	$(D ++)$(I a)$(D [b1,b2,...,bn]),
	$(I a)$(D .opIndexUnary!("++")$(LPAREN)b1,b2,...,bn$(RPAREN))
	)
	$(TROW
	$(D --)$(I a)$(D [b1,b2,...,bn]),
	$(I a)$(D .opIndexUnary!("--")$(LPAREN)b1,b2,...,bn$(RPAREN))
	)
	)

$(H3 Overloading Slice Unary Operators)

	$(TABLE2 Overloadable Slice Unary Operators,
	$(THEAD $(I op), $(I rewrite))
	$(TROW
	$(D -)$(I a)$(D [)$(SLICE)$(D ]),
	$(I a)$(D .opSliceUnary!("-")$(LPAREN))$(SLICE2)$(D $(RPAREN))
	)

	$(TROW
	$(D +)$(I a)$(D [)$(SLICE)$(D ]),
	$(I a)$(D .opSliceUnary!("+")$(LPAREN))$(SLICE2)$(D $(RPAREN))
	)

	$(TROW
	$(D ~)$(I a)$(D [)$(SLICE)$(D ]),
	$(I a)$(D .opSliceUnary!("~")$(LPAREN))$(SLICE2)$(D $(RPAREN))
	)

	$(TROW
	$(D *)$(I a)$(D [)$(SLICE)$(D ]),
	$(I a)$(D .opSliceUnary!("*")$(LPAREN))$(SLICE2)$(D $(RPAREN))
	)

	$(TROW
	$(D ++)$(I a)$(D [)$(SLICE)$(D ]),
	$(I a)$(D .opSliceUnary!("++")$(LPAREN))$(SLICE2)$(D $(RPAREN))
	)

	$(TROW
	$(D --)$(I a)$(D [)$(SLICE)$(D ]),
	$(I a)$(D .opSliceUnary!("--")$(LPAREN))$(SLICE2)$(D $(RPAREN))
	)

	$(TROW
	$(D -)$(I a)$(D [ ]),
	$(I a)$(D .opSliceUnary!("-")())
	)

	$(TROW
	$(D +)$(I a)$(D [ ]),
	$(I a)$(D .opSliceUnary!("+")())
	)

	$(TROW
	$(D ~)$(I a)$(D [ ]),
	$(I a)$(D .opSliceUnary!("~")())
	)

	$(TROW
	$(D *)$(I a)$(D [ ]),
	$(I a)$(D .opSliceUnary!("*")())
	)

	$(TROW
	$(D ++)$(I a)$(D [ ]),
	$(I a)$(D .opSliceUnary!("++")())
	)

	$(TROW
	$(D --)$(I a)$(D [ ]),
	$(I a)$(D .opSliceUnary!("--")())
	)
	)

$(H2 $(LNAME2 Cast, Cast Operator Overloading))

	$(TABLE2 Cast Operators,
	$(THEAD $(I op), $(I rewrite))
	$(TROW
	$(D cast$(LPAREN))$(I type) $(I e)$(D $(RPAREN)),
	$(I e)$(D .opCast!$(LPAREN))$(I type)$(D $(RPAREN)())
	)
	)


$(H3 Boolean Operations)

	$(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 $(LNAME2 Binary, Binary Operator Overloading))

	$(P The following binary operators are overloadable:)

	$(TABLE2 Overloadable Binary Operators,
	$(TROW $(D +), $(D -), $(D *), $(D /), $(CODE_PERCENT), $(D ^^), $(CODE_AMP))
	$(TROW $(CODE_PIPE), $(D ^), $(D <)$(D <), $(D >)$(D >), $(D >)$(D >)$(D >), $(D ~), $(D in))
	)

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

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

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

	$(P To do them all en masse:)

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


$(H2 $(LNAME2 equals, Overloading $(D ==) and $(D !=)))

	$(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)
	---
	$(P 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 than the other, or one compiles and the other
	does not, the first 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 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)
	}
	---

	$(P Alternatively, you can declare a single templated opEquals
	function with an $(XLINK2 template.html#auto-ref-parameters, auto ref)
	parameter:) $(LATEX \pagebreak[4])
	---
	struct S {
	  // for l-values and r-values,
	  // with converting both hand side implicitly to const
	  bool opEquals()(auto ref const S s) const { ... }
	}
	---


$(H2 $(LNAME2 compare, Overloading $(D <), $(D <)$(D =), $(D >), and $(D >)$(D =)))

	$(P Comparison operations are rewritten as follows:)

	$(TABLE2 Overloadable Unary Operators,
	$(THEAD comparison, rewrite 1, rewrite 2)
	$(TROW $(D a) $(D <) $(D b), $(D a.opCmp(b)) $(D <)
	$(D 0), $(ARGS $(D b.opCmp(a)) $(D >) $(D 0)))
	$(TROW $(D a) $(D <)$(D= b), $(ARGS $(D a.opCmp(b))
	$(D <)$(D= 0)), $(ARGS $(D b.opCmp(a)) $(D >)$(D = 0)))
	$(TROW $(D a) $(D >)$(D b), $(ARGS $(D a.opCmp(b))
	$(D >) $(D 0)), $(ARGS $(D b.opCmp(a)) $(D <) $(D 0)))
	$(TROW $(D a) $(D >)$(D = b), $(ARGS $(D a.opCmp(b))
	$(D >)$(D = 0)), $(ARGS $(D b.opCmp(a)) $(D <)$(D= 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) const { ... }
}
---

$(H2 $(LNAME2 FunctionCall, Function Call Operator Overloading $(D f())))

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

	-------
	struct F {
	  int $(CODE_HIGHLIGHT opCall)();
	  int $(CODE_HIGHLIGHT 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);
	}
	-------

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

	$(P $(CODE static opCall) also works as expected for function call operator with
	type names.
	)

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

	$(P Note that merely declaring $(D opCall) automatically disables
	$(XLINK2 struct.html#StructLiteral, struct literal) syntax.
	To avoid the limitation, you need to also declare $(XLINK2 Struct-Constructor,
	constructor) so that it takes priority over $(D opCall) in $(D Type(...)) syntax.
	)

	-------
	struct Multiplier {
	  int factor;
	  this(int num) { factor = num; }
	  int opCall(int value) { return value * factor; }
	}
	void test() {
	  Multiplier m = Multiplier(10);  // invoke constructor
	  int result = m(5);              // invoke opCall
	  assert(result == 50);
	}
	-------

$(H2 $(LNAME2 Assignment, Assignment Operator Overloading))

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

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

	---
	struct S {
	  // identiy assignment, allowed.
	  void $(CODE_HIGHLIGHT opAssign)(S rhs);

	  // not identity assignment, also allowed.
	  void $(CODE_HIGHLIGHT 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 $(CODE_HIGHLIGHT opAssign)(int);
	}
	C c = new C();
	c = new C();  // Rebinding referencee
	c = 1;        // Rewritten to c.opAssign(1);
	---

$(H3 Index Assignment Operator Overloading)

	$(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 $(D a[b1,b2,...,bn] = c) are rewritten
	as $(D a.opIndexAssign$(LPAREN)c,b1,b2,...,bn$(RPAREN)).
	)

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

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

$(H3 Slice Assignment Operator Overloading)

	$(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)$(D ] = c) are rewritten
	as $(CODE a.opSliceAssign$(LPAREN)c,) $(SLICE2)$(D $(RPAREN)), and
	$(CODE a[] = c) as $(CODE a.opSliceAssign(c)).
	)

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

void test() {
  A a;
  int v;

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

$(H2 $(LNAME2 OpAssign, Op Assignment Operator Overloading))

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

	$(TABLE2 Overloadable Op Assignment Operators,
	$(TROW $(D +=), $(D -=), $(D *=), $(D /=), $(CODE_PERCENT)$(D =), $(D ^^=), $(CODE_AMP)$(D =))
	$(TROW $(CODE_PIPE)$(D =), $(D ^=), $(D <)$(D <)$(D =),
	$(D >)$(D >)$(D =), $(D >)$(D >)$(D >)$(D =), $(D ~=), $(NBSP))
	)

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

	$(P is rewritten as:)

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

$(H3 Index Op Assignment Operator Overloading)

	$(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[$(METACODE $(ARGUMENTS))] $(METACODE op)= c
---

	$(P it is rewritten as:)

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

$(H3 Slice Op Assignment Operator Overloading)

	$(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[$(METACODE $(SLICE))] $(METACODE op)= c
---

	$(P it is rewritten as:)

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

	$(P and)

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

	$(P it is rewritten as:)

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

$(H2 $(LNAME2 Array, Index Operator Overloading))

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

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

void test() {
  A a;
  int i;
  i = a[5,6,7];  // 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 $(LNAME2 Slice, Slice Operator Overloading))

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

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

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

  i = a$(CODE_HIGHLIGHT []);         // same as i = a.opSlice();
  i = a$(CODE_HIGHLIGHT [)3..4$(CODE_HIGHLIGHT ]);  // 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 $(LNAME2 Dollar, Dollar Operator Overloading))

	$(P Within the arguments to array index and slicing operators, $(D $)
	gets translated to $(D opDollar), which can be overloaded by a struct
	or class object.
	)

------
struct Rectangle {
  int width, height;
  int[][] impl;
  this(int w, int h) {
    width = w;
    height = h;
    impl = new int[w][h];
  }
  int opIndex(size_t i1, size_t i2) {
    return impl[i1][i2];
  }
  int opDollar(size_t pos)() {
    static if (pos==0)
      return width;
    else
      return height;
  }
}

void test() {
  auto r = Rectangle(10,20);
  int i = r[$-1, 0];    // same as: r.opIndex(r.opDollar!0, 0),
                        // which is r.opIndex(r.width-1, 0)
  int j = r[0, $-1];    // same as: r.opIndex(0, r.opDollar!1)
                        // which is r.opIndex(0, r.height-1)
}
------

	$(P As the above example shows, a different compile-time argument is
	passed to $(D opDollar) depending on which argument it appears in. A
	$(D $) appearing in the first argument gets translated to $(D
	opDollar!0), a $(D $) appearing in the second argument gets translated
	to $(D opDollar!1), and so on. Thus, the appropriate value for $(D $)
	can be returned to implement multidimensional arrays.
	)

	$(P If $(D opIndex) is declared with only one argument, the
	compile-time argument to $(D opDollar) may be omitted. In this case, it
	is illegal to use $(D $) inside an array indexing expression with more
	than one argument.
	)

	$(P Note that $(D opDollar) does not have to return an integer index;
	it can return any type as long as that type is understood by $(D
	opIndex). For example, a special token can be returned by $(D opDollar)
	to implement slicing of infinite ranges.
	)

$(H2 $(LNAME2 Dispatch, Forwarding))

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

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