|
1 /* -*- C++ -*- |
|
2 * |
|
3 * This file is a part of LEMON, a generic C++ optimization library |
|
4 * |
|
5 * Copyright (C) 2003-2008 |
|
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 |
|
19 /*! |
|
20 |
|
21 \page named-param Named Parameters |
|
22 |
|
23 \section named-func-param Named Function Parameters |
|
24 |
|
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. |
|
40 |
|
41 \code |
|
42 class namedFn |
|
43 { |
|
44 int _id; |
|
45 double _val; |
|
46 int _dim; |
|
47 |
|
48 public: |
|
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; } |
|
53 |
|
54 run() { |
|
55 printf("Here is the function itself."); |
|
56 } |
|
57 }; |
|
58 \endcode |
|
59 |
|
60 |
|
61 The usage is the following. |
|
62 |
|
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 |
|
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 |
|
69 to implement here the original function itself. The constructor of the |
|
70 class have to give all the attributes like \c _X the default values of |
|
71 them. |
|
72 |
|
73 If we instantiate this class, the default values will be set for the |
|
74 attributes (originally the parameters), initially. If we call function |
|
75 \c X, we get a class with the modified parameter value of |
|
76 \c X. Therefore we can modify any parameter-value, independently from the |
|
77 order. To run the algorithm we have to call the <tt>run()</tt> function at the |
|
78 end of the row. |
|
79 |
|
80 Example: |
|
81 \code |
|
82 namedFn().id(3).val(2).run(); |
|
83 \endcode |
|
84 |
|
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" |
|
92 very problematic. <b>Therefore, by convention, <tt>.run()</tt> must be used |
|
93 to explicitly execute function having named parameters in Lemon.</b> |
|
94 |
|
95 |
|
96 \section traits-classes Traits Classes |
|
97 |
|
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. |
|
104 |
|
105 \section named-templ-param Named Class Template Parameters |
|
106 |
|
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. |
|
112 |
|
113 \code |
|
114 Dijkstra<>::SetPredNodeMap<NullMap<Node,Node> >::Create |
|
115 \endcode |
|
116 |
|
117 It can also be used in conjunction with other named template |
|
118 parameters in arbitrary order. |
|
119 |
|
120 \code |
|
121 Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Edge> >::Create |
|
122 \endcode |
|
123 |
|
124 The result will be an instantiated Dijkstra class, in which the |
|
125 DistMap and the PredMap is modified. |
|
126 |
|
127 \section named-templ-func-param Named Function Template Parameters |
|
128 |
|
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: |
|
132 |
|
133 */ |