Ticket #147: 1eb606fe5591.patch

new file doc/named-param.dox

@@ +1 @@
+/* -*- C++ -*-
+ *
+ * This file is a part of LEMON, a generic C++ optimization library
+ *
+ * Copyright (C) 2003-2008
+ * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
+ * (Egervary Research Group on Combinatorial Optimization, EGRES).
+ *
+ * Permission to use, modify and distribute this software is granted
+ * provided that this copyright notice appears in all copies. For
+ * precise terms see the accompanying LICENSE file.
+ *
+ * This software is provided "AS IS" with no warranty of any kind,
+ * express or implied, and with no claim as to its suitability for any
+ * purpose.
+ *
+ */
+
+/*!
+
+\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 namedFn 
+{
+  int _id;
+  double _val;
+  int _dim;
+  
+  public:
+  namedFn() : _id(0), _val(1), _dim(2) {}
+  namedFn& id(int p)     { _id  = p ; return *this; }
+  namedFn& val(double p) { _val = p ; return *this; }
+  namedFn& 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 \c namedFn.  Let us assume that
+we would like to use a parameter, called \c X. In the \c namedFn class we
+have to define an \c _X attribute, and a function \c X. The function
+expects a parameter with the type of \c _X, and sets the value of
+\c _X. After setting the value the function returns the class itself. The
+class also have to have a function, called for example <tt>run()</tt>, we have
+to implement here the original function itself. The constructor of the
+class have to give all the attributes like \c _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
+\c X, we get a class with the modified parameter value of
+\c X. Therefore we can modify any parameter-value, independently from the
+order. To run the algorithm we have to call the <tt>run()</tt> function at the
+end of the row.
+
+Example:
+\code
+namedFn().id(3).val(2).run();
+\endcode
+
+\note Although it is a class, namedFn is used pretty much like as it were
+a function. That it why it is called namedFn and not \c NamedFn.
+
+\note In fact, the final <tt>.run()</tt> could be made unnecessary if the
+actual function code were put in the destructor instead. This however would make
+hard to implement functions with return values, and would also make the
+implementation of \ref named-templ-func-param "named template parameters"
+very problematic. <b>Therefore, by convention, <tt>.run()</tt> must be used
+to explicitly execute function having named parameters in Lemon.</b>
+
+
+\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> >::Create
+\endcode
+
+It can also be used in conjunction with other named template
+parameters in arbitrary order.
+
+\code
+Dijkstra<>::SetDistMap<MyMap>::SetPredMap<NullMap<Node,Edge> >::Create
+\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:
+
+*/