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