COIN-OR::LEMON - Graph Library

Changeset 268:986d30f5c1c0 in lemon-1.2 for doc

09/21/08 08:49:57 (16 years ago)
Alpar Juttner <alpar@…>

Improvements in named-param.dox

1 edited


  • doc/named-param.dox

    r267 r268  
    2323\section named-func-param Named Function Parameters
    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.
     25Several modern languages provide a convenient way to refer the
     26function parameters by name also when you call the function. It is
     27especially comfortable in case of a function having tons of parameters
     28with natural default values. Sadly, C++ lack this amenity.
     30However, with a crafty trick and with some little
     31inconvenience, it is possible to emulate is.
     32The example below shows how to do it.
    5447  run() {
    55     printf("Here is the function itself.");
     48  std::cout << "Here comes the function itself\n" <<
     49            << "With parameters "
     50            << _id << ", " << _val << ", " << _dim << std::endl;
    5651  }
     55Then you can use it like this.
    61 The usage is the following.
    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.
    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.
    80 Example:
     61The trick is obvious, each "named parameter" changes one component of
     62the underlying class, then gives back a reference to it. Finally,
     63<tt>run()</tt> executes the algorithm itself.
    8565\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.
     66a function. That it why we called it namedFn instead of \c NamedFn.
    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>
     68\note In fact, the final <tt>.run()</tt> could be made unnecessary,
     69because the algorithm could also be implemented in the destructor of
     70\c namedFn instead. This however would make it impossible to implement
     71functions with return values, and would also cause serious problems when
     72implementing \ref named-templ-func-param "named template parameters".
     73<b>Therefore, by convention, <tt>.run()</tt> must be used
     74explicitly to execute a function having named parameters
     75everywhere in LEMON.</b>
     77\section named-templ-func-param Named Function Template Parameters
     79A named parameter can also be a template functions. The usage is
     80exactly the same, but the implementation behind is a kind of black
     81magic and they are the dirtiest part of the LEMON code.
     83You will probably never need to know how it works, but if you really
     84committed, have a look at \ref lemon/graph_to_eps.h for an example.
    9686\section traits-classes Traits Classes
    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.
     88A similar game can also be played when defining classes. In this case
     89the type of the class attributes can be changed. Initially we have to
     90define a special class called <em>Traits Class</em> defining the
     91default type of the attributes. Then the types of these attributes can
     92be changed in the same way as described in the next section.
     94See \ref lemon::DijkstraDefaultTraits for an
     95example how a traits class implementation looks like.
    10597\section named-templ-param Named Class Template Parameters
    10799If we would like to change the type of an attribute in a class that
    108100was 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.
     101the class contains named parameters, we do not have to instantiate again
     102the class with new traits class, but instead adaptor classes can
     103be used as shown in the following example.
    125117DistMap and the PredMap is modified.
    127 \section named-templ-func-param Named Function Template Parameters
    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:
Note: See TracChangeset for help on using the changeset viewer.