doc/named-param.dox
 author Alpar Juttner Sun, 21 Sep 2008 06:13:05 +0100 changeset 267 1eb606fe5591 child 268 986d30f5c1c0 permissions -rw-r--r--
Port named-param.dox from svn -r3504
 alpar@267  1 /* -*- C++ -*-  alpar@267  2  *  alpar@267  3  * This file is a part of LEMON, a generic C++ optimization library  alpar@267  4  *  alpar@267  5  * Copyright (C) 2003-2008  alpar@267  6  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport  alpar@267  7  * (Egervary Research Group on Combinatorial Optimization, EGRES).  alpar@267  8  *  alpar@267  9  * Permission to use, modify and distribute this software is granted  alpar@267  10  * provided that this copyright notice appears in all copies. For  alpar@267  11  * precise terms see the accompanying LICENSE file.  alpar@267  12  *  alpar@267  13  * This software is provided "AS IS" with no warranty of any kind,  alpar@267  14  * express or implied, and with no claim as to its suitability for any  alpar@267  15  * purpose.  alpar@267  16  *  alpar@267  17  */  alpar@267  18 alpar@267  19 /*!  alpar@267  20 alpar@267  21 \page named-param Named Parameters  alpar@267  22 alpar@267  23 \section named-func-param Named Function Parameters  alpar@267  24 alpar@267  25 C++ makes it possible to use default parameter values when calling a  alpar@267  26 function. In such a case we do not have to give value for parameters,  alpar@267  27 the program will use the default ones. Unfortunately sometimes this  alpar@267  28 is not enough. If we do not want to give values for all the  alpar@267  29 parameters, only for some of them we come across problems, because an  alpar@267  30 arbitrary set of parameters cannot be omitted. On the other hand  alpar@267  31 parameters have a fixed order in the head of the function. C++ can  alpar@267  32 apply the default values only in the back of the order, if we do not  alpar@267  33 give other value for them. So we can not give the function for  alpar@267  34 example the value of the first, and the third parameter, expecting  alpar@267  35 that the program will aplly the default value for the second  alpar@267  36 parameter. However sometimes we would like to use some functinos  alpar@267  37 exactly in this way. With a crafty trick and with some little  alpar@267  38 inconvenience this is possible. We have implemented this little trick  alpar@267  39 as an example below.  alpar@267  40 alpar@267  41 \code  alpar@267  42 class namedFn  alpar@267  43 {  alpar@267  44  int _id;  alpar@267  45  double _val;  alpar@267  46  int _dim;  alpar@267  47   alpar@267  48  public:  alpar@267  49  namedFn() : _id(0), _val(1), _dim(2) {}  alpar@267  50  namedFn& id(int p) { _id = p ; return *this; }  alpar@267  51  namedFn& val(double p) { _val = p ; return *this; }  alpar@267  52  namedFn& dim(int p) { _dim = p ; return *this; }  alpar@267  53 alpar@267  54  run() {  alpar@267  55  printf("Here is the function itself.");  alpar@267  56  }  alpar@267  57 };  alpar@267  58 \endcode  alpar@267  59 alpar@267  60 alpar@267  61 The usage is the following.  alpar@267  62 alpar@267  63 We have to define a class, let's call it \c namedFn. Let us assume that  alpar@267  64 we would like to use a parameter, called \c X. In the \c namedFn class we  alpar@267  65 have to define an \c _X attribute, and a function \c X. The function  alpar@267  66 expects a parameter with the type of \c _X, and sets the value of  alpar@267  67 \c _X. After setting the value the function returns the class itself. The  alpar@267  68 class also have to have a function, called for example run(), we have  alpar@267  69 to implement here the original function itself. The constructor of the  alpar@267  70 class have to give all the attributes like \c _X the default values of  alpar@267  71 them.  alpar@267  72 alpar@267  73 If we instantiate this class, the default values will be set for the  alpar@267  74 attributes (originally the parameters), initially. If we call function  alpar@267  75 \c X, we get a class with the modified parameter value of  alpar@267  76 \c X. Therefore we can modify any parameter-value, independently from the  alpar@267  77 order. To run the algorithm we have to call the run() function at the  alpar@267  78 end of the row.  alpar@267  79 alpar@267  80 Example:  alpar@267  81 \code  alpar@267  82 namedFn().id(3).val(2).run();  alpar@267  83 \endcode  alpar@267  84 alpar@267  85 \note Although it is a class, namedFn is used pretty much like as it were  alpar@267  86 a function. That it why it is called namedFn and not \c NamedFn.  alpar@267  87 alpar@267  88 \note In fact, the final .run() could be made unnecessary if the  alpar@267  89 actual function code were put in the destructor instead. This however would make  alpar@267  90 hard to implement functions with return values, and would also make the  alpar@267  91 implementation of \ref named-templ-func-param "named template parameters"  alpar@267  92 very problematic. Therefore, by convention, .run() must be used  alpar@267  93 to explicitly execute function having named parameters in Lemon.  alpar@267  94 alpar@267  95 alpar@267  96 \section traits-classes Traits Classes  alpar@267  97 alpar@267  98 The procedure above can also be applied when defining classes. In this  alpar@267  99 case the type of the attributes can be changed. Initially we have to  alpar@267  100 define a class with the default attribute types. This is the so called  alpar@267  101 Traits Class. Later on the types of these attributes can be changed,  alpar@267  102 as described below. In our software \ref lemon::DijkstraDefaultTraits is an  alpar@267  103 example of how a traits class looks like.  alpar@267  104 alpar@267  105 \section named-templ-param Named Class Template Parameters  alpar@267  106 alpar@267  107 If we would like to change the type of an attribute in a class that  alpar@267  108 was instantiated by using a traits class as a template parameter, and  alpar@267  109 the class contains named parameters, we do not have to reinstantiate  alpar@267  110 the class with new traits class. Instead of that, adaptor classes can  alpar@267  111 be used like in the following cases.  alpar@267  112 alpar@267  113 \code  alpar@267  114 Dijkstra<>::SetPredNodeMap >::Create  alpar@267  115 \endcode  alpar@267  116 alpar@267  117 It can also be used in conjunction with other named template  alpar@267  118 parameters in arbitrary order.  alpar@267  119 alpar@267  120 \code  alpar@267  121 Dijkstra<>::SetDistMap::SetPredMap >::Create  alpar@267  122 \endcode  alpar@267  123 alpar@267  124 The result will be an instantiated Dijkstra class, in which the  alpar@267  125 DistMap and the PredMap is modified.  alpar@267  126 alpar@267  127 \section named-templ-func-param Named Function Template Parameters  alpar@267  128 alpar@267  129 If the class has so called wizard functions, the new class with the  alpar@267  130 modified tpye of attributes can be returned by the appropriate wizard  alpar@267  131 function. The usage of these wizard functions is the following:  alpar@267  132 alpar@267  133 */