forked from PhilippeSigaud/D-templates-tutorial
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathD-templates-tutorial.html
7381 lines (6660 loc) · 555 KB
/
D-templates-tutorial.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<meta name="author" content="Philippe Sigaud" />
<title>D Templates: A Tutorial</title>
<style type="text/css">
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; }
code > span.dt { color: #902000; }
code > span.dv { color: #40a070; }
code > span.bn { color: #40a070; }
code > span.fl { color: #40a070; }
code > span.ch { color: #4070a0; }
code > span.st { color: #4070a0; }
code > span.co { color: #60a0b0; font-style: italic; }
code > span.ot { color: #007020; }
code > span.al { color: #ff0000; font-weight: bold; }
code > span.fu { color: #06287e; }
code > span.er { color: #ff0000; font-weight: bold; }
</style>
</head>
<body>
<div id="header">
<h1 class="title">D Templates: A Tutorial</h1>
<h2 class="author">Philippe Sigaud</h2>
<h3 class="date">2012, January 3rd</h3>
</div>
<div id="TOC">
<ul>
<li><a href="#introduction"><span class="toc-section-number">1</span> Introduction</a><ul>
<li><a href="#whats-in-this-document"><span class="toc-section-number">1.1</span> What's in This Document</a></li>
<li><a href="#conventions"><span class="toc-section-number">1.2</span> Conventions</a></li>
<li><a href="#how-to-get-this-document"><span class="toc-section-number">1.3</span> How to Get This Document</a></li>
<li><a href="#thanks"><span class="toc-section-number">1.4</span> Thanks</a></li>
</ul></li>
<li><a href="#basics"><span class="toc-section-number">2</span> Basics</a><ul>
<li><a href="#template-declarations"><span class="toc-section-number">2.1</span> Template Declarations</a></li>
<li><a href="#instantiating-a-template"><span class="toc-section-number">2.2</span> Instantiating a Template</a></li>
<li><a href="#template-building-blocks"><span class="toc-section-number">2.3</span> Template Building Blocks</a><ul>
<li><a href="#the-eponymous-trick"><span class="toc-section-number">2.3.1</span> The Eponymous Trick</a></li>
<li><a href="#inner-alias"><span class="toc-section-number">2.3.2</span> Inner alias</a></li>
<li><a href="#static-if"><span class="toc-section-number">2.3.3</span> <code>static if</code></a><ul>
<li><a href="#syntax"><span class="toc-section-number">2.3.3.1</span> Syntax</a></li>
<li><a href="#optional-code"><span class="toc-section-number">2.3.3.2</span> Optional Code</a></li>
<li><a href="#nested-static-ifs"><span class="toc-section-number">2.3.3.3</span> Nested <code>static if</code>s</a></li>
<li><a href="#recursion-with-static-if"><span class="toc-section-number">2.3.3.4</span> Recursion with <code>static if</code></a><ul>
<li><a href="#rank"><span class="toc-section-number">2.3.3.4.1</span> Rank:</a></li>
<li><a href="#rank-for-ranges"><span class="toc-section-number">2.3.3.4.2</span> Rank for Ranges:</a></li>
<li><a href="#base-element-type"><span class="toc-section-number">2.3.3.4.3</span> Base Element Type:</a></li>
<li><a href="#generating-arrays"><span class="toc-section-number">2.3.3.4.4</span> Generating Arrays:</a></li>
<li><a href="#repeated-composition"><span class="toc-section-number">2.3.3.4.5</span> Repeated composition:</a></li>
</ul></li>
<li><a href="#templates-specializations"><span class="toc-section-number">2.3.3.5</span> Templates Specializations</a></li>
</ul></li>
<li><a href="#default-values"><span class="toc-section-number">2.3.4</span> Default Values</a></li>
</ul></li>
<li><a href="#function-templates"><span class="toc-section-number">2.4</span> Function Templates</a><ul>
<li><a href="#syntax-1"><span class="toc-section-number">2.4.1</span> Syntax</a></li>
<li><a href="#auto-return"><span class="toc-section-number">2.4.2</span> auto return</a></li>
<li><a href="#ifti"><span class="toc-section-number">2.4.3</span> IFTI</a></li>
<li><a href="#example-flattening-arrays-and-ranges"><span class="toc-section-number">2.4.4</span> Example: Flattening Arrays and Ranges</a></li>
<li><a href="#anonymous-function-templates"><span class="toc-section-number">2.4.5</span> Anonymous Function Templates</a></li>
<li><a href="#closures-are-a-poor-mans-objects"><span class="toc-section-number">2.4.6</span> Closures are a Poor Man's Objects</a></li>
<li><a href="#function-overloading"><span class="toc-section-number">2.4.7</span> Function Overloading</a></li>
<li><a href="#storage-classes"><span class="toc-section-number">2.4.8</span> Storage Classes</a></li>
<li><a href="#properties-are-automatically-deduced"><span class="toc-section-number">2.4.9</span> Properties are Automatically Deduced</a></li>
<li><a href="#in-and-out-clauses"><span class="toc-section-number">2.4.10</span> in and out Clauses</a></li>
<li><a href="#modifying-functions"><span class="toc-section-number">2.4.11</span> Modifying Functions</a><ul>
<li><a href="#accepting-a-tuple"><span class="toc-section-number">2.4.11.1</span> Accepting a Tuple</a></li>
<li><a href="#mapping-n-ranges-in-parallel"><span class="toc-section-number">2.4.11.2</span> Mapping n ranges in parallel</a></li>
</ul></li>
</ul></li>
<li><a href="#struct-templates"><span class="toc-section-number">2.5</span> Struct Templates</a><ul>
<li><a href="#syntax-2"><span class="toc-section-number">2.5.1</span> Syntax</a></li>
<li><a href="#factory-functions"><span class="toc-section-number">2.5.2</span> Factory Functions</a></li>
<li><a href="#giving-access-to-inner-parameters"><span class="toc-section-number">2.5.3</span> Giving Access to Inner Parameters</a></li>
<li><a href="#templated-member-functions"><span class="toc-section-number">2.5.4</span> Templated Member Functions</a><ul>
<li><a href="#mapping-on-a-tree"><span class="toc-section-number">2.5.4.0.1</span> Mapping on a Tree</a></li>
<li><a href="#folding-a-tree"><span class="toc-section-number">2.5.4.0.2</span> Folding a Tree</a></li>
</ul></li>
<li><a href="#templated-constructors"><span class="toc-section-number">2.5.5</span> Templated Constructors</a></li>
<li><a href="#inner-structs"><span class="toc-section-number">2.5.6</span> Inner Structs</a></li>
<li><a href="#template-this-parameters"><span class="toc-section-number">2.5.7</span> Template This Parameters</a></li>
<li><a href="#example-a-concat-flatten-range"><span class="toc-section-number">2.5.8</span> Example: a Concat / Flatten Range</a></li>
</ul></li>
<li><a href="#class-templates"><span class="toc-section-number">2.6</span> Class Templates</a><ul>
<li><a href="#syntax-3"><span class="toc-section-number">2.6.1</span> Syntax</a></li>
<li><a href="#methods-templates"><span class="toc-section-number">2.6.2</span> Methods Templates</a></li>
<li><a href="#invariant-clauses"><span class="toc-section-number">2.6.3</span> <code>invariant</code> clauses</a></li>
<li><a href="#inner-classes"><span class="toc-section-number">2.6.4</span> Inner Classes</a></li>
<li><a href="#anonymous-classes"><span class="toc-section-number">2.6.5</span> Anonymous Classes</a></li>
<li><a href="#parametrized-base-class"><span class="toc-section-number">2.6.6</span> Parametrized Base Class</a></li>
<li><a href="#adding-functionalities-through-inheritance"><span class="toc-section-number">2.6.7</span> Adding Functionalities Through Inheritance</a></li>
<li><a href="#the-curiously-recurring-template-pattern"><span class="toc-section-number">2.6.8</span> The Curiously Recurring Template Pattern</a></li>
<li><a href="#example-automatic-dynamic-dispatch"><span class="toc-section-number">2.6.9</span> Example: Automatic Dynamic Dispatch</a></li>
</ul></li>
<li><a href="#other-templates"><span class="toc-section-number">2.7</span> Other Templates?</a><ul>
<li><a href="#interface-templates"><span class="toc-section-number">2.7.1</span> Interface Templates</a></li>
<li><a href="#union-templates"><span class="toc-section-number">2.7.2</span> Union Templates</a></li>
<li><a href="#enumeration-templates"><span class="toc-section-number">2.7.3</span> Enumeration Templates?</a></li>
</ul></li>
</ul></li>
<li><a href="#some-more-advanced-considerations"><span class="toc-section-number">3</span> Some More Advanced Considerations</a><ul>
<li><a href="#constraints"><span class="toc-section-number">3.1</span> Constraints</a><ul>
<li><a href="#syntax-4"><span class="toc-section-number">3.1.1</span> Syntax</a></li>
<li><a href="#constraints-usage"><span class="toc-section-number">3.1.2</span> Constraints Usage</a></li>
<li><a href="#constraints-limits"><span class="toc-section-number">3.1.3</span> Constraints Limits</a></li>
<li><a href="#constraints-specializations-and-static-if"><span class="toc-section-number">3.1.4</span> Constraints, Specializations and <code>static if</code></a></li>
</ul></li>
<li><a href="#predicate-templates"><span class="toc-section-number">3.2</span> Predicate Templates</a><ul>
<li><a href="#testing-for-a-member"><span class="toc-section-number">3.2.1</span> Testing for a member</a></li>
<li><a href="#testing-for-operations"><span class="toc-section-number">3.2.2</span> Testing for Operations</a></li>
<li><a href="#completing-the-flatten-range"><span class="toc-section-number">3.2.3</span> Completing the Flatten range</a></li>
</ul></li>
<li><a href="#template-tuple-parameters"><span class="toc-section-number">3.3</span> Template Tuple Parameters</a><ul>
<li><a href="#definition-and-basic-properties"><span class="toc-section-number">3.3.1</span> Definition and Basic Properties</a></li>
<li><a href="#tuple-tuple-t...-and-.tupleof"><span class="toc-section-number">3.3.2</span> <code>Tuple</code>, <code>tuple</code>, <code>T...</code> and <code>.tupleof</code></a></li>
<li><a href="#the-type-of-tuples"><span class="toc-section-number">3.3.3</span> The Type of Tuples</a><ul>
<li><a href="#void-containing-tuples-and-empty-tuples"><span class="toc-section-number">3.3.3.0.1</span> void-containing tuples and empty tuples:</a></li>
<li><a href="#example-variadic-functions"><span class="toc-section-number">3.3.3.1</span> Example: Variadic Functions</a></li>
<li><a href="#one-element-tuples-accepting-types-and-alias"><span class="toc-section-number">3.3.3.2</span> One-Element Tuples: Accepting Types and Alias</a></li>
<li><a href="#example-inheritance-lists"><span class="toc-section-number">3.3.3.3</span> Example: Inheritance Lists</a></li>
</ul></li>
</ul></li>
<li><a href="#operator-overloading"><span class="toc-section-number">3.4</span> Operator Overloading</a><ul>
<li><a href="#syntax-5"><span class="toc-section-number">3.4.1</span> Syntax</a><ul>
<li><a href="#unary-operations"><span class="toc-section-number">3.4.1.1</span> Unary Operations</a></li>
<li><a href="#binary-operations"><span class="toc-section-number">3.4.1.2</span> Binary Operations</a></li>
<li><a href="#assignement"><span class="toc-section-number">3.4.1.3</span> Assignement</a></li>
<li><a href="#index-assignement"><span class="toc-section-number">3.4.1.4</span> Index Assignement</a></li>
<li><a href="#slice-assignement"><span class="toc-section-number">3.4.1.5</span> Slice Assignement</a></li>
<li><a href="#cast-operations"><span class="toc-section-number">3.4.1.6</span> Cast Operations</a></li>
<li><a href="#example-arithmetic-operators"><span class="toc-section-number">3.4.1.7</span> Example: Arithmetic Operators</a></li>
<li><a href="#special-case-in"><span class="toc-section-number">3.4.1.8</span> Special Case: in</a></li>
<li><a href="#special-case-cast"><span class="toc-section-number">3.4.1.9</span> Special Case: cast</a></li>
</ul></li>
</ul></li>
<li><a href="#mixin-templates"><span class="toc-section-number">3.5</span> Mixin Templates</a><ul>
<li><a href="#syntax-6"><span class="toc-section-number">3.5.1</span> Syntax</a></li>
<li><a href="#mixing-code-in"><span class="toc-section-number">3.5.2</span> Mixing Code In</a></li>
<li><a href="#mixin-example-subscriber-and-stack"><span class="toc-section-number">3.5.3</span> Mixin Example: Subscriber and Stack</a></li>
</ul></li>
<li><a href="#opdispatch"><span class="toc-section-number">3.6</span> opDispatch</a><ul>
<li><a href="#syntax-7"><span class="toc-section-number">3.6.1</span> Syntax</a></li>
<li><a href="#getters-and-setters"><span class="toc-section-number">3.6.2</span> Getters and Setters</a></li>
</ul></li>
<li><a href="#wrapping-and-subtyping-expanding-types"><span class="toc-section-number">3.7</span> Wrapping and Subtyping: Expanding Types</a><ul>
<li><a href="#wrapper-templates"><span class="toc-section-number">3.7.1</span> Wrapper Templates</a></li>
<li><a href="#alias-this-transparent-types"><span class="toc-section-number">3.7.2</span> alias this: Transparent Types</a></li>
<li><a href="#library-typedef"><span class="toc-section-number">3.7.3</span> Library Typedef</a></li>
</ul></li>
<li><a href="#types-as-information"><span class="toc-section-number">3.8</span> Types as Information</a><ul>
<li><a href="#user-defined-literals"><span class="toc-section-number">3.8.1</span> User-Defined Literals</a></li>
<li><a href="#encoding-information-with-types"><span class="toc-section-number">3.8.2</span> Encoding Information With Types</a></li>
</ul></li>
<li><a href="#templates-in-templates"><span class="toc-section-number">3.9</span> Templates in Templates</a><ul>
<li><a href="#templates-all-the-way-down"><span class="toc-section-number">3.9.1</span> Templates All the Way Down</a></li>
<li><a href="#double-stage-function-templates"><span class="toc-section-number">3.9.2</span> Double-Stage Function Templates</a></li>
<li><a href="#named-fields-tuples"><span class="toc-section-number">3.9.3</span> Named-Fields Tuples</a></li>
</ul></li>
<li><a href="#file__-and-__line__"><span class="toc-section-number">3.10</span> <code>__FILE__</code> and <code>__LINE__</code></a></li>
</ul></li>
<li><a href="#around-templates-other-compile-time-tools"><span class="toc-section-number">4</span> Around Templates: Other Compile-Time Tools</a><ul>
<li><a href="#string-mixins"><span class="toc-section-number">4.1</span> String Mixins</a><ul>
<li><a href="#syntax-8"><span class="toc-section-number">4.1.1</span> Syntax</a></li>
<li><a href="#mixing-code-in-with-templates"><span class="toc-section-number">4.1.2</span> Mixing Code In, With Templates</a></li>
<li><a href="#limitations"><span class="toc-section-number">4.1.3</span> Limitations</a></li>
</ul></li>
<li><a href="#compile-time-function-evaluation"><span class="toc-section-number">4.2</span> Compile-Time Function Evaluation</a><ul>
<li><a href="#evaluation-at-compile-time"><span class="toc-section-number">4.2.1</span> Evaluation at Compile-Time</a></li>
<li><a href="#ctfe"><span class="toc-section-number">4.2.2</span> <code>__ctfe</code></a></li>
<li><a href="#templates-and-ctfe"><span class="toc-section-number">4.2.3</span> Templates and CTFE</a></li>
<li><a href="#templates-and-ctfe-and-string-mixins-oh-my"><span class="toc-section-number">4.2.4</span> Templates and CTFE and String Mixins, oh my!</a></li>
<li><a href="#simple-string-interpolation"><span class="toc-section-number">4.2.5</span> Simple String Interpolation</a></li>
<li><a href="#example-extending-std.functional.binaryfun"><span class="toc-section-number">4.2.6</span> Example: extending std.functional.binaryFun</a></li>
<li><a href="#sorting-networks"><span class="toc-section-number">4.2.7</span> Sorting Networks</a></li>
</ul></li>
<li><a href="#traits"><span class="toc-section-number">4.3</span> <code>__traits</code></a><ul>
<li><a href="#yesno-questions-with-__traits"><span class="toc-section-number">4.3.1</span> Yes/No Questions with <code>__traits</code></a></li>
<li><a href="#identifier"><span class="toc-section-number">4.3.2</span> <code>identifier</code></a></li>
<li><a href="#getmember"><span class="toc-section-number">4.3.3</span> <code>getMember</code></a></li>
<li><a href="#allmembers"><span class="toc-section-number">4.3.4</span> <code>allMembers</code></a></li>
<li><a href="#derivedmembers"><span class="toc-section-number">4.3.5</span> <code>derivedMembers</code></a></li>
<li><a href="#getoverloads"><span class="toc-section-number">4.3.6</span> <code>getOverloads</code></a></li>
<li><a href="#getting-all-members-even-overloaded-ones"><span class="toc-section-number">4.3.7</span> Getting All Members, Even Overloaded Ones</a></li>
<li><a href="#testing-for-interface-implementation"><span class="toc-section-number">4.3.8</span> Testing for Interface Implementation</a></li>
<li><a href="#getvirtualfunctions"><span class="toc-section-number">4.3.9</span> <code>getVirtualFunctions</code></a></li>
<li><a href="#parent"><span class="toc-section-number">4.3.10</span> <code>parent</code></a></li>
<li><a href="#local-scope-name"><span class="toc-section-number">4.3.11</span> Local Scope Name</a></li>
</ul></li>
<li><a href="#wrapping-it-all-together"><span class="toc-section-number">4.4</span> Wrapping it all Together</a></li>
</ul></li>
<li><a href="#examples"><span class="toc-section-number">5</span> Examples</a><ul>
<li><a href="#type-sorcery"><span class="toc-section-number">5.1</span> Type Sorcery</a><ul>
<li><a href="#mapping-filtering-and-folding-types"><span class="toc-section-number">5.1.1</span> Mapping, Filtering and Folding Types</a><ul>
<li><a href="#mapping-on-type-tuples"><span class="toc-section-number">5.1.1.1</span> Mapping on Type Tuples</a></li>
<li><a href="#example-testing-a-function"><span class="toc-section-number">5.1.1.2</span> Example: Testing a Function</a></li>
<li><a href="#filtering-type-tuples"><span class="toc-section-number">5.1.1.3</span> Filtering Type Tuples</a></li>
</ul></li>
<li><a href="#example-building-a-graph"><span class="toc-section-number">5.1.2</span> Example: building a <code>Graph</code></a><ul>
<li><a href="#folding-type-tuples"><span class="toc-section-number">5.1.2.1</span> Folding Type Tuples</a></li>
<li><a href="#sorting-types"><span class="toc-section-number">5.1.2.2</span> Sorting Types</a></li>
</ul></li>
<li><a href="#scanning-types-interleaving-types-crossing-types"><span class="toc-section-number">5.1.3</span> Scanning Types, Interleaving Types, Crossing Types</a><ul>
<li><a href="#static-scan"><span class="toc-section-number">5.1.3.1</span> Static Scan</a></li>
<li><a href="#interleaving-types"><span class="toc-section-number">5.1.3.2</span> Interleaving Types</a></li>
</ul></li>
<li><a href="#annotating-types"><span class="toc-section-number">5.1.4</span> Annotating Types</a></li>
</ul></li>
<li><a href="#tuples-as-sequences"><span class="toc-section-number">5.2</span> Tuples as Sequences</a><ul>
<li><a href="#mapping-on-tuples"><span class="toc-section-number">5.2.1</span> Mapping on Tuples</a></li>
<li><a href="#filtering-tuples"><span class="toc-section-number">5.2.2</span> Filtering Tuples</a></li>
</ul></li>
<li><a href="#fun-with-functions"><span class="toc-section-number">5.3</span> Fun With Functions</a><ul>
<li><a href="#determining-a-functions-number-of-arguments"><span class="toc-section-number">5.3.1</span> Determining a Function's Number of Arguments</a></li>
<li><a href="#memoizing-a-function"><span class="toc-section-number">5.3.2</span> Memoizing a Function</a></li>
<li><a href="#currying-a-function"><span class="toc-section-number">5.3.3</span> Currying a Function</a></li>
<li><a href="#juxtaposing-functions"><span class="toc-section-number">5.3.4</span> Juxtaposing Functions</a></li>
</ul></li>
<li><a href="#relational-algebra"><span class="toc-section-number">5.4</span> Relational Algebra</a></li>
<li><a href="#fun-with-classes-and-structs"><span class="toc-section-number">5.5</span> Fun With Classes and Structs</a><ul>
<li><a href="#class-hierarchy"><span class="toc-section-number">5.5.1</span> Class Hierarchy</a></li>
<li><a href="#generic-maker-function"><span class="toc-section-number">5.5.2</span> Generic Maker Function</a></li>
</ul></li>
<li><a href="#emitting-events"><span class="toc-section-number">5.6</span> Emitting Events</a></li>
<li><a href="#fields"><span class="toc-section-number">5.7</span> Fields</a></li>
<li><a href="#extending-an-enum"><span class="toc-section-number">5.8</span> Extending an enum</a></li>
<li><a href="#static-switching"><span class="toc-section-number">5.9</span> Static Switching </a></li>
<li><a href="#generic-structures"><span class="toc-section-number">5.10</span> Generic Structures</a><ul>
<li><a href="#gobble"><span class="toc-section-number">5.10.1</span> Gobble</a></li>
<li><a href="#polymorphic-association-lists"><span class="toc-section-number">5.10.2</span> Polymorphic Association Lists</a></li>
<li><a href="#a-polymorphic-tree"><span class="toc-section-number">5.10.3</span> A Polymorphic Tree</a></li>
<li><a href="#expression-templates"><span class="toc-section-number">5.10.4</span> Expression Templates</a></li>
</ul></li>
<li><a href="#statically-checked-writeln"><span class="toc-section-number">5.11</span> Statically-Checked Writeln</a></li>
<li><a href="#extending-a-class"><span class="toc-section-number">5.12</span> Extending a Class</a></li>
<li><a href="#pattern-matching-with-functions"><span class="toc-section-number">5.13</span> Pattern Matching With Functions</a></li>
<li><a href="#generating-a-switch-for-tuples"><span class="toc-section-number">5.14</span> Generating a Switch for Tuples</a></li>
</ul></li>
<li><a href="#appendices"><span class="toc-section-number">6</span> Appendices</a><ul>
<li><a href="#the-is-expression"><span class="toc-section-number">6.1</span> The <code>is</code> expression</a><ul>
<li><a href="#general-syntax"><span class="toc-section-number">6.1.1</span> General Syntax</a></li>
<li><a href="#istype"><span class="toc-section-number">6.1.2</span> <code>is(Type)</code></a></li>
<li><a href="#istype-anothertype-and-istype-anothertype"><span class="toc-section-number">6.1.3</span> <code>is(Type : AnotherType)</code> and <code>is(Type == AnotherType)</code></a></li>
<li><a href="#type-specializations"><span class="toc-section-number">6.1.4</span> Type Specializations</a></li>
</ul></li>
<li><a href="#resources-and-further-reading"><span class="toc-section-number">6.2</span> Resources and Further Reading</a><ul>
<li><a href="#d-templates"><span class="toc-section-number">6.2.1</span> D Templates</a><ul>
<li><a href="#d-reference"><span class="toc-section-number">6.2.1.1</span> D Reference</a></li>
<li><a href="#the-d-programming-language"><span class="toc-section-number">6.2.1.2</span> The D Programming Language</a></li>
</ul></li>
<li><a href="#programming-in-d"><span class="toc-section-number">6.2.2</span> Programming in D</a></li>
<li><a href="#the-d-wiki"><span class="toc-section-number">6.2.3</span> The D Wiki</a></li>
<li><a href="#d-metaprogramming"><span class="toc-section-number">6.2.4</span> D Metaprogramming</a></li>
<li><a href="#templates-in-other-languages"><span class="toc-section-number">6.2.5</span> Templates in Other Languages</a></li>
</ul></li>
</ul></li>
</ul>
</div>
<h1 id="introduction"><a href="#TOC"><span class="header-section-number">1</span> Introduction</a></h1>
<p>Templates are a central feature of D, giving you powerful compile-time code generation abilities that'll make your code cleaner, more flexible and even more efficient. They are used everywhere in <a href="http://www.dlang.org/phobos/">Phobos</a> --- D standard library --- and therefore any D user should know about them. But, based on C++ templates as they are, D templates can be a bit daunting at first. The <a href="http://www.dlang.org">D Programming Language</a> website's <a href="http://www.dlang.org/template.html">documentation</a> is a good start, though its description of templates is spread among many different files and (as it's a language reference) its material doesn't so much <em>teach</em> you how to use templates as <em>show</em> you their syntax and semantics.</p>
<p>This document aims to be a kind of tutorial on D templates, to show the beginning D coder what can be achieved with them. When I was using C++, I remember <em>never</em> using templates for more than <em>containers-of-T</em> stuff, and considered Boost-level<sup><a href="#fn1" class="footnoteRef" id="fnref1">1</a></sup> metaprogramming the kind of code I could never understand, never mind produce. Well, D's sane syntax for templates and nifty features such as <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code>, <code class="sourceCode d"><span class="kw">alias</span></code> or tuples cured me of that impression. I hope this document will help you, too.</p>
<h2 id="whats-in-this-document"><a href="#TOC"><span class="header-section-number">1.1</span> What's in This Document</a></h2>
<p><a href="#basics">The first part</a> deals with the very basics: how to declare and instantiate a template, the standard `building blocks' you'll use in almost all your templates, along with <a href="#function-templates">function</a>, <a href="#struct-templates">struct</a> and <a href="#class-templates">class</a> templates. Throughout the text, examples will present applications of these concepts.</p>
<p><a href="#some-more-advanced-considerations">The second part</a> is about more advanced topics a D template user will probably use, but not on a daily basis, like <a href="#constraints">template constraints</a>, <a href="#mixin-templates">mixin templates</a> or <a href="#operator-overloading">operator overloading</a>.</p>
<p><a href="#around-templates">The third part</a> presents other metaprogramming tools: <a href="#string-mixins">string mixins</a>, <a href="#compile-time-function-evaluation">compile-time function evaluation</a>, and <a href="#traits">__traits</a>. These are seen from a template-y point of view: how they can interact with templates and what you can build with them in conjunction with templates.</p>
<p><a href="#examples">The fourth part</a> presents more developed examples of what can be done with templates, based on real needs I had at some time and that could be fulfilled with templates.</p>
<p>Finally, an appendix on the <a href="#the-is-expression">ubiquitous is expression</a> and another giving <a href="#resources-and-further-reading">resources</a> and further reading advice complete this document.</p>
<h2 id="conventions"><a href="#TOC"><span class="header-section-number">1.2</span> Conventions</a></h2>
<p>To make this document more easily readable, I'll use standard coding books conventions, by highlighting parts of the text. Mainly, in this doc:</p>
<ul>
<li>D keywords will be marked like this: <code class="sourceCode d"><span class="dt">int</span></code>, <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code>, <code class="sourceCode d">__traits</code> (these will be colored or not, depending on what was used to generate the document).</li>
<li>Symbols and names used in code samples and cited in the text will be written like this: <code>myFunc</code>, <code>flatten</code>.</li>
<li>internal links will be like <a href="#introduction">this</a>.</li>
<li>external links will be like <a href="http://www.dlang.org">this</a>.</li>
<li>Syntax-highlighted code samples are shown like this:</li>
</ul>
<table class="sourceCode d numberLines"><tr class="sourceCode"><td class="lineNumbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td><td class="sourceCode"><pre><code class="sourceCode d"><span class="co">/**</span>
<span class="co"> * This is a doc comment.</span>
<span class="co"> */</span>
<span class="kw">module</span> intro;
<span class="kw">import</span> std.stdio;
<span class="dt">void</span> main()
{
<span class="dt">int</span> times = <span class="dv">10</span>;
<span class="co">// This is a comment</span>
<span class="kw">foreach</span>(i; <span class="dv">0</span>..times)
writeln(<span class="st">"Hello, Word!"</span>);
}</code></pre></td></tr></table>
<p>Numbered lines will be used only when necessary.</p>
<p>I will sometimes make a little explanatory detour, discussing a small piece of info too small to be in its own section but of interest to the reader nonetheless. These will be marked so:</p>
<blockquote>
<p><strong>Semi-Literate Programming.</strong> Most code samples presented in this document will compile with a reasonably recent D compiler. In the <code>utils</code> directory, there is a small D script called <code>codesamples.d</code> that extracts code samples from the mardkdown files.</p>
</blockquote>
<blockquote>
<p>Samples with a <code class="sourceCode d"><span class="kw">module</span> name;</code> declaration will be extracted, a file called <code>name.d</code> will be created and compiled (possibly with a stub <code class="sourceCode d">main()</code> if none exists). The previous code sample creates a file called <code>intro.d</code> and so on. The compilation results are put in a file called <code>result.txt</code>. Samples that depend on other samples just import them (yeah for D modularity, no need for specific mark-up to weave code together). Samples with a name ending in <code>_error</code> will <em>not</em> compile, as expected: they are there to show errors, mistakes and gotchas. Anonymous samples are not extracted: I use them to show small snippets not intended to stand by themselves, or just to show D-ish pseudocode.</p>
</blockquote>
<blockquote>
<p>All in all, you can see this entire document as a gigantic D package, describing hundreds of small modules.</p>
</blockquote>
<p>Finally, some sections in this doc are not finished yet. The sections I consider unfinished will contain this:</p>
<blockquote>
<p><strong>Unfinished.</strong> Hey, now I've added a Thanks section. But as long as I'm adding new parts in the document, new appendices, and new section, this intro will not be finished.</p>
</blockquote>
<p>I probably forgot some 'unfinished' tags, do not hesitate to tell me so.</p>
<h2 id="how-to-get-this-document"><a href="#TOC"><span class="header-section-number">1.3</span> How to Get This Document</a></h2>
<p>This document is just a markdown file <a href="http://github.com/PhilippeSigaud/D-templates-tutorial">hosted on Github</a>. Don't hesitate to fork it or (even better for me) to make pull requests! For those of you reading this on paper, the address is:</p>
<p><a href="https://github.com/PhilippeSigaud/D-templates-tutorial"><code class="url">https://github.com/PhilippeSigaud/D-templates-tutorial</code></a></p>
<h2 id="thanks"><a href="#TOC"><span class="header-section-number">1.4</span> Thanks</a></h2>
<p>As soon as I publicly released this document, D community members gave me help, suggestions, corrections, and code samples. This is cool to see a D network emerge and people participating in common projects. The following people helped me:</p>
<p>Andrej Mitrovic, Justin Whear, Zachary Lund, Jacob Carlborg, Timon Gehr, Simen Kjaeras, Andrei Alexandrescu, Bjorn Lietz-Spendig.</p>
<p>Thanks guys!</p>
<h1 id="basics"><a href="#TOC"><span class="header-section-number">2</span> Basics</a></h1>
<p>A template is a recipe, a blueprint that will generate code at your command and according to compile-time parameters you'll give. Templates are <em>parameterized</em> code. Each template definition is written once in a module and can then be instantiated many times with different parameters, possibly resulting in quite different code, depending on the arguments you used.</p>
<h2 id="template-declarations"><a href="#TOC"><span class="header-section-number">2.1</span> Template Declarations</a></h2>
<p>Here is the syntax for a template declaration:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">template</span> templateName(list, of, parameters)
{
<span class="co">// Some syntactically correct declarations here</span>
<span class="co">// The arguments are accessible inside the template scope.</span>
}</code></pre>
<p><code>templateName</code> is your usual D identifier and the list of parameters is a comma-separated list of zero or more template parameters. These can be:</p>
<dl>
<dt>Types</dt>
<dd><p>An <code>identifier</code> alone by itself is considered a type name. The common D style is to use identifiers beginning with a capital letter (<code>Range</code>, <code>Rest</code>), as for any user-defined types. Many D templates use the C++ tradition of one-capital-letter names for types, starting from <code>T</code> (<code>U</code>, <code>V</code>, ...). Do not feel constrained by this, use what makes your templates most easy to understand.</p>
</dd>
<dt>Aliases</dt>
<dd><p>These will capture symbols: variable names, class names, even other template names. They will also accept many compile-time literals: strings, arrays, function literals, ... Mostly, if you need a widely-accepting template, use an alias parameter. They will <em>not</em> accept built-in types as arguments, however. You declare them with <code class="sourceCode d"><span class="kw">alias</span> identifier</code>.</p>
</dd>
<dt>Literal values</dt>
<dd><p>They can be integral values (<code class="sourceCode d"><span class="dt">int</span></code>, <code class="sourceCode d"><span class="dt">ulong</span></code>, ...), enum-based, strings, chars, floating-point values or boolean values. I think the rule is that any expression that can be evaluated at compile-time is OK. They are all declared like this: <code>typeName identifier</code>. For example : <code class="sourceCode d"><span class="dt">int</span> depth</code> or <code class="sourceCode d"><span class="dt">string</span> name</code>.</p>
</dd>
<dt>Template parameters tuples</dt>
<dd><p>Template parameters tuples will capture under one identifier an entire list of template parameters (types, names, literals, ...). Tuples will store any template argument you will throw at them. If no argument is passed, you will just get a zero-length tuple. Really, as they can deal with types as well as symbols, these tuples are a bit of a mongrel type but they are wonderfully powerful and easy to use, as you will see in section <a href="#template-tuple-parameters">Tuples</a>. The syntax is <code>identifier...</code> (yes, three dots) and the tuple must be the last parameter of a template.</p>
</dd>
</dl>
<p>Of those, types and aliases are the most common, while floating point values are fairly rare: their use as arguments for compile-time calculations have been superseded by D's Compile-Time Function Evaluation, aka <a href="#ctfe">CTFE</a>. You'll see different uses of these parameters in this document.</p>
<p>Note that pointers, arrays, objects (instantiated classes), structs or functions are not part of this list. But as I said, alias parameters allow you to capture and use array, class, function or struct <em>names</em> and then access their capacities.</p>
<blockquote>
<p><strong>Aliases, Symbols and Names.</strong> There is big difference between built-in types like <code class="sourceCode d"><span class="dt">int</span></code> or <code class="sourceCode d"><span class="dt">double</span>[<span class="dv">3</span>]</code> and user-defined types. A user-defined type, say a class called <code>MyClass</code>, is a type name. So, it's <em>both</em> a type (the class <code>MyClass</code>, accepted by type templates arguments) and a name (<code>MyClass</code>, accepted by <code>alias</code> template parameters). On the other hand, <code class="sourceCode d"><span class="dt">int</span></code>, being a D keyword is not a symbol nor a name. It's just a type. You cannot pass it to an alias template parameter.</p>
</blockquote>
<p>The template body can contain any standard D declarations: variable, function, class, interface, other templates, alias declarations,... The only exception I can think of is declaring a <code>module</code>, as this is done at the top-level scope.</p>
<blockquote>
<p><strong>Syntax and Semantics.</strong> And then there is a catch: code inside a <code class="sourceCode d"><span class="kw">template</span></code> declaration must only be syntactically correct D code (that is: code that looks like D code). The semantics are not checked until instantiation. That means you can code happily, writing templates upon templates and the compiler won't bat an eye if you do not exercise your templates by instantiating them.</p>
</blockquote>
<p>Inside the template body, the parameters are all accessible as placeholders for the future arguments. Also, the template's own name refers to its current instantiation when the code is generated. This is mostly used in struct (see sections <a href="#struct-templates">Struct Templates</a> and <a href="#class-templates">Class Templates</a>).</p>
<p>Here are some template declaration examples:</p>
<table class="sourceCode d numberLines"><tr class="sourceCode"><td class="lineNumbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
</pre></td><td class="sourceCode"><pre><code class="sourceCode d"><span class="kw">module</span> declaration;
<span class="kw">template</span> ArrayOf(T) <span class="co">// T is a type</span>
{
<span class="kw">alias</span> T[] ArrayType;
<span class="kw">alias</span> T ElementType;
}
<span class="kw">template</span> Transformer(From, To) <span class="co">// From and To are types, too</span>
{
To transform(From from)
{
<span class="kw">import</span> std.conv;
<span class="kw">return</span> to!(To)(from);
}
<span class="kw">class</span> Modificator
{
From f;
To t;
<span class="kw">this</span>(From f) { <span class="co">/*...*/</span> }
}
}
<span class="kw">template</span> nameOf(<span class="kw">alias</span> a)
{
<span class="kw">enum</span> <span class="dt">string</span> name = a.<span class="dt">stringof</span>; <span class="co">// enum: manifest constant</span>
<span class="co">// determined at compile-time</span>
}
<span class="kw">template</span> ComplicatedOne(T, <span class="dt">string</span> s, <span class="kw">alias</span> a, <span class="dt">bool</span> b, <span class="dt">int</span> i)
{ <span class="co">/* some code using T, s, a, b and i */</span> }
<span class="kw">template</span> Minimalist() {} <span class="co">// Zero-parameter template declaration.</span>
<span class="kw">template</span> OneOrMore(FirstType, Rest...) <span class="co">// Rest is a tuple.</span>
{ <span class="co">/*...*/</span> }
<span class="kw">template</span> ZeroOrMore(Types...) <span class="co">// Types is a tuple.</span>
{ <span class="co">/*...*/</span> }
<span class="kw">template</span> Multiple(T) { <span class="co">/*...*/</span> } <span class="co">// One arg version.</span>
<span class="kw">template</span> Multiple(T,U) { <span class="co">/*...*/</span> } <span class="co">// Two args,</span>
<span class="kw">template</span> Multiple(T,U,V) { <span class="co">/*...*/</span> } <span class="co">// and three.</span></code></pre></td></tr></table>
<p>The real syntax for template declarations is slightly more complex, I'll introduce more of it in the next sections. You'll see for example type restrictions in section <a href="#templates-specializations">Templates Specializations</a>, default values in section <a href="#default-values">Default Values</a>, instantiation constraints in <a href="#constraints">Template Constraints</a>, and more on tuples in section <a href="#template-tuple-parameters">tuples</a>.</p>
<p>There is a limitation that's interesting to keep in mind: templates can be declared in almost any scope, except inside a (regular) function.</p>
<blockquote>
<p><strong>enum.</strong> In the previous code, see line 27? It defines a <code class="sourceCode d"><span class="dt">string</span></code> called <code>name</code> as a member of <code>nameOf</code>. The <code class="sourceCode d"><span class="kw">enum</span></code> placed right before means <code>name</code> is a compile-time constant. You can see it as a kind of storage class, in the line of <code class="sourceCode d"><span class="kw">immutable</span></code> or <code class="sourceCode d"><span class="kw">const</span></code>, one that means the value is totally defined and fixed at runtime. You'll see numerous examples of <code class="sourceCode d"><span class="kw">enum</span></code> in this document.</p>
</blockquote>
<h2 id="instantiating-a-template"><a href="#TOC"><span class="header-section-number">2.2</span> Instantiating a Template</a></h2>
<p>To instantiate a template, use the following syntax:</p>
<pre class="sourceCode d"><code class="sourceCode d">templateName!(list, of, arguments)</code></pre>
<p>Note the exclamation point (<code>!</code>) before the comma-separated argument list. If the argument list contains only one argument (one token), you can drop the parenthesis:</p>
<pre class="sourceCode d"><code class="sourceCode d">templateName!argument</code></pre>
<blockquote>
<p><strong>Templates as templates arguments.</strong> Arguments can themselves be the result of another template instantiation. If a template returns a type upon instantiation, it's perfectly OK to use it inside another template argument list. In this document you'll regularly see Matrioshka calls like this: <code>firstTemp!(secondTempl!(Arguments), OtherArguments)</code>.</p>
</blockquote>
<p>The compiler will have a look at the declarations (if more than one template was declared with the called name) and select the one with the correct number of arguments and the correct types to instantiate. If more than one template can be instantiated, it will complain and stop there (though, have a look on <a href="#templates-specializations">template specializations</a> and <a href="#constraints">template constraints</a>.</p>
<p>When you instantiate a template, the global effect is that a new named scope is created in the template declaration scope. The name of this new scope is the template name with its argument list: <code>templateName!(args)</code>. Inside the scope, the parameters are now 'replaced' with the corresponding arguments (storage classes get applied, variables are initialized, ...). Here's what possible instantiations of the previous templates might look like:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> instantiation;
<span class="kw">import</span> declaration;
<span class="dt">void</span> main()
{
ArrayOf!(<span class="dt">int</span>).ArrayType myArray;
<span class="co">// From is an alias for the type double</span>
<span class="co">// To for the type int</span>
<span class="kw">alias</span> Transformer!(<span class="dt">double</span>,<span class="dt">int</span>) transfo;
<span class="kw">struct</span> MyStruct { <span class="co">/*...*/</span> }
<span class="co">// "MyStruct" is a identifier -> captured by alias</span>
<span class="kw">auto</span> name = nameOf!(MyStruct).name;
<span class="kw">alias</span>
ComplicatedOne!( <span class="dt">int</span>[] <span class="co">// a type</span>
, <span class="st">"Hello"</span> <span class="co">// a string literal</span>
, ArrayOf <span class="co">// a name</span>
, <span class="kw">true</span> <span class="co">// a boolean literal</span>
, <span class="dv">1</span>+<span class="dv">2</span> <span class="co">// calculated to be the integral '3'.</span>
) complicatedExample;
<span class="kw">alias</span> Minimalist!() min1;
<span class="co">// Rest is (double,string,"abc")</span>
<span class="co">// Rest is (double,string,"abc")</span>
<span class="kw">alias</span> OneOrMore!( <span class="dt">int</span>
, <span class="dt">double</span>, <span class="dt">string</span>, <span class="st">"abc"</span>
) oneOrMore;
<span class="co">// Types is a 1-element tuple: (int)</span>
<span class="kw">alias</span> ZeroOrMore!(<span class="dt">int</span>) zero1;
<span class="co">// Types is (int,double,string)</span>
<span class="kw">alias</span> ZeroOrMore!(<span class="dt">int</span>,<span class="dt">double</span>,<span class="dt">string</span>) zero2;
<span class="co">// Types is the empty tuple: ()</span>
<span class="kw">alias</span> ZeroOrMore!() zero3;
<span class="co">// Selects the one-arg version</span>
<span class="kw">alias</span> Multiple!(<span class="dt">int</span>) mult1;
<span class="co">// The three args version.</span>
<span class="kw">alias</span> Multiple!(<span class="dt">int</span>,<span class="dt">double</span>,<span class="dt">string</span>) mult2;
<span class="co">// Error! No 0-arg version</span>
<span class="co">//alias Multiple!() mult3;</span>
}</code></pre>
<p>Outside the scope (that is, where you put the template instantiation in your own code), the internal declarations are accessible by fully qualifying them:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> internaldeclarations1;
<span class="kw">import</span> declaration;
<span class="co">// ArrayType is accessible (it's int[])</span>
<span class="co">// array is a completly standard dynamic array of ints.</span>
ArrayOf!(<span class="dt">int</span>).ArrayType array;
ArrayOf!(<span class="dt">int</span>).ElementType element; <span class="co">// the same, element is an int.</span>
<span class="dt">void</span> main()
{
<span class="co">// the transform function is accessible. Instantiated like this,</span>
<span class="co">// it's a function from double to string.</span>
<span class="kw">auto</span> s = Transformer!(<span class="dt">double</span>,<span class="dt">string</span>).transform(<span class="fl">3.14159</span>);
<span class="kw">assert</span>(<span class="kw">is</span>(<span class="dt">typeof</span>(s) == <span class="dt">string</span>)); <span class="co">// s is a string</span>
}</code></pre>
<p>Obviously, using templates like this, with their full name, is a pain. The nifty D <code class="sourceCode d"><span class="kw">alias</span></code> declaration is your friend:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> internaldeclarations2;
<span class="kw">import</span> declaration;
<span class="kw">alias</span> Transformer!(<span class="dt">double</span>, <span class="dt">string</span>) StoD;
<span class="dt">void</span> main()
{
<span class="kw">auto</span> s = StoD.transform(<span class="fl">3.14159</span>);
<span class="kw">auto</span> m = <span class="kw">new</span> StoD.Modificator(<span class="fl">1.618</span>); <span class="co">// StoD.Modificator is a class</span>
<span class="co">// storing a double and a string.</span>
}</code></pre>
<p>You must keep in mind that instantiating a template means generating code. Using different arguments at different places in your code will instantiate <em>as many differently named scopes</em>. This is a major difference with <em>generics</em> in languages like Java or C#, where generic code is created only once and type erasure is used to link all this together. On the other hand, trying to instantiate many times the 'same' template (ie: with the same arguments) will only create one piece of code.</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> differentinstantiations;
<span class="kw">import</span> declaration;
<span class="kw">alias</span> Transformer!(<span class="dt">string</span>,<span class="dt">double</span>) StoD;
<span class="kw">alias</span> Transformer!(<span class="dt">double</span>,<span class="dt">string</span>) DtoS;
<span class="kw">alias</span> Transformer!(<span class="dt">string</span>,<span class="dt">int</span>) StoI;
<span class="co">// Now we can use three different functions and three different classes.</span></code></pre>
<blockquote>
<p><strong>void.</strong> Note that <code class="sourceCode d"><span class="dt">void</span></code> is a D type and, as such, a possible template argument for a type parameter. Take care: many templates make no sense when <code class="sourceCode d"><span class="dt">void</span></code> is used as a type. In the following sections and in the appendix, you'll see ways to restrict arguments to only certain types.</p>
</blockquote>
<h2 id="template-building-blocks"><a href="#TOC"><span class="header-section-number">2.3</span> Template Building Blocks</a></h2>
<p>Up to now, templates may not seem that interesting to you, even with a simple declaration and instantiation syntax. But wait! D introduced a few nifty tricks that both simplify and greatly expand templates use. This section will introduce you to your future best friends, the foundations on which your templates will be built.</p>
<h3 id="the-eponymous-trick"><a href="#TOC"><span class="header-section-number">2.3.1</span> The Eponymous Trick</a></h3>
<p>If a template declares a symbol with the same name (greek: <em>epo-nymous</em>) as the enclosing template, that symbol is assumed to be referred to when the template is instantiated. This one is pretty good to clean your code:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> pair;
<span class="kw">template</span> pair(T)
{
<span class="co">// template 'pair' declares only a 'pair' member</span>
T[] pair(T t) { <span class="kw">return</span> [t,t];}
}
<span class="kw">auto</span> array = pair!(<span class="dt">int</span>)(<span class="dv">1</span>); <span class="co">// no need to do pair!(int).pair(1)</span></code></pre>
<p>or:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> nameof1;
<span class="kw">template</span> nameOf(<span class="kw">alias</span> name)
{
<span class="kw">enum</span> <span class="dt">string</span> nameOf = name.<span class="dt">stringof</span>;
}
<span class="kw">struct</span> Example { <span class="dt">int</span> i;}
<span class="dt">void</span> main()
{
Example example;
<span class="kw">auto</span> s1 = nameOf!(Example);
<span class="kw">auto</span> s2 = nameOf!(example);
<span class="kw">assert</span>(s1 == <span class="st">"Example"</span>);
<span class="kw">assert</span>(s2 == <span class="st">"example"</span>);
}</code></pre>
<p>There used to be a limitation in that the eponymous trick worked <em>only</em> if you defined one (and only one) symbol. Even if the other symbols were private, they would break the eponymous substitution. This was changed recently (Fall 2012) and now, we can do:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> record;
<span class="kw">template</span> Record(T, U, V)
{
<span class="kw">import</span> std.typecons: Tuple, tuple;
<span class="co">// The real work is done here</span>
<span class="co">// Use as many symbols as you need.</span>
<span class="kw">alias</span> Tuple!(T,U) Pair;
<span class="kw">alias</span> Pair[V] AssocArray;
<span class="kw">alias</span> AssocArray[] Record;
}</code></pre>
<p>Note that in this case, the eponymous member is an alias, whereas it was a function or a manifest constant (an <code class="sourceCode d"><span class="kw">enum</span></code>) in previous examples. As was already said, any member with the same name will do.</p>
<p>And then, to use <code>Record</code>:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> using_record;
<span class="kw">import</span> record;
Record!(<span class="dt">int</span>,<span class="dt">string</span>,<span class="dt">double</span>[]) recordslist;
<span class="co">/* ... */</span></code></pre>
<p>Although, in this case, the eponymous member hides the other members: <code>Pair</code> and <code>AssocArray</code> cannot be accessed any more. That seems logical, since if you use the eponymous trick, it's to provide a simplified interface to your users.</p>
<h3 id="inner-alias"><a href="#TOC"><span class="header-section-number">2.3.2</span> Inner alias</a></h3>
<p>A common use for templates is to do some type magics: deducing types, assembling them in new way, etc. Types are not first-class entities in D (there is no <code>type</code> type), but they can easily be manipulated as any other symbol, by aliasing them. So, when a template has to expose a type, it's done by aliasing it to a new name.</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> allarrays;
<span class="kw">template</span> AllArraysOf(T)
{
<span class="kw">alias</span> T Element;
<span class="kw">alias</span> T* PointerTo;
<span class="kw">alias</span> T[] DynamicArray;
<span class="kw">alias</span> T[<span class="dv">1</span>] StaticArray;
<span class="kw">alias</span> T[T] AssociativeArray;
}</code></pre>
<blockquote>
<p><strong>Exposing Template Parameters.</strong> Though they are part of a template's name, its parameters are <em>not</em> directly accessible externally. Keep in mind that a template name is just a scope name. Once it's instantiated, all the <code>T</code>s and <code>U</code>s and such do not exist anymore. If you need them externally, expose them through a template member, as is done with <code>AllArraysOf.Element</code>. You will find other examples of this in section <a href="#struct-templates">Struct Templates</a> and section <a href="#class-templates">Class Templates</a>.</p>
</blockquote>
<h3 id="static-if"><a href="#TOC"><span class="header-section-number">2.3.3</span> <code>static if</code></a></h3>
<h4 id="syntax"><a href="#TOC"><span class="header-section-number">2.3.3.1</span> Syntax</a></h4>
<p>The <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> construct<sup><a href="#fn2" class="footnoteRef" id="fnref2">2</a></sup> lets you decide between two code paths at compile time. It's not specific to templates (you can use it in other part of your code), but it's incredibly useful to have your templates adapt themselves to the arguments. That way, using compile-time-calculated predicates based on the template arguments, you'll generate different code and customize the template to your need.</p>
<p>The syntax is:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span> (compileTimeExpression)
{
<span class="co">/* Code created if compileTimeExpression is evaluated to true */</span>
}
<span class="kw">else</span> <span class="co">/* optional */</span>
{
<span class="co">/* Code created if it's false */</span>
}</code></pre>
<p>Something really important here is a bit of compiler magic: once the code path is selected, the resulting code is instantiated in the template body, but without the curly braces. Otherwise that would create a local scope, hiding what's happening inside and would drastically limit the power of <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code>. So the curly braces are there only to group the statements together.</p>
<p>If there is only one statement, you can get rid of the braces entirely, something you'll see frequently in D code. For example, suppose you need a template that 'returns' <code class="sourceCode d"><span class="kw">true</span></code> if the passed type is a dynamic array and <code class="sourceCode d"><span class="kw">false</span></code> otherwise (this kind of predicate template is developed a bit more in section [predicates]).</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> isdynamicarray;
<span class="kw">template</span> isDynamicArray(T)
{
<span class="kw">static</span> <span class="kw">if</span> (<span class="kw">is</span>(T t == U[], U))
<span class="kw">enum</span> isDynamicArray = <span class="kw">true</span>;
<span class="kw">else</span>
<span class="kw">enum</span> isDynamicArray = <span class="kw">false</span>;
}</code></pre>
<p>As you can see, with no curly braces after <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> and the eponymous trick (<code>isDynamicArray</code> is a symbol defined by the template and its type is automatically deduced by the compiler), results in a very clean syntax. The <code class="sourceCode d"><span class="kw">is</span>()</code> expression part is a way to get compile-time introspection which goes hand in hand with <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code>. There is a crash course on it at the end of this document (see [appendix-isExpression]).</p>
<h4 id="optional-code"><a href="#TOC"><span class="header-section-number">2.3.3.2</span> Optional Code</a></h4>
<p>A common use of <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> is to enable or disable code: a single <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> without an <code class="sourceCode d"><span class="kw">else</span></code> clause will generate code only when the condition is true. You can find many examples of this idiom in <a href="http://dlang.org/phobos/std_range.html">std.range</a> where higher-level ranges (ranges wrapping other ranges) will activate some functionality if and only if the wrapped range can support it, like this:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="co">/* We are inside a MyRange templated struct, wrapping a R. */</span>
R innerRange;
<span class="co">/* Code that exists in all instantiations of MyRange */</span>
(...)
<span class="co">/* optional code */</span>
<span class="kw">static</span> <span class="kw">if</span> (hasLength!R) <span class="co">// does innerRange have a .length() method?</span>
<span class="kw">auto</span> length() <span class="co">// Then MyRange has one also.</span>
{
<span class="kw">return</span> innerRange.<span class="dt">length</span>;
}
<span class="kw">static</span> <span class="kw">if</span> (isInfinite!R) <span class="co">// Is innerRange an infinite range?</span>
<span class="kw">enum</span> <span class="dt">bool</span> empty = <span class="kw">false</span>; <span class="co">// Then MyRange is also infinite.</span>
<span class="co">// And so on...</span></code></pre>
<h4 id="nested-static-ifs"><a href="#TOC"><span class="header-section-number">2.3.3.3</span> Nested <code>static if</code>s</a></h4>
<p><code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code>'s can be nested: just put another <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> after <code class="sourceCode d"><span class="kw">else</span></code>. Here is a template selecting an alias:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> selector;
<span class="kw">import</span> std.traits: isIntegral, isFloatingPoint;
<span class="kw">template</span> selector(T, <span class="kw">alias</span> intFoo, <span class="kw">alias</span> floatFoo, <span class="kw">alias</span> defaultFoo)
{
<span class="kw">static</span> <span class="kw">if</span> (isIntegral!T)
<span class="kw">alias</span> intFoo selector;
<span class="kw">else</span> <span class="kw">static</span> <span class="kw">if</span> (isFloatingPoint!T)
<span class="kw">alias</span> floatFoo selector;
<span class="kw">else</span> <span class="co">// default case</span>
<span class="kw">alias</span> defaultFoo selector;
}</code></pre>
<p>If you need a sort of <code>static switch</code> construct, see section [examples-staticswitch].</p>
<h4 id="recursion-with-static-if"><a href="#TOC"><span class="header-section-number">2.3.3.4</span> Recursion with <code>static if</code></a></h4>
<h5 id="rank"><a href="#TOC"><span class="header-section-number">2.3.3.4.1</span> Rank:</a></h5>
<p>Now, let's use <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> for something a bit more complicated than just dispatching between code paths: recursion. What if you know you will receive n-dimensional arrays (simple arrays, arrays of arrays, arrays of arrays of arrays, ...), and want to use the fastest, super-optimized numerical function for the 1-dim array, another one for 2D arrays and yet another one for higher-level arrays? Abstracting this away, we need a template doing some introspection on types, that will return 0 for an element (anything that's not an array), 1 for a 1-dim array (<code>T[]</code>, for some <code class="sourceCode d">T</code>), 2 for a 2-dim array (<code>T[][]</code>), and so on. Mathematicians call this the <em>rank</em> of an array, so we will use that. The definition is perfectly recursive:</p>
<table class="sourceCode d numberLines"><tr class="sourceCode"><td class="lineNumbers"><pre>1
2
3
4
5
6
7
8
9
</pre></td><td class="sourceCode"><pre><code class="sourceCode d"><span class="kw">module</span> rank1;
<span class="kw">template</span> rank(T)
{
<span class="kw">static</span> <span class="kw">if</span> (<span class="kw">is</span>(T t == U[], U)) <span class="co">// is T an array of U, for some type U?</span>
<span class="kw">enum</span> <span class="dt">size_t</span> rank = <span class="dv">1</span> + rank!(U); <span class="co">// then let's recurse down.</span>
<span class="kw">else</span>
<span class="kw">enum</span> <span class="dt">size_t</span> rank = <span class="dv">0</span>; <span class="co">// Base case, ending the recursion.</span>
}</code></pre></td></tr></table>
<p>Lines 5 and 6 are the most interesting: with some <code class="sourceCode d"><span class="kw">is</span></code> magic, <code class="sourceCode d">U</code> has been deduced by the compiler and is accessible inside the <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> branch. We use it to peel one level of <code>[]</code> off the type and recurse downward, using <code class="sourceCode d">U</code> as a new type for instantiating <code class="sourceCode d">rank</code>. Either <code class="sourceCode d">U</code> is itself an array (in which case the recursion will continue) or it will hit the base case and stop there. Since the template defines a member named like itself, the result is directly accessible: any instantiation of <code>rank</code> will be a value of type <code class="sourceCode d"><span class="dt">size_t</span></code>.</p>
<p>Let's use it:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> using_rank1;
<span class="kw">import</span> rank1;
<span class="kw">static</span> <span class="kw">assert</span>(rank!(<span class="dt">int</span>) == <span class="dv">0</span>);
<span class="kw">static</span> <span class="kw">assert</span>(rank!(<span class="dt">int</span>[]) == <span class="dv">1</span>);
<span class="kw">static</span> <span class="kw">assert</span>(rank!(<span class="dt">int</span>[][]) == <span class="dv">2</span>);
<span class="kw">static</span> <span class="kw">assert</span>(rank!(<span class="dt">int</span>[][][]) == <span class="dv">3</span>);
<span class="co">/* It will work for any type, obviously */</span>
<span class="kw">struct</span> S {}
<span class="kw">static</span> <span class="kw">assert</span>(rank!(S) == <span class="dv">0</span>);
<span class="kw">static</span> <span class="kw">assert</span>(rank!(S[])== <span class="dv">1</span>);
<span class="kw">static</span> <span class="kw">assert</span>(rank!(S*) == <span class="dv">0</span>);</code></pre>
<blockquote>
<p><strong>static assert.</strong> Putting <code class="sourceCode d"><span class="kw">static</span></code> before an <code class="sourceCode d"><span class="kw">assert</span></code> forces the <code class="sourceCode d"><span class="kw">assert</span></code> execution at compile-time. Using an <code class="sourceCode d"><span class="kw">is</span></code> expression as the test clause gives assertion on types. One common use of <code class="sourceCode d"><span class="kw">static</span> <span class="kw">assert</span></code> is to stop the compilation, for example if we ever get in a bad code path, by using <code class="sourceCode d"><span class="kw">static</span> <span class="kw">assert</span>(<span class="kw">false</span>, someString)</code> (or <code class="sourceCode d"><span class="kw">static</span> <span class="kw">assert</span>(<span class="dv">0</span>, someString)</code>). The string is then emitted as a compiler error message.</p>
</blockquote>
<h5 id="rank-for-ranges"><a href="#TOC"><span class="header-section-number">2.3.3.4.2</span> Rank for Ranges:</a></h5>
<p>D has an interesting sequence concept called a <em>range</em>. The <a href="http://dlang.org/phobos/index.html">Phobos</a> standard library comes with predefined testing templates in <a href="http://dlang.org/phobos/std_range.html">std.range</a>. Why not extend <code class="sourceCode d">rank</code> to have it deal with ranges and see if something is a range of ranges or more? A type can be tested to be a range with <code class="sourceCode d">isInputRange</code> and its element type is obtained by applying <code class="sourceCode d">ElementType</code> to the range type. Both templates are found in <a href="http://dlang.org/phobos/std_range.html">std.range</a>. Also, since arrays are included in the range concept, we can entirely ditch the array part and use only ranges. Here is a slightly modified version of <code class="sourceCode d">rank</code>:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> rank2;
<span class="kw">import</span> std.range;
<span class="kw">template</span> rank(T)
{
<span class="kw">static</span> <span class="kw">if</span> (isInputRange!T) <span class="co">// is T a range?</span>
<span class="kw">enum</span> <span class="dt">size_t</span> rank = <span class="dv">1</span> + rank!(ElementType!T); <span class="co">// if yes, recurse</span>
<span class="kw">else</span>
<span class="kw">enum</span> <span class="dt">size_t</span> rank = <span class="dv">0</span>; <span class="co">// base case, stop there</span>
}
<span class="kw">unittest</span>
{
<span class="kw">auto</span> c = cycle([[<span class="dv">0</span>,<span class="dv">1</span>],[<span class="dv">2</span>,<span class="dv">3</span>]]); <span class="co">// == [[0,1],[2,3],[0,1],[2,3],[0,1]...</span>
<span class="kw">assert</span>(rank!(<span class="dt">typeof</span>(c)) == <span class="dv">2</span>); <span class="co">// range of ranges</span>
}</code></pre>
<h5 id="base-element-type"><a href="#TOC"><span class="header-section-number">2.3.3.4.3</span> Base Element Type:</a></h5>
<p>With <code class="sourceCode d">rank</code>, we now have a way to get the number of <code>[]</code>'s in an array type (<code>T[][][]</code>) or the level of nesting in a range of ranges. The complementary query would be to get the base element type, <code class="sourceCode d">T</code>, from any array of arrays ... of <code class="sourceCode d">T</code> or the equivalent for a range. Here it is:</p>
<table class="sourceCode d numberLines"><tr class="sourceCode"><td class="lineNumbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
</pre></td><td class="sourceCode"><pre><code class="sourceCode d"><span class="kw">module</span> baseelementtype;
<span class="kw">import</span> std.range;
<span class="kw">import</span> rank2;
<span class="kw">template</span> BaseElementType(T)
{
<span class="kw">static</span> <span class="kw">if</span> (rank!T == <span class="dv">0</span>) <span class="co">// not a range</span>
<span class="kw">static</span> <span class="kw">assert</span>(<span class="dv">0</span>, T.<span class="dt">stringof</span> ~ <span class="st">" is not a range."</span>);
<span class="kw">else</span> <span class="kw">static</span> <span class="kw">if</span> (rank!T == <span class="dv">1</span>) <span class="co">// simple range</span>
<span class="kw">alias</span> ElementType!T BaseElementType;
<span class="kw">else</span> <span class="co">// at least range of ranges</span>
<span class="kw">alias</span> BaseElementType!(ElementType!(T)) BaseElementType;
}</code></pre></td></tr></table>
<p>Line 8 is an example of <code>static assert</code> stopping compilation if we ever get into a bad code path. Line 12 is an example of a Matrioshka call: a template using another template's call as its parameter.</p>
<h5 id="generating-arrays"><a href="#TOC"><span class="header-section-number">2.3.3.4.4</span> Generating Arrays:</a></h5>
<p>Now, what about becoming more generative by inverting the process? Given a type <code class="sourceCode d">T</code> and a rank <code class="sourceCode d">r</code> (a <code class="sourceCode d"><span class="dt">size_t</span></code>), we want to obtain <code>T[][]...[]</code>, with <code class="sourceCode d">r</code> levels of <code>[]</code>'s. A rank of 0 means producing <code class="sourceCode d">T</code> as the result type.</p>
<table class="sourceCode d numberLines"><tr class="sourceCode"><td class="lineNumbers"><pre>1
2
3
4
5
6
7
8
9
</pre></td><td class="sourceCode"><pre><code class="sourceCode d"><span class="kw">module</span> ndim;
<span class="kw">template</span> NDimArray(T, <span class="dt">size_t</span> r)
{
<span class="kw">static</span> <span class="kw">if</span> (r == <span class="dv">0</span>)
<span class="kw">alias</span> T NDimArray;
<span class="kw">else</span>
<span class="kw">alias</span> NDimArray!(T, r-<span class="dv">1</span>)[] NDimArray;
}</code></pre></td></tr></table>
<p>Here, recursion is done on line 8: we instantiate <code class="sourceCode d">NDimArray!(T,r-<span class="dv">1</span>)</code>, which is a type, then create an array of them by putting <code>[]</code> at the end and expose it through an alias. This is also a nice example of using an integral value, <code>r</code>, as a template parameter.</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> using_ndim;
<span class="kw">import</span> ndim;
<span class="kw">alias</span> NDimArray!(<span class="dt">double</span>, <span class="dv">8</span>) Level8;
<span class="kw">static</span> <span class="kw">assert</span>(<span class="kw">is</span>(Level8 == <span class="dt">double</span>[][][][][][][][]));
<span class="kw">static</span> <span class="kw">assert</span>(<span class="kw">is</span>(NDimArray!(<span class="dt">double</span>, <span class="dv">0</span>) == <span class="dt">double</span>));</code></pre>
<h5 id="repeated-composition"><a href="#TOC"><span class="header-section-number">2.3.3.4.5</span> Repeated composition:</a></h5>
<p>As a last example, we will use an alias template parameter in conjunction with some <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> recursion to define a template that creates the 'exponentiation' of a function, aka its repeated composition. Here is what I mean by this:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> using_power;
<span class="kw">import</span> repeatedcomposition;
<span class="co">// standard function</span>
<span class="dt">string</span> foo(<span class="dt">string</span> s) { <span class="kw">return</span> s ~ s;}
<span class="co">// function templates. You'll see them soon.</span>
Arr[] makeArray(Arr)(Arr array) { <span class="kw">return</span> [array,array];}
<span class="dt">void</span> main()
{
<span class="co">// power!(foo, n) is a function.</span>
<span class="kw">assert</span>(power!(foo, <span class="dv">0</span>)(<span class="st">"a"</span>) == <span class="st">"a"</span>); <span class="co">// identity function</span>
<span class="kw">assert</span>(power!(foo, <span class="dv">1</span>)(<span class="st">"a"</span>) == foo(<span class="st">"a"</span>)); <span class="co">// "aa"</span>
<span class="kw">assert</span>(power!(foo, <span class="dv">2</span>)(<span class="st">"a"</span>) == foo(foo(<span class="st">"a"</span>))); <span class="co">// "aaaa"</span>
<span class="kw">assert</span>(power!(foo, <span class="dv">3</span>)(<span class="st">"a"</span>) == foo(foo(foo(<span class="st">"a"</span>)))); <span class="co">// "aaaaaaaa"</span>
<span class="co">// It's even better with function templates:</span>
<span class="kw">assert</span>(power!(makeArray, <span class="dv">0</span>)(<span class="dv">1</span>) == <span class="dv">1</span>);
<span class="kw">assert</span>(power!(makeArray, <span class="dv">1</span>)(<span class="dv">1</span>) == [<span class="dv">1</span>,<span class="dv">1</span>]);
<span class="kw">assert</span>(power!(makeArray, <span class="dv">2</span>)(<span class="dv">1</span>) == [[<span class="dv">1</span>,<span class="dv">1</span>],[<span class="dv">1</span>,<span class="dv">1</span>]]);
<span class="kw">assert</span>(power!(makeArray, <span class="dv">3</span>)(<span class="dv">1</span>) == [[[<span class="dv">1</span>,<span class="dv">1</span>],[<span class="dv">1</span>,<span class="dv">1</span>]],[[<span class="dv">1</span>,<span class="dv">1</span>],[<span class="dv">1</span>,<span class="dv">1</span>]]]);
}</code></pre>
<p>First, this is a template that 'returns' (becomes, rather) a function. It's easy to do with the eponymous trick: just define inside the template a function with the same name. Secondly, it's clearly recursive in its definition, with two base cases: if the exponent is zero, then we shall produce the identity function and if the exponent is one, we shall just return the input function itself. That being said, <code class="sourceCode d">power</code> writes itself:</p>
<table class="sourceCode d numberLines"><tr class="sourceCode"><td class="lineNumbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td><td class="sourceCode"><pre><code class="sourceCode d"><span class="kw">module</span> repeatedcomposition;
<span class="kw">template</span> power(<span class="kw">alias</span> fun, <span class="dt">uint</span> exponent)
{
<span class="kw">static</span> <span class="kw">if</span> (exponent == <span class="dv">0</span>) <span class="co">// degenerate case -> id function</span>
<span class="kw">auto</span> power(Args)(Args args) { <span class="kw">return</span> args; }
<span class="kw">else</span> <span class="kw">static</span> <span class="kw">if</span> (exponent == <span class="dv">1</span>) <span class="co">// end-of-recursion case -> fun</span>
<span class="kw">alias</span> fun power;
<span class="kw">else</span>
<span class="kw">auto</span> power(Args...)(Args args)
{
<span class="kw">return</span> .power!(fun, exponent-<span class="dv">1</span>)(fun(args));
}
}</code></pre></td></tr></table>
<blockquote>
<p><strong>.power</strong> If you are wondering what's with the <code>.power</code> syntax on line 12, it's because by defining an eponymous template, we hide the parent template's name. So inside <code>power(Args...)</code>, <code>power</code> refers to <code>power(Args...)</code> and not <code class="sourceCode d">power(<span class="kw">alias</span> fun, <span class="dt">uint</span> exponent)</code>. Here we want a new <code class="sourceCode d">power</code> to be generated so we call on the global <code class="sourceCode d">power</code> template with the 'global scope' operator (<code>.</code>).</p>
</blockquote>
<p>In all three branches of <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code>, <code class="sourceCode d">power</code> exposes a <code class="sourceCode d">power</code> member, activating the eponymous template trick and allowing for an easy use by the client. Note that this template will work not only for unary (one argument) functions but also for n-args functions <sup><a href="#fn3" class="footnoteRef" id="fnref3">3</a></sup>, for delegates and for structs or classes that define the <code>()</code>(ie, <code class="sourceCode d">opCall</code>) operator and for function templates... <sup><a href="#fn4" class="footnoteRef" id="fnref4">4</a></sup></p>
<p>Now, are you beginning to see the power of templates?</p>
<blockquote>
<p><strong>Curried Templates?</strong> No, I do not mean making them spicy, but separating the template's arguments, so as to call them in different places in your code. For <code class="sourceCode d">power</code>, that could mean doing <code class="sourceCode d"><span class="kw">alias</span> power!<span class="dv">2</span> square;</code> somewhere and then using <code>square!fun1</code>, <code>square!fun2</code> at your leisure: the <code class="sourceCode d">exponent</code> parameter and the <code class="sourceCode d">fun</code> alias are separated. In fact, <code class="sourceCode d">power</code> is already partially curried: <code class="sourceCode d">fun</code> and <code class="sourceCode d">exponent</code> are separated from <code class="sourceCode d">Args</code>. For more on this, see section <a href="#templates-in-templates">Templates In Templates</a>. Given a template <code class="sourceCode d">temp</code>, writing a <code class="sourceCode d">curry</code> template that automatically generates the code for a curried version of <code class="sourceCode d">temp</code> is <em>also</em> possible, but outside the scope of this document.</p>
</blockquote>
<h4 id="templates-specializations"><a href="#TOC"><span class="header-section-number">2.3.3.5</span> Templates Specializations</a></h4>
<p>Up to now, when we write a <code class="sourceCode d">T</code> in a template parameter list, there is no constraint on the type that <code class="sourceCode d">T</code> can become during instantiation. Template specialization is a small 'subsyntax', restricting templates instantiations to a subset of all possible types and directing the compiler into instantiating a particular version of a template instead of another. If you've read [appendix-isexpression] on the <code class="sourceCode d"><span class="kw">is</span>()</code> expression, you already know how to write them. If you didn't, please do it now, as it's really the same syntax. These specializations are a direct inheritance from C++ templates, up to the way they are written and they existed in D from the very beginning, long before <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> or templates constraints were added.</p>
<p>The specializations are added in the template parameter list, the <code>(T, U, V)</code> part of the template definition. <code>Type : OtherType</code> restricts <code class="sourceCode d">Type</code> to be implicitly convertible into <code>OtherType</code>.</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> specialization1;
<span class="kw">template</span> ElementType(T : U[], U) <span class="co">// can only be instantiated with arrays</span>
{
<span class="kw">alias</span> U ElementType;
}
<span class="kw">template</span> ElementType(T : U[n], U, <span class="dt">size_t</span> n) <span class="co">// only with static arrays</span>
{
<span class="kw">alias</span> U ElementType;
}
<span class="kw">class</span> Array { <span class="kw">alias</span> <span class="dt">int</span> ElementType;}
<span class="kw">template</span> ElementType(T : Array)
{
<span class="kw">alias</span> Array.ElementType ElementType;
}</code></pre>
<p>Now, the idea may seem strange to you: if you know you want to restrict <code class="sourceCode d">Type</code> to be <code class="sourceCode d">AnotherType</code>, why make it a template parameter? It's because of templates specializations' main use: you can write different implementations of a template (with the same name, obviously), and when asked to instantiate one of them, the compiler will automatically decide which one to use, taking the 'most adapted' to the provided arguments. 'Most adapted' obeys some complicated rules you can find on the D Programming Language website, but they act in a natural way most of the time. The neat thing is that you can define the most general template <em>and</em> some specialization. The specialized ones will be chosen when it's possible.</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> specialization2;
<span class="kw">template</span> InnerType(T : U*, U) <span class="co">// Specialization for pointers</span>
{
<span class="kw">alias</span> U InnerType;
}
<span class="kw">template</span> InnerType(T : U[], U) <span class="co">// Specialization for dyn. arrays</span>
{ <span class="co">/*...*/</span> }
<span class="kw">template</span> InnerType(T) <span class="co">// Standard, default case</span>
{ <span class="co">/*...*/</span> }
<span class="dt">void</span> main()
{
<span class="dt">int</span>* p;
<span class="dt">int</span> i;
<span class="kw">alias</span> InnerType!(<span class="dt">typeof</span>(p)) Pointer; <span class="co">// pointer spec. selected</span>
<span class="kw">alias</span> InnerType!(<span class="dt">typeof</span>(i)) Default; <span class="co">// standard template selected</span>
}</code></pre>
<p>This idiom is frequently used in C++, where there is no (built-in) <code class="sourceCode d"><span class="kw">static</span> <span class="kw">if</span></code> construct or template constraints. Oldish D templates used it a lot, too, but since other ways have been around for some years, recent D code seems to be more constraint-oriented: have a look at heavily templated Phobos modules, for example <a href="http://dlang.org/phobos/std_algorithm.html">std.algorithm</a> or <a href="http://dlang.org/phobos/std_range.html">std.range</a>.</p>
<blockquote>
<p><strong>Specializations or static if or Templates Constraints?</strong> Yes indeed. Let's defer this discussion for when we have seen all three subsystems.</p>
</blockquote>
<h3 id="default-values"><a href="#TOC"><span class="header-section-number">2.3.4</span> Default Values</a></h3>
<p>Like functions parameters, templates parameters can have default values. The syntax is the same: <code>Param = defaultValue</code>. The default can be anything that makes sense with respect to the parameter kind: a type, a literal value, a symbol or another template parameter.</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> def;
<span class="kw">template</span> Default(T = <span class="dt">int</span>, <span class="dt">bool</span> flag = <span class="kw">false</span>)
{
<span class="kw">static</span> <span class="kw">if</span> (flag)
<span class="kw">alias</span> T Default;
<span class="kw">else</span>
<span class="kw">alias</span> <span class="dt">void</span> Default;
}
<span class="kw">alias</span> Default!(<span class="dt">double</span>) D1; <span class="co">// Instantiate Default!(double, false)</span>
<span class="kw">alias</span> Default!(<span class="dt">double</span>, <span class="kw">true</span>) D2; <span class="co">// Instantiate Default!(double, true) (Doh!)</span>
<span class="kw">alias</span> Default!() D3; <span class="co">// Instantiate Default!(int, false)</span></code></pre>
<p>In contrast to function parameters, thanks to <a href="#templates-specializations">Templates Specializations</a> or <a href="#ifti">IFTI</a>, some template parameters can be automatically deduced by the compiler. So, default template parameters are not required to be the final parameters in the list:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> deduced;
<span class="kw">import</span> std.typecons: Tuple;
<span class="kw">template</span> Deduced(T : U[], V = T, U)
{
<span class="kw">alias</span> Tuple!(T,U,V) Deduced;
}
<span class="kw">alias</span> Deduced!(<span class="dt">int</span>[], <span class="dt">double</span>) D1; <span class="co">// U deduced to be int. Force V to be a double.</span>
<span class="kw">alias</span> Deduced!(<span class="dt">int</span>[]) D2; <span class="co">// U deduced to be int. V is int, too.</span></code></pre>
<blockquote>
<p><strong>Specialization and Default Value?</strong> Yes you can. Put the specialization first, then the default value. Like this: <code>(T : U[] = int[], U)</code>. It's not commonly used, though.</p>
</blockquote>
<p>As for functions, well-chosen defaults can greatly simplify standard calls. See for example <a href="http://dlang.org/phobos/std_algorithm.html#sort">std.algorithm.sort</a>. It's parameterized on a predicate and a swapping strategy, but both are adapted to what most people need when sorting. That way, most client uses of the template will be short and clean, but customization to their own need is still possible.</p>
<blockquote>
<p><strong>TODO</strong> Maybe something on template dummy parameters, like those used by <a href="http://dlang.org/phobos/std_traits.html#ReturnType">std.traits.ReturnType</a>. Things like <code class="sourceCode d">dummy == <span class="dt">void</span></code>.</p>
</blockquote>
<h2 id="function-templates"><a href="#TOC"><span class="header-section-number">2.4</span> Function Templates</a></h2>
<h3 id="syntax-1"><a href="#TOC"><span class="header-section-number">2.4.1</span> Syntax</a></h3>
<p>If you come from languages with generics, maybe you thought D templates were all about parameterized classes and functions and didn't see any interest in the previous sections (acting on types?). Fear not, you can also do type-generic functions and such in D, with the added generative power of templates.</p>
<p>As we have seen in <a href="#the-eponymous-trick">The Eponymous Trick</a>, if you define a function inside a template and use the template's own name, you can call it easily:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> function_declaration1;
<span class="kw">import</span> std.conv : to;
<span class="co">// declaration:</span>
<span class="kw">template</span> myFunc(T, <span class="dt">int</span> n)
{
<span class="kw">auto</span> myFunc(T t) { <span class="kw">return</span> to!<span class="dt">int</span>(t) * n;}
}
<span class="dt">void</span> main()
{
<span class="co">// call:</span>
<span class="kw">auto</span> result = myFunc!(<span class="dt">double</span>,<span class="dv">3</span>)(<span class="fl">3.1415</span>);
<span class="kw">assert</span>(result == to!<span class="dt">int</span>(<span class="fl">3.1415</span>)*<span class="dv">3</span>);
}</code></pre>
<p>Well, the full story is even better. First, D has a simple way to declare a function template: just put a template parameter list before the argument list:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> function_declaration2;
<span class="kw">import</span> std.conv:to;
<span class="dt">string</span> concatenate(A,B)(A a, B b)
{
<span class="kw">return</span> to!<span class="dt">string</span>(a) ~ to!<span class="dt">string</span>(b);
}
Arg select(<span class="dt">string</span> how = <span class="st">"max"</span>, Arg)(Arg arg0, Arg arg1)
{
<span class="kw">static</span> <span class="kw">if</span> (how == <span class="st">"max"</span>)
<span class="kw">return</span> (arg0 < arg1) ? arg1 : arg0;
<span class="kw">else</span> <span class="kw">static</span> <span class="kw">if</span> (how == <span class="st">"min"</span>)
<span class="kw">return</span> (arg0 < arg1) ? arg0 : arg1;
<span class="kw">else</span>
<span class="kw">static</span> <span class="kw">assert</span>(<span class="dv">0</span>,
<span class="st">"select: string 'how' must be either \"max\" or \"min\"."</span>);
}</code></pre>
<p>Nice and clean, uh? Notice how the return type can be templated too, using <code class="sourceCode d">Arg</code> as a return type in <code class="sourceCode d">select</code>.</p>
<h3 id="auto-return"><a href="#TOC"><span class="header-section-number">2.4.2</span> auto return</a></h3>
<p>Since you can select among code paths, the function return type can vary widely, depending on the template parameters you passed it. Use <code class="sourceCode d"><span class="kw">auto</span></code> to simplify your code:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> morph;
<span class="co">// What morph will return will heavily depend on T and U</span>
<span class="kw">auto</span> morph(<span class="kw">alias</span> f, T, U)(U arg)
{
<span class="kw">static</span> <span class="kw">if</span> (<span class="kw">is</span>(T == <span class="kw">class</span>))
<span class="kw">return</span> <span class="kw">new</span> T(f(arg));
<span class="kw">else</span> <span class="kw">static</span> <span class="kw">if</span> (<span class="kw">is</span>(T == <span class="kw">struct</span>))
<span class="kw">return</span> T(f(arg));
<span class="kw">else</span>
<span class="kw">return</span>; <span class="co">// void-returning function.</span>
}</code></pre>
<blockquote>
<p><strong>auto ref.</strong> A function template can have an <code>auto ref</code> return type. That means that for templates where the returned values are lvalues, the template will get the <code class="sourceCode d"><span class="kw">ref</span></code>ed version. And the non-<code class="sourceCode d"><span class="kw">ref</span></code> version if not. I should add some examples for that behaviour.</p>
</blockquote>
<h3 id="ifti"><a href="#TOC"><span class="header-section-number">2.4.3</span> IFTI</a></h3>
<p>Even better is Implicit Function Template Instantiation (IFTI), which means that the compiler will generally be able to automatically determine a template's parameters by studying the function arguments. If some template arguments are pure compile-time parameters, just provide them directly:</p>
<pre class="sourceCode d"><code class="sourceCode d"><span class="kw">module</span> ifti;