root/trunk/docsrc/operatoroverloading.dd

Revision 2040, 26.8 kB (checked in by walter, 4 years ago)

typography

  • Property svn:eol-style set to native
Line 
1 Ddoc
2
3 $(SPEC_S Operator Overloading,
4
5 $(V2
6     $(P Operator overloading is accomplished by rewriting operators whose
7     operands are class or struct objects into calls to specially named
8     member functions. No additional syntax is used.
9     )
10
11     $(UL
12     $(LI $(LINK2 #Unary, Unary Operator Overloading))
13     $(LI $(LINK2 #Cast, Cast Operator Overloading))
14     $(LI $(LINK2 #Binary, Binary Operator Overloading))
15     $(LI $(LINK2 #equals, Overloading == and !=))
16     $(LI $(LINK2 #compare, Overloading < <=, > and >=))
17     $(LI $(LINK2 #FunctionCall, Function Call Operator Overloading))
18     $(LI $(LINK2 #Assignment, Assignment Operator Overloading))
19     $(LI $(LINK2 #OpAssign, Op Assignment Operator Overloading))
20     $(LI $(LINK2 #Array, Index Operator Overloading))
21     $(LI $(LINK2 #Slice, Slice Operator Overloading))
22     $(LI $(LINK2 #Dispatch, Forwarding))
23     )
24
25 <h2><a name="Unary">Unary Operator Overloading</a></h2>
26
27     $(TABLE2 Overloadable Unary Operators,
28
29     $(TR $(TH$(I op)) $(TH$(I rewrite)) )
30
31     $(TR
32     $(TD -$(I e))
33     $(TD $(CODE $(I e).opUnary!("-")()))
34     )
35
36     $(TR
37     $(TD +$(I e))
38     $(TD $(CODE $(I e).opUnary!("+")()))
39     )
40
41     $(TR
42     $(TD ~$(I e))
43     $(TD $(CODE $(I e).opUnary!("~")()))
44     )
45
46     $(TR
47     $(TD *$(I e))
48     $(TD $(CODE $(I e).opUnary!("*")()))
49     )
50
51     $(TR
52     $(TD ++$(I e))
53     $(TD $(CODE $(I e).opUnary!("++")()))
54     )
55
56     $(TR
57     $(TD --$(I e))
58     $(TD $(CODE $(I e).opUnary!("--")()))
59     )
60
61     )
62
63     $(P For example, in order to overload the - (negation) operator for struct S, and
64     no other operator:)
65
66 ---
67 struct S {
68     int m;
69
70     int opUnary(string s)() if (s == "-") {
71         return -m;
72     }
73 }
74
75 int foo(S s) {
76     return -s;
77 }
78 ---
79
80 <h3>Postincrement $(I e)++ and Postdecrement $(I e)-- Operators</h3>
81
82     $(P These are not directly overloadable, but instead are rewritten
83     in terms of the ++$(I e) and --$(I e) prefix operators:
84     )
85
86     $(TABLE2 Postfix Operator Rewrites,
87
88     $(TR $(TH$(I op)) $(TH$(I rewrite)) )
89
90     $(TR
91     $(TD $(I e)--)
92     $(TD $(CODE (auto t = e, --$(I e), t)))
93     )
94
95     $(TR
96     $(TD $(I e)++)
97     $(TD $(CODE (auto t = e, ++$(I e), t)))
98     )
99     )
100
101 <h3>Overloading Index Unary Operators</h3>
102
103     $(TABLE2 Overloadable Index Unary Operators,
104
105     $(TR $(TH$(I op)) $(TH$(I rewrite)) )
106
107     $(TR
108     $(TD $(CODE -$(I a)[$(ARGUMENTS)]))
109     $(TD $(CODE $(I a).opIndexUnary!("-")($(ARGUMENTS))))
110     )
111
112     $(TR
113     $(TD $(CODE +$(I a)[$(ARGUMENTS)]))
114     $(TD $(CODE $(I a).opIndexUnary!("+")($(ARGUMENTS))))
115     )
116
117     $(TR
118     $(TD $(CODE ~$(I a)[$(ARGUMENTS)]))
119     $(TD $(CODE $(I a).opIndexUnary!("~")($(ARGUMENTS))))
120     )
121
122     $(TR
123     $(TD $(CODE *$(I a)[$(ARGUMENTS)]))
124     $(TD $(CODE $(I a).opIndexUnary!("*")($(ARGUMENTS))))
125     )
126
127     $(TR
128     $(TD $(CODE ++$(I a)[$(ARGUMENTS)]))
129     $(TD $(CODE $(I a).opIndexUnary!("++")($(ARGUMENTS))))
130     )
131
132     $(TR
133     $(TD $(CODE --$(I a)[$(ARGUMENTS)]))
134     $(TD $(CODE $(I a).opIndexUnary!("--")($(ARGUMENTS))))
135     )
136
137     )
138
139 <h3>Overloading Slice Unary Operators</h3>
140
141     $(TABLE2 Overloadable Slice Unary Operators,
142
143     $(TR $(TH$(I op)) $(TH$(I rewrite)) )
144
145     $(TR
146     $(TD $(CODE -$(I a)[$(SLICE)]))
147     $(TD $(CODE $(I a).opSliceUnary!("-")($(SLICE2))))
148     )
149
150     $(TR
151     $(TD $(CODE +$(I a)[$(SLICE)]))
152     $(TD $(CODE $(I a).opSliceUnary!("+")($(SLICE2))))
153     )
154
155     $(TR
156     $(TD $(CODE ~$(I a)[$(SLICE)]))
157     $(TD $(CODE $(I a).opSliceUnary!("~")($(SLICE2))))
158     )
159
160     $(TR
161     $(TD $(CODE *$(I a)[$(SLICE)]))
162     $(TD $(CODE $(I a).opSliceUnary!("*")($(SLICE2))))
163     )
164
165     $(TR
166     $(TD $(CODE ++$(I a)[$(SLICE)]))
167     $(TD $(CODE $(I a).opSliceUnary!("++")($(SLICE2))))
168     )
169
170     $(TR
171     $(TD $(CODE --$(I a)[$(SLICE)]))
172     $(TD $(CODE $(I a).opSliceUnary!("--")($(SLICE2))))
173     )
174
175     $(TR
176     $(TD $(CODE -$(I a)[ ]))
177     $(TD $(CODE $(I a).opSliceUnary!("-")()))
178     )
179
180     $(TR
181     $(TD $(CODE +$(I a)[ ]))
182     $(TD $(CODE $(I a).opSliceUnary!("+")()))
183     )
184
185     $(TR
186     $(TD $(CODE ~$(I a)[ ]))
187     $(TD $(CODE $(I a).opSliceUnary!("~")()))
188     )
189
190     $(TR
191     $(TD $(CODE *$(I a)[ ]))
192     $(TD $(CODE $(I a).opSliceUnary!("*")()))
193     )
194
195     $(TR
196     $(TD $(CODE ++$(I a)[ ]))
197     $(TD $(CODE $(I a).opSliceUnary!("++")()))
198     )
199
200     $(TR
201     $(TD $(CODE --$(I a)[ ]))
202     $(TD $(CODE $(I a).opSliceUnary!("--")()))
203     )
204     )
205
206 <h2><a name="Cast">Cast Operator Overloading</a></h2>
207
208     $(TABLE2 Cast Operators,
209
210     $(TR $(TH$(I op)) $(TH$(I rewrite)) )
211
212     $(TR
213     $(TD cast($(I type))$(I e))
214     $(TD $(CODE $(I e).opCast!($(I type))()))
215     )
216
217     )
218
219
220 <h3>Boolean Operations</h3>
221
222     $(P Notably absent from the list of overloaded unary operators is the !
223     logical negation operator. More obscurely absent is a unary operator
224     to convert to a bool result.
225     Instead, these are covered by a rewrite to:
226     )
227 ---
228 opCast!(bool)(e)
229 ---
230
231     $(P So,)
232
233 ---
234 if (e)   =>  if (e.opCast!(bool))
235 if (!e)  =>  if (!e.opCast!(bool))
236 ---
237
238     $(P etc., whenever a bool result is expected. This only happens, however, for
239     instances of structs. Class references are converted to bool by checking to
240     see if the class reference is null or not.
241     )
242
243 <h2><a name="Binary">Binary Operator Overloading</a></h2>
244
245     $(P The following binary operators are overloadable:)
246
247     $(TABLE2 Overloadable Binary Operators,
248
249     $(TR $(TD +) $(TD -) $(TD *) $(TD /) $(TD %) $(TD ^^) $(TD &amp;) )
250     $(TR $(TD |) $(TD ^) $(TD &lt;&lt;) $(TD &gt;&gt;) $(TD &gt;&gt;&gt;) $(TD ~) $(TD in) )
251
252     )
253
254     $(P The expression:)
255 ---
256 a $(I op) b
257 ---
258     $(P is rewritten as both:)
259 ---
260 a.opBinary!("$(I op)")(b)
261 b.opBinaryRight!("$(I op)")(a)
262 ---
263
264     $(P and the one with the $(SINGLEQUOTE better) match is selected.
265     It is an error for both to equally match.
266     )
267
268 <h2><a name="equals">Overloading == and !=</a></h2>
269
270     $(P Expressions of the form $(CODE a != b) are rewritten as $(CODE !(a == b)).)
271
272     $(P Given $(CODE a == b) :)
273
274 $(OL
275     $(LI If a and b are both class objects, then the expression is rewritten as:
276 ---
277 .object.opEquals(a, b)
278 ---
279     and that function is implemented as:
280 ---
281 bool opEquals(Object a, Object b) {
282     if (a is b) return true;
283     if (a is null || b is null) return false;
284     if (typeid(a) == typeid(b)) return a.opEquals(b);
285     return a.opEquals(b) && b.opEquals(a);
286 }
287 ---
288     )
289     $(LI Otherwise the expressions $(CODE a.opEquals(b)) and
290     $(CODE b.opEquals(a)) are tried. If both resolve to the same opEquals
291     function, then the expression is rewritten to be $(CODE a.opEquals(b)).
292     )
293     $(LI If one is a better match then the other, or one compiles and the other
294     does not, the one is selected.)
295     $(LI Otherwise, an error results.)
296 )
297
298     $(P If overridding Object.opEquals() for classes, the class member function
299     signature should look like:)
300 ---
301 class C {
302     override bool opEquals(Object o) { ... }
303 }
304 ---
305
306     $(P If structs declare an opEquals member function, it should follow the following
307     form:)
308 ---
309 struct S {
310     int opEquals(ref const S s) { ... }
311 }
312 ---
313
314 <h2><a name="compare">Overloading &lt; &lt;=, &gt; and &gt;=</a></h2>
315
316     $(P Comparison operations are rewritten as follows:)
317
318     $(TABLE2 Overloadable Unary Operators,
319     $(TR $(TH comparison) $(TH rewrite 1) $(TH rewrite 2) )
320
321     $(TR $(TD $(CODE a &lt; b)) $(TD $(CODE a.opCmp(b) &lt; 0)) $(TD $(CODE b.opCmp(a) &gt; 0)))
322     $(TR $(TD $(CODE a &lt;= b)) $(TD $(CODE a.opCmp(b) &lt;= 0)) $(TD $(CODE b.opCmp(a) &gt;= 0)))
323     $(TR $(TD $(CODE a &gt; b)) $(TD $(CODE a.opCmp(b) &gt; 0)) $(TD $(CODE b.opCmp(a) &lt; 0)))
324     $(TR $(TD $(CODE a &gt;= b)) $(TD $(CODE a.opCmp(b) &gt;= 0)) $(TD $(CODE b.opCmp(a) &lt;= 0)))
325     )
326
327     $(P Both rewrites are tried. If only one compiles, that one is taken.
328     If they both resolve to the same function, the first
329     rewrite is done. If they resolve to different functions, the best matching one
330     is used. If they both match the same, but are different functions, an ambiguity
331     error results.
332     )
333
334     $(P If overriding Object.opCmp() for classes, the class member function
335     signature should look like:)
336 ---
337 class C {
338     override int opCmp(Object o) { ... }
339 }
340 ---
341
342     $(P If structs declare an opCmp member function, it should follow the following
343     form:)
344 ---
345 struct S {
346     int opCmp(ref const S s) { ... }
347 }
348 ---
349
350 <h2><a name="FunctionCall">Function Call Operator Overloading $(I f)()</a></h2>
351
352     $(P The function call operator, (), can be overloaded by
353     declaring a function named $(B opCall):
354     )
355
356 -------
357 struct F
358 {
359     int $(B opCall)();
360     int $(B opCall)(int x, int y, int z);
361 }
362
363 void test()
364 {   F f;
365     int i;
366
367     i = f$(B ());       // same as i = f.opCall();
368     i = f$(B (3,4,5));  // same as i = f.opCall(3,4,5);
369 }
370 -------
371
372     $(P In this way a struct or class object can behave as if it
373     were a function.
374     )
375
376 <h2><a name="Assignment">Assignment Operator Overloading</a></h2>
377
378     $(P The assignment operator $(CODE =) can be overloaded if the
379     lvalue is a struct aggregate, and $(CODE opAssign)
380     is a member function of that aggregate.)
381
382     $(P The assignment operator cannot be overloaded for rvalues
383     that can be implicitly cast to the lvalue type.
384     Furthermore, the following parameter signatures for $(CODE opAssign)
385     are not allowed:)
386
387 ---
388 opAssign(...)
389 opAssign(T)
390 opAssign(T, ...)
391 opAssign(T ...)
392 opAssign(T, U = defaultValue, etc.)
393 ---
394
395     $(P where $(I T) is the same type as the aggregate type $(I A),
396     is implicitly
397     convertible to $(I A), or if $(I A) is a struct and $(I T)
398     is a pointer to a type that is
399     implicitly convertible to $(I A).
400     )
401
402 <h3>Index Assignment Operator Overloading</h2>
403
404     $(P If the left hand side of an assignment is an index operation
405     on a struct or class instance,
406     it can be overloaded by providing an opIndexAssign member function.
407     Expressions of the form $(CODE a[$(ARGUMENTS)] = c) are rewritten
408     as $(CODE a.opIndexAssign(c, $(ARGUMENTS))).
409     )
410
411 -------
412 struct A
413 {
414     int $(B opIndexAssign)(int value, size_t i1, size_t i2);
415 }
416
417 void test()
418 {   A a;
419
420     a$(B [)i,3$(B ]) = 7;       // same as a.opIndexAssign(7,i,3);
421 }
422 -------
423
424 <h3>Slice Assignment Operator Overloading</h2>
425
426     $(P If the left hand side of an assignment is a slice operation
427     on a struct or class instance,
428     it can be overloaded by providing an opSliceAssign member function.
429     Expressions of the form $(CODE a[$(SLICE)] = c) are rewritten
430     as $(CODE a.opSliceAssign(c, $(SLICE2))), and
431     $(CODE a[] = c) as $(CODE a.opSliceAssign(c)).
432     )
433
434 -------
435 struct A
436 {
437     int $(B opSliceAssign)(int v);            // overloads a[] = v
438     int $(B opSliceAssign)(int v, size_t x, size_t y); // overloads a[i .. j] = v
439 }
440
441 void test()
442 {   A a;
443     int v;
444
445     a$(B []) = v;       // same as a.opSliceAssign(v);
446     a$(B [)3..4$(B ]) = v;  // same as a.opSliceAssign(v,3,4);
447 }
448 -------
449
450 <h2><a name="OpAssign">Op Assignment Operator Overloading</a></h2>
451
452     $(P The following op assignment operators are overloadable:)
453
454     $(TABLE2 Overloadable Op Assignment Operators,
455
456     $(TR $(TD +=) $(TD -=) $(TD *=) $(TD /=) $(TD %=) $(TD ^^=) $(TD &amp;=) )
457     $(TR $(TD |=) $(TD ^=) $(TD &lt;&lt;=) $(TD &gt;&gt;=) $(TD &gt;&gt;&gt;=) $(TD ~=) $(TD &nbsp;) )
458
459     )
460
461     $(P The expression:)
462 ---
463 a $(I op)= b
464 ---
465
466     $(P is rewritten as:)
467
468 ---
469 a.opOpAssign!("$(I op)")(b)
470 ---
471
472 <h3>Index Op Assignment Operator Overloading</h3>
473
474     $(P If the left hand side of an $(I op)= is an index expression on
475     a struct or class instance and opIndexOpAssign is a member:)
476
477 ---
478 a[$(ARGUMENTS)] $(I op)= c
479 ---
480
481     $(P it is rewritten as:)
482
483 ---
484 a.opIndexOpAssign!("$(I op)")(c, $(ARGUMENTS))
485 ---
486
487 <h3>Slice Op Assignment Operator Overloading</h3>
488
489     $(P If the left hand side of an $(I op)= is a slice expression on
490     a struct or class instance and opSliceOpAssign is a member:)
491
492 ---
493 a[$(SLICE)] $(I op)= c
494 ---
495
496     $(P it is rewritten as:)
497
498 ---
499 a.opSliceOpAssign!("$(I op)")(c, $(SLICE2))
500 ---
501
502     $(P and)
503
504 ---
505 a[] $(I op)= c
506 ---
507
508     $(P it is rewritten as:)
509
510 ---
511 a.opSliceOpAssign!("$(I op)")(c)
512 ---
513
514 <h2><a name="Array">Index Operator Overloading</a></h2>
515
516     $(P The array index operator, $(CODE a[$(ARGUMENTS)]), can be overloaded by
517     declaring a function named $(B opIndex) with one
518     or more parameters.
519     )
520
521 -------
522 struct A
523 {
524     int $(B opIndex)(size_t i1, size_t i2, size_t i3);
525 }
526
527 void test()
528 {   A a;
529     int i;
530
531     i = a$(B [)5,6,7$(B ]); // same as i = a.opIndex(5,6,7);
532 }
533 -------
534
535     $(P In this way a struct or class object can behave as if it
536     were an array.
537     )
538
539     $(P If an index expression can be rewritten using opIndexAssign or opIndexOpAssign,
540     those are preferred over opIndex.
541     )
542
543
544 <h2><a name="Slice">Slice Operator Overloading</a></h2>
545
546     $(P Overloading the slicing operator means overloading expressions
547     like $(CODE a[]) and $(CODE a[$(SLICE)]).
548     This can be done by declaring a member function named $(B opSlice).
549     )
550
551 -------
552 class A
553 {
554     int $(B opSlice)();               // overloads a[]
555     int $(B opSlice)(size_t x, size_t y);         // overloads a[i .. j]
556 }
557
558 void test()
559 {   A a = new A();
560     int i;
561     int v;
562
563     i = a$(B []);       // same as i = a.opSlice();
564     i = a$(B [)3..4$(B ]);  // same as i = a.opSlice(3,4);
565 }
566 -------
567
568     $(P If a slice expression can be rewritten using opSliceAssign or opSliceOpAssign,
569     those are preferred over opSlice.
570     )
571
572 <h2><a name="Dispatch">Forwarding</a></h2>
573
574     $(P Member names not found in a class or struct can be forwarded
575     to a template function named $(CODE opDispatch) for resolution.
576     )
577
578 ---
579 import std.stdio;
580
581 struct S
582 {
583     void opDispatch(string s, T)(T i)
584     {
585     writefln("S.opDispatch('%s', %s)", s, i);
586     }
587 }
588
589 class C
590 {
591     void opDispatch(string s)(int i)
592     {
593     writefln("C.opDispatch('%s', %s)", s, i);
594     }
595 }
596
597 struct D
598 {
599     template opDispatch(string s)
600     {
601     enum int opDispatch = 8;
602     }
603 }
604
605 void main()
606 {
607     S s;
608     s.opDispatch!("hello")(7);
609     s.foo(7);
610
611     auto c = new C();
612     c.foo(8);
613
614     D d;
615     writefln("d.foo = %s", d.foo);
616     assert(d.foo == 8);
617 }
618 ---
619 )
620
621 $(V1
622     $(P Overloading is accomplished by interpreting specially named
623     struct and class member functions as being implementations of unary and
624     binary operators. No additional syntax is used.
625     )
626
627     $(UL
628     $(LI $(LINK2 #Unary, Unary Operator Overloading))
629     $(LI $(LINK2 #Binary, Binary Operator Overloading))
630     $(LI $(LINK2 #FunctionCall, Function Call Operator Overloading))
631     $(LI $(LINK2 #Array, Array Operator Overloading))
632     $(LI $(LINK2 #Assignment, Assignment Operator Overloading))
633 $(V2
634     $(DOT $(LI $(LINK2 #Dot, Forwarding)))
635 )
636     $(LI $(LINK2 #Future, Future Directions))
637     )
638
639 <h2><a name="Unary">Unary Operator Overloading</a></h2>
640
641
642     $(TABLE2 Overloadable Unary Operators,
643
644     $(TR $(TH$(I op)) $(TH$(I opfunc)) )
645
646     $(TR
647     $(TD -$(I e))
648     $(TD $(CODE opNeg))
649     )
650
651     $(TR
652     $(TD +$(I e))
653     $(TD $(CODE opPos))
654     )
655
656     $(TR
657     $(TD ~$(I e))
658     $(TD $(CODE opCom))
659     )
660
661     $(TR
662     $(TD $(I e)++)
663     $(TD $(CODE opPostInc))
664     )
665
666     $(TR
667     $(TD $(I e)--)
668     $(TD $(CODE opPostDec))
669     )
670
671     $(TR
672     $(TD cast($(I type))$(I e))
673     $(TD $(CODE opCast))
674     )
675
676     )
677
678
679     $(P Given a unary
680     overloadable operator $(I op) and its corresponding
681     class or struct member
682     function name $(I opfunc), the syntax:
683     )
684
685 ---
686 $(I op) a
687 ---
688
689     $(P where $(I a) is a class or struct object reference,
690     is interpreted as if it was written as:
691     )
692 ---
693 a.$(I opfunc)()
694 ---
695
696 <h3>Overloading ++$(I e) and --$(I e)</h3>
697
698     $(P Since ++$(I e) is defined to be semantically equivalent
699     to ($(I e) += 1), the expression ++$(I e) is rewritten
700     as ($(I e) += 1), and then checking for operator overloading
701     is done. The situation is analogous for --$(I e).
702     )
703
704 <h3>Examples</h3>
705
706     $(OL
707     $(LI
708 -------
709 class A { int $(B opNeg)(); }
710 A a;
711 -a; // equivalent to a.opNeg();
712 -------
713     )
714     $(LI
715 -------
716 class A { int $(B opNeg)(int i); }
717 A a;
718 -a; // equivalent to a.opNeg(), which is an error
719 -------
720     )
721     )
722
723 <h3>Overloading cast($(I type))$(I e)</h3>
724
725     $(P The member function $(I e).$(B opCast()) is called,
726     and the return value of $(B opCast()) is implicitly converted
727     to $(I type). Since functions cannot be overloaded based on
728     return value, there can be only one $(B opCast) per struct or
729     class.
730     Overloading the cast operator does not affect implicit casts, it
731     only applies to explicit casts.
732     )
733
734 -------
735 struct A
736 {
737     int $(B opCast)() { return 28; }
738 }
739
740 void test()
741 {
742     A a;
743
744     long i = cast(long)a;   // i is set to 28L
745     void* p = cast(void*)a; // error, cannot implicitly
746                 // convert int to void*
747     int j = a;          // error, cannot implicitly convert
748                 // A to int
749 }
750 -------
751
752 <h2><a name="Binary">Binary Operator Overloading</a></h2>
753
754
755     $(TABLE2 Overloadable Binary Operators,
756
757     $(TR $(TH $(I op))
758     $(TH commutative?)
759     $(TH $(I opfunc))
760     $(TH $(I opfunc_r))
761     )
762
763     $(TR $(TD +) $(TD yes) $(TD $(CODE opAdd)) $(TD $(CODE opAdd_r)))
764
765     $(TR $(TD -) $(TD no) $(TD $(CODE opSub)) $(TD $(CODE opSub_r)))
766
767     $(TR $(TD *) $(TD yes) $(TD $(CODE opMul)) $(TD $(CODE opMul_r)))
768
769     $(TR $(TD /) $(TD no) $(TD $(CODE opDiv)) $(TD $(CODE opDiv_r)))
770
771     $(TR $(TD %) $(TD no) $(TD $(CODE opMod)) $(TD $(CODE opMod_r)))
772
773     $(TR $(TD &) $(TD yes) $(TD $(CODE opAnd)) $(TD $(CODE opAnd_r)))
774
775     $(TR $(TD |) $(TD yes) $(TD $(CODE opOr)) $(TD $(CODE opOr_r)))
776
777     $(TR $(TD ^) $(TD yes) $(TD $(CODE opXor)) $(TD $(CODE opXor_r)))
778
779     $(TR $(TD &lt;&lt;) $(TD no) $(TD $(CODE opShl)) $(TD $(CODE opShl_r)))
780
781     $(TR $(TD &gt;&gt;) $(TD no) $(TD $(CODE opShr)) $(TD $(CODE opShr_r)))
782
783     $(TR $(TD &gt;&gt;&gt;) $(TD no) $(TD $(CODE opUShr)) $(TD $(CODE opUShr_r)))
784
785     $(TR $(TD ~) $(TD no) $(TD $(CODE opCat)) $(TD $(CODE opCat_r)))
786
787     $(TR $(TD ==) $(TD yes) $(TD $(CODE opEquals)) $(TD  -))
788
789     $(TR $(TD !=) $(TD yes) $(TD $(CODE opEquals)) $(TD  -))
790
791     $(TR $(TD &lt;) $(TD yes) $(TD $(CODE opCmp)) $(TD  -))
792
793     $(TR $(TD &lt;=) $(TD yes) $(TD $(CODE opCmp)) $(TD  -))
794
795     $(TR $(TD &gt;) $(TD yes) $(TD $(CODE opCmp)) $(TD  -))
796
797     $(TR $(TD &gt;=) $(TD yes) $(TD $(CODE opCmp)) $(TD  -))
798
799     $(TR $(TD =) $(TD no ) $(TD $(CODE opAssign)) $(TD -) )
800
801     $(TR $(TD +=) $(TD no) $(TD $(CODE opAddAssign)) $(TD  -))
802
803     $(TR $(TD -=) $(TD no) $(TD $(CODE opSubAssign)) $(TD  -))
804
805     $(TR $(TD *=) $(TD no) $(TD $(CODE opMulAssign)) $(TD  -))
806
807     $(TR $(TD /=) $(TD no) $(TD $(CODE opDivAssign)) $(TD  -))
808
809     $(TR $(TD %=) $(TD no) $(TD $(CODE opModAssign)) $(TD  -))
810
811     $(TR $(TD &=) $(TD no) $(TD $(CODE opAndAssign)) $(TD  -))
812
813     $(TR $(TD |=) $(TD no) $(TD $(CODE opOrAssign)) $(TD  -))
814
815     $(TR $(TD ^=) $(TD no) $(TD $(CODE opXorAssign)) $(TD  -))
816
817     $(TR $(TD &lt;&lt;=) $(TD no) $(TD $(CODE opShlAssign)) $(TD  -))
818
819     $(TR $(TD &gt;&gt;=) $(TD no) $(TD $(CODE opShrAssign)) $(TD  -))
820
821     $(TR $(TD &gt;&gt;&gt;=) $(TD no) $(TD $(CODE opUShrAssign)) $(TD  -))
822
823     $(TR $(TD ~=) $(TD no) $(TD $(CODE opCatAssign)) $(TD  -))
824
825     $(TR $(TD in ) $(TD no ) $(TD $(CODE opIn) ) $(TD $(CODE opIn_r) ))
826
827     )
828
829     $(P Given a binary
830     overloadable operator $(I op) and its corresponding
831     class or struct member
832     function name $(I opfunc) and $(I opfunc_r),
833     and the syntax:
834     )
835
836 ---
837 a $(I op) b
838 ---
839
840     the following sequence of rules is applied, in order, to determine
841     which form is used:
842
843     $(OL
844     $(LI The expression is rewritten as both:
845 ---
846 a.$(I opfunc)(b)
847 b.$(I opfunc_r)(a)
848 ---
849     If any $(I a.opfunc) or $(I b.opfunc_r) functions exist,
850     then overloading is applied
851     across all of them and the best match is used. If either exist,
852     and there is no argument match, then it is an error.
853     )
854
855     $(LI If the operator is commutative, then the following
856     forms are tried:
857 ---
858 a.$(I opfunc_r)(b)
859 b.$(I opfunc)(a)
860 ---
861     )
862
863     $(LI If $(I a) or $(I b) is a struct or class object reference,
864     it is an error.
865     )
866     )
867
868 <h4>Examples</h4>
869
870     $(OL
871     $(LI
872
873 -------
874 class A { int $(B opAdd)(int i); }
875 A a;
876 a + 1;  // equivalent to a.opAdd(1)
877 1 + a;  // equivalent to a.opAdd(1)
878 -------
879     )
880     $(LI
881
882 -------
883 class B { int $(B opDiv_r)(int i); }
884 B b;
885 1 / b;  // equivalent to b.opDiv_r(1)
886 -------
887     )
888     $(LI
889 -------
890 class A { int $(B opAdd)(int i); }
891 class B { int $(B opAdd_r)(A a); }
892 A a;
893 B b;
894 a + 1;  // equivalent to a.opAdd(1)
895 a + b;  // equivalent to b.opAdd_r(a)
896 b + a;  // equivalent to b.opAdd_r(a)
897 -------
898     )
899     $(LI
900 -------
901 class A { int $(B opAdd)(B b);  int $(B opAdd_r)(B b); }
902 class B { }
903 A a;
904 B b;
905 a + b;  // equivalent to a.opAdd(b)
906 b + a;  // equivalent to a.opAdd_r(b)
907 -------
908     )
909     $(LI
910 -------
911 class A { int $(B opAdd)(B b);  int $(B opAdd_r)(B b); }
912 class B { int $(B opAdd_r)(A a); }
913 A a;
914 B b;
915 a + b;  // ambiguous: a.opAdd(b) or b.opAdd_r(a)
916 b + a;  // equivalent to a.opAdd_r(b)
917 -------
918     )
919     )
920
921 <h3>Overloading == and !=</h3>
922
923     $(P Both operators use the $(CODE $(B opEquals)()) function.
924     The expression
925     $(CODE (a == b)) is rewritten as $(CODE a.$(B opEquals)(b)),
926     and $(CODE (a != b)) is rewritten as $(CODE !a.$(B opEquals)(b)).
927     )
928
929     $(P The member function $(CODE $(B opEquals)()) is defined as part of
930     Object as:
931     )
932
933 -------
934 $(V1 int)$(V2 bool) $(B opEquals)(Object o);
935 -------
936
937     $(P so that every class object has a default $(CODE $(B opEquals)()).
938     But every class definition which will be using == or != should
939     expect to need to override opEquals. The parameter to the overriding
940     function must be of type $(CODE Object), not the type for the class.
941     )
942
943     $(P Structs and unions (hereafter just called structs) can
944     provide a member function:
945     )
946
947 -------
948 $(V1 int)$(V2 bool) $(B opEquals)(S s)
949 -------
950     $(P or:)
951 -------
952 $(V1 int)$(V2 bool) $(B opEquals)(S* s)
953 -------
954
955     $(P where $(CODE S) is the struct name, to define how equality is
956     determined.)
957
958     $(P If a struct has no $(B opEquals) function declared for it,
959     a bit compare of the contents of the two structs is done to
960     determine equality or inequality.
961     )
962
963     $(P $(B Note:) Comparing a reference to a class object against $(B null)
964     should be done as:
965     )
966 -------
967 if (a is null)
968 -------
969     $(P and not as:)
970 -------
971 if (a == null)
972 -------
973     $(P The latter is converted to:)
974 -------
975 if (a.$(B opEquals)(null))
976 -------
977     $(P which will fail if $(CODE $(B opEquals)()) is a virtual function.)
978
979 <h3>Overloading &lt;, &lt;=, &gt; and &gt;=</h3>
980
981     $(P These comparison operators all use the $(CODE $(B opCmp)()) function.
982     The expression
983     $(CODE (a $(I op) b)) is rewritten as $(CODE (a.$(B opCmp)(b) $(I op) 0)).
984     The commutative operation is rewritten as $(CODE (0 $(I op) b.$(B opCmp)(a)))
985     )
986
987     $(P The member function $(CODE $(B opCmp)()) is defined as part of Object
988     as:
989     )
990
991 -------
992 int $(B opCmp)(Object o);
993 -------
994
995     $(P so that every class object has a $(CODE $(B opCmp)()).
996     )
997
998     $(P $(CODE $(B opCmp)) for structs works analogously to
999     $(CODE $(B opEquals)) for structs:
1000     )
1001 -------
1002 struct Pair
1003 {
1004     int a, b;
1005     int $(B opCmp)(Pair rhs)
1006     {
1007         if (a!=rhs.a) return a-rhs.a;
1008         return b-rhs.b;
1009     }
1010 }
1011 -------
1012
1013     $(P If a struct has no $(CODE $(B opCmp)()) function declared for it,
1014     attempting
1015     to compare two structs is an error.
1016     )
1017
1018 <h4>Rationale</h4>
1019
1020     $(P The reason for having both $(CODE $(B opEquals)) and
1021     $(CODE $(B opCmp)) is that:)
1022
1023     $(UL
1024     $(LI Testing for equality can sometimes be a much more efficient
1025     operation than testing for less or greater than.)
1026     $(LI Having an $(CODE $(B opCmp)) defined in $(CODE Object)
1027     makes it possible to
1028     make associative arrays work generically for classes.)
1029     $(LI For some objects, testing for less or greater makes no sense.
1030     This is why $(CODE Object.$(B opCmp)) throws a runtime error.
1031     $(CODE $(B opCmp)) must be overridden in each class for which comparison
1032     makes sense.)
1033     )
1034
1035     $(P The parameter to $(B opEquals) and $(B opCmp)
1036     for class definitions must
1037     be of type $(CODE Object), rather than the type of the particular class,
1038     in order to override the $(CODE Object.$(B opEquals)) and
1039     $(CODE Object.$(B opCmp))
1040     functions properly.
1041     )
1042
1043 <h2><a name="FunctionCall">Function Call Operator Overloading $(I f)()</a></h2>
1044
1045     $(P The function call operator, (), can be overloaded by
1046     declaring a function named $(B opCall):
1047     )
1048
1049 -------
1050 struct F
1051 {
1052     int $(B opCall)();
1053     int $(B opCall)(int x, int y, int z);
1054 }
1055
1056 void test()
1057 {   F f;
1058     int i;
1059
1060     i = f$(B ());       // same as i = f.opCall();
1061     i = f$(B (3,4,5));  // same as i = f.opCall(3,4,5);
1062 }
1063 -------
1064
1065     $(P In this way a struct or class object can behave as if it
1066     were a function.
1067     )
1068
1069 <h2><a name="Array">Array Operator Overloading</a></h2>
1070
1071 <h3>Overloading Indexing $(I a)[$(I i)]</h3>
1072
1073     $(P The array index operator, [], can be overloaded by
1074     declaring a function named $(B opIndex) with one
1075     or more parameters.
1076     Assignment to an array can be overloaded with a function
1077     named $(B opIndexAssign) with two or more parameters.
1078     The first parameter is the rvalue of the assignment expression.
1079     )
1080
1081 -------
1082 struct A
1083 {
1084     int $(B opIndex)(size_t i1, size_t i2, size_t i3);
1085     int $(B opIndexAssign)(int value, size_t i1, size_t i2);
1086 }
1087
1088 void test()
1089 {   A a;
1090     int i;
1091
1092     i = a$(B [)5,6,7$(B ]); // same as i = a.opIndex(5,6,7);
1093     a$(B [)i,3$(B ]) = 7;       // same as a.opIndexAssign(7,i,3);
1094 }
1095 -------
1096
1097     $(P In this way a struct or class object can behave as if it
1098     were an array.
1099     )
1100
1101 $(V1
1102     $(P $(B Note:) Array index overloading currently does not
1103     work for the lvalue of an $(I op)=, ++, or -- operator.
1104     )
1105 )
1106 $(V2
1107     $(P $(B Note:) To use array index overloading
1108     with the $(I op)=, ++, or -- operators,
1109     have the opIndex function return a reference type.
1110     This reference is then used as the lvalue for those operators.
1111     )
1112 )
1113
1114 <h3>Overloading Slicing $(I a)[] and $(I a)[$(I i) .. $(I j)]</h3>
1115
1116     $(P Overloading the slicing operator means overloading expressions
1117     like $(CODE a[]) and $(CODE a[i .. j]).
1118     This can be done by declaring a function named $(B opSlice).
1119     Assignment to a slice can be done by declaring $(B opSliceAssign).
1120     )
1121
1122 -------
1123 class A
1124 {
1125     int $(B opSlice)();               // overloads a[]
1126     int $(B opSlice)(size_t x, size_t y);         // overloads a[i .. j]
1127
1128     int $(B opSliceAssign)(int v);            // overloads a[] = v
1129     int $(B opSliceAssign)(int v, size_t x, size_t y); // overloads a[i .. j] = v
1130 }
1131
1132 void test()
1133 {   A a = new A();
1134     int i;
1135     int v;
1136
1137     i = a$(B []);       // same as i = a.opSlice();
1138     i = a$(B [)3..4$(B ]);  // same as i = a.opSlice(3,4);
1139
1140     a$(B []) = v;       // same as a.opSliceAssign(v);
1141     a$(B [)3..4$(B ]) = v;  // same as a.opSliceAssign(v,3,4);
1142 }
1143 -------
1144
1145 <h2><a name="Assignment">Assignment Operator Overloading</a></h2>
1146
1147     $(P The assignment operator $(CODE =) can be overloaded if the
1148     lvalue is a struct $(V1 or class) aggregate, and $(CODE opAssign)
1149     is a member function of that aggregate.)
1150
1151     $(P The assignment operator cannot be overloaded for rvalues
1152     that can be implicitly cast to the lvalue type.
1153     Furthermore, the following parameter signatures for $(CODE opAssign)
1154     are not allowed:)
1155
1156 ---
1157 opAssign(...)
1158 opAssign(T)
1159 opAssign(T, ...)
1160 opAssign(T ...)
1161 opAssign(T, U = defaultValue, etc.)
1162 ---
1163
1164     $(P where $(I T) is the same type as the aggregate type $(I A),
1165     is implicitly
1166     convertible to $(I A), or if $(I A) is a struct and $(I T)
1167     is a pointer to a type that is
1168     implicitly convertible to $(I A).
1169     )
1170
1171 $(V2
1172 $(DOT
1173 <h2><a name="Dot">Forwarding</a></h2>
1174
1175     $(P Providing a struct or class member function $(CODE opDot) enables
1176     the forwarding
1177     of any names not found in the struct's scope to be forwarded
1178     to the return type of the $(CODE opDot) function. In other words:
1179     )
1180
1181 ---
1182 struct T {
1183   ...
1184   S opDot() { ... }
1185 }
1186 T t;
1187 ...
1188 t.m
1189 ---
1190
1191     $(P is rewritten as:)
1192
1193 ---
1194 t.opDot().m
1195 ---
1196
1197     $(P if m does not exist as a member of the struct T.)
1198
1199     $(P The members .sizeof, .init, .offsetof, .alignof, .mangleof
1200     and .stringof are not forwarded to $(CODE opDot).)
1201
1202 ---
1203 struct S {
1204     int a, b, c;
1205 }
1206
1207 struct T {
1208     S s;
1209     int b = 7;
1210
1211     S* opDot() {
1212         return &s;    // forwards to member s
1213     }
1214 }
1215
1216 void main() {
1217     T t;
1218     t.a = 4;
1219     t.b = 5;
1220     t.c = 6;
1221     assert(t.a == 4);
1222     assert(t.b == 5);    // T.b overrides S.b
1223     assert(t.c == 6);
1224     assert(t.s.b == 0);
1225     assert(t.sizeof == 4*4); // sizeof T, not sizeof S
1226 }
1227 ---
1228 )
1229 )
1230
1231 <h2><a name="Future">Future Directions</a></h2>
1232
1233     $(P The operators $(CODE ! && || ?:) and a few others will
1234     likely never be overloadable.
1235     )
1236 )
1237 )
1238
1239 Macros:
1240     TITLE=Operator Overloading
1241     WIKI=OperatorOverloading
1242     SUB=<sub>$0</sub>
1243     ARGUMENTS=$(I b)$(SUB 1), $(I b)$(SUB 2), ... $(I b)$(SUB n)
1244     SLICE=$(I i)..$(I j)
1245     SLICE2=$(I i), $(I j)
1246     FOO=
Note: See TracBrowser for help on using the browser.