ladanyi@666: /*! ladanyi@666: ladanyi@666: \page graphs How to use graphs ladanyi@666: alpar@921: The primary data structures of LEMON are the graph classes. They all alpar@756: provide a node list - edge list interface, i.e. they have alpar@756: functionalities to list the nodes and the edges of the graph as well alpar@756: as in incoming and outgoing edges of a given node. alpar@756: alpar@756: alpar@873: Each graph should meet the alpar@921: \ref lemon::skeleton::StaticGraph "StaticGraph" concept. alpar@873: This concept does not alpar@756: makes it possible to change the graph (i.e. it is not possible to add alpar@756: or delete edges or nodes). Most of the graph algorithms will run on alpar@756: these graphs. alpar@756: alpar@873: The graphs meeting the alpar@921: \ref lemon::skeleton::ExtendableGraph "ExtendableGraph" alpar@873: concept allow node and alpar@756: edge addition. You can also "clear" (i.e. erase all edges and nodes) alpar@756: such a graph. alpar@756: alpar@873: In case of graphs meeting the full feature alpar@921: \ref lemon::skeleton::ErasableGraph "ErasableGraph" alpar@873: concept alpar@756: you can also erase individual edges and node in arbitrary order. alpar@756: alpar@756: The implemented graph structures are the following. alpar@921: \li \ref lemon::ListGraph "ListGraph" is the most versatile graph class. It meets alpar@921: the \ref lemon::skeleton::ErasableGraph "ErasableGraph" concept alpar@873: and it also have some convenience features. alpar@921: \li \ref lemon::SmartGraph "SmartGraph" is a more memory alpar@921: efficient version of \ref lemon::ListGraph "ListGraph". The alpar@873: price of it is that it only meets the alpar@921: \ref lemon::skeleton::ExtendableGraph "ExtendableGraph" concept, alpar@756: so you cannot delete individual edges or nodes. alpar@921: \li \ref lemon::SymListGraph "SymListGraph" and alpar@921: \ref lemon::SymSmartGraph "SymSmartGraph" classes are very similar to alpar@921: \ref lemon::ListGraph "ListGraph" and \ref lemon::SmartGraph "SmartGraph". alpar@756: The difference is that whenever you add a alpar@756: new edge to the graph, it actually adds a pair of oppositely directed edges. alpar@756: They are linked together so it is possible to access the counterpart of an alpar@756: edge. An even more important feature is that using these classes you can also alpar@756: attach data to the edges in such a way that the stored data alpar@756: are shared by the edge pairs. alpar@921: \li \ref lemon::FullGraph "FullGraph" alpar@921: implements a full graph. It is a \ref lemon::skeleton::StaticGraph, so you cannot alpar@756: change the number of nodes once it is constructed. It is extremely memory alpar@756: efficient: it uses constant amount of memory independently from the number of alpar@756: the nodes of the graph. Of course, the size of the \ref maps "NodeMap"'s and alpar@756: \ref maps "EdgeMap"'s will depend on the number of nodes. alpar@756: alpar@921: \li \ref lemon::NodeSet "NodeSet" implements a graph with no edges. This class alpar@921: can be used as a base class of \ref lemon::EdgeSet "EdgeSet". alpar@921: \li \ref lemon::EdgeSet "EdgeSet" can be used to create a new graph on alpar@873: the node set of another graph. The base graph can be an arbitrary graph and it alpar@921: is possible to attach several \ref lemon::EdgeSet "EdgeSet"'s to a base graph. alpar@756: alpar@756: \todo Don't we need SmartNodeSet and SmartEdgeSet? alpar@756: \todo Some cross-refs are wrong. alpar@756: alpar@756: The graph structures itself can not store data attached alpar@756: to the edges and nodes. However they all provide alpar@756: \ref maps "map classes" alpar@756: to dynamically attach data the to graph components. alpar@756: alpar@921: The following program demonstrates the basic features of LEMON's graph ladanyi@666: structures. ladanyi@666: ladanyi@666: \code ladanyi@666: #include alpar@921: #include ladanyi@666: alpar@921: using namespace lemon; ladanyi@666: ladanyi@666: int main() ladanyi@666: { ladanyi@666: typedef ListGraph Graph; ladanyi@666: \endcode ladanyi@666: alpar@921: ListGraph is one of LEMON's graph classes. It is based on linked lists, ladanyi@666: therefore iterating throuh its edges and nodes is fast. ladanyi@666: ladanyi@666: \code ladanyi@666: typedef Graph::Edge Edge; ladanyi@666: typedef Graph::InEdgeIt InEdgeIt; ladanyi@666: typedef Graph::OutEdgeIt OutEdgeIt; ladanyi@666: typedef Graph::EdgeIt EdgeIt; ladanyi@666: typedef Graph::Node Node; ladanyi@666: typedef Graph::NodeIt NodeIt; ladanyi@666: ladanyi@666: Graph g; ladanyi@666: ladanyi@666: for (int i = 0; i < 3; i++) ladanyi@666: g.addNode(); ladanyi@666: ladanyi@875: for (NodeIt i(g); i!=INVALID; ++i) ladanyi@875: for (NodeIt j(g); j!=INVALID; ++j) ladanyi@666: if (i != j) g.addEdge(i, j); ladanyi@666: \endcode ladanyi@666: ladanyi@666: After some convenience typedefs we create a graph and add three nodes to it. ladanyi@666: Then we add edges to it to form a full graph. ladanyi@666: ladanyi@666: \code ladanyi@666: std::cout << "Nodes:"; ladanyi@875: for (NodeIt i(g); i!=INVALID; ++i) ladanyi@666: std::cout << " " << g.id(i); ladanyi@666: std::cout << std::endl; ladanyi@666: \endcode ladanyi@666: ladanyi@666: Here we iterate through all nodes of the graph. We use a constructor of the ladanyi@875: node iterator to initialize it to the first node. The operator++ is used to ladanyi@875: step to the next node. Using operator++ on the iterator pointing to the last ladanyi@875: node invalidates the iterator i.e. sets its value to alpar@921: \ref lemon::INVALID "INVALID". This is what we exploit in the stop condition. ladanyi@666: ladanyi@875: The previous code fragment prints out the following: ladanyi@666: ladanyi@666: \code ladanyi@666: Nodes: 2 1 0 ladanyi@666: \endcode ladanyi@666: ladanyi@666: \code ladanyi@666: std::cout << "Edges:"; ladanyi@875: for (EdgeIt i(g); i!=INVALID; ++i) ladanyi@666: std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")"; ladanyi@666: std::cout << std::endl; ladanyi@666: \endcode ladanyi@666: ladanyi@666: \code ladanyi@666: Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0) ladanyi@666: \endcode ladanyi@666: ladanyi@666: We can also iterate through all edges of the graph very similarly. The head and ladanyi@666: tail member functions can be used to access the endpoints of an edge. ladanyi@666: ladanyi@666: \code ladanyi@666: NodeIt first_node(g); ladanyi@666: ladanyi@666: std::cout << "Out-edges of node " << g.id(first_node) << ":"; ladanyi@875: for (OutEdgeIt i(g, first_node); i!=INVALID; ++i) ladanyi@666: std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")"; ladanyi@666: std::cout << std::endl; ladanyi@666: ladanyi@666: std::cout << "In-edges of node " << g.id(first_node) << ":"; ladanyi@875: for (InEdgeIt i(g, first_node); i!=INVALID; ++i) ladanyi@666: std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")"; ladanyi@666: std::cout << std::endl; ladanyi@666: \endcode ladanyi@666: ladanyi@666: \code ladanyi@666: Out-edges of node 2: (2,0) (2,1) ladanyi@666: In-edges of node 2: (0,2) (1,2) ladanyi@666: \endcode ladanyi@666: ladanyi@666: We can also iterate through the in and out-edges of a node. In the above ladanyi@666: example we print out the in and out-edges of the first node of the graph. ladanyi@666: ladanyi@666: \code ladanyi@666: Graph::EdgeMap m(g); ladanyi@666: ladanyi@875: for (EdgeIt e(g); e!=INVALID; ++e) ladanyi@666: m.set(e, 10 - g.id(e)); ladanyi@666: ladanyi@666: std::cout << "Id Edge Value" << std::endl; ladanyi@875: for (EdgeIt e(g); e!=INVALID; ++e) ladanyi@666: std::cout << g.id(e) << " (" << g.id(g.tail(e)) << "," << g.id(g.head(e)) ladanyi@666: << ") " << m[e] << std::endl; ladanyi@666: \endcode ladanyi@666: ladanyi@666: \code ladanyi@666: Id Edge Value ladanyi@666: 4 (0,2) 6 ladanyi@666: 2 (1,2) 8 ladanyi@666: 5 (0,1) 5 ladanyi@666: 0 (2,1) 10 ladanyi@666: 3 (1,0) 7 ladanyi@666: 1 (2,0) 9 ladanyi@666: \endcode ladanyi@666: alpar@873: As we mentioned above, graphs are not containers rather alpar@921: incidence structures which are iterable in many ways. LEMON introduces ladanyi@666: concepts that allow us to attach containers to graphs. These containers are ladanyi@666: called maps. ladanyi@666: ladanyi@666: In the example above we create an EdgeMap which assigns an int value to all ladanyi@666: edges of the graph. We use the set member function of the map to write values ladanyi@666: into the map and the operator[] to retrieve them. ladanyi@666: ladanyi@666: Here we used the maps provided by the ListGraph class, but you can also write ladanyi@666: your own maps. You can read more about using maps \ref maps "here". ladanyi@666: ladanyi@666: */