1 | namespace lemon { |
---|
2 | |
---|
3 | /** |
---|
4 | \page basic_concepts Basic concepts |
---|
5 | |
---|
6 | \section basic_graph The graph classes |
---|
7 | The most important classes in LEMON are the graph classes. An instance of a graph |
---|
8 | class is the representation of the mathematical graph. It holds the topology and |
---|
9 | every structural information of the graph. The structural manipulations are also |
---|
10 | provided by the graph object. There is no universal graph class instead we have |
---|
11 | different classes for different purposes. They can differ in many ways, but all |
---|
12 | have to satisfy one or more \ref concept "graph concepts" which are standardized |
---|
13 | interfaces to work with the rest of the library. The most basic concept is the |
---|
14 | \ref Graph.<br> |
---|
15 | A good example is the \ref ListGraph which we already know from Hello World and |
---|
16 | will be used in our examples as well. |
---|
17 | |
---|
18 | One main advantage of the templates are, that you can write your own graph classes. |
---|
19 | As long as they provide the interface a concept is defining all the LEMON algorithms |
---|
20 | and classes will work with it properly - no representation or implementation is |
---|
21 | written into stone. |
---|
22 | |
---|
23 | |
---|
24 | \subsection basic_node Nodes |
---|
25 | To refer to a node of a graph we need some kind of typed variable. Graph classes |
---|
26 | have the Node public type for this purpose. Stacking by the last example: |
---|
27 | \code lemon::ListGraph::Node \endcode |
---|
28 | |
---|
29 | If the graph fits the ExtendableGraphComponent concept, then you can add new nodes |
---|
30 | to the graph with the addNode() member function. It returns the newly added node |
---|
31 | (as value). So if you need the new node to do something useful with, for example |
---|
32 | create an edge, assign a value to it through \ref map1 maps. |
---|
33 | \code lemon::ListGraph::Node new_node = graph.addNode(); \endcode |
---|
34 | |
---|
35 | If the graph fits into the ErasableGraphComponent concept you can also remove nodes |
---|
36 | from the graph with the erase() member function. |
---|
37 | \code graph.erase( new_node ); \endcode |
---|
38 | |
---|
39 | You don't have to store every node in a variable, you can access individual nodes |
---|
40 | with node iterators discussed in the next section. But how do you know which |
---|
41 | node is which?<br> |
---|
42 | The graph class has the id( Node n ) member function providing an unique identifier |
---|
43 | assigned to every node. |
---|
44 | |
---|
45 | |
---|
46 | \subsection basic_edge Edges |
---|
47 | An Edge is what you think it is. It goes from one node to another node (they can |
---|
48 | be identical if the edge is a loop). If the graph class is directed, the Edge is directed too. Otherwise |
---|
49 | the edge is considered undirected and called UEdge. |
---|
50 | \code lemon::ListUGraph::UEdge \endcode |
---|
51 | |
---|
52 | The addEdge() member function will create a new edge. It has two arguments, the |
---|
53 | source node and the target node. The graph class must be extendable. |
---|
54 | \code lemon::ListGraph::Edge new_edge = graph.addEdge( src_node, trg_node ); \endcode |
---|
55 | You can handle edges similar as nodes. The erase() member function has an edge taking |
---|
56 | overload too. |
---|
57 | |
---|
58 | You can ask for the source or target node of the edge by the corresponding member |
---|
59 | functions: |
---|
60 | \code |
---|
61 | graph.source( new_edge ); |
---|
62 | lemon::ListGraph::Node n = graph.target( new_edge ); \endcode |
---|
63 | These functions are always legal even if the graph is undirected. UEdge has a |
---|
64 | default direction. |
---|
65 | |
---|
66 | |
---|
67 | \section basic_iterators Iterators |
---|
68 | Graphs are some kind of containers. And as you expect they have iterator types. |
---|
69 | One for nodes and a couple for edges - and special classes can have additional |
---|
70 | iterators too. An example: |
---|
71 | \code lemon::ListGraph::NodeIt \endcode |
---|
72 | This is a node iterator. Every iterator type starts with a name that refers to |
---|
73 | the iterated object, and ends with 'It'. |
---|
74 | |
---|
75 | LEMON style iterators differ from \c stl or \c boost iterators in a very tasty |
---|
76 | way. A graph has no begin or end - or at least a generic graph class has none. |
---|
77 | If by some topology you could pick a good begin node, it would be misleading and |
---|
78 | incorrect. A LEMON style iterator must be initialized at construction time. |
---|
79 | The constructor takes the needed parameters - by a node iterator it's the graph |
---|
80 | object. And will be compared to the lemon::INVALID to check if it's still valid. |
---|
81 | Every iterator can be compared to INVALID. No \c begin() or \c end() needed.<br> |
---|
82 | Let's see these things working together: |
---|
83 | \code |
---|
84 | for( ListGraph::NodeIt n(graph); n != INVALID; ++n ) |
---|
85 | do_useful_things_with_node(n); |
---|
86 | \endcode |
---|
87 | Note that the function \c do_useful_things_with_node() expects a Node type argument |
---|
88 | ad we just gave him the iterator. LEMON style iterators must provide "on demand |
---|
89 | dereferencing". For example a NodeIt can be used everywhere a Node could. (In some |
---|
90 | graph classes Node is the base class of NodeIt. But in other cases this is implemented |
---|
91 | through typecast operator.) |
---|
92 | |
---|
93 | <b>Very important!</b> The iteration has no defined order. There is absolutely no |
---|
94 | warranty that the next time the iteration will give us the nodes in the same order. |
---|
95 | Don't use this order to identify nodes! Use the \c id() member function of the |
---|
96 | graph class described above. (There is a powerful technique using maps right in |
---|
97 | the next page.) |
---|
98 | |
---|
99 | The \ref EdgeIt works exactly the same - nothing more to say. But there are \ref InEdgeIt |
---|
100 | and \ref OutEdgeIt by directed graphs and \ref IncEdgeIt by undirected graphs. |
---|
101 | They take two arguments. The first is a graph, the second is certain node of the |
---|
102 | graph. InEdgeIt iterates on the incoming edges of that node and OutEdgeIt does it |
---|
103 | on the outgoing edges. The IncEdgeIt of course iterates every edge connecting to |
---|
104 | the given node. |
---|
105 | |
---|
106 | \code |
---|
107 | for( ListGraph::NodeIt n(graph); n != INVALID; ++n ) { |
---|
108 | int in = 0, out = 0; |
---|
109 | for( ListGraph::InEdgeIt e(graph,n); e != INVALID; ++e ) ++in; |
---|
110 | for( ListGraph::OutEdgeIt e(graph,n); e != INVALID; ++e ) ++out; |
---|
111 | |
---|
112 | std::cout << "#" << graph.id(n) << " node has " << in << " incoming and " |
---|
113 | << out << "outgoing edges." << std::endl; |
---|
114 | } |
---|
115 | \endcode |
---|
116 | |
---|
117 | |
---|
118 | \section basic_ListGraph ListGraph - a versatile directed graph |
---|
119 | As you see ListGraph satisfies most of the basic concepts and ideal for general |
---|
120 | graph representations. It has an undirected version too: ListUGraph. |
---|
121 | */ |
---|
122 | |
---|
123 | } |
---|