1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/maps1.dox	Mon Sep 04 20:07:37 2006 +0000
     1.3 @@ -0,0 +1,72 @@
     1.4 +/**
     1.5 +\page maps1 Maps I.
     1.6 +
     1.7 +In the previous section we discussed graph topology. That is the skeleton a complex
     1.8 +graph represented data-set needs. But how to assign the data itself to that skeleton?<br>
     1.9 +Here come the \b maps in.
    1.10 +
    1.11 +\section maps_intro Introduction to maps
    1.12 +Maps play a central role in LEMON. As their name suggests, they map a certain range of <i>keys</i> to certain <i>values</i>.
    1.13 +In LEMON there is many types of maps. Each map has two typedef's to determine the types of keys and values, like this:
    1.14 +\code
    1.15 +  typedef Edge Key;
    1.16 +  typedef double Value;
    1.17 +\endcode
    1.18 +(Except matrix maps, they have two key types.)
    1.19 +
    1.20 +To make easy to use them - especially as template parameters - there are <i>map concepts</i> like by graph classes.
    1.21 +<ul>
    1.22 +<li>\ref ReadMap - values can be red out with the \c operator[].
    1.23 +\code value_typed_variable = map_instance[key_value]; \endcode
    1.24 +</li>
    1.25 +<li>\ref WriteMap - values can be set with the \c set() member function.
    1.26 +\code map_instance.set(key_value, value_typed_expression); \endcode
    1.27 +</li>
    1.28 +<li>\ref ReadWriteMap - it's just a shortcut to indicate that the map is both
    1.29 +readable and writable. It is delivered from them.
    1.30 +</li>
    1.31 +<li>\ref ReferenceMap - a subclass of ReadWriteMap. It has two additional typedefs
    1.32 +<i>Reference</i> and <i>ConstReference</i> and two overloads of \c operator[] to
    1.33 +providing you constant or non-constant reference to the value belonging to a key,
    1.34 +so you have a direct access to the memory address where it is stored.
    1.35 +</li>
    1.36 +<li>And there are the Matrix version of these maps, where the values are assigned to a pair of keys.
    1.37 +The keys can be different types. (\ref ReadMatrixMap, \ref WriteMatrixMap, \ref ReadWriteMatrixMap, \ref ReferenceMatrixMap)
    1.38 +</li>
    1.39 +</ul>
    1.40 +
    1.41 +\section maps_graph Graphs' maps
    1.42 +Every \ref MappableGraphComponent "mappable" graph class has two public templates: NodeMap<VALUE> and EdgeMap<VALUE>
    1.43 +satisfying the \ref GraphMap concept.
    1.44 +If you want to assign data to nodes, just declare a NodeMap with the corresponding
    1.45 +type. As an example, think of a edge-weighted directed graph.
    1.46 +\code ListGraph::EdgeMap<int>  weight(graph); \endcode
    1.47 +You can see that the map needs the graph hows edges will mapped, but nothing more.
    1.48 +
    1.49 +If the graph class is extendable or erasable the map will automatically follow
    1.50 +the changes you make. If a new node is added a default value is mapped to it.
    1.51 +You can define the default value by passing a second argument to the map's constructor.
    1.52 +\code ListGraph::EdgeMap<int>  weight(graph, 13); \endcode
    1.53 +But keep in mind that \c VALUE has to have copy constructor.
    1.54 +
    1.55 +Of course \c VALUE can be a rather complex type.
    1.56 +
    1.57 +For practice let's see the following template function (from \ref maps_summary "maps-summary.cc" in the \ref demo directory)!
    1.58 +\dontinclude maps_summary.cc
    1.59 +\skip template
    1.60 +\until }
    1.61 +The task is simple. We need the summary of some kind of data assigned to a graph's nodes.
    1.62 +(Whit a little trick the summary can be calculated only to a sub-graph without changing
    1.63 +this code. See \ref SubGraph techniques - that's LEMON's true potential.)
    1.64 +
    1.65 +And the usage is simpler than the declaration suggests. The compiler deduces the
    1.66 +template specialization, so the usage is like a simple function call.
    1.67 +\skip std
    1.68 +\until ;
    1.69 +
    1.70 +Most of the time you will probably use graph maps, but keep in mind, that in LEMON maps are more general and can be used widely.
    1.71 +
    1.72 +If you want some 'real-life' examples see the next page, where we discuss \ref algorithms
    1.73 +(coming soon) and will use maps hardly.
    1.74 +Or if you want to know more about maps read these \ref maps2 "advanced map techniques".
    1.75 +*/