namespace lemon {

 /*!

 \page adaptor-references Smart Reference Handling

 The adaptor classes are very useful tools in the lemon library. It makes

 possible to create various data view of the current data structures without

 of the copy of them. This makes the lemon programming efficient and 

 consederably fast.

 \section problem The problem

 The adaptors usually use references or pointers to reference to an 

 existing data structure. We may use an algorithm in the following way:

 \code

 function_algorithm(adaptor(structure));

 \endcode 

 But what about the class algorithms:

 \code

 class_algorithm alg;

 alg.add(adaptor(structure));

 alg.run();

 \endcode

 The algorithm store a reference to the given structure. It is a created

 as temporarly and when the expression of the \c add() function is evaluated it

 will be destructed. It is very dangerous handling of the adaptors.

 \section solution The solution

 We made reference to a temporarly constructed adaptor but we should make

 a copy of the adaptor when it is given as parameter to a class.

 It is not impossible with a little tranformation of the code.

 Let's first create some helper class:

 \code

 template <typename _Type, typename Enable = void>

 struct SmartConstReference {

   typedef const _Type& Type;

 };

 template <typename _Type>

 struct SmartConstReference<

   _Type, 

   typename enable_if<typename _Type::NeedCopy, void>::type

 > {

   typedef const _Type Type;

 };

 \endcode

 Then we can place NeedCopy tags in the adaptor classes:

 \code

 template<class M1,class M2> 

 class AddMap {

   typename SmartConstReference<M1>::Type m1;

   typename SmartConstReference<M2>::Type m2;

 public:

   typedef True NeedCopy;

   typedef typename M1::Key Key;

   typedef typename M1::Value Value;

   AddMap(const M1 &_m1,const M2 &_m2) : m1(_m1), m2(_m2) {};

   Value operator[](Key k) const {return m1[k]+m2[k];}

 };

 \endcode

 Then we can transform all of the template map and graph references to

 \c SmartConstReference<Map>::Type or \c SmartConstReference<Graph>::Type.

 This way we copy all of maps and graphs what we should copy but the

 greater data structures are not copied.

 \section not-const If the adaptor is not const

 The solution is very similar but it gives an additional problem.

 We make the same \c SmartReferences:

 \code

 template <typename _Type, typename Enable = void>

 struct SmartReference {

   typedef _Type& Type;

 };

 template <typename _Type>

 struct SmartReference<

   _Type, 

   typename enable_if<typename _Type::NeedCopy, void>::type

 > {

   typedef _Type Type;

 };

 \endcode

 Let's create a class that use it:

 \code

 template <typename Map>

 class Algorithm {

 public:

   SmartReference<Map>::Type map;

   Algorithm(Map& _map) : map(_map) {}

   ...

 };

 \endcode

 But if we want to give an adaptor function as parameter

 it will be a compile error. The adaptor will be created as temporarly

 so it cannot give as reference just as const reference.

 Make more helper class:

 \code

 template <typename _Type, typename Enable = void>

 struct SmartParameter {

   typedef _Type& Type;

 };

 template <typename _Type>

 struct SmartParameter<

   _Type, 

   typename enable_if<typename _Type::NeedCopy, void>::type

 > {

   typedef const _Type& Type;

 };

 \endcode

 And the repaired code:

 \code

 template <typename Map>

 class Algorithm {

 public:

   SmartReference<Map>::Type map;

   Algorithm(SmartParameter<Map>::Type _map) : map(_map) {}

   ...

 };

 \endcode

 But some times it does not help:

 \code

 class Algorithm {

 public:

   ...

   template <typename Map>

   void addMap(SmartParameter<Map>::Type _map) {

     ...

   }

   ...

 };

 \endcode

 Actually, it is a good code but the template parameter should

 be written because it cannot be found out from the parameter type.

 This can be solved with a bigger transformation:

 \code

 class Algorithm {

 public:

   ...

   template <typename Map>

   void addMap(const Map& _map) {

     _addMap<SmartParameter<Map>::Type, Map>(_map);

   }

   template <typename Map>

   void addMap(const Map& _map) {

     _addMap<SmartParameter<Map>::Type, Map>(_map);

   }

 private:

   template <typename MapParameter, typename Map>

   void _addMap(MapParameter _map) {

     ...

   }

   ...

 };

 \endcode

 This way we solved the smart referencing problem.

 \author Balazs Dezso

 */

 }