source: lemon-0.x/doc/named-param.dox @ 1619:f0700b9e6418

*!

\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 named_fn 
{
  int _id;
  double _val;
  int _dim;
  
  public:
  named_fn() : _id(0), _val(1), _dim(2) {}
  named_fn& id(int p)     { _id  = p ; return *this; }
  named_fn& val(double p) { _val = p ; return *this; }
  named_fn& 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 named_fn.  Let us assume that
we would like to use a parameter, called X. In the named_fn class we
have to define an _X attribute, and a function X. The function
expects a parameter with the type of _X, and sets the value of
_X. After setting the value the function returns the class itself. The
class also have to have a function, called for example run(), we have
to implement here the original function itself. The constructor of the
class have to give all the attributes like _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
X, we get a class with the modified parameter value of
X. Therefore we can modify any parameter-value, independent from the
order. To run the algorithm we have to call the run() function at the
end of the row.

Example: named_fn().id(3).val(2).run();

\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> >
\endcode

It can also be used in conjunction with other named template
parameters in arbitrary order.

\code
Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Edge> >
\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:

*/