alpar@2391: /* -*- C++ -*-
alpar@2391:  *
alpar@2391:  * This file is a part of LEMON, a generic C++ optimization library
alpar@2391:  *
alpar@2553:  * Copyright (C) 2003-2008
alpar@2391:  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
alpar@2391:  * (Egervary Research Group on Combinatorial Optimization, EGRES).
alpar@2391:  *
alpar@2391:  * Permission to use, modify and distribute this software is granted
alpar@2391:  * provided that this copyright notice appears in all copies. For
alpar@2391:  * precise terms see the accompanying LICENSE file.
alpar@2391:  *
alpar@2391:  * This software is provided "AS IS" with no warranty of any kind,
alpar@2391:  * express or implied, and with no claim as to its suitability for any
alpar@2391:  * purpose.
alpar@2391:  *
alpar@2391:  */
alpar@2391: 
alpar@1624: /*!
alpar@954: 
alpar@953: \page named-param Named Parameters
alpar@953: 
alpar@1624: \section named-func-param Named Function Parameters
alpar@955: 
alpar@1536: C++ makes it possible to use default parameter values when calling a
alpar@1536: function. In such a case we do not have to give value for parameters,
alpar@1536: the program will use the default ones.  Unfortunately sometimes this
alpar@1536: is not enough. If we do not want to give values for all the
alpar@1536: parameters, only for some of them we come across problems, because an
alpar@1536: arbitrary set of parameters cannot be omitted. On the other hand
alpar@1536: parameters have a fixed order in the head of the function.  C++ can
alpar@1536: apply the default values only in the back of the order, if we do not
alpar@1536: give other value for them.  So we can not give the function for
alpar@1536: example the value of the first, and the third parameter, expecting
alpar@1536: that the program will aplly the default value for the second
alpar@1536: parameter.  However sometimes we would like to use some functinos
alpar@1536: exactly in this way. With a crafty trick and with some little
alpar@1536: inconvenience this is possible. We have implemented this little trick
alpar@1536: as an example below.
hegyi@1141: 
hegyi@1141: \code
alpar@1713: class namedFn 
hegyi@1141: {
hegyi@1141:   int _id;
hegyi@1141:   double _val;
hegyi@1141:   int _dim;
hegyi@1141:   
hegyi@1141:   public:
alpar@1713:   namedFn() : _id(0), _val(1), _dim(2) {}
alpar@1713:   namedFn& id(int p)     { _id  = p ; return *this; }
alpar@1713:   namedFn& val(double p) { _val = p ; return *this; }
alpar@1713:   namedFn& dim(int p)    { _dim = p ; return *this; }
hegyi@1141: 
hegyi@1141:   run() {
hegyi@1141:     printf("Here is the function itself.");
hegyi@1141:   }
hegyi@1141: };
hegyi@1141: \endcode
hegyi@1141: 
hegyi@1141: 
hegyi@1141: The usage is the following.
hegyi@1141: 
alpar@1713: We have to define a class, let's call it \c namedFn.  Let us assume that
alpar@1713: we would like to use a parameter, called \c X. In the \c namedFn class we
alpar@1624: have to define an \c _X attribute, and a function \c X. The function
alpar@1624: expects a parameter with the type of \c _X, and sets the value of
alpar@1624: \c _X. After setting the value the function returns the class itself. The
alpar@1624: class also have to have a function, called for example <tt>run()</tt>, we have
alpar@1536: to implement here the original function itself. The constructor of the
alpar@1624: class have to give all the attributes like \c _X the default values of
alpar@1536: them.
hegyi@1141: 
alpar@1536: If we instantiate this class, the default values will be set for the
hegyi@1619: attributes (originally the parameters), initially. If we call function
alpar@1624: \c X, we get a class with the modified parameter value of
alpar@1713: \c X. Therefore we can modify any parameter-value, independently from the
alpar@1624: order. To run the algorithm we have to call the <tt>run()</tt> function at the
alpar@1536: end of the row.
hegyi@1141: 
alpar@1624: Example:
alpar@1624: \code
alpar@1713: namedFn().id(3).val(2).run();
alpar@1624: \endcode
alpar@955: 
alpar@1713: \note Although it is a class, namedFn is used pretty much like as it were
alpar@1713: a function. That it why it is called namedFn and not \c NamedFn.
alpar@1713: 
alpar@1713: \note In fact, the final <tt>.run()</tt> could be made unnecessary if the
alpar@1713: actual function code were put in the destructor instead. This however would make
alpar@1713: hard to implement functions with return values, and would also make the
alpar@1713: implementation of \ref named-templ-func-param "named template parameters"
alpar@1929: very problematic. <b>Therefore, by convention, <tt>.run()</tt> must be used
alpar@1929: to explicitly execute function having named parameters in Lemon.</b>
alpar@1713: 
alpar@1713: 
alpar@955: \section traits-classes Traits Classes
alpar@955: 
alpar@1536: The procedure above can also be applied when defining classes. In this
alpar@1536: case the type of the attributes can be changed.  Initially we have to
alpar@1536: define a class with the default attribute types. This is the so called
alpar@1536: Traits Class. Later on the types of these attributes can be changed,
alpar@1536: as described below. In our software \ref lemon::DijkstraDefaultTraits is an
alpar@1536: example of how a traits class looks like.
hegyi@1141: 
alpar@955: \section named-templ-param Named Class Template Parameters
alpar@954: 
alpar@1536: If we would like to change the type of an attribute in a class that
alpar@1536: was instantiated by using a traits class as a template parameter, and
alpar@1536: the class contains named parameters, we do not have to reinstantiate
alpar@1536: the class with new traits class. Instead of that, adaptor classes can
alpar@1536: be used like in the following cases.
hegyi@1141: 
alpar@954: \code
deba@1709: Dijkstra<>::SetPredNodeMap<NullMap<Node,Node> >::Create
alpar@954: \endcode
hegyi@1141: 
alpar@954: It can also be used in conjunction with other named template
alpar@954: parameters in arbitrary order.
hegyi@1141: 
alpar@954: \code
deba@1709: Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Edge> >::Create
alpar@954: \endcode
alpar@954: 
alpar@1536: The result will be an instantiated Dijkstra class, in which the
alpar@1536: DistMap and the PredMap is modified.
hegyi@1141: 
alpar@1624: \section named-templ-func-param Named Function Template Parameters
alpar@955: 
alpar@1536: If the class has so called wizard functions, the new class with the
alpar@1536: modified tpye of attributes can be returned by the appropriate wizard
alpar@1536: function. The usage of these wizard functions is the following:
alpar@953: 
alpar@953: */