1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/gwrappers.dox	Wed Feb 23 22:00:05 2005 +0000
     1.3 @@ -0,0 +1,61 @@
     1.4 +/**
     1.5 +   @defgroup gwrappers Wrapper Classes for Graphs
     1.6 +   \brief This group contains several wrapper classes for graphs
     1.7 +   @ingroup graphs
     1.8 +   
     1.9 +   The main parts of LEMON are the different graph structures, 
    1.10 +   generic graph algorithms, graph concepts which couple these, and 
    1.11 +   graph wrappers. While the previous ones are more or less clear, the 
    1.12 +   latter notion needs further explanation.
    1.13 +   Graph wrappers are graph classes which serve for considering graph 
    1.14 +   structures in different ways. A short example makes the notion much 
    1.15 +   clearer. 
    1.16 +   Suppose that we have an instance \c g of a directed graph
    1.17 +   type say \c ListGraph and an algorithm 
    1.18 +   \code template<typename Graph> int algorithm(const Graph&); \endcode 
    1.19 +   is needed to run on the reversely oriented graph. 
    1.20 +   It may be expensive (in time or in memory usage) to copy 
    1.21 +   \c g with the reverse orientation. 
    1.22 +   Thus, a wrapper class
    1.23 +   \code template<typename Graph> class RevGraphWrapper; \endcode is used. 
    1.24 +   The code looks as follows
    1.25 +   \code
    1.26 +   ListGraph g;
    1.27 +   RevGraphWrapper<ListGraph> rgw(g);
    1.28 +   int result=algorithm(rgw);
    1.29 +   \endcode
    1.30 +   After running the algorithm, the original graph \c g 
    1.31 +   remains untouched. Thus the graph wrapper used above is to consider the 
    1.32 +   original graph with reverse orientation. 
    1.33 +   This techniques gives rise to an elegant code, and 
    1.34 +   based on stable graph wrappers, complex algorithms can be 
    1.35 +   implemented easily. 
    1.36 +   In flow, circulation and bipartite matching problems, the residual 
    1.37 +   graph is of particular importance. Combining a wrapper implementing 
    1.38 +   this, shortest path algorithms and minimum mean cycle algorithms, 
    1.39 +   a range of weighted and cardinality optimization algorithms can be 
    1.40 +   obtained. For lack of space, for other examples, 
    1.41 +   the interested user is referred to the detailed documentation of graph 
    1.42 +   wrappers. 
    1.43 +   The behavior of graph wrappers can be very different. Some of them keep 
    1.44 +   capabilities of the original graph while in other cases this would be 
    1.45 +   meaningless. This means that the concepts that they are a model of depend 
    1.46 +   on the graph wrapper, and the wrapped graph(s). 
    1.47 +   If an edge of \c rgw is deleted, this is carried out by 
    1.48 +   deleting the corresponding edge of \c g. But for a residual 
    1.49 +   graph, this operation has no sense. 
    1.50 +   Let we stand one more example here to simplify your work. 
    1.51 +   wrapper class
    1.52 +   \code template<typename Graph> class RevGraphWrapper; \endcode 
    1.53 +   has constructor 
    1.54 +   <tt> RevGraphWrapper(Graph& _g)</tt>. 
    1.55 +   This means that in a situation, 
    1.56 +   when a <tt> const ListGraph& </tt> reference to a graph is given, 
    1.57 +   then it have to be instantiated with <tt>Graph=const ListGraph</tt>.
    1.58 +   \code
    1.59 +   int algorithm1(const ListGraph& g) {
    1.60 +   RevGraphWrapper<const ListGraph> rgw(g);
    1.61 +   return algorithm2(rgw);
    1.62 +   }
    1.63 +   \endcode
    1.64 +*/