COIN-OR::LEMON - Graph Library

source: lemon-0.x/doc/graph_io.dox @ 1424:c3d754f5e631

Last change on this file since 1424:c3d754f5e631 was 1394:f0c48d7fa73d, checked in by Balazs Dezso, 19 years ago

Modifying the interface.
add -> read, write

File size: 7.1 KB
RevLine 
[1118]1namespace lemon {
[1114]2/*!
3
4
5\page graph-io-page Graph Input-Output
6
7The standard graph IO makes possible to store graphs and additional maps
[1118]8in a flexible and efficient way.
[1114]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
[1333]22in the right order the values of the maps. The map named "id" should contain
23unique values because it regarded as ID-map.
[1114]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.
[1118]36Each of the next lines describes one edge. The first two elements in the line
[1333]37are the ID of the source and target node as they occur in the ID node map.
[1114]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
[1333]47The next section contains <em>labeled nodes</em> (i.e. nodes having a special
[1118]48label on them). The section starts with
[1114]49\c \@nodes. Each of the next lines contains a label for a node in the graph
[1333]50and then the ID described in the nodeset.
[1114]51
52\code
53@nodes
54source 3
55target 12
56\endcode
57
[1333]58The last section describes the <em>labeled edges</em>
59(i.e. edges having a special label on them). It starts with \c \@edges
[1114]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
[1118]78adds writing and reading commands for the reader or writer class, then
79calls the \c run() method that executes all the given commands.
[1114]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
[1118]85write command as \c NodeMap or \c EdgeMap writing and labeled Node and
[1114]86Edge writing.
87
88\code
[1333]89GraphWriter<ListGraph> writer(std::cout, graph);
[1114]90\endcode
91
[1394]92The \c writeNodeMap() function declares a \c NodeMap writing command in the
[1114]93\c GraphWriter. You should give as parameter the name of the map and the map
[1333]94object. The NodeMap writing command with name "id" should write a
95unique map because it is regarded as ID map.
[1114]96
97\see IdMap, DescriptorMap 
98
99\code
100IdMap<ListGraph, Node> nodeIdMap;
[1394]101writer.writeNodeMap("id", nodeIdMap);
[1114]102
[1394]103writer.writeNodeMap("x-coord", xCoordMap);
104writer.writeNodeMap("y-coord", yCoordMap);
105writer.writeNodeMap("color", colorMap);
[1114]106\endcode
107
[1394]108With the \c writeEdgeMap() member function you can give an edge map
[1333]109writing command similar to the NodeMaps.
[1114]110
111\see IdMap, DescriptorMap 
112\code
113DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
[1394]114writer.writeEdgeMap("descriptor", edgeDescMap);
[1114]115
[1394]116writer.writeEdgeMap("weight", weightMap);
117writer.writeEdgeMap("label", labelMap);
[1114]118\endcode
119
[1394]120With \c writeNode() and \c writeEdge() functions you can point out Nodes and
[1114]121Edges in the graph. By example, you can write out the source and target
122of the graph.
123
124\code
[1394]125writer.writeNode("source", sourceNode);
126writer.writeNode("target", targetNode);
[1114]127
[1394]128writer.writeEdge("observed", edge);
[1114]129\endcode
130
131After you give all write commands you must call the \c run() member
[1333]132function, which execute all the writer commands.
[1114]133
134\code
135writer.run();
136\endcode
137
138\subsection reading Reading a graph
139
[1118]140The given file format may contain several maps and labeled nodes or edges.
[1114]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
[1118]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.
[1114]149
150\code
[1333]151GraphReader<ListGraph> reader(std::cin, graph);
[1114]152\endcode
153
[1394]154The \c readNodeMap() function reads a map from the \c \@nodeset section.
[1118]155If there is a map that you do not want to read from the file and there is
[1114]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
[1394]161reader.readNodeMap("x-coord", xCoordMap);
162reader.readNodeMap("y-coord", yCoordMap);
[1114]163
[1394]164reader.readNodeMap<QuotedStringReader>("label", labelMap);
[1114]165reader.skipNodeMap<QuotedStringReader>("description");
166
[1394]167reader.readNodeMap("color", colorMap);
[1114]168\endcode
169
[1394]170With the \c readEdgeMap() member function you can give an edge map
[1114]171reading command similar to the NodeMaps.
172
173\code
[1394]174reader.readEdgeMap("weight", weightMap);
175reader.readEdgeMap("label", labelMap);
[1114]176\endcode
177
[1394]178With \c readNode() and \c readEdge() functions you can read labeled Nodes and
[1114]179Edges.
180
181\code
[1394]182reader.readNode("source", sourceNode);
183reader.readNode("target", targetNode);
[1114]184
[1394]185reader.readEdge("observed", edge);
[1114]186\endcode
187
188After you give all read commands you must call the \c run() member
[1118]189function, which execute all the commands.
[1114]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.
[1333]206With this template parameter you can control how the Reader reads
[1114]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...
[1394]233reader.readNodeMap<LengthReader>("strings", lengthMap);
[1114]234\endcode 
235
236The global functionality of the reader class can be changed by giving a
[1118]237special template parameter for the GraphReader class. By default, the
238template parameter is \c DefaultReaderTraits. A reader traits class
[1114]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
[1333]244\author Balazs Dezso
[1114]245*/
[1333]246}
Note: See TracBrowser for help on using the repository browser.