1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc/named-param.dox Tue Sep 23 18:42:49 2008 +0200
1.3 @@ -0,0 +1,119 @@
1.4 +/* -*- mode: C++; indent-tabs-mode: nil; -*-
1.5 + *
1.6 + * This file is a part of LEMON, a generic C++ optimization library.
1.7 + *
1.8 + * Copyright (C) 2003-2008
1.9 + * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
1.10 + * (Egervary Research Group on Combinatorial Optimization, EGRES).
1.11 + *
1.12 + * Permission to use, modify and distribute this software is granted
1.13 + * provided that this copyright notice appears in all copies. For
1.14 + * precise terms see the accompanying LICENSE file.
1.15 + *
1.16 + * This software is provided "AS IS" with no warranty of any kind,
1.17 + * express or implied, and with no claim as to its suitability for any
1.18 + * purpose.
1.19 + *
1.20 + */
1.21 +
1.22 +/*!
1.23 +
1.24 +\page named-param Named Parameters
1.25 +
1.26 +\section named-func-param Named Function Parameters
1.27 +
1.28 +Several modern languages provide a convenient way to refer the
1.29 +function parameters by name also when you call the function. It is
1.30 +especially comfortable in case of a function having tons of parameters
1.31 +with natural default values. Sadly, C++ lack this amenity.
1.32 +
1.33 +However, with a crafty trick and with some little
1.34 +inconvenience, it is possible to emulate is.
1.35 +The example below shows how to do it.
1.36 +
1.37 +\code
1.38 +class namedFn
1.39 +{
1.40 + int _id;
1.41 + double _val;
1.42 + int _dim;
1.43 +
1.44 + public:
1.45 + namedFn() : _id(0), _val(1), _dim(2) {}
1.46 + namedFn& id(int p) { _id = p ; return *this; }
1.47 + namedFn& val(double p) { _val = p ; return *this; }
1.48 + namedFn& dim(int p) { _dim = p ; return *this; }
1.49 +
1.50 + run() {
1.51 + std::cout << "Here comes the function itself\n" <<
1.52 + << "With parameters "
1.53 + << _id << ", " << _val << ", " << _dim << std::endl;
1.54 + }
1.55 +};
1.56 +\endcode
1.57 +
1.58 +Then you can use it like this.
1.59 +
1.60 +\code
1.61 +namedFn().id(3).val(2).run();
1.62 +\endcode
1.63 +
1.64 +The trick is obvious, each "named parameter" changes one component of
1.65 +the underlying class, then gives back a reference to it. Finally,
1.66 +<tt>run()</tt> executes the algorithm itself.
1.67 +
1.68 +\note Although it is a class, namedFn is used pretty much like as it were
1.69 +a function. That it why we called it namedFn instead of \c NamedFn.
1.70 +
1.71 +\note In fact, the final <tt>.run()</tt> could be made unnecessary,
1.72 +because the algorithm could also be implemented in the destructor of
1.73 +\c namedFn instead. This however would make it impossible to implement
1.74 +functions with return values, and would also cause serious problems when
1.75 +implementing \ref named-templ-func-param "named template parameters".
1.76 +<b>Therefore, by convention, <tt>.run()</tt> must be used
1.77 +explicitly to execute a function having named parameters
1.78 +everywhere in LEMON.</b>
1.79 +
1.80 +\section named-templ-func-param Named Function Template Parameters
1.81 +
1.82 +A named parameter can also be a template function. The usage is
1.83 +exactly the same, but the implementation behind is a kind of black
1.84 +magic and they are the dirtiest part of the LEMON code.
1.85 +
1.86 +You will probably never need to know how it works, but if you really
1.87 +committed, have a look at \ref lemon/graph_to_eps.h for an example.
1.88 +
1.89 +\section traits-classes Traits Classes
1.90 +
1.91 +A similar game can also be played when defining classes. In this case
1.92 +the type of the class attributes can be changed. Initially we have to
1.93 +define a special class called <em>Traits Class</em> defining the
1.94 +default type of the attributes. Then the types of these attributes can
1.95 +be changed in the same way as described in the next section.
1.96 +
1.97 +See \ref lemon::DijkstraDefaultTraits for an
1.98 +example how a traits class implementation looks like.
1.99 +
1.100 +\section named-templ-param Named Class Template Parameters
1.101 +
1.102 +If we would like to change the type of an attribute in a class that
1.103 +was instantiated by using a traits class as a template parameter, and
1.104 +the class contains named parameters, we do not have to instantiate again
1.105 +the class with new traits class, but instead adaptor classes can
1.106 +be used as shown in the following example.
1.107 +
1.108 +\code
1.109 +Dijkstra<>::SetPredMap<NullMap<Node,Arc> >::Create
1.110 +\endcode
1.111 +
1.112 +It can also be used in conjunction with other named template
1.113 +parameters in arbitrary order.
1.114 +
1.115 +\code
1.116 +Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Arc> >::Create
1.117 +\endcode
1.118 +
1.119 +The result will be an instantiated Dijkstra class, in which the
1.120 +DistMap and the PredMap is modified.
1.121 +
1.122 +*/