COIN-OR::LEMON - Graph Library

source: lemon-0.x/doc/named-param.dox @ 1928:2e957d67d7b9

Last change on this file since 1928:2e957d67d7b9 was 1713:49d22d34d95f, checked in by Alpar Juttner, 14 years ago

Doc improvments

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