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 | */ |
---|