COIN-OR::LEMON - Graph Library

source: lemon-0.x/doc/graph_io.dox @ 1117:5767cc417f62

Last change on this file since 1117:5767cc417f62 was 1114:eb57527fd183, checked in by Balazs Dezso, 15 years ago

Tutorial for graph input - output

File size: 7.0 KB
Line 
1/*!
2
3
4
5\page graph-io-page Graph Input-Output
6
7The standard graph IO makes possible to store graphs and additional maps
8in flexible and efficient way.
9
10\section format The general file format
11
12The graph file contains at most four section in the next order:
13
14\li nodeset
15\li edgeset
16\li nodes
17\li edges
18
19The nodeset section starts with the \c \@nodeset line.
20The next line contains the names of the maps separated by whitespaces.
21Each following line describes a node in the graph, it contains
22in the right order the values of the maps. The first map should contain
23unique values because it regarded as Id-map.
24
25\code
26@nodeset
27id  x-coord  y-coord  color
283   1.0      4.0      blue
295   2.3      5.7      red
3012  7.8      2.3      green
31\endcode
32
33The edgeset section is very similar to the nodeset section, it has
34same coloumn oriented structure. It starts with the line \c \@edgeset
35The next line contains the whitespace separated list of names of the map.
36Each of the next lines describes one edge. The first two element in the line
37is the ID of the source and target node as occurs in the first node map.
38
39\code
40@edgeset
41             id    weight   label
423   5        a     4.3      a-edge
435   12       c     2.6      c-edge
443   12       g     3.4      g-edge
45\endcode
46
47The next section contains outpointed nodes. The section starts with
48\c \@nodes. Each of the next lines contains a label for a node in the graph
49and then the ID described in the first column in the nodeset.
50
51\code
52@nodes
53source 3
54target 12
55\endcode
56
57The last section describes the outpointed edges. It starts with \c \@edges
58and then each line contains the name of the edge and the ID.
59
60\code
61@nodes
62observed c
63\endcode
64
65The file ends with the \c \@end line.
66
67The file may contain empty lines and comment lines. The comment lines
68start with an \c # character.
69
70\code
71@end
72\endcode
73
74\section use Using graph input-output
75The graph input and output based on writing and reading commands. The user
76adds writing and reading commands for the reader or writer class, after
77calls the \c run() method what executes all the given commands.
78
79\subsection write Writing a graph
80
81The \c GraphWriter class provides the graph output. To write a graph
82you should first give writing commands for the writer. You can declare
83write command as \c NodeMap or \c EdgeMap writing and outpointed Node and
84Edge writing.
85
86\code
87GraphWriter<ListGraph> writer(graph);
88\endcode
89
90The \c addNodeMap() function declares a \c NodeMap writing command in the
91\c GraphWriter. You should give as parameter the name of the map and the map
92object. The first NodeMap writing command should write an unique map because
93it is regarded as ID map.
94
95\see IdMap, DescriptorMap 
96
97\code
98IdMap<ListGraph, Node> nodeIdMap;
99writer.addNodeMap("id", nodeIdMap);
100
101writer.addNodeMap("x-coord", xCoordMap);
102writer.addNodeMap("y-coord", yCoordMap);
103writer.addNodeMap("color", colorMap);
104\endcode
105
106With the \c addEdgeMap() member function you can give an edge map
107writing command similar to the NodeMaps. The first map writing command should
108write unique map.
109
110\see IdMap, DescriptorMap 
111\code
112DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
113writer.addEdgeMap("descriptor", edgeDescMap);
114
115writer.addEdgeMap("weight", weightMap);
116writer.addEdgeMap("label", labelMap);
117\endcode
118
119With \c addNode() and \c addEdge() functions you can point out Nodes and
120Edges in the graph. By example, you can write out the source and target
121of the graph.
122
123\code
124writer.addNode("source", sourceNode);
125writer.addNode("target", targetNode);
126
127writer.addEdge("observed", edge);
128\endcode
129
130After you give all write commands you must call the \c run() member
131function, what execute all the write commands.
132
133\code
134writer.run();
135\endcode
136
137\subsection reading Reading a graph
138
139The given file format may contain many maps and outpointed nodes or edges.
140If you read a graph you need not read all the maps and items just those
141that you need. The interface of the \c GraphReader is very similar to
142the GraphWriter but the reading method does not depend on the order the
143given commands.
144
145The reader object suppose that each not readed value does not contains
146whitespaces therefore it has some extra possibilities to control how could
147it skip the values when the string representation contains spaces.
148
149\code
150GraphReader<ListGraph> reader(graph);
151\endcode
152
153The \c addNodeMap() function reads a map from the \c \@nodeset section.
154If there is a map what you do not want to read from the file and there is
155whitespace in the string represenation of the values then you should
156call the \c skipNodeMap() template member function with proper parameters.
157
158\see QuotedStringReader
159\code
160reader.addNodeMap("x-coord", xCoordMap);
161reader.addNodeMap("y-coord", yCoordMap);
162
163reader.addNodeMap<QuotedStringReader>("label", labelMap);
164reader.skipNodeMap<QuotedStringReader>("description");
165
166reader.addNodeMap("color", colorMap);
167\endcode
168
169With the \c addEdgeMap() member function you can give an edge map
170reading command similar to the NodeMaps.
171
172\code
173reader.addEdgeMap("weight", weightMap);
174reader.addEdgeMap("label", labelMap);
175\endcode
176
177With \c addNode() and \c addEdge() functions you can read outpointed Nodes and
178Edges.
179
180\code
181reader.addNode("source", sourceNode);
182reader.addNode("target", targetNode);
183
184reader.addEdge("observed", edge);
185\endcode
186
187After you give all read commands you must call the \c run() member
188function, what execute all the commands.
189
190\code
191reader.run();
192\endcode
193
194\section types The background of the Reading and Writing
195The \c GraphReader should know how can read a Value from the given map.
196By the default implementation the input operator reads a value from
197the stream and the type of the readed value is the value type of the given map.
198When the reader should skip a value in the stream, because you do not
199want to store it in map, the reader skips a character sequence without
200whitespace.
201
202If you want to change the functionality of the reader, you can use
203template parameters to specialize it. When you give a reading
204command for a map you can give a Reader type as template parameter.
205With this template parameter you can control how does read the Reader
206a value from the stream.
207
208The reader has the next structure:
209\code
210struct TypeReader {
211  typedef TypeName Value;
212
213  void read(std::istream& is, Value& value);
214};
215\endcode
216
217By example, the \c "strings" nodemap contains strings and you do not need
218the value of the string just the length. Then you can implement own Reader
219struct.
220
221\code
222struct LengthReader {
223  typedef int Value;
224
225  void read(std::istream& is, Value& value) {
226    std::string tmp;
227    is >> tmp;
228    value = tmp.length();
229  }
230};
231...
232reader.addNodeMap<LengthReader>("strings", lengthMap);
233\endcode 
234
235The global functionality of the reader class can be changed by giving a
236special template parameter for the GraphReader class. In default way the
237template parameter the \c DefaultReaderTraits. A reader traits class
238should provide an inner template class Reader for each type, and an
239DefaultReader for skipping a value.
240
241The specialization of the writing should be very similar to the reading.
242
243
244*/
Note: See TracBrowser for help on using the repository browser.