diff -r f47faf6913ab -r 09af6d2b683b doc/maps1.dox
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/maps1.dox	Mon Sep 04 20:07:37 2006 +0000
@@ -0,0 +1,72 @@
+/**
+\page maps1 Maps I.
+
+In the previous section we discussed graph topology. That is the skeleton a complex
+graph represented data-set needs. But how to assign the data itself to that skeleton?<br>
+Here come the \b maps in.
+
+\section maps_intro Introduction to maps
+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>.
+In LEMON there is many types of maps. Each map has two typedef's to determine the types of keys and values, like this:
+\code
+  typedef Edge Key;
+  typedef double Value;
+\endcode
+(Except matrix maps, they have two key types.)
+
+To make easy to use them - especially as template parameters - there are <i>map concepts</i> like by graph classes.
+<ul>
+<li>\ref ReadMap - values can be red out with the \c operator[].
+\code value_typed_variable = map_instance[key_value]; \endcode
+</li>
+<li>\ref WriteMap - values can be set with the \c set() member function.
+\code map_instance.set(key_value, value_typed_expression); \endcode
+</li>
+<li>\ref ReadWriteMap - it's just a shortcut to indicate that the map is both
+readable and writable. It is delivered from them.
+</li>
+<li>\ref ReferenceMap - a subclass of ReadWriteMap. It has two additional typedefs
+<i>Reference</i> and <i>ConstReference</i> and two overloads of \c operator[] to
+providing you constant or non-constant reference to the value belonging to a key,
+so you have a direct access to the memory address where it is stored.
+</li>
+<li>And there are the Matrix version of these maps, where the values are assigned to a pair of keys.
+The keys can be different types. (\ref ReadMatrixMap, \ref WriteMatrixMap, \ref ReadWriteMatrixMap, \ref ReferenceMatrixMap)
+</li>
+</ul>
+
+\section maps_graph Graphs' maps
+Every \ref MappableGraphComponent "mappable" graph class has two public templates: NodeMap<VALUE> and EdgeMap<VALUE>
+satisfying the \ref GraphMap concept.
+If you want to assign data to nodes, just declare a NodeMap with the corresponding
+type. As an example, think of a edge-weighted directed graph.
+\code ListGraph::EdgeMap<int>  weight(graph); \endcode
+You can see that the map needs the graph hows edges will mapped, but nothing more.
+
+If the graph class is extendable or erasable the map will automatically follow
+the changes you make. If a new node is added a default value is mapped to it.
+You can define the default value by passing a second argument to the map's constructor.
+\code ListGraph::EdgeMap<int>  weight(graph, 13); \endcode
+But keep in mind that \c VALUE has to have copy constructor.
+
+Of course \c VALUE can be a rather complex type.
+
+For practice let's see the following template function (from \ref maps_summary "maps-summary.cc" in the \ref demo directory)!
+\dontinclude maps_summary.cc
+\skip template
+\until }
+The task is simple. We need the summary of some kind of data assigned to a graph's nodes.
+(Whit a little trick the summary can be calculated only to a sub-graph without changing
+this code. See \ref SubGraph techniques - that's LEMON's true potential.)
+
+And the usage is simpler than the declaration suggests. The compiler deduces the
+template specialization, so the usage is like a simple function call.
+\skip std
+\until ;
+
+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.
+
+If you want some 'real-life' examples see the next page, where we discuss \ref algorithms
+(coming soon) and will use maps hardly.
+Or if you want to know more about maps read these \ref maps2 "advanced map techniques".
+*/