COIN-OR::LEMON - Graph Library

source: lemon/doc/named-param.dox @ 461:1229dc2f1d36

Last change on this file since 461:1229dc2f1d36 was 269:f5965bbf1353, checked in by Peter Kovacs <kpeter@…>, 16 years ago

Improvements in named-param.dox (ticket #147)

File size: 4.0 KB
Line 
1/* -*- mode: C++; indent-tabs-mode: nil; -*-
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
25Several modern languages provide a convenient way to refer the
26function parameters by name also when you call the function. It is
27especially comfortable in case of a function having tons of parameters
28with natural default values. Sadly, C++ lack this amenity.
29
30However, with a crafty trick and with some little
31inconvenience, it is possible to emulate is.
32The example below shows how to do it.
33
34\code
35class namedFn
36{
37  int _id;
38  double _val;
39  int _dim;
40
41  public:
42  namedFn() : _id(0), _val(1), _dim(2) {}
43  namedFn& id(int p)     { _id  = p ; return *this; }
44  namedFn& val(double p) { _val = p ; return *this; }
45  namedFn& dim(int p)    { _dim = p ; return *this; }
46
47  run() {
48    std::cout << "Here comes the function itself\n" <<
49              << "With parameters "
50              << _id << ", " << _val << ", " << _dim << std::endl;
51  }
52};
53\endcode
54
55Then you can use it like this.
56
57\code
58namedFn().id(3).val(2).run();
59\endcode
60
61The trick is obvious, each "named parameter" changes one component of
62the underlying class, then gives back a reference to it. Finally,
63<tt>run()</tt> executes the algorithm itself.
64
65\note Although it is a class, namedFn is used pretty much like as it were
66a function. That it why we called it namedFn instead of \c NamedFn.
67
68\note In fact, the final <tt>.run()</tt> could be made unnecessary,
69because the algorithm could also be implemented in the destructor of
70\c namedFn instead. This however would make it impossible to implement
71functions with return values, and would also cause serious problems when
72implementing \ref named-templ-func-param "named template parameters".
73<b>Therefore, by convention, <tt>.run()</tt> must be used
74explicitly to execute a function having named parameters
75everywhere in LEMON.</b>
76
77\section named-templ-func-param Named Function Template Parameters
78
79A named parameter can also be a template function. The usage is
80exactly the same, but the implementation behind is a kind of black
81magic and they are the dirtiest part of the LEMON code.
82
83You will probably never need to know how it works, but if you really
84committed, have a look at \ref lemon/graph_to_eps.h for an example.
85
86\section traits-classes Traits Classes
87
88A similar game can also be played when defining classes. In this case
89the type of the class attributes can be changed. Initially we have to
90define a special class called <em>Traits Class</em> defining the
91default type of the attributes. Then the types of these attributes can
92be changed in the same way as described in the next section.
93
94See \ref lemon::DijkstraDefaultTraits for an
95example how a traits class implementation looks like.
96
97\section named-templ-param Named Class Template Parameters
98
99If we would like to change the type of an attribute in a class that
100was instantiated by using a traits class as a template parameter, and
101the class contains named parameters, we do not have to instantiate again
102the class with new traits class, but instead adaptor classes can
103be used as shown in the following example.
104
105\code
106Dijkstra<>::SetPredMap<NullMap<Node,Arc> >::Create
107\endcode
108
109It can also be used in conjunction with other named template
110parameters in arbitrary order.
111
112\code
113Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Arc> >::Create
114\endcode
115
116The result will be an instantiated Dijkstra class, in which the
117DistMap and the PredMap is modified.
118
119*/
Note: See TracBrowser for help on using the repository browser.