Add more docs to LGF function interface (#109)
authorBalazs Dezso <deba@inf.elte.hu>
Sat, 18 Apr 2009 21:54:30 +0200
changeset 590a3402913cffe
parent 565 37216ca5b9c6
child 591 f63e87b9748e
Add more docs to LGF function interface (#109)
lemon/lgf_reader.h
lemon/lgf_writer.h
     1.1 --- a/lemon/lgf_reader.h	Tue Apr 07 14:50:20 2009 +0100
     1.2 +++ b/lemon/lgf_reader.h	Sat Apr 18 21:54:30 2009 +0200
     1.3 @@ -101,23 +101,23 @@
     1.4        }
     1.5      };
     1.6  
     1.7 -    template <typename _Graph, bool _dir, typename _Map,
     1.8 +    template <typename _GR, bool _dir, typename _Map,
     1.9                typename _Converter = DefaultConverter<typename _Map::Value> >
    1.10 -    class GraphArcMapStorage : public MapStorageBase<typename _Graph::Edge> {
    1.11 +    class GraphArcMapStorage : public MapStorageBase<typename _GR::Edge> {
    1.12      public:
    1.13        typedef _Map Map;
    1.14        typedef _Converter Converter;
    1.15 -      typedef _Graph Graph;
    1.16 -      typedef typename Graph::Edge Item;
    1.17 +      typedef _GR GR;
    1.18 +      typedef typename GR::Edge Item;
    1.19        static const bool dir = _dir;
    1.20  
    1.21      private:
    1.22 -      const Graph& _graph;
    1.23 +      const GR& _graph;
    1.24        Map& _map;
    1.25        Converter _converter;
    1.26  
    1.27      public:
    1.28 -      GraphArcMapStorage(const Graph& graph, Map& map,
    1.29 +      GraphArcMapStorage(const GR& graph, Map& map,
    1.30                           const Converter& converter = Converter())
    1.31          : _graph(graph), _map(map), _converter(converter) {}
    1.32        virtual ~GraphArcMapStorage() {}
    1.33 @@ -173,21 +173,21 @@
    1.34        }
    1.35      };
    1.36  
    1.37 -    template <typename Graph>
    1.38 +    template <typename GR>
    1.39      struct GraphArcLookUpConverter {
    1.40 -      const Graph& _graph;
    1.41 -      const std::map<std::string, typename Graph::Edge>& _map;
    1.42 -
    1.43 -      GraphArcLookUpConverter(const Graph& graph,
    1.44 +      const GR& _graph;
    1.45 +      const std::map<std::string, typename GR::Edge>& _map;
    1.46 +
    1.47 +      GraphArcLookUpConverter(const GR& graph,
    1.48                                const std::map<std::string,
    1.49 -                                             typename Graph::Edge>& map)
    1.50 +                                             typename GR::Edge>& map)
    1.51          : _graph(graph), _map(map) {}
    1.52  
    1.53 -      typename Graph::Arc operator()(const std::string& str) {
    1.54 +      typename GR::Arc operator()(const std::string& str) {
    1.55          if (str.empty() || (str[0] != '+' && str[0] != '-')) {
    1.56            throw FormatError("Item must start with '+' or '-'");
    1.57          }
    1.58 -        typename std::map<std::string, typename Graph::Edge>
    1.59 +        typename std::map<std::string, typename GR::Edge>
    1.60            ::const_iterator it = _map.find(str.substr(1));
    1.61          if (it == _map.end()) {
    1.62            throw FormatError("Item not found");
    1.63 @@ -387,16 +387,15 @@
    1.64  
    1.65    }
    1.66  
    1.67 -  template <typename Digraph>
    1.68 +  template <typename DGR>
    1.69    class DigraphReader;
    1.70  
    1.71 -  template <typename Digraph>
    1.72 -  DigraphReader<Digraph> digraphReader(Digraph& digraph, 
    1.73 -                                       std::istream& is = std::cin);
    1.74 -  template <typename Digraph>
    1.75 -  DigraphReader<Digraph> digraphReader(Digraph& digraph, const std::string& fn);
    1.76 -  template <typename Digraph>
    1.77 -  DigraphReader<Digraph> digraphReader(Digraph& digraph, const char *fn);
    1.78 +  template <typename TDGR>
    1.79 +  DigraphReader<TDGR> digraphReader(TDGR& digraph, std::istream& is = std::cin);
    1.80 +  template <typename TDGR>
    1.81 +  DigraphReader<TDGR> digraphReader(TDGR& digraph, const std::string& fn);
    1.82 +  template <typename TDGR>
    1.83 +  DigraphReader<TDGR> digraphReader(TDGR& digraph, const char *fn);
    1.84  
    1.85    /// \ingroup lemon_io
    1.86    ///
    1.87 @@ -419,7 +418,7 @@
    1.88    /// rules.
    1.89    ///
    1.90    ///\code
    1.91 -  /// DigraphReader<Digraph>(digraph, std::cin).
    1.92 +  /// DigraphReader<DGR>(digraph, std::cin).
    1.93    ///   nodeMap("coordinates", coord_map).
    1.94    ///   arcMap("capacity", cap_map).
    1.95    ///   node("source", src).
    1.96 @@ -448,21 +447,21 @@
    1.97    /// It is impossible to read this in
    1.98    /// a single pass, because the arcs are not constructed when the node
    1.99    /// maps are read.
   1.100 -  template <typename GR>
   1.101 +  template <typename DGR>
   1.102    class DigraphReader {
   1.103    public:
   1.104  
   1.105 -    typedef GR Digraph;
   1.106 +    typedef DGR Digraph;
   1.107  
   1.108    private:
   1.109  
   1.110 -    TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
   1.111 +    TEMPLATE_DIGRAPH_TYPEDEFS(DGR);
   1.112  
   1.113      std::istream* _is;
   1.114      bool local_is;
   1.115      std::string _filename;
   1.116  
   1.117 -    Digraph& _digraph;
   1.118 +    DGR& _digraph;
   1.119  
   1.120      std::string _nodes_caption;
   1.121      std::string _arcs_caption;
   1.122 @@ -500,7 +499,7 @@
   1.123      ///
   1.124      /// Construct a directed graph reader, which reads from the given
   1.125      /// input stream.
   1.126 -    DigraphReader(Digraph& digraph, std::istream& is = std::cin)
   1.127 +    DigraphReader(DGR& digraph, std::istream& is = std::cin)
   1.128        : _is(&is), local_is(false), _digraph(digraph),
   1.129          _use_nodes(false), _use_arcs(false),
   1.130          _skip_nodes(false), _skip_arcs(false) {}
   1.131 @@ -509,7 +508,7 @@
   1.132      ///
   1.133      /// Construct a directed graph reader, which reads from the given
   1.134      /// file.
   1.135 -    DigraphReader(Digraph& digraph, const std::string& fn)
   1.136 +    DigraphReader(DGR& digraph, const std::string& fn)
   1.137        : _is(new std::ifstream(fn.c_str())), local_is(true),
   1.138          _filename(fn), _digraph(digraph),
   1.139          _use_nodes(false), _use_arcs(false),
   1.140 @@ -524,7 +523,7 @@
   1.141      ///
   1.142      /// Construct a directed graph reader, which reads from the given
   1.143      /// file.
   1.144 -    DigraphReader(Digraph& digraph, const char* fn)
   1.145 +    DigraphReader(DGR& digraph, const char* fn)
   1.146        : _is(new std::ifstream(fn)), local_is(true),
   1.147          _filename(fn), _digraph(digraph),
   1.148          _use_nodes(false), _use_arcs(false),
   1.149 @@ -560,13 +559,13 @@
   1.150  
   1.151    private:
   1.152  
   1.153 -    template <typename DGR>
   1.154 -    friend DigraphReader<DGR> digraphReader(DGR& digraph, std::istream& is);
   1.155 -    template <typename DGR>
   1.156 -    friend DigraphReader<DGR> digraphReader(DGR& digraph, 
   1.157 -                                            const std::string& fn);
   1.158 -    template <typename DGR>
   1.159 -    friend DigraphReader<DGR> digraphReader(DGR& digraph, const char *fn);
   1.160 +    template <typename TDGR>
   1.161 +    friend DigraphReader<TDGR> digraphReader(TDGR& digraph, std::istream& is);
   1.162 +    template <typename TDGR>
   1.163 +    friend DigraphReader<TDGR> digraphReader(TDGR& digraph, 
   1.164 +                                             const std::string& fn);
   1.165 +    template <typename TDGR>
   1.166 +    friend DigraphReader<TDGR> digraphReader(TDGR& digraph, const char *fn);
   1.167  
   1.168      DigraphReader(DigraphReader& other)
   1.169        : _is(other._is), local_is(other.local_is), _digraph(other._digraph),
   1.170 @@ -1188,14 +1187,52 @@
   1.171      /// @}
   1.172  
   1.173    };
   1.174 +  
   1.175 +  /// \ingroup lemon_io
   1.176 +  ///
   1.177 +  /// \brief Return a \ref DigraphReader class
   1.178 +  ///
   1.179 +  /// This function just returns a \ref DigraphReader class.
   1.180 +  ///
   1.181 +  /// With this function a digraph can be read from an 
   1.182 +  /// \ref lgf-format "LGF" file or input stream with several maps and
   1.183 +  /// attributes. For example, there is network flow problem on a
   1.184 +  /// digraph, i.e. a digraph with a \e capacity map on the arcs and
   1.185 +  /// \e source and \e target nodes. This digraph can be read with the
   1.186 +  /// following code:
   1.187 +  ///
   1.188 +  ///\code
   1.189 +  ///ListDigraph digraph;
   1.190 +  ///ListDigraph::ArcMap<int> cm(digraph);
   1.191 +  ///ListDigraph::Node src, trg;
   1.192 +  ///digraphReader(digraph, std::cin).
   1.193 +  ///  arcMap("capacity", cap).
   1.194 +  ///  node("source", src).
   1.195 +  ///  node("target", trg).
   1.196 +  ///  run();
   1.197 +  ///\endcode
   1.198 +  ///
   1.199 +  /// For a complete documentation, please see the \ref DigraphReader
   1.200 +  /// class documentation.
   1.201 +  /// \warning Don't forget to put the \ref DigraphReader::run() "run()"
   1.202 +  /// to the end of the parameter list.
   1.203 +  /// \relates DigraphReader
   1.204 +  /// \sa digraphReader(TDGR& digraph, const std::string& fn)
   1.205 +  /// \sa digraphReader(TDGR& digraph, const char* fn)
   1.206 +  template <typename TDGR>
   1.207 +  DigraphReader<TDGR> digraphReader(TDGR& digraph, std::istream& is) {
   1.208 +    DigraphReader<TDGR> tmp(digraph, is);
   1.209 +    return tmp;
   1.210 +  }
   1.211  
   1.212    /// \brief Return a \ref DigraphReader class
   1.213    ///
   1.214    /// This function just returns a \ref DigraphReader class.
   1.215    /// \relates DigraphReader
   1.216 -  template <typename Digraph>
   1.217 -  DigraphReader<Digraph> digraphReader(Digraph& digraph, std::istream& is) {
   1.218 -    DigraphReader<Digraph> tmp(digraph, is);
   1.219 +  /// \sa digraphReader(TDGR& digraph, std::istream& is)
   1.220 +  template <typename TDGR>
   1.221 +  DigraphReader<TDGR> digraphReader(TDGR& digraph, const std::string& fn) {
   1.222 +    DigraphReader<TDGR> tmp(digraph, fn);
   1.223      return tmp;
   1.224    }
   1.225  
   1.226 @@ -1203,33 +1240,22 @@
   1.227    ///
   1.228    /// This function just returns a \ref DigraphReader class.
   1.229    /// \relates DigraphReader
   1.230 -  template <typename Digraph>
   1.231 -  DigraphReader<Digraph> digraphReader(Digraph& digraph,
   1.232 -                                       const std::string& fn) {
   1.233 -    DigraphReader<Digraph> tmp(digraph, fn);
   1.234 +  /// \sa digraphReader(TDGR& digraph, std::istream& is)
   1.235 +  template <typename TDGR>
   1.236 +  DigraphReader<TDGR> digraphReader(TDGR& digraph, const char* fn) {
   1.237 +    DigraphReader<TDGR> tmp(digraph, fn);
   1.238      return tmp;
   1.239    }
   1.240  
   1.241 -  /// \brief Return a \ref DigraphReader class
   1.242 -  ///
   1.243 -  /// This function just returns a \ref DigraphReader class.
   1.244 -  /// \relates DigraphReader
   1.245 -  template <typename Digraph>
   1.246 -  DigraphReader<Digraph> digraphReader(Digraph& digraph, const char* fn) {
   1.247 -    DigraphReader<Digraph> tmp(digraph, fn);
   1.248 -    return tmp;
   1.249 -  }
   1.250 -
   1.251 -  template <typename Graph>
   1.252 +  template <typename GR>
   1.253    class GraphReader;
   1.254   
   1.255 -  template <typename Graph>
   1.256 -  GraphReader<Graph> graphReader(Graph& graph, 
   1.257 -                                 std::istream& is = std::cin);
   1.258 -  template <typename Graph>
   1.259 -  GraphReader<Graph> graphReader(Graph& graph, const std::string& fn);
   1.260 -  template <typename Graph>
   1.261 -  GraphReader<Graph> graphReader(Graph& graph, const char *fn);
   1.262 +  template <typename TGR>
   1.263 +  GraphReader<TGR> graphReader(TGR& graph, std::istream& is = std::cin);
   1.264 +  template <typename TGR>
   1.265 +  GraphReader<TGR> graphReader(TGR& graph, const std::string& fn);
   1.266 +  template <typename TGR>
   1.267 +  GraphReader<TGR> graphReader(TGR& graph, const char *fn);
   1.268  
   1.269    /// \ingroup lemon_io
   1.270    ///
   1.271 @@ -1254,13 +1280,13 @@
   1.272  
   1.273    private:
   1.274  
   1.275 -    TEMPLATE_GRAPH_TYPEDEFS(Graph);
   1.276 +    TEMPLATE_GRAPH_TYPEDEFS(GR);
   1.277  
   1.278      std::istream* _is;
   1.279      bool local_is;
   1.280      std::string _filename;
   1.281  
   1.282 -    Graph& _graph;
   1.283 +    GR& _graph;
   1.284  
   1.285      std::string _nodes_caption;
   1.286      std::string _edges_caption;
   1.287 @@ -1298,7 +1324,7 @@
   1.288      ///
   1.289      /// Construct an undirected graph reader, which reads from the given
   1.290      /// input stream.
   1.291 -    GraphReader(Graph& graph, std::istream& is = std::cin)
   1.292 +    GraphReader(GR& graph, std::istream& is = std::cin)
   1.293        : _is(&is), local_is(false), _graph(graph),
   1.294          _use_nodes(false), _use_edges(false),
   1.295          _skip_nodes(false), _skip_edges(false) {}
   1.296 @@ -1307,7 +1333,7 @@
   1.297      ///
   1.298      /// Construct an undirected graph reader, which reads from the given
   1.299      /// file.
   1.300 -    GraphReader(Graph& graph, const std::string& fn)
   1.301 +    GraphReader(GR& graph, const std::string& fn)
   1.302        : _is(new std::ifstream(fn.c_str())), local_is(true),
   1.303          _filename(fn), _graph(graph),
   1.304          _use_nodes(false), _use_edges(false),
   1.305 @@ -1322,7 +1348,7 @@
   1.306      ///
   1.307      /// Construct an undirected graph reader, which reads from the given
   1.308      /// file.
   1.309 -    GraphReader(Graph& graph, const char* fn)
   1.310 +    GraphReader(GR& graph, const char* fn)
   1.311        : _is(new std::ifstream(fn)), local_is(true),
   1.312          _filename(fn), _graph(graph),
   1.313          _use_nodes(false), _use_edges(false),
   1.314 @@ -1357,12 +1383,12 @@
   1.315      }
   1.316  
   1.317    private:
   1.318 -    template <typename Graph>
   1.319 -    friend GraphReader<Graph> graphReader(Graph& graph, std::istream& is);
   1.320 -    template <typename Graph>
   1.321 -    friend GraphReader<Graph> graphReader(Graph& graph, const std::string& fn); 
   1.322 -    template <typename Graph>
   1.323 -    friend GraphReader<Graph> graphReader(Graph& graph, const char *fn);
   1.324 +    template <typename TGR>
   1.325 +    friend GraphReader<TGR> graphReader(TGR& graph, std::istream& is);
   1.326 +    template <typename TGR>
   1.327 +    friend GraphReader<TGR> graphReader(TGR& graph, const std::string& fn); 
   1.328 +    template <typename TGR>
   1.329 +    friend GraphReader<TGR> graphReader(TGR& graph, const char *fn);
   1.330  
   1.331      GraphReader(GraphReader& other)
   1.332        : _is(other._is), local_is(other.local_is), _graph(other._graph),
   1.333 @@ -1454,7 +1480,7 @@
   1.334          new _reader_bits::GraphArcMapStorage<Graph, true, Map>(_graph, map);
   1.335        _edge_maps.push_back(std::make_pair('+' + caption, forward_storage));
   1.336        _reader_bits::MapStorageBase<Edge>* backward_storage =
   1.337 -        new _reader_bits::GraphArcMapStorage<Graph, false, Map>(_graph, map);
   1.338 +        new _reader_bits::GraphArcMapStorage<GR, false, Map>(_graph, map);
   1.339        _edge_maps.push_back(std::make_pair('-' + caption, backward_storage));
   1.340        return *this;
   1.341      }
   1.342 @@ -1468,11 +1494,11 @@
   1.343                            const Converter& converter = Converter()) {
   1.344        checkConcept<concepts::WriteMap<Arc, typename Map::Value>, Map>();
   1.345        _reader_bits::MapStorageBase<Edge>* forward_storage =
   1.346 -        new _reader_bits::GraphArcMapStorage<Graph, true, Map, Converter>
   1.347 +        new _reader_bits::GraphArcMapStorage<GR, true, Map, Converter>
   1.348          (_graph, map, converter);
   1.349        _edge_maps.push_back(std::make_pair('+' + caption, forward_storage));
   1.350        _reader_bits::MapStorageBase<Edge>* backward_storage =
   1.351 -        new _reader_bits::GraphArcMapStorage<Graph, false, Map, Converter>
   1.352 +        new _reader_bits::GraphArcMapStorage<GR, false, Map, Converter>
   1.353          (_graph, map, converter);
   1.354        _edge_maps.push_back(std::make_pair('-' + caption, backward_storage));
   1.355        return *this;
   1.356 @@ -1530,7 +1556,7 @@
   1.357      ///
   1.358      /// Add an arc reading rule to reader.
   1.359      GraphReader& arc(const std::string& caption, Arc& arc) {
   1.360 -      typedef _reader_bits::GraphArcLookUpConverter<Graph> Converter;
   1.361 +      typedef _reader_bits::GraphArcLookUpConverter<GR> Converter;
   1.362        Converter converter(_graph, _edge_index);
   1.363        _reader_bits::ValueStorageBase* storage =
   1.364          new _reader_bits::ValueStorage<Arc, Converter>(arc, converter);
   1.365 @@ -2033,13 +2059,47 @@
   1.366  
   1.367    };
   1.368  
   1.369 +  /// \ingroup lemon_io
   1.370 +  ///
   1.371 +  /// \brief Return a \ref GraphReader class
   1.372 +  ///
   1.373 +  /// This function just returns a \ref GraphReader class. 
   1.374 +  ///
   1.375 +  /// With this function a graph can be read from an 
   1.376 +  /// \ref lgf-format "LGF" file or input stream with several maps and
   1.377 +  /// attributes. For example, there is weighted matching problem on a
   1.378 +  /// graph, i.e. a graph with a \e weight map on the edges. This
   1.379 +  /// graph can be read with the following code:
   1.380 +  ///
   1.381 +  ///\code
   1.382 +  ///ListGraph graph;
   1.383 +  ///ListGraph::EdgeMap<int> weight(graph);
   1.384 +  ///graphReader(graph, std::cin).
   1.385 +  ///  edgeMap("weight", weight).
   1.386 +  ///  run();
   1.387 +  ///\endcode
   1.388 +  ///
   1.389 +  /// For a complete documentation, please see the \ref GraphReader
   1.390 +  /// class documentation.
   1.391 +  /// \warning Don't forget to put the \ref GraphReader::run() "run()"
   1.392 +  /// to the end of the parameter list.
   1.393 +  /// \relates GraphReader
   1.394 +  /// \sa graphReader(TGR& graph, const std::string& fn)
   1.395 +  /// \sa graphReader(TGR& graph, const char* fn)
   1.396 +  template <typename TGR>
   1.397 +  GraphReader<TGR> graphReader(TGR& graph, std::istream& is) {
   1.398 +    GraphReader<TGR> tmp(graph, is);
   1.399 +    return tmp;
   1.400 +  }
   1.401 +
   1.402    /// \brief Return a \ref GraphReader class
   1.403    ///
   1.404    /// This function just returns a \ref GraphReader class.
   1.405    /// \relates GraphReader
   1.406 -  template <typename Graph>
   1.407 -  GraphReader<Graph> graphReader(Graph& graph, std::istream& is) {
   1.408 -    GraphReader<Graph> tmp(graph, is);
   1.409 +  /// \sa graphReader(TGR& graph, std::istream& is)
   1.410 +  template <typename TGR>
   1.411 +  GraphReader<TGR> graphReader(TGR& graph, const std::string& fn) {
   1.412 +    GraphReader<TGR> tmp(graph, fn);
   1.413      return tmp;
   1.414    }
   1.415  
   1.416 @@ -2047,19 +2107,10 @@
   1.417    ///
   1.418    /// This function just returns a \ref GraphReader class.
   1.419    /// \relates GraphReader
   1.420 -  template <typename Graph>
   1.421 -  GraphReader<Graph> graphReader(Graph& graph, const std::string& fn) {
   1.422 -    GraphReader<Graph> tmp(graph, fn);
   1.423 -    return tmp;
   1.424 -  }
   1.425 -
   1.426 -  /// \brief Return a \ref GraphReader class
   1.427 -  ///
   1.428 -  /// This function just returns a \ref GraphReader class.
   1.429 -  /// \relates GraphReader
   1.430 -  template <typename Graph>
   1.431 -  GraphReader<Graph> graphReader(Graph& graph, const char* fn) {
   1.432 -    GraphReader<Graph> tmp(graph, fn);
   1.433 +  /// \sa graphReader(TGR& graph, std::istream& is)
   1.434 +  template <typename TGR>
   1.435 +  GraphReader<TGR> graphReader(TGR& graph, const char* fn) {
   1.436 +    GraphReader<TGR> tmp(graph, fn);
   1.437      return tmp;
   1.438    }
   1.439  
   1.440 @@ -2316,12 +2367,30 @@
   1.441  
   1.442    };
   1.443  
   1.444 +  /// \ingroup lemon_io
   1.445 +  ///
   1.446 +  /// \brief Return a \ref SectionReader class
   1.447 +  ///
   1.448 +  /// This function just returns a \ref SectionReader class.
   1.449 +  ///
   1.450 +  /// Please see SectionReader documentation about the custom section
   1.451 +  /// input.
   1.452 +  ///
   1.453 +  /// \relates SectionReader
   1.454 +  /// \sa sectionReader(const std::string& fn)
   1.455 +  /// \sa sectionReader(const char *fn)
   1.456 +  inline SectionReader sectionReader(std::istream& is) {
   1.457 +    SectionReader tmp(is);
   1.458 +    return tmp;
   1.459 +  }
   1.460 +
   1.461    /// \brief Return a \ref SectionReader class
   1.462    ///
   1.463    /// This function just returns a \ref SectionReader class.
   1.464    /// \relates SectionReader
   1.465 -  inline SectionReader sectionReader(std::istream& is) {
   1.466 -    SectionReader tmp(is);
   1.467 +  /// \sa sectionReader(std::istream& is)
   1.468 +  inline SectionReader sectionReader(const std::string& fn) {
   1.469 +    SectionReader tmp(fn);
   1.470      return tmp;
   1.471    }
   1.472  
   1.473 @@ -2329,15 +2398,7 @@
   1.474    ///
   1.475    /// This function just returns a \ref SectionReader class.
   1.476    /// \relates SectionReader
   1.477 -  inline SectionReader sectionReader(const std::string& fn) {
   1.478 -    SectionReader tmp(fn);
   1.479 -    return tmp;
   1.480 -  }
   1.481 -
   1.482 -  /// \brief Return a \ref SectionReader class
   1.483 -  ///
   1.484 -  /// This function just returns a \ref SectionReader class.
   1.485 -  /// \relates SectionReader
   1.486 +  /// \sa sectionReader(std::istream& is)
   1.487    inline SectionReader sectionReader(const char* fn) {
   1.488      SectionReader tmp(fn);
   1.489      return tmp;
     2.1 --- a/lemon/lgf_writer.h	Tue Apr 07 14:50:20 2009 +0100
     2.2 +++ b/lemon/lgf_writer.h	Sat Apr 18 21:54:30 2009 +0200
     2.3 @@ -347,19 +347,17 @@
     2.4  
     2.5    }
     2.6  
     2.7 -  template <typename Digraph>
     2.8 +  template <typename DGR>
     2.9    class DigraphWriter;
    2.10  
    2.11 -  template <typename Digraph>
    2.12 -  DigraphWriter<Digraph> digraphWriter(const Digraph& digraph,
    2.13 -                                       std::ostream& os = std::cout);
    2.14 -  template <typename Digraph>
    2.15 -  DigraphWriter<Digraph> digraphWriter(const Digraph& digraph,
    2.16 -                                       const std::string& fn);
    2.17 +  template <typename TDGR>
    2.18 +  DigraphWriter<TDGR> digraphWriter(const TDGR& digraph, 
    2.19 +                                   std::ostream& os = std::cout);
    2.20 +  template <typename TDGR>
    2.21 +  DigraphWriter<TDGR> digraphWriter(const TDGR& digraph, const std::string& fn);
    2.22  
    2.23 -  template <typename Digraph>
    2.24 -  DigraphWriter<Digraph> digraphWriter(const Digraph& digraph,
    2.25 -                                       const char* fn);
    2.26 +  template <typename TDGR>
    2.27 +  DigraphWriter<TDGR> digraphWriter(const TDGR& digraph, const char* fn);
    2.28  
    2.29  
    2.30    /// \ingroup lemon_io
    2.31 @@ -381,7 +379,7 @@
    2.32    /// arc() functions are used to add attribute writing rules.
    2.33    ///
    2.34    ///\code
    2.35 -  /// DigraphWriter<Digraph>(digraph, std::cout).
    2.36 +  /// DigraphWriter<DGR>(digraph, std::cout).
    2.37    ///   nodeMap("coordinates", coord_map).
    2.38    ///   nodeMap("size", size).
    2.39    ///   nodeMap("title", title).
    2.40 @@ -406,12 +404,12 @@
    2.41    /// section to the stream. The output stream can be retrieved with
    2.42    /// the \c ostream() function, hence the second pass can append its
    2.43    /// output to the output of the first pass.
    2.44 -  template <typename GR>
    2.45 +  template <typename DGR>
    2.46    class DigraphWriter {
    2.47    public:
    2.48  
    2.49 -    typedef GR Digraph;
    2.50 -    TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
    2.51 +    typedef DGR Digraph;
    2.52 +    TEMPLATE_DIGRAPH_TYPEDEFS(DGR);
    2.53  
    2.54    private:
    2.55  
    2.56 @@ -419,7 +417,7 @@
    2.57      std::ostream* _os;
    2.58      bool local_os;
    2.59  
    2.60 -    const Digraph& _digraph;
    2.61 +    const DGR& _digraph;
    2.62  
    2.63      std::string _nodes_caption;
    2.64      std::string _arcs_caption;
    2.65 @@ -451,7 +449,7 @@
    2.66      ///
    2.67      /// Construct a directed graph writer, which writes to the given
    2.68      /// output stream.
    2.69 -    DigraphWriter(const Digraph& digraph, std::ostream& os = std::cout)
    2.70 +    DigraphWriter(const DGR& digraph, std::ostream& os = std::cout)
    2.71        : _os(&os), local_os(false), _digraph(digraph),
    2.72          _skip_nodes(false), _skip_arcs(false) {}
    2.73  
    2.74 @@ -459,7 +457,7 @@
    2.75      ///
    2.76      /// Construct a directed graph writer, which writes to the given
    2.77      /// output file.
    2.78 -    DigraphWriter(const Digraph& digraph, const std::string& fn)
    2.79 +    DigraphWriter(const DGR& digraph, const std::string& fn)
    2.80        : _os(new std::ofstream(fn.c_str())), local_os(true), _digraph(digraph),
    2.81          _skip_nodes(false), _skip_arcs(false) {
    2.82        if (!(*_os)) {
    2.83 @@ -472,7 +470,7 @@
    2.84      ///
    2.85      /// Construct a directed graph writer, which writes to the given
    2.86      /// output file.
    2.87 -    DigraphWriter(const Digraph& digraph, const char* fn)
    2.88 +    DigraphWriter(const DGR& digraph, const char* fn)
    2.89        : _os(new std::ofstream(fn)), local_os(true), _digraph(digraph),
    2.90          _skip_nodes(false), _skip_arcs(false) {
    2.91        if (!(*_os)) {
    2.92 @@ -505,15 +503,15 @@
    2.93  
    2.94    private:
    2.95  
    2.96 -    template <typename DGR>
    2.97 -    friend DigraphWriter<DGR> digraphWriter(const DGR& digraph, 
    2.98 -                                            std::ostream& os);
    2.99 -    template <typename DGR>
   2.100 -    friend DigraphWriter<DGR> digraphWriter(const DGR& digraph,
   2.101 -                                            const std::string& fn);
   2.102 -    template <typename DGR>
   2.103 -    friend DigraphWriter<DGR> digraphWriter(const DGR& digraph,
   2.104 -                                            const char *fn);
   2.105 +    template <typename TDGR>
   2.106 +    friend DigraphWriter<TDGR> digraphWriter(const TDGR& digraph, 
   2.107 +                                             std::ostream& os);
   2.108 +    template <typename TDGR>
   2.109 +    friend DigraphWriter<TDGR> digraphWriter(const TDGR& digraph,
   2.110 +                                             const std::string& fn);
   2.111 +    template <typename TDGR>
   2.112 +    friend DigraphWriter<TDGR> digraphWriter(const TDGR& digraph,
   2.113 +                                             const char *fn);
   2.114  
   2.115      DigraphWriter(DigraphWriter& other)
   2.116        : _os(other._os), local_os(other.local_os), _digraph(other._digraph),
   2.117 @@ -724,8 +722,8 @@
   2.118        }
   2.119  
   2.120        if (label == 0) {
   2.121 -        IdMap<Digraph, Node> id_map(_digraph);
   2.122 -        _writer_bits::MapLess<IdMap<Digraph, Node> > id_less(id_map);
   2.123 +        IdMap<DGR, Node> id_map(_digraph);
   2.124 +        _writer_bits::MapLess<IdMap<DGR, Node> > id_less(id_map);
   2.125          std::sort(nodes.begin(), nodes.end(), id_less);
   2.126        } else {
   2.127          label->sort(nodes);
   2.128 @@ -809,8 +807,8 @@
   2.129        }
   2.130  
   2.131        if (label == 0) {
   2.132 -        IdMap<Digraph, Arc> id_map(_digraph);
   2.133 -        _writer_bits::MapLess<IdMap<Digraph, Arc> > id_less(id_map);
   2.134 +        IdMap<DGR, Arc> id_map(_digraph);
   2.135 +        _writer_bits::MapLess<IdMap<DGR, Arc> > id_less(id_map);
   2.136          std::sort(arcs.begin(), arcs.end(), id_less);
   2.137        } else {
   2.138          label->sort(arcs);
   2.139 @@ -915,14 +913,41 @@
   2.140      /// @}
   2.141    };
   2.142  
   2.143 +  /// \ingroup lemon_io
   2.144 +  ///
   2.145    /// \brief Return a \ref DigraphWriter class
   2.146    ///
   2.147 -  /// This function just returns a \ref DigraphWriter class.
   2.148 +  /// This function just returns a \ref DigraphWriter class. 
   2.149 +  ///
   2.150 +  /// With this function a digraph can be write to a file or output
   2.151 +  /// stream in \ref lgf-format "LGF" format with several maps and
   2.152 +  /// attributes. For example, with the following code a network flow
   2.153 +  /// problem can be written to the standard output, i.e. a digraph
   2.154 +  /// with a \e capacity map on the arcs and \e source and \e target
   2.155 +  /// nodes:
   2.156 +  ///
   2.157 +  ///\code
   2.158 +  ///ListDigraph digraph;
   2.159 +  ///ListDigraph::ArcMap<int> cap(digraph);
   2.160 +  ///ListDigraph::Node src, trg;
   2.161 +  ///  // Setting the capacity map and source and target nodes
   2.162 +  ///digraphWriter(digraph, std::cout).
   2.163 +  ///  arcMap("capacity", cap).
   2.164 +  ///  node("source", src).
   2.165 +  ///  node("target", trg).
   2.166 +  ///  run();
   2.167 +  ///\endcode
   2.168 +  ///
   2.169 +  /// For a complete documentation, please see the \ref DigraphWriter
   2.170 +  /// class documentation.
   2.171 +  /// \warning Don't forget to put the \ref DigraphWriter::run() "run()"
   2.172 +  /// to the end of the parameter list.
   2.173    /// \relates DigraphWriter
   2.174 -  template <typename Digraph>
   2.175 -  DigraphWriter<Digraph> digraphWriter(const Digraph& digraph,
   2.176 -                                       std::ostream& os) {
   2.177 -    DigraphWriter<Digraph> tmp(digraph, os);
   2.178 +  /// \sa digraphWriter(const TDGR& digraph, const std::string& fn)
   2.179 +  /// \sa digraphWriter(const TDGR& digraph, const char* fn)
   2.180 +  template <typename TDGR>
   2.181 +  DigraphWriter<TDGR> digraphWriter(const TDGR& digraph, std::ostream& os) {
   2.182 +    DigraphWriter<TDGR> tmp(digraph, os);
   2.183      return tmp;
   2.184    }
   2.185  
   2.186 @@ -930,10 +955,11 @@
   2.187    ///
   2.188    /// This function just returns a \ref DigraphWriter class.
   2.189    /// \relates DigraphWriter
   2.190 -  template <typename Digraph>
   2.191 -  DigraphWriter<Digraph> digraphWriter(const Digraph& digraph,
   2.192 -                                       const std::string& fn) {
   2.193 -    DigraphWriter<Digraph> tmp(digraph, fn);
   2.194 +  /// \sa digraphWriter(const TDGR& digraph, std::ostream& os)
   2.195 +  template <typename TDGR>
   2.196 +  DigraphWriter<TDGR> digraphWriter(const TDGR& digraph, 
   2.197 +                                    const std::string& fn) {
   2.198 +    DigraphWriter<TDGR> tmp(digraph, fn);
   2.199      return tmp;
   2.200    }
   2.201  
   2.202 @@ -941,23 +967,22 @@
   2.203    ///
   2.204    /// This function just returns a \ref DigraphWriter class.
   2.205    /// \relates DigraphWriter
   2.206 -  template <typename Digraph>
   2.207 -  DigraphWriter<Digraph> digraphWriter(const Digraph& digraph,
   2.208 -                                       const char* fn) {
   2.209 -    DigraphWriter<Digraph> tmp(digraph, fn);
   2.210 +  /// \sa digraphWriter(const TDGR& digraph, std::ostream& os)
   2.211 +  template <typename TDGR>
   2.212 +  DigraphWriter<TDGR> digraphWriter(const TDGR& digraph, const char* fn) {
   2.213 +    DigraphWriter<TDGR> tmp(digraph, fn);
   2.214      return tmp;
   2.215    }
   2.216  
   2.217 -  template <typename Graph>
   2.218 +  template <typename GR>
   2.219    class GraphWriter;
   2.220  
   2.221 -  template <typename Graph>
   2.222 -  GraphWriter<Graph> graphWriter(const Graph& graph,
   2.223 -                                 std::ostream& os = std::cout);
   2.224 -  template <typename Graph>
   2.225 -  GraphWriter<Graph> graphWriter(const Graph& graph, const std::string& fn);
   2.226 -  template <typename Graph>
   2.227 -  GraphWriter<Graph> graphWriter(const Graph& graph, const char* fn);
   2.228 +  template <typename TGR>
   2.229 +  GraphWriter<TGR> graphWriter(const TGR& graph, std::ostream& os = std::cout);
   2.230 +  template <typename TGR>
   2.231 +  GraphWriter<TGR> graphWriter(const TGR& graph, const std::string& fn);
   2.232 +  template <typename TGR>
   2.233 +  GraphWriter<TGR> graphWriter(const TGR& graph, const char* fn);
   2.234  
   2.235    /// \ingroup lemon_io
   2.236    ///
   2.237 @@ -979,7 +1004,7 @@
   2.238    public:
   2.239  
   2.240      typedef GR Graph;
   2.241 -    TEMPLATE_GRAPH_TYPEDEFS(Graph);
   2.242 +    TEMPLATE_GRAPH_TYPEDEFS(GR);
   2.243  
   2.244    private:
   2.245  
   2.246 @@ -987,7 +1012,7 @@
   2.247      std::ostream* _os;
   2.248      bool local_os;
   2.249  
   2.250 -    const Graph& _graph;
   2.251 +    const GR& _graph;
   2.252  
   2.253      std::string _nodes_caption;
   2.254      std::string _edges_caption;
   2.255 @@ -1019,7 +1044,7 @@
   2.256      ///
   2.257      /// Construct a directed graph writer, which writes to the given
   2.258      /// output stream.
   2.259 -    GraphWriter(const Graph& graph, std::ostream& os = std::cout)
   2.260 +    GraphWriter(const GR& graph, std::ostream& os = std::cout)
   2.261        : _os(&os), local_os(false), _graph(graph),
   2.262          _skip_nodes(false), _skip_edges(false) {}
   2.263  
   2.264 @@ -1027,7 +1052,7 @@
   2.265      ///
   2.266      /// Construct a directed graph writer, which writes to the given
   2.267      /// output file.
   2.268 -    GraphWriter(const Graph& graph, const std::string& fn)
   2.269 +    GraphWriter(const GR& graph, const std::string& fn)
   2.270        : _os(new std::ofstream(fn.c_str())), local_os(true), _graph(graph),
   2.271          _skip_nodes(false), _skip_edges(false) {
   2.272        if (!(*_os)) {
   2.273 @@ -1040,7 +1065,7 @@
   2.274      ///
   2.275      /// Construct a directed graph writer, which writes to the given
   2.276      /// output file.
   2.277 -    GraphWriter(const Graph& graph, const char* fn)
   2.278 +    GraphWriter(const GR& graph, const char* fn)
   2.279        : _os(new std::ofstream(fn)), local_os(true), _graph(graph),
   2.280          _skip_nodes(false), _skip_edges(false) {
   2.281        if (!(*_os)) {
   2.282 @@ -1073,15 +1098,13 @@
   2.283  
   2.284    private:
   2.285  
   2.286 -    template <typename Graph>
   2.287 -    friend GraphWriter<Graph> graphWriter(const Graph& graph,
   2.288 -                                          std::ostream& os);
   2.289 -    template <typename Graph>
   2.290 -    friend GraphWriter<Graph> graphWriter(const Graph& graph,
   2.291 -                                          const std::string& fn);
   2.292 -    template <typename Graph>
   2.293 -    friend GraphWriter<Graph> graphWriter(const Graph& graph,
   2.294 -                                          const char *fn);
   2.295 +    template <typename TGR>
   2.296 +    friend GraphWriter<TGR> graphWriter(const TGR& graph, std::ostream& os);
   2.297 +    template <typename TGR>
   2.298 +    friend GraphWriter<TGR> graphWriter(const TGR& graph, 
   2.299 +                                        const std::string& fn);
   2.300 +    template <typename TGR>
   2.301 +    friend GraphWriter<TGR> graphWriter(const TGR& graph, const char *fn);
   2.302      
   2.303      GraphWriter(GraphWriter& other)
   2.304        : _os(other._os), local_os(other.local_os), _graph(other._graph),
   2.305 @@ -1168,10 +1191,10 @@
   2.306      GraphWriter& arcMap(const std::string& caption, const Map& map) {
   2.307        checkConcept<concepts::ReadMap<Arc, typename Map::Value>, Map>();
   2.308        _writer_bits::MapStorageBase<Edge>* forward_storage =
   2.309 -        new _writer_bits::GraphArcMapStorage<Graph, true, Map>(_graph, map);
   2.310 +        new _writer_bits::GraphArcMapStorage<GR, true, Map>(_graph, map);
   2.311        _edge_maps.push_back(std::make_pair('+' + caption, forward_storage));
   2.312        _writer_bits::MapStorageBase<Edge>* backward_storage =
   2.313 -        new _writer_bits::GraphArcMapStorage<Graph, false, Map>(_graph, map);
   2.314 +        new _writer_bits::GraphArcMapStorage<GR, false, Map>(_graph, map);
   2.315        _edge_maps.push_back(std::make_pair('-' + caption, backward_storage));
   2.316        return *this;
   2.317      }
   2.318 @@ -1185,11 +1208,11 @@
   2.319                            const Converter& converter = Converter()) {
   2.320        checkConcept<concepts::ReadMap<Arc, typename Map::Value>, Map>();
   2.321        _writer_bits::MapStorageBase<Edge>* forward_storage =
   2.322 -        new _writer_bits::GraphArcMapStorage<Graph, true, Map, Converter>
   2.323 +        new _writer_bits::GraphArcMapStorage<GR, true, Map, Converter>
   2.324          (_graph, map, converter);
   2.325        _edge_maps.push_back(std::make_pair('+' + caption, forward_storage));
   2.326        _writer_bits::MapStorageBase<Edge>* backward_storage =
   2.327 -        new _writer_bits::GraphArcMapStorage<Graph, false, Map, Converter>
   2.328 +        new _writer_bits::GraphArcMapStorage<GR, false, Map, Converter>
   2.329          (_graph, map, converter);
   2.330        _edge_maps.push_back(std::make_pair('-' + caption, backward_storage));
   2.331        return *this;
   2.332 @@ -1247,7 +1270,7 @@
   2.333      ///
   2.334      /// Add an arc writing rule to writer.
   2.335      GraphWriter& arc(const std::string& caption, const Arc& arc) {
   2.336 -      typedef _writer_bits::GraphArcLookUpConverter<Graph> Converter;
   2.337 +      typedef _writer_bits::GraphArcLookUpConverter<GR> Converter;
   2.338        Converter converter(_graph, _edge_index);
   2.339        _writer_bits::ValueStorageBase* storage =
   2.340          new _writer_bits::ValueStorage<Arc, Converter>(arc, converter);
   2.341 @@ -1338,8 +1361,8 @@
   2.342        }
   2.343  
   2.344        if (label == 0) {
   2.345 -        IdMap<Graph, Node> id_map(_graph);
   2.346 -        _writer_bits::MapLess<IdMap<Graph, Node> > id_less(id_map);
   2.347 +        IdMap<GR, Node> id_map(_graph);
   2.348 +        _writer_bits::MapLess<IdMap<GR, Node> > id_less(id_map);
   2.349          std::sort(nodes.begin(), nodes.end(), id_less);
   2.350        } else {
   2.351          label->sort(nodes);
   2.352 @@ -1423,8 +1446,8 @@
   2.353        }
   2.354  
   2.355        if (label == 0) {
   2.356 -        IdMap<Graph, Edge> id_map(_graph);
   2.357 -        _writer_bits::MapLess<IdMap<Graph, Edge> > id_less(id_map);
   2.358 +        IdMap<GR, Edge> id_map(_graph);
   2.359 +        _writer_bits::MapLess<IdMap<GR, Edge> > id_less(id_map);
   2.360          std::sort(edges.begin(), edges.end(), id_less);
   2.361        } else {
   2.362          label->sort(edges);
   2.363 @@ -1529,14 +1552,37 @@
   2.364      /// @}
   2.365    };
   2.366  
   2.367 +  /// \ingroup lemon_io
   2.368 +  ///
   2.369    /// \brief Return a \ref GraphWriter class
   2.370    ///
   2.371 -  /// This function just returns a \ref GraphWriter class.
   2.372 +  /// This function just returns a \ref GraphWriter class. 
   2.373 +  ///
   2.374 +  /// With this function a graph can be write to a file or output
   2.375 +  /// stream in \ref lgf-format "LGF" format with several maps and
   2.376 +  /// attributes. For example, with the following code a weighted
   2.377 +  /// matching problem can be written to the standard output, i.e. a
   2.378 +  /// graph with a \e weight map on the edges:
   2.379 +  ///
   2.380 +  ///\code
   2.381 +  ///ListGraph graph;
   2.382 +  ///ListGraph::EdgeMap<int> weight(graph);
   2.383 +  ///  // Setting the weight map
   2.384 +  ///graphWriter(graph, std::cout).
   2.385 +  ///  edgeMap("weight", weight).
   2.386 +  ///  run();
   2.387 +  ///\endcode
   2.388 +  ///
   2.389 +  /// For a complete documentation, please see the \ref GraphWriter
   2.390 +  /// class documentation.
   2.391 +  /// \warning Don't forget to put the \ref GraphWriter::run() "run()"
   2.392 +  /// to the end of the parameter list.
   2.393    /// \relates GraphWriter
   2.394 -  template <typename Graph>
   2.395 -  GraphWriter<Graph> graphWriter(const Graph& graph,
   2.396 -                                 std::ostream& os) {
   2.397 -    GraphWriter<Graph> tmp(graph, os);
   2.398 +  /// \sa graphWriter(const TGR& graph, const std::string& fn)
   2.399 +  /// \sa graphWriter(const TGR& graph, const char* fn)
   2.400 +  template <typename TGR>
   2.401 +  GraphWriter<TGR> graphWriter(const TGR& graph, std::ostream& os) {
   2.402 +    GraphWriter<TGR> tmp(graph, os);
   2.403      return tmp;
   2.404    }
   2.405  
   2.406 @@ -1544,9 +1590,10 @@
   2.407    ///
   2.408    /// This function just returns a \ref GraphWriter class.
   2.409    /// \relates GraphWriter
   2.410 -  template <typename Graph>
   2.411 -  GraphWriter<Graph> graphWriter(const Graph& graph, const std::string& fn) {
   2.412 -    GraphWriter<Graph> tmp(graph, fn);
   2.413 +  /// \sa graphWriter(const TGR& graph, std::ostream& os)
   2.414 +  template <typename TGR>
   2.415 +  GraphWriter<TGR> graphWriter(const TGR& graph, const std::string& fn) {
   2.416 +    GraphWriter<TGR> tmp(graph, fn);
   2.417      return tmp;
   2.418    }
   2.419  
   2.420 @@ -1554,9 +1601,10 @@
   2.421    ///
   2.422    /// This function just returns a \ref GraphWriter class.
   2.423    /// \relates GraphWriter
   2.424 -  template <typename Graph>
   2.425 -  GraphWriter<Graph> graphWriter(const Graph& graph, const char* fn) {
   2.426 -    GraphWriter<Graph> tmp(graph, fn);
   2.427 +  /// \sa graphWriter(const TGR& graph, std::ostream& os)
   2.428 +  template <typename TGR>
   2.429 +  GraphWriter<TGR> graphWriter(const TGR& graph, const char* fn) {
   2.430 +    GraphWriter<TGR> tmp(graph, fn);
   2.431      return tmp;
   2.432    }
   2.433  
   2.434 @@ -1746,10 +1794,18 @@
   2.435  
   2.436    };
   2.437  
   2.438 +  /// \ingroup lemon_io
   2.439 +  ///
   2.440    /// \brief Return a \ref SectionWriter class
   2.441    ///
   2.442    /// This function just returns a \ref SectionWriter class.
   2.443 +  ///
   2.444 +  /// Please see SectionWriter documentation about the custom section
   2.445 +  /// output.
   2.446 +  ///
   2.447    /// \relates SectionWriter
   2.448 +  /// \sa sectionWriter(const std::string& fn)
   2.449 +  /// \sa sectionWriter(const char *fn)
   2.450    inline SectionWriter sectionWriter(std::ostream& os) {
   2.451      SectionWriter tmp(os);
   2.452      return tmp;
   2.453 @@ -1759,6 +1815,7 @@
   2.454    ///
   2.455    /// This function just returns a \ref SectionWriter class.
   2.456    /// \relates SectionWriter
   2.457 +  /// \sa sectionWriter(std::ostream& os)
   2.458    inline SectionWriter sectionWriter(const std::string& fn) {
   2.459      SectionWriter tmp(fn);
   2.460      return tmp;
   2.461 @@ -1768,6 +1825,7 @@
   2.462    ///
   2.463    /// This function just returns a \ref SectionWriter class.
   2.464    /// \relates SectionWriter
   2.465 +  /// \sa sectionWriter(std::ostream& os)
   2.466    inline SectionWriter sectionWriter(const char* fn) {
   2.467      SectionWriter tmp(fn);
   2.468      return tmp;