/* -*- C++ -*-

 *

 * This file is a part of LEMON, a generic C++ optimization library

 *

 * Copyright (C) 2003-2008

 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

 * (Egervary Research Group on Combinatorial Optimization, EGRES).

 *

 * Permission to use, modify and distribute this software is granted

 * provided that this copyright notice appears in all copies. For

 * precise terms see the accompanying LICENSE file.

 *

 * This software is provided "AS IS" with no warranty of any kind,

 * express or implied, and with no claim as to its suitability for any

 * purpose.

 *

 */

/*!

\page named-param Named Parameters

\section named-func-param Named Function Parameters

C++ makes it possible to use default parameter values when calling a

function. In such a case we do not have to give value for parameters,

the program will use the default ones.  Unfortunately sometimes this

is not enough. If we do not want to give values for all the

parameters, only for some of them we come across problems, because an

arbitrary set of parameters cannot be omitted. On the other hand

parameters have a fixed order in the head of the function.  C++ can

apply the default values only in the back of the order, if we do not

give other value for them.  So we can not give the function for

example the value of the first, and the third parameter, expecting

that the program will aplly the default value for the second

parameter.  However sometimes we would like to use some functinos

exactly in this way. With a crafty trick and with some little

inconvenience this is possible. We have implemented this little trick

as an example below.

\code

class namedFn 

{

  int _id;

  double _val;

  int _dim;

  public:

  namedFn() : _id(0), _val(1), _dim(2) {}

  namedFn& id(int p)     { _id  = p ; return *this; }

  namedFn& val(double p) { _val = p ; return *this; }

  namedFn& dim(int p)    { _dim = p ; return *this; }

  run() {

    printf("Here is the function itself.");

  }

};

\endcode

The usage is the following.

We have to define a class, let's call it \c namedFn.  Let us assume that

we would like to use a parameter, called \c X. In the \c namedFn class we

have to define an \c _X attribute, and a function \c X. The function

expects a parameter with the type of \c _X, and sets the value of

\c _X. After setting the value the function returns the class itself. The

class also have to have a function, called for example <tt>run()</tt>, we have

to implement here the original function itself. The constructor of the

class have to give all the attributes like \c _X the default values of

them.

If we instantiate this class, the default values will be set for the

attributes (originally the parameters), initially. If we call function

\c X, we get a class with the modified parameter value of

\c X. Therefore we can modify any parameter-value, independently from the

order. To run the algorithm we have to call the <tt>run()</tt> function at the

end of the row.

Example:

\code

namedFn().id(3).val(2).run();

\endcode

\note Although it is a class, namedFn is used pretty much like as it were

a function. That it why it is called namedFn and not \c NamedFn.

\note In fact, the final <tt>.run()</tt> could be made unnecessary if the

actual function code were put in the destructor instead. This however would make

hard to implement functions with return values, and would also make the

implementation of \ref named-templ-func-param "named template parameters"

very problematic. <b>Therefore, by convention, <tt>.run()</tt> must be used

to explicitly execute function having named parameters in Lemon.</b>

\section traits-classes Traits Classes

The procedure above can also be applied when defining classes. In this

case the type of the attributes can be changed.  Initially we have to

define a class with the default attribute types. This is the so called

Traits Class. Later on the types of these attributes can be changed,

as described below. In our software \ref lemon::DijkstraDefaultTraits is an

example of how a traits class looks like.

\section named-templ-param Named Class Template Parameters

If we would like to change the type of an attribute in a class that

was instantiated by using a traits class as a template parameter, and

the class contains named parameters, we do not have to reinstantiate

the class with new traits class. Instead of that, adaptor classes can

be used like in the following cases.

\code

Dijkstra<>::SetPredNodeMap<NullMap<Node,Node> >::Create

\endcode

It can also be used in conjunction with other named template

parameters in arbitrary order.

\code

Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Edge> >::Create

\endcode

The result will be an instantiated Dijkstra class, in which the

DistMap and the PredMap is modified.

\section named-templ-func-param Named Function Template Parameters

If the class has so called wizard functions, the new class with the

modified tpye of attributes can be returned by the appropriate wizard

function. The usage of these wizard functions is the following:

*/