doc/graph_io.dox
changeset 1671 3c82a0d9e0e7
parent 1540 7d028a73d7f2
child 1788 614ce2dd3cba
equal deleted inserted replaced
8:336dfe133429 9:0f5b35087ec9
   120 writer class, then he calls the \c run() method that executes all the given
   120 writer class, then he calls the \c run() method that executes all the given
   121 commands.
   121 commands.
   122 
   122 
   123 \subsection write Writing a graph
   123 \subsection write Writing a graph
   124 
   124 
   125 The \c GraphWriter class provides the graph output. To write a graph
   125 The \ref lemon::GraphWriter "GraphWriter" template class
       
   126 provides the graph output. To write a graph
   126 you should first give writing commands to the writer. You can declare
   127 you should first give writing commands to the writer. You can declare
   127 writing command as \c NodeMap or \c EdgeMap writing and labeled Node and
   128 writing command as \c NodeMap or \c EdgeMap writing and labeled Node and
   128 Edge writing.
   129 Edge writing.
   129 
   130 
   130 \code
   131 \code
   131 GraphWriter<ListGraph> writer(std::cout, graph);
   132 GraphWriter<ListGraph> writer(std::cout, graph);
   132 \endcode
   133 \endcode
   133 
   134 
   134 The \c writeNodeMap() function declares a \c NodeMap writing command in the
   135 The \ref lemon::GraphWriter::writeNodeMap() "writeNodeMap()"
   135 \c GraphWriter. You should give a name to the map and the map
   136 function declares a \c NodeMap writing command in the
       
   137 \ref lemon::GraphWriter "GraphWriter".
       
   138 You should give a name to the map and the map
   136 object as parameters. The NodeMap writing command with name "id" should write a 
   139 object as parameters. The NodeMap writing command with name "id" should write a 
   137 unique map because it will be regarded as an ID map.
   140 unique map because it will be regarded as an ID map.
   138 
   141 
   139 \see IdMap, DescriptorMap  
   142 \see IdMap, DescriptorMap  
   140 
   143 
   145 writer.writeNodeMap("x-coord", xCoordMap);
   148 writer.writeNodeMap("x-coord", xCoordMap);
   146 writer.writeNodeMap("y-coord", yCoordMap);
   149 writer.writeNodeMap("y-coord", yCoordMap);
   147 writer.writeNodeMap("color", colorMap);
   150 writer.writeNodeMap("color", colorMap);
   148 \endcode
   151 \endcode
   149 
   152 
   150 With the \c writeEdgeMap() member function you can give an edge map
   153 With the \ref lemon::GraphWriter::writeEdgeMap() "writeEdgeMap()"
       
   154 member function you can give an edge map
   151 writing command similar to the NodeMaps.
   155 writing command similar to the NodeMaps.
   152 
   156 
   153 \see IdMap, DescriptorMap  
   157 \see IdMap, DescriptorMap  
   154 
   158 
   155 \code
   159 \code
   158 
   162 
   159 writer.writeEdgeMap("weight", weightMap);
   163 writer.writeEdgeMap("weight", weightMap);
   160 writer.writeEdgeMap("label", labelMap);
   164 writer.writeEdgeMap("label", labelMap);
   161 \endcode
   165 \endcode
   162 
   166 
   163 With \c writeNode() and \c writeEdge() functions you can designate Nodes and
   167 With \ref lemon::GraphWriter::writeNode() "writeNode()"
       
   168 and \ref lemon::GraphWriter::writeEdge() "writeEdge()"
       
   169 functions you can designate Nodes and
   164 Edges in the graph. For example, you can write out the source and target node
   170 Edges in the graph. For example, you can write out the source and target node
   165 of a maximum flow instance.
   171 of a maximum flow instance.
   166 
   172 
   167 \code
   173 \code
   168 writer.writeNode("source", sourceNode);
   174 writer.writeNode("source", sourceNode);
   169 writer.writeNode("target", targetNode);
   175 writer.writeNode("target", targetNode);
   170 
   176 
   171 writer.writeEdge("observed", edge);
   177 writer.writeEdge("observed", edge);
   172 \endcode
   178 \endcode
   173 
   179 
   174 With \c writeAttribute() function you can write an attribute to the file.
   180 With \ref lemon::GraphWriter::writeAttribute() "writeAttribute()"
       
   181 function you can write an attribute to the file.
   175 
   182 
   176 \code
   183 \code
   177 writer.writeAttribute("author", "Balazs DEZSO");
   184 writer.writeAttribute("author", "Balazs DEZSO");
   178 writer.writeAttribute("version", 12);
   185 writer.writeAttribute("version", 12);
   179 \endcode
   186 \endcode
   180 
   187 
   181 After you give all write commands you must call the \c run() member
   188 After you give all write commands you must call the
       
   189 \ref lemon::GraphWriter::run() "run()" member
   182 function, which executes all the writing commands.
   190 function, which executes all the writing commands.
   183 
   191 
   184 \code
   192 \code
   185 writer.run();
   193 writer.run();
   186 \endcode
   194 \endcode
   187 
   195 
   188 \subsection reading Reading a graph
   196 \subsection reading Reading a graph
   189 
   197 
   190 The file to be read may contain several maps and labeled nodes or edges.
   198 The file to be read may contain several maps and labeled nodes or edges.
   191 If you read a graph you need not read all the maps and items just those
   199 If you read a graph you need not read all the maps and items just those
   192 that you need. The interface of the \c GraphReader is very similar to
   200 that you need. The interface of the \ref lemon::GraphReader "GraphReader"
   193 the GraphWriter but the reading method does not depend on the order of the
   201 is very similar to
       
   202 the \ref lemon::GraphWriter "GraphWriter"
       
   203 but the reading method does not depend on the order of the
   194 given commands.
   204 given commands.
   195 
   205 
   196 The reader object assumes that each not readed value does not contain 
   206 The reader object assumes that each not readed value does not contain 
   197 whitespaces, therefore it has some extra possibilities to control how
   207 whitespaces, therefore it has some extra possibilities to control how
   198 it should skip the values when the string representation contains spaces.
   208 it should skip the values when the string representation contains spaces.
   199 
   209 
   200 \code
   210 \code
   201 GraphReader<ListGraph> reader(std::cin, graph);
   211 GraphReader<ListGraph> reader(std::cin, graph);
   202 \endcode
   212 \endcode
   203 
   213 
   204 The \c readNodeMap() function reads a map from the \c nodeset section.
   214 The \ref lemon::GraphReader::readNodeMap() "readNodeMap()"
       
   215 function reads a map from the \c nodeset section.
   205 If there is a map that you do not want to read from the file and there are
   216 If there is a map that you do not want to read from the file and there are
   206 whitespaces in the string represenation of the values then you should
   217 whitespaces in the string represenation of the values then you should
   207 call the \c skipNodeMap() template member function with proper parameters.
   218 call the \ref lemon::GraphReader::skipNodeMap() "skipNodeMap()"
       
   219 template member function with proper parameters.
   208 
   220 
   209 \see QuotedStringReader
   221 \see QuotedStringReader
   210 
   222 
   211 \code
   223 \code
   212 reader.readNodeMap("x-coord", xCoordMap);
   224 reader.readNodeMap("x-coord", xCoordMap);
   216 reader.skipNodeMap<QuotedStringReader>("description");
   228 reader.skipNodeMap<QuotedStringReader>("description");
   217 
   229 
   218 reader.readNodeMap("color", colorMap);
   230 reader.readNodeMap("color", colorMap);
   219 \endcode
   231 \endcode
   220 
   232 
   221 With the \c readEdgeMap() member function you can give an edge map
   233 With the \ref lemon::GraphReader::readEdgeMap() "readEdgeMap()"
       
   234 member function you can give an edge map
   222 reading command similar to the NodeMaps. 
   235 reading command similar to the NodeMaps. 
   223 
   236 
   224 \code
   237 \code
   225 reader.readEdgeMap("weight", weightMap);
   238 reader.readEdgeMap("weight", weightMap);
   226 reader.readEdgeMap("label", labelMap);
   239 reader.readEdgeMap("label", labelMap);
   227 \endcode
   240 \endcode
   228 
   241 
   229 With \c readNode() and \c readEdge() functions you can read labeled Nodes and
   242 With \ref lemon::GraphReader::readNode() "readNode()"
       
   243 and \ref lemon::GraphReader::readEdge() "readEdge()"
       
   244 functions you can read labeled Nodes and
   230 Edges.
   245 Edges.
   231 
   246 
   232 \code
   247 \code
   233 reader.readNode("source", sourceNode);
   248 reader.readNode("source", sourceNode);
   234 reader.readNode("target", targetNode);
   249 reader.readNode("target", targetNode);
   235 
   250 
   236 reader.readEdge("observed", edge);
   251 reader.readEdge("observed", edge);
   237 \endcode
   252 \endcode
   238 
   253 
   239 With \c readAttribute() function you can read an attribute from the file.
   254 With \ref lemon::GraphReader::readAttribute() "readAttribute()"
       
   255 function you can read an attribute from the file.
   240 
   256 
   241 \code
   257 \code
   242 std::string author;
   258 std::string author;
   243 writer.readAttribute("author", author);
   259 writer.readAttribute("author", author);
   244 int version;
   260 int version;
   245 writer.writeAttribute("version", version);
   261 writer.writeAttribute("version", version);
   246 \endcode
   262 \endcode
   247 
   263 
   248 After you give all read commands you must call the \c run() member
   264 After you give all read commands you must call the
       
   265 \ref lemon::GraphReader::run() "run()" member
   249 function, which executes all the commands.
   266 function, which executes all the commands.
   250 
   267 
   251 \code
   268 \code
   252 reader.run();
   269 reader.run();
   253 \endcode
   270 \endcode
   255 \anchor rwbackground
   272 \anchor rwbackground
   256 \section types Background of Reading and Writing
   273 \section types Background of Reading and Writing
   257 
   274 
   258 
   275 
   259 To read a map (on the nodes or edges)
   276 To read a map (on the nodes or edges)
   260 the \c GraphReader should know how to read a Value from the given map.
   277 the \ref lemon::GraphReader "GraphReader"
       
   278 should know how to read a Value from the given map.
   261 By the default implementation the input operator reads a value from
   279 By the default implementation the input operator reads a value from
   262 the stream and the type of the readed value is the value type of the given map.
   280 the stream and the type of the readed value is the value type of the given map.
   263 When the reader should skip a value in the stream, because you do not
   281 When the reader should skip a value in the stream, because you do not
   264 want to store it in a map, the reader skips a character sequence without 
   282 want to store it in a map, the reader skips a character sequence without 
   265 whitespaces. 
   283 whitespaces. 
   335 undiredge 1
   353 undiredge 1
   336 +edge 5
   354 +edge 5
   337 -back 5
   355 -back 5
   338 \endcode
   356 \endcode
   339 
   357 
   340 There are similar classes to the \c GraphReader ans \c GraphWriter
   358 There are similar classes to the \ref lemon::GraphReader "GraphReader" and
   341 which handle the undirected graphs. These classes are the 
   359 \ref lemon::GraphWriter "GraphWriter" which
   342 \c UndirGraphReader and \UndirGraphWriter.
   360 handle the undirected graphs. These classes are
   343 
   361 the \ref lemon::UndirGraphReader "UndirGraphReader"
   344 The \c readUndirMap() function reads an undirected map and the
   362 and \ref lemon::UndirGraphWriter "UndirGraphWriter".
   345 \c readUndirEdge() reads an undirected edge from the file, 
   363 
       
   364 The \ref lemon::UndirGraphReader::readUndirMap() "readUndirMap()"
       
   365 function reads an undirected map and the
       
   366 \ref lemon::UndirGraphReader::readUndirEdge() "readUndirEdge()"
       
   367 reads an undirected edge from the file, 
   346 
   368 
   347 \code
   369 \code
   348 reader.readUndirEdgeMap("capacity", capacityMap);
   370 reader.readUndirEdgeMap("capacity", capacityMap);
   349 reader.readEdgeMap("flow", flowMap);
   371 reader.readEdgeMap("flow", flowMap);
   350 ...
   372 ...
   362 more sections, each starting with a line identifying its type 
   384 more sections, each starting with a line identifying its type 
   363 (the word starting with the \c \@  character).
   385 (the word starting with the \c \@  character).
   364 The content of the section this way cannot contain line with \c \@ first
   386 The content of the section this way cannot contain line with \c \@ first
   365 character. The file may contains comment lines with \c # first character.
   387 character. The file may contains comment lines with \c # first character.
   366 
   388 
   367 The \c LemonReader and \c LemonWriter gives a framework to read and
   389 The \ref lemon::LemonReader "LemonReader"
       
   390 and \ref lemon::LemonWriter "LemonWriter"
       
   391 gives a framework to read and
   368 write sections. There are various section reader and section writer
   392 write sections. There are various section reader and section writer
   369 classes which can be attached to a \c LemonReader or a \c LemonWriter.
   393 classes which can be attached to a \ref lemon::LemonReader "LemonReader"
       
   394 or a \ref lemon::LemonWriter "LemonWriter".
   370 
   395 
   371 There are default section readers and writers for reading and writing
   396 There are default section readers and writers for reading and writing
   372 item sets, and labeled items in the graph. These read and write
   397 item sets, and labeled items in the graph. These read and write
   373 the format described above. Other type of data can be handled with own
   398 the format described above. Other type of data can be handled with own
   374 section reader and writer classes which are inherited from the
   399 section reader and writer classes which are inherited from the
   375 \c LemonReader::SectionReader or the \c LemonWriter::SectionWriter classes.
   400 \c LemonReader::SectionReader or the
       
   401 \ref lemon::LemonWriter::SectionWriter "LemonWriter::SectionWriter"
       
   402 classes.
   376 
   403 
   377 The next example defines a special section reader which reads the
   404 The next example defines a special section reader which reads the
   378 \c \@description sections into a string:
   405 \c \@description sections into a string:
   379 
   406 
   380 \code 
   407 \code 
   412 multiple edgesets can be stored to the same nodeset. It can be used 
   439 multiple edgesets can be stored to the same nodeset. It can be used 
   413 for example as a network traffic matrix.
   440 for example as a network traffic matrix.
   414 
   441 
   415 In our example there is a network with symmetric links and there are assymetric
   442 In our example there is a network with symmetric links and there are assymetric
   416 traffic request on the network. This construction can be stored in an
   443 traffic request on the network. This construction can be stored in an
   417 undirected graph and in a directed NewEdgeSetAdaptor class. The example
   444 undirected graph and in a directed \c NewEdgeSetAdaptor class. The example
   418 shows the input with the LemonReader class:
   445 shows the input with the \ref lemon::LemonReader "LemonReader" class:
   419 
   446 
   420 \code
   447 \code
   421 UndirListGraph network;
   448 UndirListGraph network;
   422 UndirListGraph::UndirEdgeSet<double> capacity;
   449 UndirListGraph::UndirEdgeSet<double> capacity;
   423 NewEdgeSetAdaptor<UndirListGraph> traffic(network);
   450 NewEdgeSetAdaptor<UndirListGraph> traffic(network);
   431 edgesetReader.readEdgeMap("request", request);
   458 edgesetReader.readEdgeMap("request", request);
   432 
   459 
   433 reader.run();
   460 reader.run();
   434 \endcode
   461 \endcode
   435 
   462 
   436 Because the GraphReader and the UndirGraphReader can be converted
   463 Because both the \ref lemon::GraphReader "GraphReader"
   437 to LemonReader and it can resolve the ID's of the items, the previous
   464 and the \ref lemon::UndirGraphReader "UndirGraphReader" can be converted
   438 result can be achived with the UndirGraphReader class, too.
   465 to \ref lemon::LemonReader "LemonReader"
       
   466 and it can resolve the ID's of the items, the previous
       
   467 result can be achived with the \ref lemon::UndirGraphReader "UndirGraphReader"
       
   468 class, too.
   439 
   469 
   440 
   470 
   441 \code
   471 \code
   442 UndirListGraph network;
   472 UndirListGraph network;
   443 UndirListGraph::UndirEdgeSet<double> capacity;
   473 UndirListGraph::UndirEdgeSet<double> capacity;