5 \page graph-io-page Graph Input-Output
7 The standard graph IO makes possible to store graphs and additional maps
8 in flexible and efficient way.
10 \section format The general file format
12 The graph file contains at most four section in the next order:
19 The nodeset section starts with the \c \@nodeset line.
20 The next line contains the names of the maps separated by whitespaces.
21 Each following line describes a node in the graph, it contains
22 in the right order the values of the maps. The first map should contain
23 unique values because it regarded as Id-map.
27 id x-coord y-coord color
33 The edgeset section is very similar to the nodeset section, it has
34 same coloumn oriented structure. It starts with the line \c \@edgeset
35 The next line contains the whitespace separated list of names of the map.
36 Each of the next lines describes one edge. The first two element in the line
37 is the ID of the source and target node as occurs in the first node map.
47 The 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
49 and then the ID described in the first column in the nodeset.
57 The last section describes the outpointed edges. It starts with \c \@edges
58 and then each line contains the name of the edge and the ID.
65 The file ends with the \c \@end line.
67 The file may contain empty lines and comment lines. The comment lines
68 start with an \c # character.
74 \section use Using graph input-output
75 The graph input and output based on writing and reading commands. The user
76 adds writing and reading commands for the reader or writer class, after
77 calls the \c run() method what executes all the given commands.
79 \subsection write Writing a graph
81 The \c GraphWriter class provides the graph output. To write a graph
82 you should first give writing commands for the writer. You can declare
83 write command as \c NodeMap or \c EdgeMap writing and outpointed Node and
87 GraphWriter<ListGraph> writer(graph);
90 The \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
92 object. The first NodeMap writing command should write an unique map because
93 it is regarded as ID map.
95 \see IdMap, DescriptorMap
98 IdMap<ListGraph, Node> nodeIdMap;
99 writer.addNodeMap("id", nodeIdMap);
101 writer.addNodeMap("x-coord", xCoordMap);
102 writer.addNodeMap("y-coord", yCoordMap);
103 writer.addNodeMap("color", colorMap);
106 With the \c addEdgeMap() member function you can give an edge map
107 writing command similar to the NodeMaps. The first map writing command should
110 \see IdMap, DescriptorMap
112 DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
113 writer.addEdgeMap("descriptor", edgeDescMap);
115 writer.addEdgeMap("weight", weightMap);
116 writer.addEdgeMap("label", labelMap);
119 With \c addNode() and \c addEdge() functions you can point out Nodes and
120 Edges in the graph. By example, you can write out the source and target
124 writer.addNode("source", sourceNode);
125 writer.addNode("target", targetNode);
127 writer.addEdge("observed", edge);
130 After you give all write commands you must call the \c run() member
131 function, what execute all the write commands.
137 \subsection reading Reading a graph
139 The given file format may contain many maps and outpointed nodes or edges.
140 If you read a graph you need not read all the maps and items just those
141 that you need. The interface of the \c GraphReader is very similar to
142 the GraphWriter but the reading method does not depend on the order the
145 The reader object suppose that each not readed value does not contains
146 whitespaces therefore it has some extra possibilities to control how could
147 it skip the values when the string representation contains spaces.
150 GraphReader<ListGraph> reader(graph);
153 The \c addNodeMap() function reads a map from the \c \@nodeset section.
154 If there is a map what you do not want to read from the file and there is
155 whitespace in the string represenation of the values then you should
156 call the \c skipNodeMap() template member function with proper parameters.
158 \see QuotedStringReader
160 reader.addNodeMap("x-coord", xCoordMap);
161 reader.addNodeMap("y-coord", yCoordMap);
163 reader.addNodeMap<QuotedStringReader>("label", labelMap);
164 reader.skipNodeMap<QuotedStringReader>("description");
166 reader.addNodeMap("color", colorMap);
169 With the \c addEdgeMap() member function you can give an edge map
170 reading command similar to the NodeMaps.
173 reader.addEdgeMap("weight", weightMap);
174 reader.addEdgeMap("label", labelMap);
177 With \c addNode() and \c addEdge() functions you can read outpointed Nodes and
181 reader.addNode("source", sourceNode);
182 reader.addNode("target", targetNode);
184 reader.addEdge("observed", edge);
187 After you give all read commands you must call the \c run() member
188 function, what execute all the commands.
194 \section types The background of the Reading and Writing
195 The \c GraphReader should know how can read a Value from the given map.
196 By the default implementation the input operator reads a value from
197 the stream and the type of the readed value is the value type of the given map.
198 When the reader should skip a value in the stream, because you do not
199 want to store it in map, the reader skips a character sequence without
202 If you want to change the functionality of the reader, you can use
203 template parameters to specialize it. When you give a reading
204 command for a map you can give a Reader type as template parameter.
205 With this template parameter you can control how does read the Reader
206 a value from the stream.
208 The reader has the next structure:
211 typedef TypeName Value;
213 void read(std::istream& is, Value& value);
217 By example, the \c "strings" nodemap contains strings and you do not need
218 the value of the string just the length. Then you can implement own Reader
222 struct LengthReader {
225 void read(std::istream& is, Value& value) {
228 value = tmp.length();
232 reader.addNodeMap<LengthReader>("strings", lengthMap);
235 The global functionality of the reader class can be changed by giving a
236 special template parameter for the GraphReader class. In default way the
237 template parameter the \c DefaultReaderTraits. A reader traits class
238 should provide an inner template class Reader for each type, and an
239 DefaultReader for skipping a value.
241 The specialization of the writing should be very similar to the reading.