1.1 --- a/lemon/lgf_reader.h Fri Jul 04 16:12:31 2008 +0200
1.2 +++ b/lemon/lgf_reader.h Sat Jul 05 00:14:27 2008 +0200
1.3 @@ -18,7 +18,7 @@
1.4
1.5 ///\ingroup lemon_io
1.6 ///\file
1.7 -///\brief Lemon Graph Format reader.
1.8 +///\brief \ref lgf-format "Lemon Graph Format" reader.
1.9
1.10
1.11 #ifndef LEMON_LGF_READER_H
1.12 @@ -400,7 +400,7 @@
1.13
1.14 /// \ingroup lemon_io
1.15 ///
1.16 - /// \brief LGF reader for directed graphs
1.17 + /// \brief \ref lgf-format "LGF" reader for directed graphs
1.18 ///
1.19 /// This utility reads an \ref lgf-format "LGF" file.
1.20 ///
1.21 @@ -410,22 +410,22 @@
1.22 /// member function. A map reading rule can be added to the reader
1.23 /// with the \c nodeMap() or \c arcMap() members. An optional
1.24 /// converter parameter can also be added as a standard functor
1.25 - /// converting from std::string to the value type of the map. If it
1.26 + /// converting from \c std::string to the value type of the map. If it
1.27 /// is set, it will determine how the tokens in the file should be
1.28 - /// is converted to the map's value type. If the functor is not set,
1.29 + /// converted to the value type of the map. If the functor is not set,
1.30 /// then a default conversion will be used. One map can be read into
1.31 /// multiple map objects at the same time. The \c attribute(), \c
1.32 /// node() and \c arc() functions are used to add attribute reading
1.33 /// rules.
1.34 ///
1.35 ///\code
1.36 - /// DigraphReader<Digraph>(std::cin, digraph).
1.37 - /// nodeMap("coordinates", coord_map).
1.38 - /// arcMap("capacity", cap_map).
1.39 - /// node("source", src).
1.40 - /// node("target", trg).
1.41 - /// attribute("caption", caption).
1.42 - /// run();
1.43 + /// DigraphReader<Digraph>(std::cin, digraph).
1.44 + /// nodeMap("coordinates", coord_map).
1.45 + /// arcMap("capacity", cap_map).
1.46 + /// node("source", src).
1.47 + /// node("target", trg).
1.48 + /// attribute("caption", caption).
1.49 + /// run();
1.50 ///\endcode
1.51 ///
1.52 /// By default the reader uses the first section in the file of the
1.53 @@ -437,14 +437,14 @@
1.54 /// that the nodes or arcs should not be constructed (added to the
1.55 /// graph) during the reading, but instead the label map of the items
1.56 /// are given as a parameter of these functions. An
1.57 - /// application of these function is multipass reading, which is
1.58 - /// important if two \e \@arcs sections must be read from the
1.59 - /// file. In this example the first phase would read the node set and one
1.60 + /// application of these functions is multipass reading, which is
1.61 + /// important if two \c \@arcs sections must be read from the
1.62 + /// file. In this case the first phase would read the node set and one
1.63 /// of the arc sets, while the second phase would read the second arc
1.64 /// set into an \e ArcSet class (\c SmartArcSet or \c ListArcSet).
1.65 /// The previously read label node map should be passed to the \c
1.66 /// useNodes() functions. Another application of multipass reading when
1.67 - /// paths are given as a node map or an arc map. It is impossible read this in
1.68 + /// paths are given as a node map or an arc map. It is impossible to read this in
1.69 /// a single pass, because the arcs are not constructed when the node
1.70 /// maps are read.
1.71 template <typename _Digraph>
1.72 @@ -735,7 +735,7 @@
1.73 ///
1.74 /// Use previously constructed node set, and specify the node
1.75 /// label map and a functor which converts the label map values to
1.76 - /// std::string.
1.77 + /// \c std::string.
1.78 template <typename Map, typename Converter>
1.79 DigraphReader& useNodes(const Map& map,
1.80 const Converter& converter = Converter()) {
1.81 @@ -768,7 +768,7 @@
1.82 ///
1.83 /// Use previously constructed arc set, and specify the arc
1.84 /// label map and a functor which converts the label map values to
1.85 - /// std::string.
1.86 + /// \c std::string.
1.87 template <typename Map, typename Converter>
1.88 DigraphReader& useArcs(const Map& map,
1.89 const Converter& converter = Converter()) {
1.90 @@ -784,12 +784,11 @@
1.91 /// \brief Skips the reading of node section
1.92 ///
1.93 /// Omit the reading of the node section. This implies that each node
1.94 - /// map reading rule will be abanoned, and the nodes of the graph
1.95 + /// map reading rule will be abandoned, and the nodes of the graph
1.96 /// will not be constructed, which usually cause that the arc set
1.97 - /// could not be read due to lack of node name
1.98 - /// resolving. Therefore, the \c skipArcs() should be used too, or
1.99 - /// the useNodes() member function should be used to specify the
1.100 - /// label of the nodes.
1.101 + /// could not be read due to lack of node name resolving.
1.102 + /// Therefore \c skipArcs() function should also be used, or
1.103 + /// \c useNodes() should be used to specify the label of the nodes.
1.104 DigraphReader& skipNodes() {
1.105 LEMON_ASSERT(!_skip_nodes, "Skip nodes already set");
1.106 _skip_nodes = true;
1.107 @@ -799,7 +798,7 @@
1.108 /// \brief Skips the reading of arc section
1.109 ///
1.110 /// Omit the reading of the arc section. This implies that each arc
1.111 - /// map reading rule will be abanoned, and the arcs of the graph
1.112 + /// map reading rule will be abandoned, and the arcs of the graph
1.113 /// will not be constructed.
1.114 DigraphReader& skipArcs() {
1.115 LEMON_ASSERT(!_skip_arcs, "Skip arcs already set");
1.116 @@ -1175,6 +1174,9 @@
1.117
1.118 };
1.119
1.120 + /// \brief Return a \ref DigraphReader class
1.121 + ///
1.122 + /// This function just returns a \ref DigraphReader class.
1.123 /// \relates DigraphReader
1.124 template <typename Digraph>
1.125 DigraphReader<Digraph> digraphReader(std::istream& is, Digraph& digraph) {
1.126 @@ -1182,6 +1184,9 @@
1.127 return tmp;
1.128 }
1.129
1.130 + /// \brief Return a \ref DigraphReader class
1.131 + ///
1.132 + /// This function just returns a \ref DigraphReader class.
1.133 /// \relates DigraphReader
1.134 template <typename Digraph>
1.135 DigraphReader<Digraph> digraphReader(const std::string& fn,
1.136 @@ -1190,6 +1195,9 @@
1.137 return tmp;
1.138 }
1.139
1.140 + /// \brief Return a \ref DigraphReader class
1.141 + ///
1.142 + /// This function just returns a \ref DigraphReader class.
1.143 /// \relates DigraphReader
1.144 template <typename Digraph>
1.145 DigraphReader<Digraph> digraphReader(const char* fn, Digraph& digraph) {
1.146 @@ -1211,9 +1219,13 @@
1.147
1.148 /// \ingroup lemon_io
1.149 ///
1.150 - /// \brief LGF reader for undirected graphs
1.151 + /// \brief \ref lgf-format "LGF" reader for undirected graphs
1.152 ///
1.153 /// This utility reads an \ref lgf-format "LGF" file.
1.154 + ///
1.155 + /// It can be used almost the same way as \c DigraphReader.
1.156 + /// The only difference is that this class can handle edges and
1.157 + /// edge maps as well as arcs and arc maps.
1.158 template <typename _Graph>
1.159 class GraphReader {
1.160 public:
1.161 @@ -1262,7 +1274,7 @@
1.162
1.163 /// \brief Constructor
1.164 ///
1.165 - /// Construct a undirected graph reader, which reads from the given
1.166 + /// Construct an undirected graph reader, which reads from the given
1.167 /// input stream.
1.168 GraphReader(std::istream& is, Graph& graph)
1.169 : _is(&is), local_is(false), _graph(graph),
1.170 @@ -1271,7 +1283,7 @@
1.171
1.172 /// \brief Constructor
1.173 ///
1.174 - /// Construct a undirected graph reader, which reads from the given
1.175 + /// Construct an undirected graph reader, which reads from the given
1.176 /// file.
1.177 GraphReader(const std::string& fn, Graph& graph)
1.178 : _is(new std::ifstream(fn.c_str())), local_is(true), _graph(graph),
1.179 @@ -1280,7 +1292,7 @@
1.180
1.181 /// \brief Constructor
1.182 ///
1.183 - /// Construct a undirected graph reader, which reads from the given
1.184 + /// Construct an undirected graph reader, which reads from the given
1.185 /// file.
1.186 GraphReader(const char* fn, Graph& graph)
1.187 : _is(new std::ifstream(fn)), local_is(true), _graph(graph),
1.188 @@ -1497,7 +1509,7 @@
1.189
1.190 /// \brief Set \c \@nodes section to be read
1.191 ///
1.192 - /// Set \c \@nodes section to be read
1.193 + /// Set \c \@nodes section to be read.
1.194 GraphReader& nodes(const std::string& caption) {
1.195 _nodes_caption = caption;
1.196 return *this;
1.197 @@ -1505,7 +1517,7 @@
1.198
1.199 /// \brief Set \c \@edges section to be read
1.200 ///
1.201 - /// Set \c \@edges section to be read
1.202 + /// Set \c \@edges section to be read.
1.203 GraphReader& edges(const std::string& caption) {
1.204 _edges_caption = caption;
1.205 return *this;
1.206 @@ -1513,7 +1525,7 @@
1.207
1.208 /// \brief Set \c \@attributes section to be read
1.209 ///
1.210 - /// Set \c \@attributes section to be read
1.211 + /// Set \c \@attributes section to be read.
1.212 GraphReader& attributes(const std::string& caption) {
1.213 _attributes_caption = caption;
1.214 return *this;
1.215 @@ -1544,7 +1556,7 @@
1.216 ///
1.217 /// Use previously constructed node set, and specify the node
1.218 /// label map and a functor which converts the label map values to
1.219 - /// std::string.
1.220 + /// \c std::string.
1.221 template <typename Map, typename Converter>
1.222 GraphReader& useNodes(const Map& map,
1.223 const Converter& converter = Converter()) {
1.224 @@ -1577,7 +1589,7 @@
1.225 ///
1.226 /// Use previously constructed edge set, and specify the edge
1.227 /// label map and a functor which converts the label map values to
1.228 - /// std::string.
1.229 + /// \c std::string.
1.230 template <typename Map, typename Converter>
1.231 GraphReader& useEdges(const Map& map,
1.232 const Converter& converter = Converter()) {
1.233 @@ -1590,25 +1602,25 @@
1.234 return *this;
1.235 }
1.236
1.237 - /// \brief Skips the reading of node section
1.238 + /// \brief Skip the reading of node section
1.239 ///
1.240 /// Omit the reading of the node section. This implies that each node
1.241 - /// map reading rule will be abanoned, and the nodes of the graph
1.242 + /// map reading rule will be abandoned, and the nodes of the graph
1.243 /// will not be constructed, which usually cause that the edge set
1.244 /// could not be read due to lack of node name
1.245 - /// resolving. Therefore, the \c skipEdges() should be used too, or
1.246 - /// the useNodes() member function should be used to specify the
1.247 - /// label of the nodes.
1.248 + /// could not be read due to lack of node name resolving.
1.249 + /// Therefore \c skipEdges() function should also be used, or
1.250 + /// \c useNodes() should be used to specify the label of the nodes.
1.251 GraphReader& skipNodes() {
1.252 LEMON_ASSERT(!_skip_nodes, "Skip nodes already set");
1.253 _skip_nodes = true;
1.254 return *this;
1.255 }
1.256
1.257 - /// \brief Skips the reading of edge section
1.258 + /// \brief Skip the reading of edge section
1.259 ///
1.260 /// Omit the reading of the edge section. This implies that each edge
1.261 - /// map reading rule will be abanoned, and the edges of the graph
1.262 + /// map reading rule will be abandoned, and the edges of the graph
1.263 /// will not be constructed.
1.264 GraphReader& skipEdges() {
1.265 LEMON_ASSERT(!_skip_edges, "Skip edges already set");
1.266 @@ -1982,6 +1994,9 @@
1.267
1.268 };
1.269
1.270 + /// \brief Return a \ref GraphReader class
1.271 + ///
1.272 + /// This function just returns a \ref GraphReader class.
1.273 /// \relates GraphReader
1.274 template <typename Graph>
1.275 GraphReader<Graph> graphReader(std::istream& is, Graph& graph) {
1.276 @@ -1989,6 +2004,9 @@
1.277 return tmp;
1.278 }
1.279
1.280 + /// \brief Return a \ref GraphReader class
1.281 + ///
1.282 + /// This function just returns a \ref GraphReader class.
1.283 /// \relates GraphReader
1.284 template <typename Graph>
1.285 GraphReader<Graph> graphReader(const std::string& fn,
1.286 @@ -1997,6 +2015,9 @@
1.287 return tmp;
1.288 }
1.289
1.290 + /// \brief Return a \ref GraphReader class
1.291 + ///
1.292 + /// This function just returns a \ref GraphReader class.
1.293 /// \relates GraphReader
1.294 template <typename Graph>
1.295 GraphReader<Graph> graphReader(const char* fn, Graph& graph) {
1.296 @@ -2010,13 +2031,15 @@
1.297 SectionReader sectionReader(const std::string& fn);
1.298 SectionReader sectionReader(const char* fn);
1.299
1.300 + /// \ingroup lemon_io
1.301 + ///
1.302 /// \brief Section reader class
1.303 ///
1.304 - /// In the \e LGF file extra sections can be placed, which contain
1.305 - /// any data in arbitrary format. Such sections can be read with
1.306 - /// this class. A reading rule can be added with two different
1.307 - /// functions, with the \c sectionLines() function a functor can
1.308 - /// process the section line-by-line. While with the \c
1.309 + /// In the \ref lgf-format "LGF" file extra sections can be placed,
1.310 + /// which contain any data in arbitrary format. Such sections can be
1.311 + /// read with this class. A reading rule can be added to the class
1.312 + /// with two different functions. With the \c sectionLines() function a
1.313 + /// functor can process the section line-by-line, while with the \c
1.314 /// sectionStream() member the section can be read from an input
1.315 /// stream.
1.316 class SectionReader {
1.317 @@ -2105,7 +2128,7 @@
1.318 /// 23 6
1.319 ///\endcode
1.320 ///
1.321 - /// The functor is implemented as an struct:
1.322 + /// The functor is implemented as a struct:
1.323 ///\code
1.324 /// struct NumberSection {
1.325 /// std::vector<int>& _data;
1.326 @@ -2123,7 +2146,7 @@
1.327 ///\endcode
1.328 template <typename Functor>
1.329 SectionReader& sectionLines(const std::string& type, Functor functor) {
1.330 - LEMON_ASSERT(!type.empty(), "Type is not empty.");
1.331 + LEMON_ASSERT(!type.empty(), "Type is empty.");
1.332 LEMON_ASSERT(_sections.find(type) == _sections.end(),
1.333 "Multiple reading of section.");
1.334 _sections.insert(std::make_pair(type,
1.335 @@ -2135,13 +2158,13 @@
1.336 /// \brief Add a section processor with stream oriented reading
1.337 ///
1.338 /// The first parameter is the type of the section, the second is
1.339 - /// a functor, which takes an \c std::istream& and an int&
1.340 + /// a functor, which takes an \c std::istream& and an \c int&
1.341 /// parameter, the latter regard to the line number of stream. The
1.342 /// functor can read the input while the section go on, and the
1.343 /// line number should be modified accordingly.
1.344 template <typename Functor>
1.345 SectionReader& sectionStream(const std::string& type, Functor functor) {
1.346 - LEMON_ASSERT(!type.empty(), "Type is not empty.");
1.347 + LEMON_ASSERT(!type.empty(), "Type is empty.");
1.348 LEMON_ASSERT(_sections.find(type) == _sections.end(),
1.349 "Multiple reading of section.");
1.350 _sections.insert(std::make_pair(type,
1.351 @@ -2186,7 +2209,7 @@
1.352
1.353 /// \brief Start the batch processing
1.354 ///
1.355 - /// This function starts the batch processing
1.356 + /// This function starts the batch processing.
1.357 void run() {
1.358
1.359 LEMON_ASSERT(_is != 0, "This reader assigned to an other reader");
1.360 @@ -2239,18 +2262,27 @@
1.361
1.362 };
1.363
1.364 + /// \brief Return a \ref SectionReader class
1.365 + ///
1.366 + /// This function just returns a \ref SectionReader class.
1.367 /// \relates SectionReader
1.368 inline SectionReader sectionReader(std::istream& is) {
1.369 SectionReader tmp(is);
1.370 return tmp;
1.371 }
1.372
1.373 + /// \brief Return a \ref SectionReader class
1.374 + ///
1.375 + /// This function just returns a \ref SectionReader class.
1.376 /// \relates SectionReader
1.377 inline SectionReader sectionReader(const std::string& fn) {
1.378 SectionReader tmp(fn);
1.379 return tmp;
1.380 }
1.381
1.382 + /// \brief Return a \ref SectionReader class
1.383 + ///
1.384 + /// This function just returns a \ref SectionReader class.
1.385 /// \relates SectionReader
1.386 inline SectionReader sectionReader(const char* fn) {
1.387 SectionReader tmp(fn);
1.388 @@ -2269,19 +2301,20 @@
1.389 /// reads the graph and stores the appropriate information for
1.390 /// reading the graph.
1.391 ///
1.392 - ///\code LgfContents contents("graph.lgf");
1.393 + ///\code
1.394 + /// LgfContents contents("graph.lgf");
1.395 /// contents.run();
1.396 ///
1.397 - /// // does it contain any node section and arc section
1.398 + /// // Does it contain any node section and arc section?
1.399 /// if (contents.nodeSectionNum() == 0 || contents.arcSectionNum()) {
1.400 - /// std::cerr << "Failure, cannot find graph" << std::endl;
1.401 + /// std::cerr << "Failure, cannot find graph." << std::endl;
1.402 /// return -1;
1.403 /// }
1.404 - /// std::cout << "The name of the default node section : "
1.405 + /// std::cout << "The name of the default node section: "
1.406 /// << contents.nodeSection(0) << std::endl;
1.407 - /// std::cout << "The number of the arc maps : "
1.408 + /// std::cout << "The number of the arc maps: "
1.409 /// << contents.arcMaps(0).size() << std::endl;
1.410 - /// std::cout << "The name of second arc map : "
1.411 + /// std::cout << "The name of second arc map: "
1.412 /// << contents.arcMaps(0)[1] << std::endl;
1.413 ///\endcode
1.414 class LgfContents {
1.415 @@ -2352,9 +2385,9 @@
1.416 return _node_sections.size();
1.417 }
1.418
1.419 - /// \brief Returns the section name at the given position.
1.420 + /// \brief Returns the node section name at the given position.
1.421 ///
1.422 - /// Returns the section name at the given position.
1.423 + /// Returns the node section name at the given position.
1.424 const std::string& nodeSection(int i) const {
1.425 return _node_sections[i];
1.426 }
1.427 @@ -2379,9 +2412,9 @@
1.428 return _edge_sections.size();
1.429 }
1.430
1.431 - /// \brief Returns the section name at the given position.
1.432 + /// \brief Returns the arc/edge section name at the given position.
1.433 ///
1.434 - /// Returns the section name at the given position.
1.435 + /// Returns the arc/edge section name at the given position.
1.436 /// \note It is synonym of \c edgeSection().
1.437 const std::string& arcSection(int i) const {
1.438 return _edge_sections[i];
1.439 @@ -2436,9 +2469,9 @@
1.440 return _attribute_sections.size();
1.441 }
1.442
1.443 - /// \brief Returns the section name at the given position.
1.444 + /// \brief Returns the attribute section name at the given position.
1.445 ///
1.446 - /// Returns the section name at the given position.
1.447 + /// Returns the attribute section name at the given position.
1.448 const std::string& attributeSectionNames(int i) const {
1.449 return _attribute_sections[i];
1.450 }
1.451 @@ -2529,9 +2562,9 @@
1.452 /// \name Execution of the contents reader
1.453 /// @{
1.454
1.455 - /// \brief Start the reading
1.456 + /// \brief Starts the reading
1.457 ///
1.458 - /// This function starts the reading
1.459 + /// This function starts the reading.
1.460 void run() {
1.461
1.462 readLine();