COIN-OR::LEMON - Graph Library

Ticket #147: 1eb606fe5591.patch

File 1eb606fe5591.patch, 5.4 KB (added by Alpar Juttner, 12 years ago)
  • new file doc/named-param.dox

    # HG changeset patch
    # User Alpar Juttner <alpar@cs.elte.hu>
    # Date 1221973985 -3600
    # Node ID 1eb606fe559192ace62ce6bcc59df065bff5a48c
    # Parent  983d8c23aff82750de15e5d76dd699b8e5b19593
    Port named-param.dox from svn -r3504
    
    diff --git a/doc/named-param.dox b/doc/named-param.dox
    new file mode 100644
    - +  
     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
     25C++ makes it possible to use default parameter values when calling a
     26function. In such a case we do not have to give value for parameters,
     27the program will use the default ones.  Unfortunately sometimes this
     28is not enough. If we do not want to give values for all the
     29parameters, only for some of them we come across problems, because an
     30arbitrary set of parameters cannot be omitted. On the other hand
     31parameters have a fixed order in the head of the function.  C++ can
     32apply the default values only in the back of the order, if we do not
     33give other value for them.  So we can not give the function for
     34example the value of the first, and the third parameter, expecting
     35that the program will aplly the default value for the second
     36parameter.  However sometimes we would like to use some functinos
     37exactly in this way. With a crafty trick and with some little
     38inconvenience this is possible. We have implemented this little trick
     39as an example below.
     40
     41\code
     42class 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
     61The usage is the following.
     62
     63We have to define a class, let's call it \c namedFn.  Let us assume that
     64we would like to use a parameter, called \c X. In the \c namedFn class we
     65have to define an \c _X attribute, and a function \c X. The function
     66expects 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
     68class also have to have a function, called for example <tt>run()</tt>, we have
     69to implement here the original function itself. The constructor of the
     70class have to give all the attributes like \c _X the default values of
     71them.
     72
     73If we instantiate this class, the default values will be set for the
     74attributes (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
     77order. To run the algorithm we have to call the <tt>run()</tt> function at the
     78end of the row.
     79
     80Example:
     81\code
     82namedFn().id(3).val(2).run();
     83\endcode
     84
     85\note Although it is a class, namedFn is used pretty much like as it were
     86a 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
     89actual function code were put in the destructor instead. This however would make
     90hard to implement functions with return values, and would also make the
     91implementation of \ref named-templ-func-param "named template parameters"
     92very problematic. <b>Therefore, by convention, <tt>.run()</tt> must be used
     93to explicitly execute function having named parameters in Lemon.</b>
     94
     95
     96\section traits-classes Traits Classes
     97
     98The procedure above can also be applied when defining classes. In this
     99case the type of the attributes can be changed.  Initially we have to
     100define a class with the default attribute types. This is the so called
     101Traits Class. Later on the types of these attributes can be changed,
     102as described below. In our software \ref lemon::DijkstraDefaultTraits is an
     103example of how a traits class looks like.
     104
     105\section named-templ-param Named Class Template Parameters
     106
     107If we would like to change the type of an attribute in a class that
     108was instantiated by using a traits class as a template parameter, and
     109the class contains named parameters, we do not have to reinstantiate
     110the class with new traits class. Instead of that, adaptor classes can
     111be used like in the following cases.
     112
     113\code
     114Dijkstra<>::SetPredNodeMap<NullMap<Node,Node> >::Create
     115\endcode
     116
     117It can also be used in conjunction with other named template
     118parameters in arbitrary order.
     119
     120\code
     121Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Edge> >::Create
     122\endcode
     123
     124The result will be an instantiated Dijkstra class, in which the
     125DistMap and the PredMap is modified.
     126
     127\section named-templ-func-param Named Function Template Parameters
     128
     129If the class has so called wizard functions, the new class with the
     130modified tpye of attributes can be returned by the appropriate wizard
     131function. The usage of these wizard functions is the following:
     132
     133*/