COIN-OR::LEMON - Graph Library

Changeset 192:7bf5f97d574f in lemon-1.2 for lemon/lgf_reader.h


Ignore:
Timestamp:
07/05/08 00:14:27 (11 years ago)
Author:
Peter Kovacs <kpeter@…>
Branch:
default
Phase:
public
Message:

Doc improvements in LGF related files

File:
1 edited

Legend:

Unmodified
Added
Removed
  • lemon/lgf_reader.h

    r190 r192  
    1919///\ingroup lemon_io
    2020///\file
    21 ///\brief Lemon Graph Format reader.
     21///\brief \ref lgf-format "Lemon Graph Format" reader.
    2222
    2323
     
    401401  /// \ingroup lemon_io
    402402  /// 
    403   /// \brief LGF reader for directed graphs
     403  /// \brief \ref lgf-format "LGF" reader for directed graphs
    404404  ///
    405405  /// This utility reads an \ref lgf-format "LGF" file.
     
    411411  /// with the \c nodeMap() or \c arcMap() members. An optional
    412412  /// converter parameter can also be added as a standard functor
    413   /// converting from std::string to the value type of the map. If it
     413  /// converting from \c std::string to the value type of the map. If it
    414414  /// is set, it will determine how the tokens in the file should be
    415   /// is converted to the map's value type. If the functor is not set,
     415  /// converted to the value type of the map. If the functor is not set,
    416416  /// then a default conversion will be used. One map can be read into
    417417  /// multiple map objects at the same time. The \c attribute(), \c
     
    420420  ///
    421421  ///\code
    422   ///     DigraphReader<Digraph>(std::cin, digraph).
    423   ///       nodeMap("coordinates", coord_map).
    424   ///       arcMap("capacity", cap_map).
    425   ///       node("source", src).
    426   ///       node("target", trg).
    427   ///       attribute("caption", caption).
    428   ///       run();
     422  /// DigraphReader<Digraph>(std::cin, digraph).
     423  ///   nodeMap("coordinates", coord_map).
     424  ///   arcMap("capacity", cap_map).
     425  ///   node("source", src).
     426  ///   node("target", trg).
     427  ///   attribute("caption", caption).
     428  ///   run();
    429429  ///\endcode
    430430  ///
     
    438438  /// graph) during the reading, but instead the label map of the items
    439439  /// are given as a parameter of these functions. An
    440   /// application of these function is multipass reading, which is
    441   /// important if two \e \@arcs sections must be read from the
    442   /// file. In this example the first phase would read the node set and one
     440  /// application of these functions is multipass reading, which is
     441  /// important if two \c \@arcs sections must be read from the
     442  /// file. In this case the first phase would read the node set and one
    443443  /// of the arc sets, while the second phase would read the second arc
    444444  /// set into an \e ArcSet class (\c SmartArcSet or \c ListArcSet).
    445445  /// The previously read label node map should be passed to the \c
    446446  /// useNodes() functions. Another application of multipass reading when
    447   /// paths are given as a node map or an arc map. It is impossible read this in
     447  /// paths are given as a node map or an arc map. It is impossible to read this in
    448448  /// a single pass, because the arcs are not constructed when the node
    449449  /// maps are read.
     
    736736    /// Use previously constructed node set, and specify the node
    737737    /// label map and a functor which converts the label map values to
    738     /// std::string.
     738    /// \c std::string.
    739739    template <typename Map, typename Converter>
    740740    DigraphReader& useNodes(const Map& map,
     
    769769    /// Use previously constructed arc set, and specify the arc
    770770    /// label map and a functor which converts the label map values to
    771     /// std::string.
     771    /// \c std::string.
    772772    template <typename Map, typename Converter>
    773773    DigraphReader& useArcs(const Map& map,
     
    785785    ///
    786786    /// Omit the reading of the node section. This implies that each node
    787     /// map reading rule will be abanoned, and the nodes of the graph
     787    /// map reading rule will be abandoned, and the nodes of the graph
    788788    /// will not be constructed, which usually cause that the arc set
    789     /// could not be read due to lack of node name
    790     /// resolving. Therefore, the \c skipArcs() should be used too, or
    791     /// the useNodes() member function should be used to specify the
    792     /// label of the nodes.
     789    /// could not be read due to lack of node name resolving.
     790    /// Therefore \c skipArcs() function should also be used, or
     791    /// \c useNodes() should be used to specify the label of the nodes.
    793792    DigraphReader& skipNodes() {
    794793      LEMON_ASSERT(!_skip_nodes, "Skip nodes already set");
     
    800799    ///
    801800    /// Omit the reading of the arc section. This implies that each arc
    802     /// map reading rule will be abanoned, and the arcs of the graph
     801    /// map reading rule will be abandoned, and the arcs of the graph
    803802    /// will not be constructed.
    804803    DigraphReader& skipArcs() {
     
    11761175  };
    11771176
     1177  /// \brief Return a \ref DigraphReader class
     1178  ///
     1179  /// This function just returns a \ref DigraphReader class.
    11781180  /// \relates DigraphReader
    11791181  template <typename Digraph>
     
    11831185  }
    11841186
     1187  /// \brief Return a \ref DigraphReader class
     1188  ///
     1189  /// This function just returns a \ref DigraphReader class.
    11851190  /// \relates DigraphReader
    11861191  template <typename Digraph>
     
    11911196  }
    11921197
     1198  /// \brief Return a \ref DigraphReader class
     1199  ///
     1200  /// This function just returns a \ref DigraphReader class.
    11931201  /// \relates DigraphReader
    11941202  template <typename Digraph>
     
    12121220  /// \ingroup lemon_io
    12131221  /// 
    1214   /// \brief LGF reader for undirected graphs
     1222  /// \brief \ref lgf-format "LGF" reader for undirected graphs
    12151223  ///
    12161224  /// This utility reads an \ref lgf-format "LGF" file.
     1225  ///
     1226  /// It can be used almost the same way as \c DigraphReader.
     1227  /// The only difference is that this class can handle edges and
     1228  /// edge maps as well as arcs and arc maps.
    12171229  template <typename _Graph>
    12181230  class GraphReader {
     
    12631275    /// \brief Constructor
    12641276    ///
    1265     /// Construct a undirected graph reader, which reads from the given
     1277    /// Construct an undirected graph reader, which reads from the given
    12661278    /// input stream.
    12671279    GraphReader(std::istream& is, Graph& graph)
     
    12721284    /// \brief Constructor
    12731285    ///
    1274     /// Construct a undirected graph reader, which reads from the given
     1286    /// Construct an undirected graph reader, which reads from the given
    12751287    /// file.
    12761288    GraphReader(const std::string& fn, Graph& graph)
     
    12811293    /// \brief Constructor
    12821294    ///
    1283     /// Construct a undirected graph reader, which reads from the given
     1295    /// Construct an undirected graph reader, which reads from the given
    12841296    /// file.
    12851297    GraphReader(const char* fn, Graph& graph)
     
    14981510    /// \brief Set \c \@nodes section to be read
    14991511    ///
    1500     /// Set \c \@nodes section to be read
     1512    /// Set \c \@nodes section to be read.
    15011513    GraphReader& nodes(const std::string& caption) {
    15021514      _nodes_caption = caption;
     
    15061518    /// \brief Set \c \@edges section to be read
    15071519    ///
    1508     /// Set \c \@edges section to be read
     1520    /// Set \c \@edges section to be read.
    15091521    GraphReader& edges(const std::string& caption) {
    15101522      _edges_caption = caption;
     
    15141526    /// \brief Set \c \@attributes section to be read
    15151527    ///
    1516     /// Set \c \@attributes section to be read
     1528    /// Set \c \@attributes section to be read.
    15171529    GraphReader& attributes(const std::string& caption) {
    15181530      _attributes_caption = caption;
     
    15451557    /// Use previously constructed node set, and specify the node
    15461558    /// label map and a functor which converts the label map values to
    1547     /// std::string.
     1559    /// \c std::string.
    15481560    template <typename Map, typename Converter>
    15491561    GraphReader& useNodes(const Map& map,
     
    15781590    /// Use previously constructed edge set, and specify the edge
    15791591    /// label map and a functor which converts the label map values to
    1580     /// std::string.
     1592    /// \c std::string.
    15811593    template <typename Map, typename Converter>
    15821594    GraphReader& useEdges(const Map& map,
     
    15911603    }
    15921604
    1593     /// \brief Skips the reading of node section
     1605    /// \brief Skip the reading of node section
    15941606    ///
    15951607    /// Omit the reading of the node section. This implies that each node
    1596     /// map reading rule will be abanoned, and the nodes of the graph
     1608    /// map reading rule will be abandoned, and the nodes of the graph
    15971609    /// will not be constructed, which usually cause that the edge set
    15981610    /// could not be read due to lack of node name
    1599     /// resolving. Therefore, the \c skipEdges() should be used too, or
    1600     /// the useNodes() member function should be used to specify the
    1601     /// label of the nodes.
     1611    /// could not be read due to lack of node name resolving.
     1612    /// Therefore \c skipEdges() function should also be used, or
     1613    /// \c useNodes() should be used to specify the label of the nodes.
    16021614    GraphReader& skipNodes() {
    16031615      LEMON_ASSERT(!_skip_nodes, "Skip nodes already set");
     
    16061618    }
    16071619
    1608     /// \brief Skips the reading of edge section
     1620    /// \brief Skip the reading of edge section
    16091621    ///
    16101622    /// Omit the reading of the edge section. This implies that each edge
    1611     /// map reading rule will be abanoned, and the edges of the graph
     1623    /// map reading rule will be abandoned, and the edges of the graph
    16121624    /// will not be constructed.
    16131625    GraphReader& skipEdges() {
     
    19831995  };
    19841996
     1997  /// \brief Return a \ref GraphReader class
     1998  ///
     1999  /// This function just returns a \ref GraphReader class.
    19852000  /// \relates GraphReader
    19862001  template <typename Graph>
     
    19902005  }
    19912006
     2007  /// \brief Return a \ref GraphReader class
     2008  ///
     2009  /// This function just returns a \ref GraphReader class.
    19922010  /// \relates GraphReader
    19932011  template <typename Graph>
     
    19982016  }
    19992017
     2018  /// \brief Return a \ref GraphReader class
     2019  ///
     2020  /// This function just returns a \ref GraphReader class.
    20002021  /// \relates GraphReader
    20012022  template <typename Graph>
     
    20112032  SectionReader sectionReader(const char* fn);
    20122033 
     2034  /// \ingroup lemon_io
     2035  ///
    20132036  /// \brief Section reader class
    20142037  ///
    2015   /// In the \e LGF file extra sections can be placed, which contain
    2016   /// any data in arbitrary format. Such sections can be read with
    2017   /// this class. A reading rule can be added with two different
    2018   /// functions, with the \c sectionLines() function a functor can
    2019   /// process the section line-by-line. While with the \c
     2038  /// In the \ref lgf-format "LGF" file extra sections can be placed,
     2039  /// which contain any data in arbitrary format. Such sections can be
     2040  /// read with this class. A reading rule can be added to the class
     2041  /// with two different functions. With the \c sectionLines() function a
     2042  /// functor can process the section line-by-line, while with the \c
    20202043  /// sectionStream() member the section can be read from an input
    20212044  /// stream.
     
    21062129    ///\endcode
    21072130    ///
    2108     /// The functor is implemented as an struct:
     2131    /// The functor is implemented as a struct:
    21092132    ///\code
    21102133    ///  struct NumberSection {
     
    21242147    template <typename Functor>
    21252148    SectionReader& sectionLines(const std::string& type, Functor functor) {
    2126       LEMON_ASSERT(!type.empty(), "Type is not empty.");
     2149      LEMON_ASSERT(!type.empty(), "Type is empty.");
    21272150      LEMON_ASSERT(_sections.find(type) == _sections.end(),
    21282151                   "Multiple reading of section.");
     
    21362159    ///
    21372160    /// The first parameter is the type of the section, the second is
    2138     /// a functor, which takes an \c std::istream& and an int&
     2161    /// a functor, which takes an \c std::istream& and an \c int&
    21392162    /// parameter, the latter regard to the line number of stream. The
    21402163    /// functor can read the input while the section go on, and the
     
    21422165    template <typename Functor>
    21432166    SectionReader& sectionStream(const std::string& type, Functor functor) {
    2144       LEMON_ASSERT(!type.empty(), "Type is not empty.");
     2167      LEMON_ASSERT(!type.empty(), "Type is empty.");
    21452168      LEMON_ASSERT(_sections.find(type) == _sections.end(),
    21462169                   "Multiple reading of section.");
     
    21872210    /// \brief Start the batch processing
    21882211    ///
    2189     /// This function starts the batch processing
     2212    /// This function starts the batch processing.
    21902213    void run() {
    21912214     
     
    22402263  };
    22412264
     2265  /// \brief Return a \ref SectionReader class
     2266  ///
     2267  /// This function just returns a \ref SectionReader class.
    22422268  /// \relates SectionReader
    22432269  inline SectionReader sectionReader(std::istream& is) {
     
    22462272  }
    22472273
     2274  /// \brief Return a \ref SectionReader class
     2275  ///
     2276  /// This function just returns a \ref SectionReader class.
    22482277  /// \relates SectionReader
    22492278  inline SectionReader sectionReader(const std::string& fn) {
     
    22522281  }
    22532282
     2283  /// \brief Return a \ref SectionReader class
     2284  ///
     2285  /// This function just returns a \ref SectionReader class.
    22542286  /// \relates SectionReader
    22552287  inline SectionReader sectionReader(const char* fn) {
     
    22702302  /// reading the graph.
    22712303  ///
    2272   ///\code LgfContents contents("graph.lgf");
     2304  ///\code
     2305  /// LgfContents contents("graph.lgf");
    22732306  /// contents.run();
    22742307  ///
    2275   /// // does it contain any node section and arc section
     2308  /// // Does it contain any node section and arc section?
    22762309  /// if (contents.nodeSectionNum() == 0 || contents.arcSectionNum()) {
    2277   ///   std::cerr << "Failure, cannot find graph" << std::endl;
     2310  ///   std::cerr << "Failure, cannot find graph." << std::endl;
    22782311  ///   return -1;
    22792312  /// }
    2280   /// std::cout << "The name of the default node section : "
     2313  /// std::cout << "The name of the default node section: "
    22812314  ///           << contents.nodeSection(0) << std::endl;
    2282   /// std::cout << "The number of the arc maps : "
     2315  /// std::cout << "The number of the arc maps: "
    22832316  ///           << contents.arcMaps(0).size() << std::endl;
    2284   /// std::cout << "The name of second arc map : "
     2317  /// std::cout << "The name of second arc map: "
    22852318  ///           << contents.arcMaps(0)[1] << std::endl;
    22862319  ///\endcode
     
    23532386    }
    23542387
    2355     /// \brief Returns the section name at the given position.
    2356     ///
    2357     /// Returns the section name at the given position.
     2388    /// \brief Returns the node section name at the given position.
     2389    ///
     2390    /// Returns the node section name at the given position.
    23582391    const std::string& nodeSection(int i) const {
    23592392      return _node_sections[i];
     
    23802413    }
    23812414
    2382     /// \brief Returns the section name at the given position.
    2383     ///
    2384     /// Returns the section name at the given position.
     2415    /// \brief Returns the arc/edge section name at the given position.
     2416    ///
     2417    /// Returns the arc/edge section name at the given position.
    23852418    /// \note It is synonym of \c edgeSection().
    23862419    const std::string& arcSection(int i) const {
     
    24372470    }
    24382471
    2439     /// \brief Returns the section name at the given position.
    2440     ///
    2441     /// Returns the section name at the given position.
     2472    /// \brief Returns the attribute section name at the given position.
     2473    ///
     2474    /// Returns the attribute section name at the given position.
    24422475    const std::string& attributeSectionNames(int i) const {
    24432476      return _attribute_sections[i];
     
    25302563    /// @{
    25312564
    2532     /// \brief Start the reading
    2533     ///
    2534     /// This function starts the reading
     2565    /// \brief Starts the reading
     2566    ///
     2567    /// This function starts the reading.
    25352568    void run() {
    25362569
Note: See TracChangeset for help on using the changeset viewer.