doc/named-param.dox
author deba
Fri, 14 Apr 2006 18:07:33 +0000
changeset 2051 08652c1763f6
parent 1713 49d22d34d95f
child 2391 14a343be7a5a
permissions -rw-r--r--
MaxWeightedBipartiteMatching
MinCostMaxBipartiteMatching

Both algorithms are based on successive shortest
path algorithm with dijkstra shortest path
finding
     1 /*!
     2 
     3 \page named-param Named Parameters
     4 
     5 \section named-func-param Named Function Parameters
     6 
     7 C++ makes it possible to use default parameter values when calling a
     8 function. In such a case we do not have to give value for parameters,
     9 the program will use the default ones.  Unfortunately sometimes this
    10 is not enough. If we do not want to give values for all the
    11 parameters, only for some of them we come across problems, because an
    12 arbitrary set of parameters cannot be omitted. On the other hand
    13 parameters have a fixed order in the head of the function.  C++ can
    14 apply the default values only in the back of the order, if we do not
    15 give other value for them.  So we can not give the function for
    16 example the value of the first, and the third parameter, expecting
    17 that the program will aplly the default value for the second
    18 parameter.  However sometimes we would like to use some functinos
    19 exactly in this way. With a crafty trick and with some little
    20 inconvenience this is possible. We have implemented this little trick
    21 as an example below.
    22 
    23 \code
    24 class namedFn 
    25 {
    26   int _id;
    27   double _val;
    28   int _dim;
    29   
    30   public:
    31   namedFn() : _id(0), _val(1), _dim(2) {}
    32   namedFn& id(int p)     { _id  = p ; return *this; }
    33   namedFn& val(double p) { _val = p ; return *this; }
    34   namedFn& dim(int p)    { _dim = p ; return *this; }
    35 
    36   run() {
    37     printf("Here is the function itself.");
    38   }
    39 };
    40 \endcode
    41 
    42 
    43 The usage is the following.
    44 
    45 We have to define a class, let's call it \c namedFn.  Let us assume that
    46 we would like to use a parameter, called \c X. In the \c namedFn class we
    47 have to define an \c _X attribute, and a function \c X. The function
    48 expects a parameter with the type of \c _X, and sets the value of
    49 \c _X. After setting the value the function returns the class itself. The
    50 class also have to have a function, called for example <tt>run()</tt>, we have
    51 to implement here the original function itself. The constructor of the
    52 class have to give all the attributes like \c _X the default values of
    53 them.
    54 
    55 If we instantiate this class, the default values will be set for the
    56 attributes (originally the parameters), initially. If we call function
    57 \c X, we get a class with the modified parameter value of
    58 \c X. Therefore we can modify any parameter-value, independently from the
    59 order. To run the algorithm we have to call the <tt>run()</tt> function at the
    60 end of the row.
    61 
    62 Example:
    63 \code
    64 namedFn().id(3).val(2).run();
    65 \endcode
    66 
    67 \note Although it is a class, namedFn is used pretty much like as it were
    68 a function. That it why it is called namedFn and not \c NamedFn.
    69 
    70 \note In fact, the final <tt>.run()</tt> could be made unnecessary if the
    71 actual function code were put in the destructor instead. This however would make
    72 hard to implement functions with return values, and would also make the
    73 implementation of \ref named-templ-func-param "named template parameters"
    74 very problematic. <b>Therefore, by convention, <tt>.run()</tt> must be used
    75 to explicitly execute function having named parameters in Lemon.</b>
    76 
    77 
    78 \section traits-classes Traits Classes
    79 
    80 The procedure above can also be applied when defining classes. In this
    81 case the type of the attributes can be changed.  Initially we have to
    82 define a class with the default attribute types. This is the so called
    83 Traits Class. Later on the types of these attributes can be changed,
    84 as described below. In our software \ref lemon::DijkstraDefaultTraits is an
    85 example of how a traits class looks like.
    86 
    87 \section named-templ-param Named Class Template Parameters
    88 
    89 If we would like to change the type of an attribute in a class that
    90 was instantiated by using a traits class as a template parameter, and
    91 the class contains named parameters, we do not have to reinstantiate
    92 the class with new traits class. Instead of that, adaptor classes can
    93 be used like in the following cases.
    94 
    95 \code
    96 Dijkstra<>::SetPredNodeMap<NullMap<Node,Node> >::Create
    97 \endcode
    98 
    99 It can also be used in conjunction with other named template
   100 parameters in arbitrary order.
   101 
   102 \code
   103 Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Edge> >::Create
   104 \endcode
   105 
   106 The result will be an instantiated Dijkstra class, in which the
   107 DistMap and the PredMap is modified.
   108 
   109 \section named-templ-func-param Named Function Template Parameters
   110 
   111 If the class has so called wizard functions, the new class with the
   112 modified tpye of attributes can be returned by the appropriate wizard
   113 function. The usage of these wizard functions is the following:
   114 
   115 */