doc/named-param.dox
author kpeter
Mon, 18 Feb 2008 03:34:16 +0000
changeset 2577 2c6204d4b0f6
parent 2391 14a343be7a5a
permissions -rw-r--r--
Add a cost scaling min cost flow algorithm.

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