1.1 --- a/doc/named-param.dox Sun Sep 21 06:13:05 2008 +0100
1.2 +++ b/doc/named-param.dox Sun Sep 21 07:49:57 2008 +0100
1.3 @@ -22,21 +22,14 @@
1.4
1.5 \section named-func-param Named Function Parameters
1.6
1.7 -C++ makes it possible to use default parameter values when calling a
1.8 -function. In such a case we do not have to give value for parameters,
1.9 -the program will use the default ones. Unfortunately sometimes this
1.10 -is not enough. If we do not want to give values for all the
1.11 -parameters, only for some of them we come across problems, because an
1.12 -arbitrary set of parameters cannot be omitted. On the other hand
1.13 -parameters have a fixed order in the head of the function. C++ can
1.14 -apply the default values only in the back of the order, if we do not
1.15 -give other value for them. So we can not give the function for
1.16 -example the value of the first, and the third parameter, expecting
1.17 -that the program will aplly the default value for the second
1.18 -parameter. However sometimes we would like to use some functinos
1.19 -exactly in this way. With a crafty trick and with some little
1.20 -inconvenience this is possible. We have implemented this little trick
1.21 -as an example below.
1.22 +Several modern languages provide a convenient way to refer the
1.23 +function parameters by name also when you call the function. It is
1.24 +especially comfortable in case of a function having tons of parameters
1.25 +with natural default values. Sadly, C++ lack this amenity.
1.26 +
1.27 +However, with a crafty trick and with some little
1.28 +inconvenience, it is possible to emulate is.
1.29 +The example below shows how to do it.
1.30
1.31 \code
1.32 class namedFn
1.33 @@ -52,63 +45,62 @@
1.34 namedFn& dim(int p) { _dim = p ; return *this; }
1.35
1.36 run() {
1.37 - printf("Here is the function itself.");
1.38 + std::cout << "Here comes the function itself\n" <<
1.39 + << "With parameters "
1.40 + << _id << ", " << _val << ", " << _dim << std::endl;
1.41 }
1.42 };
1.43 \endcode
1.44
1.45 +Then you can use it like this.
1.46
1.47 -The usage is the following.
1.48 -
1.49 -We have to define a class, let's call it \c namedFn. Let us assume that
1.50 -we would like to use a parameter, called \c X. In the \c namedFn class we
1.51 -have to define an \c _X attribute, and a function \c X. The function
1.52 -expects a parameter with the type of \c _X, and sets the value of
1.53 -\c _X. After setting the value the function returns the class itself. The
1.54 -class also have to have a function, called for example <tt>run()</tt>, we have
1.55 -to implement here the original function itself. The constructor of the
1.56 -class have to give all the attributes like \c _X the default values of
1.57 -them.
1.58 -
1.59 -If we instantiate this class, the default values will be set for the
1.60 -attributes (originally the parameters), initially. If we call function
1.61 -\c X, we get a class with the modified parameter value of
1.62 -\c X. Therefore we can modify any parameter-value, independently from the
1.63 -order. To run the algorithm we have to call the <tt>run()</tt> function at the
1.64 -end of the row.
1.65 -
1.66 -Example:
1.67 \code
1.68 namedFn().id(3).val(2).run();
1.69 \endcode
1.70
1.71 +The trick is obvious, each "named parameter" changes one component of
1.72 +the underlying class, then gives back a reference to it. Finally,
1.73 +<tt>run()</tt> executes the algorithm itself.
1.74 +
1.75 \note Although it is a class, namedFn is used pretty much like as it were
1.76 -a function. That it why it is called namedFn and not \c NamedFn.
1.77 +a function. That it why we called it namedFn instead of \c NamedFn.
1.78
1.79 -\note In fact, the final <tt>.run()</tt> could be made unnecessary if the
1.80 -actual function code were put in the destructor instead. This however would make
1.81 -hard to implement functions with return values, and would also make the
1.82 -implementation of \ref named-templ-func-param "named template parameters"
1.83 -very problematic. <b>Therefore, by convention, <tt>.run()</tt> must be used
1.84 -to explicitly execute function having named parameters in Lemon.</b>
1.85 +\note In fact, the final <tt>.run()</tt> could be made unnecessary,
1.86 +because the algorithm could also be implemented in the destructor of
1.87 +\c namedFn instead. This however would make it impossible to implement
1.88 +functions with return values, and would also cause serious problems when
1.89 +implementing \ref named-templ-func-param "named template parameters".
1.90 +<b>Therefore, by convention, <tt>.run()</tt> must be used
1.91 +explicitly to execute a function having named parameters
1.92 +everywhere in LEMON.</b>
1.93
1.94 +\section named-templ-func-param Named Function Template Parameters
1.95 +
1.96 +A named parameter can also be a template functions. The usage is
1.97 +exactly the same, but the implementation behind is a kind of black
1.98 +magic and they are the dirtiest part of the LEMON code.
1.99 +
1.100 +You will probably never need to know how it works, but if you really
1.101 +committed, have a look at \ref lemon/graph_to_eps.h for an example.
1.102
1.103 \section traits-classes Traits Classes
1.104
1.105 -The procedure above can also be applied when defining classes. In this
1.106 -case the type of the attributes can be changed. Initially we have to
1.107 -define a class with the default attribute types. This is the so called
1.108 -Traits Class. Later on the types of these attributes can be changed,
1.109 -as described below. In our software \ref lemon::DijkstraDefaultTraits is an
1.110 -example of how a traits class looks like.
1.111 +A similar game can also be played when defining classes. In this case
1.112 +the type of the class attributes can be changed. Initially we have to
1.113 +define a special class called <em>Traits Class</em> defining the
1.114 +default type of the attributes. Then the types of these attributes can
1.115 +be changed in the same way as described in the next section.
1.116 +
1.117 +See \ref lemon::DijkstraDefaultTraits for an
1.118 +example how a traits class implementation looks like.
1.119
1.120 \section named-templ-param Named Class Template Parameters
1.121
1.122 If we would like to change the type of an attribute in a class that
1.123 was instantiated by using a traits class as a template parameter, and
1.124 -the class contains named parameters, we do not have to reinstantiate
1.125 -the class with new traits class. Instead of that, adaptor classes can
1.126 -be used like in the following cases.
1.127 +the class contains named parameters, we do not have to instantiate again
1.128 +the class with new traits class, but instead adaptor classes can
1.129 +be used as shown in the following example.
1.130
1.131 \code
1.132 Dijkstra<>::SetPredNodeMap<NullMap<Node,Node> >::Create
1.133 @@ -124,10 +116,4 @@
1.134 The result will be an instantiated Dijkstra class, in which the
1.135 DistMap and the PredMap is modified.
1.136
1.137 -\section named-templ-func-param Named Function Template Parameters
1.138 -
1.139 -If the class has so called wizard functions, the new class with the
1.140 -modified tpye of attributes can be returned by the appropriate wizard
1.141 -function. The usage of these wizard functions is the following:
1.142 -
1.143 */