6 \page graph-io-page Graph Input-Output
8 The standard graph IO makes possible to store graphs and additional maps
9 in a flexible and efficient way.
11 \section format The general file format
13 The graph file contains at most four section in the next order:
20 The nodeset section starts with the \c \@nodeset line.
21 The next line contains the names of the maps separated by whitespaces.
22 Each following line describes a node in the graph, it contains
23 in the right order the values of the maps. The first map should contain
24 unique values because it regarded as Id-map.
28 id x-coord y-coord color
34 The edgeset section is very similar to the nodeset section, it has
35 same coloumn oriented structure. It starts with the line \c \@edgeset
36 The next line contains the whitespace separated list of names of the map.
37 Each of the next lines describes one edge. The first two elements in the line
38 are the ID of the source and target node as they occur in the first node map.
48 The next section contains <em>labeles nodes</em> (i.e. nodes having a special
49 label on them). The section starts with
50 \c \@nodes. Each of the next lines contains a label for a node in the graph
51 and then the ID described in the first column in the nodeset.
59 The last section describes the <em>labeles edges</em>
60 (i.e. edges having a special
61 label on them). It starts with \c \@edges
62 and then each line contains the name of the edge and the ID.
69 The file ends with the \c \@end line.
71 The file may contain empty lines and comment lines. The comment lines
72 start with an \c # character.
78 \section use Using graph input-output
79 The graph input and output based on writing and reading commands. The user
80 adds writing and reading commands for the reader or writer class, then
81 calls the \c run() method that executes all the given commands.
83 \subsection write Writing a graph
85 The \c GraphWriter class provides the graph output. To write a graph
86 you should first give writing commands for the writer. You can declare
87 write command as \c NodeMap or \c EdgeMap writing and labeled Node and
91 GraphWriter<ListGraph> writer(graph);
94 The \c addNodeMap() function declares a \c NodeMap writing command in the
95 \c GraphWriter. You should give as parameter the name of the map and the map
96 object. The first NodeMap writing command should write a unique map because
97 it is regarded as ID map.
99 \see IdMap, DescriptorMap
102 IdMap<ListGraph, Node> nodeIdMap;
103 writer.addNodeMap("id", nodeIdMap);
105 writer.addNodeMap("x-coord", xCoordMap);
106 writer.addNodeMap("y-coord", yCoordMap);
107 writer.addNodeMap("color", colorMap);
110 With the \c addEdgeMap() member function you can give an edge map
111 writing command similar to the NodeMaps. The first map writing command should
114 \see IdMap, DescriptorMap
116 DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
117 writer.addEdgeMap("descriptor", edgeDescMap);
119 writer.addEdgeMap("weight", weightMap);
120 writer.addEdgeMap("label", labelMap);
123 With \c addNode() and \c addEdge() functions you can point out Nodes and
124 Edges in the graph. By example, you can write out the source and target
128 writer.addNode("source", sourceNode);
129 writer.addNode("target", targetNode);
131 writer.addEdge("observed", edge);
134 After you give all write commands you must call the \c run() member
135 function, which execute all the write commands.
141 \subsection reading Reading a graph
143 The given file format may contain several maps and labeled nodes or edges.
144 If you read a graph you need not read all the maps and items just those
145 that you need. The interface of the \c GraphReader is very similar to
146 the GraphWriter but the reading method does not depend on the order the
149 The reader object suppose that each not readed value does not contain
150 whitespaces, therefore it has some extra possibilities to control how
151 it should skip the values when the string representation contains spaces.
154 GraphReader<ListGraph> reader(graph);
157 The \c addNodeMap() function reads a map from the \c \@nodeset section.
158 If there is a map that you do not want to read from the file and there is
159 whitespace in the string represenation of the values then you should
160 call the \c skipNodeMap() template member function with proper parameters.
162 \see QuotedStringReader
164 reader.addNodeMap("x-coord", xCoordMap);
165 reader.addNodeMap("y-coord", yCoordMap);
167 reader.addNodeMap<QuotedStringReader>("label", labelMap);
168 reader.skipNodeMap<QuotedStringReader>("description");
170 reader.addNodeMap("color", colorMap);
173 With the \c addEdgeMap() member function you can give an edge map
174 reading command similar to the NodeMaps.
177 reader.addEdgeMap("weight", weightMap);
178 reader.addEdgeMap("label", labelMap);
181 With \c addNode() and \c addEdge() functions you can read labeled Nodes and
185 reader.addNode("source", sourceNode);
186 reader.addNode("target", targetNode);
188 reader.addEdge("observed", edge);
191 After you give all read commands you must call the \c run() member
192 function, which execute all the commands.
198 \section types The background of the Reading and Writing
199 The \c GraphReader should know how can read a Value from the given map.
200 By the default implementation the input operator reads a value from
201 the stream and the type of the readed value is the value type of the given map.
202 When the reader should skip a value in the stream, because you do not
203 want to store it in map, the reader skips a character sequence without
206 If you want to change the functionality of the reader, you can use
207 template parameters to specialize it. When you give a reading
208 command for a map you can give a Reader type as template parameter.
209 With this template parameter you can control how does read the Reader
210 a value from the stream.
212 The reader has the next structure:
215 typedef TypeName Value;
217 void read(std::istream& is, Value& value);
221 By example, the \c "strings" nodemap contains strings and you do not need
222 the value of the string just the length. Then you can implement own Reader
226 struct LengthReader {
229 void read(std::istream& is, Value& value) {
232 value = tmp.length();
236 reader.addNodeMap<LengthReader>("strings", lengthMap);
239 The global functionality of the reader class can be changed by giving a
240 special template parameter for the GraphReader class. By default, the
241 template parameter is \c DefaultReaderTraits. A reader traits class
242 should provide an inner template class Reader for each type, and an
243 DefaultReader for skipping a value.
245 The specialization of the writing should be very similar to the reading.