\section read-maps Readable Maps

 \page maps Maps

 Maps play central role in HUGOlib. As their name suggests, they map a

 certain range of \e keys to certain \e values. Each map has two

 <tt>typedef</tt>'s to determine the types of keys and values, like this:

 \code

   typedef Edge KeyType;

   typedef double ValueType;

 \endcode

 A map can \e readable (ReadMap, for short), \e writable (WriteMap) or both

 (ReadWrite Map). There also exists a special type of

 ReadWrite map called <em>reference map</em>. In addition that you can

 read and write the values of a key, a reference map

 can also give you a reference to the

 value belonging to a key, so you have a direct access to the memory address

 where it is stored.

 Each graph structure in HUGOlib provides two standard map templates called

 \c EdgeMap and \c NodeMap. Both are reference maps and you can easily

 assign data to the nodes and to the edges of the graph. For example if you

 have a graph \c G defined as

 \code

   ListGraph G;

 \endcode

 and you want to assign floating point value to each edge, you can do

 it like this.

 \code

   ListGraph::EdgeMap<double> length(G);

 \endcode

 The value of a readable map can be obtained by <tt>operator[]</tt>.

 \code

   d=length[e];

 \endcode

 where \c e is an instance of \c ListGraph::Edge.

 (Or anything else

 that converts to \c ListGraph::Edge, like  \c ListGraph::EdgeIt or

 \c ListGraph::OutEdgeIt)

 There are two ways the assign a new value to a key

 - In case of a <em>reference map</em> <tt>operator[]</tt>

 gives you a reference to the

 value, thus you can use this.

 \code

   length[e]=3.5;

 \endcode

 - <em>Writable maps</em> have

 a member function \c set(KeyType,const ValueType &)

 for this purpose.

 \code

   length.set(e,3.5);

 \endcode

 The first case is more comfortable and if you store complex structures in your

 map, it might be more efficient. However, there are writable but

 not reference maps, so if you want to write an generic algorithm, you should

 insist on the second method.

 \section how-to-write-your-own-map How To write your own maps

 \subsection read-maps Readable Maps

 algorithms.  For this purpose the most straightforward is to use the

 algorithms.  For this purpose the most straightforward way is the use of the

 maps provided by Hugo's graph structres. Very often however, it is more

 default maps provided by Hugo's graph structures.

 Very often however, it is more

 You can find some examples below.

 You can find some examples below. In these examples \c Graph is the

 type of the particular graph structure you use.

   double operator[](Graph::Edge e) const { return M_PI;}

   typedef Graph::Edge KeyType;

   double operator[](KeyType e) const { return M_PI;}

 An alternative way to define maps. For this, \c MapBase seems to

 An alternative way to define maps is to use \c MapBase

 be a better name then \c NullMap

 \todo For this, \c MapBase seems to be a better name then \c NullMap.

 struct MyMap : public MapBase<Edge,double>

 struct MyMap : public MapBase<Graph::Edge,double>

 {

   double operator[](Graph::Edge e) const { return M_PI;}

 };

 \endcode

 Or, if we had \c KeyType and \c ValueType

 \code

 struct MyMap : public MapBase<Edge,double>

 Here is a bit more complex example.

 Here is a more complex example. It provides a length function which is obtained

 It provides a length function which is obtained

 from a base length function modified by a potential difference.

 from a base length function shifted by a potential difference.

 class MyLengthMap 

 class MyLengthMap  : public MapBase<Graph::Edge,double>

   const Graph::EdgeMap &ol;

   const Graph &G;

   const Graph::NodeMap &pot;

   const Graph::EdgeMap<double> &orig_len;

   const Graph::NodeMap<double> &pot;

   typedef double ValueType;

   KeyType operator[](ValueType e) const {

     return orig_len.get(e)-pot.get(G.head(e))-pot.get(G.tail(e));

   double operator[](Graph::Edge e) const {

     return ol.get(e)-pot.get(v)-pot.get(u);

   MyComplexMap(const Graph::EdgeMap &o,const Graph::NodeMap &p) :

   MyLengthMap(const Graph &g, const Graph::EdgeMap &o,const Graph::NodeMap &p)

     ol(o), pot(p);

     : G(g), orig_len(o), pot(p) {};

 \todo Please improve on the english. 

 \todo Don't we need \e to \e require a 'typedef xxx KeyType' tag, as well?

 \subsection write-maps Writable Maps

 To be written...

 \subsection side-effect-maps Maps with Side Effect

 To be written...