1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc/named-param.dox Sun Sep 21 06:13:05 2008 +0100
1.3 @@ -0,0 +1,133 @@
1.4 +/* -*- C++ -*-
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 +C++ makes it possible to use default parameter values when calling a
1.29 +function. In such a case we do not have to give value for parameters,
1.30 +the program will use the default ones. Unfortunately sometimes this
1.31 +is not enough. If we do not want to give values for all the
1.32 +parameters, only for some of them we come across problems, because an
1.33 +arbitrary set of parameters cannot be omitted. On the other hand
1.34 +parameters have a fixed order in the head of the function. C++ can
1.35 +apply the default values only in the back of the order, if we do not
1.36 +give other value for them. So we can not give the function for
1.37 +example the value of the first, and the third parameter, expecting
1.38 +that the program will aplly the default value for the second
1.39 +parameter. However sometimes we would like to use some functinos
1.40 +exactly in this way. With a crafty trick and with some little
1.41 +inconvenience this is possible. We have implemented this little trick
1.42 +as an example below.
1.43 +
1.44 +\code
1.45 +class namedFn
1.46 +{
1.47 + int _id;
1.48 + double _val;
1.49 + int _dim;
1.50 +
1.51 + public:
1.52 + namedFn() : _id(0), _val(1), _dim(2) {}
1.53 + namedFn& id(int p) { _id = p ; return *this; }
1.54 + namedFn& val(double p) { _val = p ; return *this; }
1.55 + namedFn& dim(int p) { _dim = p ; return *this; }
1.56 +
1.57 + run() {
1.58 + printf("Here is the function itself.");
1.59 + }
1.60 +};
1.61 +\endcode
1.62 +
1.63 +
1.64 +The usage is the following.
1.65 +
1.66 +We have to define a class, let's call it \c namedFn. Let us assume that
1.67 +we would like to use a parameter, called \c X. In the \c namedFn class we
1.68 +have to define an \c _X attribute, and a function \c X. The function
1.69 +expects a parameter with the type of \c _X, and sets the value of
1.70 +\c _X. After setting the value the function returns the class itself. The
1.71 +class also have to have a function, called for example <tt>run()</tt>, we have
1.72 +to implement here the original function itself. The constructor of the
1.73 +class have to give all the attributes like \c _X the default values of
1.74 +them.
1.75 +
1.76 +If we instantiate this class, the default values will be set for the
1.77 +attributes (originally the parameters), initially. If we call function
1.78 +\c X, we get a class with the modified parameter value of
1.79 +\c X. Therefore we can modify any parameter-value, independently from the
1.80 +order. To run the algorithm we have to call the <tt>run()</tt> function at the
1.81 +end of the row.
1.82 +
1.83 +Example:
1.84 +\code
1.85 +namedFn().id(3).val(2).run();
1.86 +\endcode
1.87 +
1.88 +\note Although it is a class, namedFn is used pretty much like as it were
1.89 +a function. That it why it is called namedFn and not \c NamedFn.
1.90 +
1.91 +\note In fact, the final <tt>.run()</tt> could be made unnecessary if the
1.92 +actual function code were put in the destructor instead. This however would make
1.93 +hard to implement functions with return values, and would also make the
1.94 +implementation of \ref named-templ-func-param "named template parameters"
1.95 +very problematic. <b>Therefore, by convention, <tt>.run()</tt> must be used
1.96 +to explicitly execute function having named parameters in Lemon.</b>
1.97 +
1.98 +
1.99 +\section traits-classes Traits Classes
1.100 +
1.101 +The procedure above can also be applied when defining classes. In this
1.102 +case the type of the attributes can be changed. Initially we have to
1.103 +define a class with the default attribute types. This is the so called
1.104 +Traits Class. Later on the types of these attributes can be changed,
1.105 +as described below. In our software \ref lemon::DijkstraDefaultTraits is an
1.106 +example of how a traits class looks like.
1.107 +
1.108 +\section named-templ-param Named Class Template Parameters
1.109 +
1.110 +If we would like to change the type of an attribute in a class that
1.111 +was instantiated by using a traits class as a template parameter, and
1.112 +the class contains named parameters, we do not have to reinstantiate
1.113 +the class with new traits class. Instead of that, adaptor classes can
1.114 +be used like in the following cases.
1.115 +
1.116 +\code
1.117 +Dijkstra<>::SetPredNodeMap<NullMap<Node,Node> >::Create
1.118 +\endcode
1.119 +
1.120 +It can also be used in conjunction with other named template
1.121 +parameters in arbitrary order.
1.122 +
1.123 +\code
1.124 +Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Edge> >::Create
1.125 +\endcode
1.126 +
1.127 +The result will be an instantiated Dijkstra class, in which the
1.128 +DistMap and the PredMap is modified.
1.129 +
1.130 +\section named-templ-func-param Named Function Template Parameters
1.131 +
1.132 +If the class has so called wizard functions, the new class with the
1.133 +modified tpye of attributes can be returned by the appropriate wizard
1.134 +function. The usage of these wizard functions is the following:
1.135 +
1.136 +*/