www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - A tutorial on D templates

reply Philippe Sigaud <philippe.sigaud gmail.com> writes:
[Cross-posted with D.announce, since it's also an annoucement]

Hello all,

I discovered D a few years ago and, seeing the recent increase in community
projects, I
looked for a way to bring my own small part to it.

I quite like D templates and wanted to try LaTeX again, so I decided to bite
the bullet
and wrote a tutorial on templates. It's far from finished and most probably
full of
mistakes but since it's already quite big, I need some inputs.

It's a Github project, here:

https://github.com/PhilippeSigaud/D-templates-tutorial

The resulting pdf is there:

https://github.com/PhilippeSigaud/D-templates-tutorial/blob/master/dtemplates.pdf

(click on View Raw)

If you have any comment, criticism, explanation, what have you, I'm game. What
section
should be expanded, what example would be cool, etc. If you see a mistake, do
not
hesitate to tell me: it's the first time I put thoughts on paper like this.
Github
issues management is far from perfect, but it's usable. Even better would be
pull
requests :)

There is an 'Examples' section where I show what can be done with templates and
there I
'borrowed' some code posted here, with attribution. I already exchanged with
Andrej
Mitrovic (thanks!), but also took some code from Timon Gehr, Simen Kjaeraas,
Trass3r
and Jacob Carlborg. Guys, if any of you have a problem with that, tell me so
and I'll
take down the code of course. But if any of you could give me some explanation
(a small
paragraph or two?) about what your code does, I'll be forever grateful :)

This also extend to anyone who would want to share some template love/lore with
the
rest of us.

Philippe
Jan 13 2012
next sibling parent reply "DNewbie" <run3 myopera.com> writes:
I can't understand it. Why would someone need template programming. What
problem does template solve?
-- 
  
  D
Jan 13 2012
next sibling parent reply Peter Alexander <peter.alexander.au gmail.com> writes:
On 13/01/12 10:48 PM, DNewbie wrote:

 I can't understand it. Why would someone need template programming. What
problem does template solve?


Suppose you want to write a function to get the minimum of two integers. 
It's easy:

int min(int a, int b)
{
     return a < b ? a : b;
}

Suppose then you want to use it with floats. You now need to write 
another function.

float min(float a, float b)
{
     return a < b ? a : b;
}

Suppose you then want to use it with doubles, reals, complex numbers, 
strings etc. etc.  You would quickly get tired of writing these 
functions, and more importantly you would likely make mistakes at some 
point.

Templates allow you to solve this problem by writing the function once 
with placeholders for types:

T min(T)(T a, T b)
{
     return a < b ? a : b;
}

This will work for ints, floats, doubles... Anything that has a < 
operator will work.

There's much more you can do with templates, but that's the fundamental 
problem that they solve.
Jan 13 2012
parent Philippe Sigaud <philippe.sigaud gmail.com> writes:
 On 13/01/12 10:48 PM, DNewbie wrote:

 I can't understand it. Why would someone need template programming. What
problem does template solve?






Well read on and see :-)

Peter:

 Suppose you want to write a function to get the minimum of two integers.
 It's easy:


 Oh.. I see.
 Thank you everybody.


And that's the first, more visible part of templates, a bit like
generics in Java.
Template are incomplete pieces of code with left-empty 'slots' which
you can fill at compile-time to decide what code will be compiled.
You can generate entire functions / class hierarchies or nicely
crafted-for-your-need code / pre-computed-by-the-compiler code with
templates.

Philippe
Jan 14 2012
prev sibling parent reply =?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
On 01/13/2012 02:48 PM, DNewbie wrote:

 I can't understand it. Why would someone need template programming. What
problem does template solve?


Here is another resource that tries to answer that question:

   http://ddili.org/ders/d.en/templates.html

"Parts of the source code may be left to the compiler to be filled in 
until that part is actually used in the program."

Ali
Jan 13 2012
parent reply Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sat, Jan 14, 2012 at 01:08, Ali =C3=87ehreli <acehreli yahoo.com> wrote:


 Here is another resource that tries to answer that question:

 =C2=A0http://ddili.org/ders/d.en/templates.html

 "Parts of the source code may be left to the compiler to be filled in unt=


il

 that part is actually used in the program."


Hi Ali, I discovered you had a chapter on templates just a few days
ago. I'll go and read it. I think I'll add a ressources/further
reading part in my doc and put a link to your chapter.

Philippe
Jan 14 2012
parent reply =?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
On 01/14/2012 12:11 AM, Philippe Sigaud wrote:

 On Sat, Jan 14, 2012 at 01:08, Ali Çehreli<acehreli yahoo.com>  wrote:



   http://ddili.org/ders/d.en/templates.html





 Hi Ali, I discovered you had a chapter on templates just a few days
 ago.


That chapter is intentionally incomplete. I think function, struct, and 
class templates and their uses with type template parameters are the 
most common. (That's a C++ programmer talking. ;)) I've left the rest of 
templates to a later chapter.


 I'll go and read it.


Thank you. Please ignore the Inglish ;) mistakes for now. It is 
constantly being corrected by my editor (Ergin Güney) and I.


 I think I'll add a ressources/further
 reading part in my doc and put a link to your chapter.


Thank you. I will do the same. It will be easier if it gets a permanent 
home, in addition to its github page ( 
https://github.com/PhilippeSigaud/D-templates-tutorial ).


 Philippe


Ali
Jan 14 2012
parent reply Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sat, Jan 14, 2012 at 15:56, Ali =C3=87ehreli <acehreli yahoo.com> wrote:

 On 01/14/2012 12:11 AM, Philippe Sigaud wrote:

 On Sat, Jan 14, 2012 at 01:08, Ali =C3=87ehreli<acehreli yahoo.com> =C2=




=A0wrote:

 =C2=A0 http://ddili.org/ders/d.en/templates.html






 Hi Ali, I discovered you had a chapter on templates just a few days
 ago.


 That chapter is intentionally incomplete. I think function, struct, and
 class templates and their uses with type template parameters are the most
 common. (That's a C++ programmer talking. ;)) I've left the rest of
 templates to a later chapter.


I agree. Your goal is not exactly the same as mine: you intend to give
a view on the entire language, for beginners, whereas I intend my doc
to be a deep plunge into templates, as complete as possible.


 I'll go and read it.


 Thank you. Please ignore the Inglish ;) mistakes for now. It is constantl=


y

 being corrected by my editor (Ergin G=C3=BCney) and I.


What I see is quite readable :-)



 I think I'll add a ressources/further
 reading part in my doc and put a link to your chapter.


 Thank you. I will do the same.


That's cool, because the D community is small enough and still
dispersed enough that we should link one another to bring it all
together.


 It will be easier if it gets a permanent
 home, in addition to its github page (
 https://github.com/PhilippeSigaud/D-templates-tutorial ).


I have no permanent home for my D projects, nor do I intend to do. You
can link to the Github project, that's what people do. Or directly to
the pdf, if you wish.
Jan 14 2012
parent reply =?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
On 01/14/2012 07:49 AM, Philippe Sigaud wrote:


 That's cool, because the D community is small enough and still
 dispersed enough that we should link one another to bring it all
 together.


Thank you very much for your link! :)

And I've finally found time to create two links to your 'D Templates: A 
Tutorial' from the following page

   http://ddili.org/ders/d.en/templates.html

Ali

P.S. Going off-topic, the following chapters of 'Programming in D' have 
been translated since the last announcement:

* Redirecting Standard Input and Output Streams
* Files
* auto and typeof
* Name Space
* The for Loop
* The Ternary Operator ?:
* Literals
* Formatted Output

Now the book can also be downloaded as pdf from the [Download as PDF] 
link on chapter headers:

   http://ddili.org/ders/d.en/index.html
Jan 31 2012
parent Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Tue, Jan 31, 2012 at 09:12, Ali =C3=87ehreli <acehreli yahoo.com> wrote:

 On 01/14/2012 07:49 AM, Philippe Sigaud wrote:


 That's cool, because the D community is small enough and still
 dispersed enough that we should link one another to bring it all
 together.


 Thank you very much for your link! :)


That's quite normal.


 And I've finally found time to create two links to your 'D Templates: A
 Tutorial' from the following page

 =C2=A0http://ddili.org/ders/d.en/templates.html


And thank you too!


 Ali

 P.S. Going off-topic, the following chapters of 'Programming in D' have b=


een

 translated since the last announcement:

 * Redirecting Standard Input and Output Streams
 * Files
 * auto and typeof
 * Name Space
 * The for Loop
 * The Ternary Operator ?:
 * Literals
 * Formatted Output

 Now the book can also be downloaded as pdf from the [Download as PDF] lin=


k

 on chapter headers:

 =C2=A0http://ddili.org/ders/d.en/index.html


I think you should make an independent announce on D.announce and
D.learn. And maybe then monthly (or every three month, say) updates on
the state of your book.
Jan 31 2012
prev sibling next sibling parent "DNewbie" <run3 myopera.com> writes:
On Fri, Jan 13, 2012, at 11:28 PM, Peter Alexander wrote:

 On 13/01/12 10:48 PM, DNewbie wrote:

 I can't understand it. Why would someone need template programming. What
problem does template solve?


 
 Suppose you want to write a function to get the minimum of two integers. 
 It's easy:


Oh.. I see.
Thank you everybody.
Jan 13 2012
prev sibling next sibling parent "DNewbie" <run3 myopera.com> writes:
On Sat, Jan 14, 2012, at 09:07 AM, Philippe Sigaud wrote:

 On 13/01/12 10:48 PM, DNewbie wrote:

 I can't understand it. Why would someone need template programming. What
problem does template solve?






 
 Well read on and see :-)
 
 Peter:

 Suppose you want to write a function to get the minimum of two integers.
 It's easy:


 Oh.. I see.
 Thank you everybody.


 
 And that's the first, more visible part of templates, a bit like
 generics in Java.
 Template are incomplete pieces of code with left-empty 'slots' which
 you can fill at compile-time to decide what code will be compiled.
 You can generate entire functions / class hierarchies or nicely
 crafted-for-your-need code / pre-computed-by-the-compiler code with
 templates.
 
 Philippe
 


OK... I won't play with templates for now, but please keep up the good work.
Jan 14 2012
prev sibling next sibling parent "Joel" <joelcnz gmail.com> writes:
Good work Philippe, looks good!
Jan 14 2012
prev sibling parent reply =?utf-8?Q?Simen_Kj=C3=A6r=C3=A5s?= <simen.kjaras gmail.com> writes:
On Fri, 13 Jan 2012 22:21:52 +0100, Philippe Sigaud  
<philippe.sigaud gmail.com> wrote:


 There is an 'Examples' section where I show what can be done with  
 templates and there I
 'borrowed' some code posted here, with attribution. I already exchanged  
 with Andrej
 Mitrovic (thanks!), but also took some code from Timon Gehr, Simen  
 Kjaeraas, Trass3r
 and Jacob Carlborg. Guys, if any of you have a problem with that, tell  
 me so and I'll
 take down the code of course. But if any of you could give me some  
 explanation (a small
 paragraph or two?) about what your code does, I'll be forever grateful :)



The extended enum example does not compile, because you've removed the
unittest{} block around the the tests. I'd say the code in your document
should compile straight out of the box, to be newb-friendly.

As for an explanation:



string EnumDefAsString(T)() if (is(T == enum)) {
     string result = "";
     foreach (e; __traits(allMembers, T))
         result ~= e ~ " = T." ~ e ~ ",";
     return result;
}

This piece of code iterates over all members of the passed enum T,
generating a string containing all members and their values. For
this enum:

   enum bar {
       a, b, c
   }

the generated string looks like this (if you want to check this,
feel free to call EnumDefAsString at run-time and print its result):

   "a = bar.a,b = bar.b,c = bar.c"

As we can see, this is a valid body for an enum. That means we can use
mixin() to generate this exact same enum. But wait - there's more:


template ExtendEnum(T, string s)
     if (is(T == enum) &&
     is(typeof({mixin("enum a{"~s~"}");})))
{
     mixin(
     "enum ExtendEnum {"
     ~ EnumDefAsString!T()
     ~ s
     ~ "}");
}

This code concatenates the string generated from the previous function
with that passed to the function as parameter s. So with bar previously
defined, and this instantiation:

     ExtendEnum!(bar, "d=25")

the body of the function will look like this (after string expansion):



     mixin(
     "enum ExtendEnum {"
     ~ "a = bar.a,b = bar.b,c = bar.c"
     ~ "d=25"
     ~ "}");

concatenating those strings, we see that we have a valid enum definition:

     enum ExtendEnum {a = bar.a,b = bar.b,c = bar.c,d=25}

The mixin then pastes it in, and it is compiled as regular D code.


TLDR:

This code generates an enum definition as a string, by taking all the
members of the old enum, and adding those passed in string parameter s,
and mixing it in.
Jan 16 2012
parent reply Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Mon, Jan 16, 2012 at 17:36, Simen Kj=C3=A6r=C3=A5s <simen.kjaras gmail.c=
om> wrote:

 The extended enum example does not compile, because you've removed the
 unittest{} block around the the tests. I'd say the code in your document
 should compile straight out of the box, to be newb-friendly.


Yeah. I just coded a small D script that extract all code samples,
compile them and store the result in a log.
That way, I can now slowly make all samples compile.

I hesitate between showing the boilerplate or not (imports, empty
mains or code in main...)



 As for an explanation:



 This code generates an enum definition as a string, by taking all the
 members of the old enum, and adding those passed in string parameter s,
 and mixing it in.


Thanks! I'll add it.
Jan 16 2012
parent =?utf-8?Q?Simen_Kj=C3=A6r=C3=A5s?= <simen.kjaras gmail.com> writes:
On Tue, 17 Jan 2012 00:10:41 +0100, Philippe Sigaud  =

<philippe.sigaud gmail.com> wrote:


 On Mon, Jan 16, 2012 at 17:36, Simen Kj=C3=A6r=C3=A5s <simen.kjaras gm=


ail.com>  =


 wrote:

 The extended enum example does not compile, because you've removed th=




e

 unittest{} block around the the tests. I'd say the code in your docum=




ent

 should compile straight out of the box, to be newb-friendly.


 Yeah. I just coded a small D script that extract all code samples,
 compile them and store the result in a log.
 That way, I can now slowly make all samples compile.

 I hesitate between showing the boilerplate or not (imports, empty
 mains or code in main...)


I would say it should be there. If possible, perhaps have those pieces a=
ll
gray, to mark them as unimportant?
Jan 17 2012