/*!

\page graphs How to use graphs

The primary data structures of LEMON are the graph classes. They all

provide a node list - edge list interface, i.e. they have

functionalities to list the nodes and the edges of the graph as well

as  incoming and outgoing edges of a given node. 

Each graph should meet the

\ref lemon::concept::StaticGraph "StaticGraph" concept.

This concept does not

make it possible to change the graph (i.e. it is not possible to add

or delete edges or nodes). Most of the graph algorithms will run on

these graphs.

The graphs meeting the

\ref lemon::concept::ExtendableGraph "ExtendableGraph"

concept allow node and

edge addition. You can also "clear" such a graph (i.e. erase all edges and nodes ).

In case of graphs meeting the full feature

\ref lemon::concept::ErasableGraph "ErasableGraph"

concept

you can also erase individual edges and nodes in arbitrary order.

The implemented graph structures are the following.

\li \ref lemon::ListGraph "ListGraph" is the most versatile graph class. It meets

the \ref lemon::concept::ErasableGraph "ErasableGraph" concept

and it also has some convenient extra features.

\li \ref lemon::SmartGraph "SmartGraph" is a more memory

efficient version of \ref lemon::ListGraph "ListGraph". The

price of this is that it only meets the

\ref lemon::concept::ExtendableGraph "ExtendableGraph" concept,

so you cannot delete individual edges or nodes.

\li \ref lemon::SymListGraph "SymListGraph" and

\ref lemon::SymSmartGraph "SymSmartGraph" classes are very similar to

\ref lemon::ListGraph "ListGraph" and \ref lemon::SmartGraph "SmartGraph".

The difference is that whenever you add a

new edge to the graph, it actually adds a pair of oppositely directed edges.

They are linked together so it is possible to access the counterpart of an

edge. An even more important feature is that using these classes you can also

attach data to the edges in such a way that the stored data

are shared by the edge pairs. 

\li \ref lemon::FullGraph "FullGraph"

implements a complete graph. It is a

\ref lemon::concept::StaticGraph "StaticGraph", so you cannot

change the number of nodes once it is constructed. It is extremely memory

efficient: it uses constant amount of memory independently from the number of

the nodes of the graph. Of course, the size of the \ref maps-page "NodeMap"'s and

\ref maps-page "EdgeMap"'s will depend on the number of nodes.

\li \ref lemon::NodeSet "NodeSet" implements a graph with no edges. This class

can be used as a base class of \ref lemon::EdgeSet "EdgeSet".

\li \ref lemon::EdgeSet "EdgeSet" can be used to create a new graph on

the node set of another graph. The base graph can be an arbitrary graph and it

is possible to attach several \ref lemon::EdgeSet "EdgeSet"'s to a base graph.

\todo Don't we need SmartNodeSet and SmartEdgeSet?

\todo Some cross-refs are wrong.

The graph structures themselves can not store data attached

to the edges and nodes. However they all provide

\ref maps-page "map classes"

to dynamically attach data the to graph components.

The following program demonstrates the basic features of LEMON's graph

structures.

\code

#include <iostream>

#include <lemon/list_graph.h>

using namespace lemon;

int main()

{

  typedef ListGraph Graph;

\endcode

ListGraph is one of LEMON's graph classes. It is based on linked lists,

therefore iterating throuh its edges and nodes is fast.

\code

  typedef Graph::Edge Edge;

  typedef Graph::InEdgeIt InEdgeIt;

  typedef Graph::OutEdgeIt OutEdgeIt;

  typedef Graph::EdgeIt EdgeIt;

  typedef Graph::Node Node;

  typedef Graph::NodeIt NodeIt;

  Graph g;

  for (int i = 0; i < 3; i++)

    g.addNode();

  for (NodeIt i(g); i!=INVALID; ++i)

    for (NodeIt j(g); j!=INVALID; ++j)

      if (i != j) g.addEdge(i, j);

\endcode

After some convenient typedefs we create a graph and add three nodes to it.

Then we add edges to it to form a complete graph.

\code

  std::cout << "Nodes:";

  for (NodeIt i(g); i!=INVALID; ++i)

    std::cout << " " << g.id(i);

  std::cout << std::endl;

\endcode

Here we iterate through all nodes of the graph. We use a constructor of the

node iterator to initialize it to the first node. The operator++ is used to

step to the next node. Using operator++ on the iterator pointing to the last

node invalidates the iterator i.e. sets its value to

\ref lemon::INVALID "INVALID". This is what we exploit in the stop condition.

The previous code fragment prints out the following:

\code

Nodes: 2 1 0

\endcode

\code

  std::cout << "Edges:";

  for (EdgeIt i(g); i!=INVALID; ++i)

    std::cout << " (" << g.id(g.source(i)) << "," << g.id(g.target(i)) << ")";

  std::cout << std::endl;

\endcode

\code

Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)

\endcode

We can also iterate through all edges of the graph very similarly. The 

\c target and

\c source member functions can be used to access the endpoints of an edge.

\code

  NodeIt first_node(g);

  std::cout << "Out-edges of node " << g.id(first_node) << ":";

  for (OutEdgeIt i(g, first_node); i!=INVALID; ++i)

    std::cout << " (" << g.id(g.source(i)) << "," << g.id(g.target(i)) << ")"; 

  std::cout << std::endl;

  std::cout << "In-edges of node " << g.id(first_node) << ":";

  for (InEdgeIt i(g, first_node); i!=INVALID; ++i)

    std::cout << " (" << g.id(g.source(i)) << "," << g.id(g.target(i)) << ")"; 

  std::cout << std::endl;

\endcode

\code

Out-edges of node 2: (2,0) (2,1)

In-edges of node 2: (0,2) (1,2)

\endcode

We can also iterate through the in and out-edges of a node. In the above

example we print out the in and out-edges of the first node of the graph.

\code

  Graph::EdgeMap<int> m(g);

  for (EdgeIt e(g); e!=INVALID; ++e)

    m.set(e, 10 - g.id(e));

  std::cout << "Id Edge  Value" << std::endl;

  for (EdgeIt e(g); e!=INVALID; ++e)

    std::cout << g.id(e) << "  (" << g.id(g.source(e)) << "," << g.id(g.target(e))

      << ") " << m[e] << std::endl;

\endcode

\code

Id Edge  Value

4  (0,2) 6

2  (1,2) 8

5  (0,1) 5

0  (2,1) 10

3  (1,0) 7

1  (2,0) 9

\endcode

As we mentioned above, graphs are not containers rather

incidence structures which are iterable in many ways. LEMON introduces

concepts that allow us to attach containers to graphs. These containers are

called maps.

In the example above we create an EdgeMap which assigns an integer value to all

edges of the graph. We use the set member function of the map to write values

into the map and the operator[] to retrieve them.

Here we used the maps provided by the ListGraph class, but you can also write

your own maps. You can read more about using maps \ref maps-page "here".

*/