/* -*- C++ -*-

  *

  * This file is a part of LEMON, a generic C++ optimization library

  *

  * Copyright (C) 2003-2008

  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

  * (Egervary Research Group on Combinatorial Optimization, EGRES).

  *

  * Permission to use, modify and distribute this software is granted

  * provided that this copyright notice appears in all copies. For

  * precise terms see the accompanying LICENSE file.

  *

  * This software is provided "AS IS" with no warranty of any kind,

  * express or implied, and with no claim as to its suitability for any

  * purpose.

  *

  */

 namespace lemon {

 /*!

 \page graphs Graphs

 \todo Write a new Graphs page. I think it should be contain the Graph,

 UGraph and BpUGraph concept. It should be describe the iterators and

 the basic functions and the differences of the implementations.

 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 concepts::Graph "Graph" 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.

 In case of graphs meeting the full feature

 \ref concepts::ErasableGraph "ErasableGraph" concept

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

 The implemented graph structures are the following.

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

 the \ref concepts::ErasableGraph "ErasableGraph" concept

 and it also has some convenient extra features.

 \li \ref SmartGraph is a more memory efficient version of \ref ListGraph.

 The price of this is that it only meets the

 \ref concepts::ExtendableGraph "ExtendableGraph" concept,

 so you cannot delete individual edges or nodes.

 \li \ref FullGraph "FullGraph"

 implements a complete graph. It is a

 \ref concepts::Graph "Graph", 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 NodeSet "NodeSet" implements a graph with no edges. This class

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

 \li \ref 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 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 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".

 */

 }