COIN-OR::LEMON - Graph Library

source: lemon-0.x/doc/graph_io.dox @ 1465:60c2961c75ca

Last change on this file since 1465:60c2961c75ca was 1394:f0c48d7fa73d, checked in by Balazs Dezso, 14 years ago

Modifying the interface.
add -> read, write

File size: 7.1 KB
Line 
1namespace lemon {
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 a 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 map named "id" 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 elements in the line
37are the ID of the source and target node as they occur in the ID 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 <em>labeled nodes</em> (i.e. nodes having a special
48label on them). The section starts with
49\c \@nodes. Each of the next lines contains a label for a node in the graph
50and then the ID described in the nodeset.
51
52\code
53@nodes
54source 3
55target 12
56\endcode
57
58The last section describes the <em>labeled edges</em>
59(i.e. edges having a special label on them). It starts with \c \@edges
60and then each line contains the name of the edge and the ID.
61
62\code
63@nodes
64observed c
65\endcode
66
67The file ends with the \c \@end line.
68
69The file may contain empty lines and comment lines. The comment lines
70start with an \c # character.
71
72\code
73@end
74\endcode
75
76\section use Using graph input-output
77The graph input and output based on writing and reading commands. The user
78adds writing and reading commands for the reader or writer class, then
79calls the \c run() method that executes all the given commands.
80
81\subsection write Writing a graph
82
83The \c GraphWriter class provides the graph output. To write a graph
84you should first give writing commands for the writer. You can declare
85write command as \c NodeMap or \c EdgeMap writing and labeled Node and
86Edge writing.
87
88\code
89GraphWriter<ListGraph> writer(std::cout, graph);
90\endcode
91
92The \c writeNodeMap() function declares a \c NodeMap writing command in the
93\c GraphWriter. You should give as parameter the name of the map and the map
94object. The NodeMap writing command with name "id" should write a
95unique map because it is regarded as ID map.
96
97\see IdMap, DescriptorMap 
98
99\code
100IdMap<ListGraph, Node> nodeIdMap;
101writer.writeNodeMap("id", nodeIdMap);
102
103writer.writeNodeMap("x-coord", xCoordMap);
104writer.writeNodeMap("y-coord", yCoordMap);
105writer.writeNodeMap("color", colorMap);
106\endcode
107
108With the \c writeEdgeMap() member function you can give an edge map
109writing command similar to the NodeMaps.
110
111\see IdMap, DescriptorMap 
112\code
113DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
114writer.writeEdgeMap("descriptor", edgeDescMap);
115
116writer.writeEdgeMap("weight", weightMap);
117writer.writeEdgeMap("label", labelMap);
118\endcode
119
120With \c writeNode() and \c writeEdge() functions you can point out Nodes and
121Edges in the graph. By example, you can write out the source and target
122of the graph.
123
124\code
125writer.writeNode("source", sourceNode);
126writer.writeNode("target", targetNode);
127
128writer.writeEdge("observed", edge);
129\endcode
130
131After you give all write commands you must call the \c run() member
132function, which execute all the writer commands.
133
134\code
135writer.run();
136\endcode
137
138\subsection reading Reading a graph
139
140The given file format may contain several maps and labeled nodes or edges.
141If you read a graph you need not read all the maps and items just those
142that you need. The interface of the \c GraphReader is very similar to
143the GraphWriter but the reading method does not depend on the order the
144given commands.
145
146The reader object suppose that each not readed value does not contain
147whitespaces, therefore it has some extra possibilities to control how
148it should skip the values when the string representation contains spaces.
149
150\code
151GraphReader<ListGraph> reader(std::cin, graph);
152\endcode
153
154The \c readNodeMap() function reads a map from the \c \@nodeset section.
155If there is a map that you do not want to read from the file and there is
156whitespace in the string represenation of the values then you should
157call the \c skipNodeMap() template member function with proper parameters.
158
159\see QuotedStringReader
160\code
161reader.readNodeMap("x-coord", xCoordMap);
162reader.readNodeMap("y-coord", yCoordMap);
163
164reader.readNodeMap<QuotedStringReader>("label", labelMap);
165reader.skipNodeMap<QuotedStringReader>("description");
166
167reader.readNodeMap("color", colorMap);
168\endcode
169
170With the \c readEdgeMap() member function you can give an edge map
171reading command similar to the NodeMaps.
172
173\code
174reader.readEdgeMap("weight", weightMap);
175reader.readEdgeMap("label", labelMap);
176\endcode
177
178With \c readNode() and \c readEdge() functions you can read labeled Nodes and
179Edges.
180
181\code
182reader.readNode("source", sourceNode);
183reader.readNode("target", targetNode);
184
185reader.readEdge("observed", edge);
186\endcode
187
188After you give all read commands you must call the \c run() member
189function, which execute all the commands.
190
191\code
192reader.run();
193\endcode
194
195\section types The background of the Reading and Writing
196The \c GraphReader should know how can read a Value from the given map.
197By the default implementation the input operator reads a value from
198the stream and the type of the readed value is the value type of the given map.
199When the reader should skip a value in the stream, because you do not
200want to store it in map, the reader skips a character sequence without
201whitespace.
202
203If you want to change the functionality of the reader, you can use
204template parameters to specialize it. When you give a reading
205command for a map you can give a Reader type as template parameter.
206With this template parameter you can control how the Reader reads
207a value from the stream.
208
209The reader has the next structure:
210\code
211struct TypeReader {
212  typedef TypeName Value;
213
214  void read(std::istream& is, Value& value);
215};
216\endcode
217
218By example, the \c "strings" nodemap contains strings and you do not need
219the value of the string just the length. Then you can implement own Reader
220struct.
221
222\code
223struct LengthReader {
224  typedef int Value;
225
226  void read(std::istream& is, Value& value) {
227    std::string tmp;
228    is >> tmp;
229    value = tmp.length();
230  }
231};
232...
233reader.readNodeMap<LengthReader>("strings", lengthMap);
234\endcode 
235
236The global functionality of the reader class can be changed by giving a
237special template parameter for the GraphReader class. By default, the
238template parameter is \c DefaultReaderTraits. A reader traits class
239should provide an inner template class Reader for each type, and an
240DefaultReader for skipping a value.
241
242The specialization of the writing should be very similar to the reading.
243
244\author Balazs Dezso
245*/
246}
Note: See TracBrowser for help on using the repository browser.