# HG changeset patch
# User deba
# Date 1107773294 0
# Node ID 9fd485470fee2c667907fc3a5febc6a160d47d05
# Parent  ab5c81fcc31a89adf765573dd122674565941790
Documentation

diff -r ab5c81fcc31a -r 9fd485470fee src/work/deba/graph_reader.h
--- a/src/work/deba/graph_reader.h	Sun Feb 06 20:14:30 2005 +0000
+++ b/src/work/deba/graph_reader.h	Mon Feb 07 10:48:14 2005 +0000
@@ -73,32 +73,50 @@
   };  
 
 
-  // Readers and ReaderTraits
   /// \brief Standard ReaderTraits for the GraphReader class.
   ///
-  /// 
- 
+  /// Standard ReaderTraits for the GraphReader class.
+  /// It defines standard reading method for all type of value. 
   struct DefaultReaderTraits {
 
+    /// \brief Template class for reading an value.
+    ///
+    /// Template class for reading an value.
     template <typename _Value>
     struct Reader {
+      /// The value type.
       typedef _Value Value;
+      /// \brief Reads a value from the given stream.
+      ///
+      /// Reads a value from the given stream.
       void read(std::istream& is, Value& value) {
 	if (!(is >> value)) 
 	  throw DataFormatException("Default Reader format exception");
       }
     };
 
+    /// The reader class for the not needed maps.
     typedef Reader<std::string> DefaultReader;
 
   };
 
+  /// \brief Reader class for quoted strings.
+  ///
+  /// Reader class for quoted strings. It can process the escape
+  /// sequences in the string.
   class QuotedStringReader {
   public:
     typedef std::string Value;
-
+    
+    /// \brief Constructor for the reader.
+    ///
+    /// Constructor for the reader. If the given parameter is true
+    /// the reader processes the escape sequences.
     QuotedStringReader(bool _escaped = true) : escaped(_escaped) {}
-
+    
+    /// \brief Reads a quoted string from the given stream.
+    ///
+    /// Reads a quoted string from the given stream.
     void read(std::istream& is, std::string& value) {
       char c;
       value.clear();
@@ -145,7 +163,8 @@
       case 'x':
 	{
 	  int code;
-	  if (!is.get(c) || !isHex(c)) throw DataFormatException("Escape format exception");
+	  if (!is.get(c) || !isHex(c)) 
+	    throw DataFormatException("Escape format exception");
 	  else if (code = valueHex(c), !is.get(c) || !isHex(c)) is.putback(c);
 	  else code = code * 16 + valueHex(c);
 	  return code;
@@ -153,9 +172,12 @@
       default:
 	{
 	  int code;
-	  if (!isOct(c)) throw DataFormatException("Escape format exception");
-	  else if (code = valueOct(c), !is.get(c) || !isOct(c)) is.putback(c);
-	  else if (code = code * 8 + valueOct(c), !is.get(c) || !isOct(c)) is.putback(c);
+	  if (!isOct(c)) 
+	    throw DataFormatException("Escape format exception");
+	  else if (code = valueOct(c), !is.get(c) || !isOct(c)) 
+	    is.putback(c);
+	  else if (code = code * 8 + valueOct(c), !is.get(c) || !isOct(c)) 
+	    is.putback(c);
 	  else code = code * 8 + valueOct(c);
 	  return code;
 	}	      
@@ -171,7 +193,9 @@
     }
 
    static bool isHex(char c) {
-      return ('0' <= c && c <= '9') || ('a' <= c && c <= 'z') || ('A' <= c && c <= 'Z'); 
+      return ('0' <= c && c <= '9') || 
+	('a' <= c && c <= 'z') || 
+	('A' <= c && c <= 'Z'); 
     }
     
     static int valueHex(char c) {
@@ -183,12 +207,10 @@
     bool escaped;
   };
 
-
-
-
-
-  // Graph reader
-  
+  /// \brief The graph reader class.
+  ///
+  /// The reader class for the graph input.
+  /// \see graph-io-page
   template <typename _Graph, typename _ReaderTraits = DefaultReaderTraits> 
   class GraphReader {
   public:
@@ -200,11 +222,18 @@
     typedef _ReaderTraits ReaderTraits;
     typedef typename ReaderTraits::DefaultReader DefaultReader;
 
+    /// \brief Construct a new GraphReader.
+    ///
+    /// Construct a new GraphReader. It reads from the given map,
+    /// it constructs the given map and it use the given reader as the
+    /// default skipper.
     GraphReader(std::istream& _is, Graph& _graph, 
 		const DefaultReader& _reader = DefaultReader()) 
       : is(_is), graph(_graph), nodeSkipper(_reader), edgeSkipper(_reader) {}
 
-
+    /// \brief Destruct the graph reader.
+    ///
+    /// Destruct the graph reader.
     ~GraphReader() {
 
       for (typename NodeMapReaders::iterator it = node_map_readers.begin(); 
@@ -219,14 +248,18 @@
 
     }
 
-    // Node map rules
-
+    /// \brief Add a new node map reader command for the reader.
+    ///
+    /// Add a new node map reader command for the reader.
     template <typename Map>
     GraphReader& addNodeMap(std::string name, Map& map) {
       return addNodeMap<typename ReaderTraits::template 
 	Reader<typename Map::Value>, Map>(name, map);
     }
 
+    /// \brief Add a new node map reader command for the reader.
+    ///
+    /// Add a new node map reader command for the reader.
     template <typename Reader, typename Map>
     GraphReader& addNodeMap(std::string name, Map& map, 
 			     const Reader& reader = Reader()) {
@@ -238,6 +271,9 @@
       return *this;
     }
 
+    /// \brief Add a new node map skipper command for the reader.
+    ///
+    /// Add a new node map skipper command for the reader.
     template <typename Reader>
     GraphReader& skipNodeMap(std::string name, 
 			     const Reader& reader = Reader()) {
@@ -249,8 +285,9 @@
       return *this;
     }
 
-    // Edge map rules
-
+    /// \brief Add a new edge map reader command for the reader.
+    ///
+    /// Add a new edge map reader command for the reader.
     template <typename Map>
     GraphReader& addEdgeMap(std::string name, Map& map) { 
       return addEdgeMap<typename ReaderTraits::template
@@ -258,6 +295,9 @@
     }
 
 
+    /// \brief Add a new edge map reader command for the reader.
+    ///
+    /// Add a new edge map reader command for the reader.
     template <typename Reader, typename Map>
     GraphReader& addEdgeMap(std::string name, Map& map,
 			     const Reader& reader = Reader()) {
@@ -269,6 +309,9 @@
       return *this;
     }
 
+    /// \brief Add a new edge map skipper command for the reader.
+    ///
+    /// Add a new edge map skipper command for the reader.
     template <typename Reader>
     GraphReader& skipEdgeMap(std::string name,
 			     const Reader& reader = Reader()) {
@@ -280,7 +323,9 @@
       return *this;
     }
 
-    // Node rules
+    /// \brief Add a new labeled node reader for the reader.
+    ///
+    /// Add a new labeled node reader for the reader.
     GraphReader& addNode(std::string name, Node& node) {
       if (node_readers.find(name) != node_readers.end()) {
 	throw Exception() << "Multiple read rule for node";
@@ -289,8 +334,9 @@
       return *this;
     }
 
-    // Edge rules
-
+    /// \brief Add a new labeled edge reader for the reader.
+    ///
+    /// Add a new labeled edge reader for the reader.
     GraphReader& addEdge(std::string name, Edge& edge) {
       if (edge_readers.find(name) != edge_readers.end()) {
 	throw Exception() << "Multiple read rule for edge";
@@ -299,7 +345,10 @@
       return *this;
     }
 
-    void read() {
+    /// \brief Executes the reader commands.
+    ///
+    /// Executes the reader commands.
+    void run() {
       int line_num = 0;
       std::auto_ptr<InverterBase<Node> > nodeInverter;
       std::auto_ptr<InverterBase<Edge> > edgeInverter;
diff -r ab5c81fcc31a -r 9fd485470fee src/work/deba/graph_writer.h
--- a/src/work/deba/graph_writer.h	Sun Feb 06 20:14:30 2005 +0000
+++ b/src/work/deba/graph_writer.h	Mon Feb 07 10:48:14 2005 +0000
@@ -33,12 +33,23 @@
 
 namespace lemon {
 
+  /// \brief Standard WriterTraits for the GraphWriter class.
+  ///
+  /// Standard WriterTraits for the GraphWriter class.
+  /// It defines standard writing method for all type of value. 
   struct DefaultWriterTraits {
 
+    /// \brief Template class for writing an value.
+    ///
+    /// Template class for writing an value.
     template <typename _Value>
     struct Writer {
+      /// The value type.
       typedef _Value Value;
 
+      /// \brief Writes a value from the given stream.
+      ///
+      /// Writes a value from the given stream.
       void write(std::ostream& os, const Value& value) {
 	os << value << '\t';
       }
@@ -47,12 +58,23 @@
   };
 
 
+  /// \brief Writer class for quoted strings.
+  ///
+  /// Writer class for quoted strings. It can process the escape
+  /// sequences in the string.
   class QuotedStringWriter {
   public:
     typedef std::string Value;
 
+    /// \brief Constructor for the writer.
+    ///
+    /// Constructor for the writer. If the given parameter is true
+    /// the writer creates escape sequences from special characters.
     QuotedStringWriter(bool _escaped = true) : escaped(_escaped) {}
 
+    /// \brief Writes a quoted string from the given stream.
+    ///
+    /// Writes a quoted string from the given stream.
     void write(std::ostream& os, const std::string& value) {
       os << "\"";
       if (escaped) {
@@ -117,8 +139,11 @@
     bool escaped;
   };
 
-  // Graph writer
   
+  /// \brief The graph writer class.
+  ///
+  /// The writer class for the graph output.
+  /// \see graph-io-page
   template <typename _Graph, typename _WriterTraits = DefaultWriterTraits> 
   class GraphWriter {
   public:
@@ -130,10 +155,18 @@
     typedef typename Graph::EdgeIt EdgeIt;
 
     typedef _WriterTraits WriterTraits;
-
+ 
+    /// \brief Construct a new GraphWriter.
+    ///
+    /// Construct a new GraphWriter. It writes from the given map,
+    /// it constructs the given map and it use the given writer as the
+    /// default skipper.
     GraphWriter(std::ostream& _os, Graph& _graph) : os(_os), graph(_graph) {}
 
 
+    /// \brief Destruct the graph writer.
+    ///
+    /// Destruct the graph writer.
     ~GraphWriter() {
       for (typename NodeMapWriters::iterator it = node_map_writers.begin(); 
 	   it != node_map_writers.end(); ++it) {
@@ -149,19 +182,21 @@
 
     // Node map rules
 
+    /// \brief Add a new node map writer command for the writer.
+    ///
+    /// Add a new node map writer command for the writer.
     template <typename Map>
     GraphWriter& addNodeMap(std::string name, const Map& map) {
       return addNodeMap<typename WriterTraits::template Writer<
 	typename Map::Value>, Map>(name, map);
     }
 
+    /// \brief Add a new node map writer command for the writer.
+    ///
+    /// Add a new node map writer command for the writer.
     template <typename Writer, typename Map>
     GraphWriter& addNodeMap(std::string name, const Map& map, 
 			      const Writer& writer = Writer()) {
-      //      if (node_map_writers.find(name) != node_map_writers.end()) {
-      //	throw Exception() << "Multiple write rule for node map: " 
-      //        << name;
-      //      }
       node_map_writers.push_back(
         make_pair(name, new MapWriter<Node, Map, Writer>(map, writer)));
       return *this;
@@ -169,41 +204,47 @@
 
     // Edge map rules
 
+    /// \brief Add a new edge map writer command for the writer.
+    ///
+    /// Add a new edge map writer command for the writer.
     template <typename Map>
     GraphWriter& addEdgeMap(std::string name, const Map& map) { 
-      return addEdgeMap<typename WriterTraits::template Writer<typename Map::Value>, Map>(name, map);
+      return addEdgeMap<typename WriterTraits::template Writer<
+        typename Map::Value>, Map>(name, map);
     }
 
 
+    /// \brief Add a new edge map writer command for the writer.
+    ///
+    /// Add a new edge map writer command for the writer.
     template <typename Writer, typename Map>
-    GraphWriter& addEdgeMap(std::string name, const Map& map, const Writer& writer = Writer()) {
-      //      if (edge_map_writers.find(name) != edge_map_writers.end()) {
-      //	throw Exception() << "Multiple write rule for edge map: " << name;
-      //      }
-      edge_map_writers.push_back(make_pair(name, new MapWriter<Edge, Map, Writer>(map, writer)));
+    GraphWriter& addEdgeMap(std::string name, 
+			    const Map& map, const Writer& writer = Writer()) {
+      edge_map_writers.push_back(make_pair(name, 
+	new MapWriter<Edge, Map, Writer>(map, writer)));
       return *this;
     }
 
-    // Node rules
+    /// \brief Add a new labeled node writer for the writer.
+    ///
+    /// Add a new labeled node writer for the writer.
     GraphWriter& addNode(std::string name, const Node& node) {
-      //      if (node_writers.find(name) != node_writers.end()) {
-      //	throw Exception() << "Multiple write rule for node";
-      //      }
       node_writers.push_back(make_pair(name, node));
       return *this;
     }
 
-    // Edge rules
-
+    /// \brief Add a new labeled edge writer for the writer.
+    ///
+    /// Add a new labeled edge writer for the writer.
     GraphWriter& addEdge(std::string name, const Edge& edge) {
-      //      if (edge_writers.find(name) != edge_writers.end()) {
-      //	throw Exception() << "Multiple write rule for edge";
-      //      }
       edge_writers.push_back(make_pair(name, edge));
       return *this;
     }
 
-    void write() {   
+    /// \brief Executes the writer commands.
+    ///
+    /// Executes the writer commands.
+    void run() {   
       writeNodeSet();
       writeEdgeSet();
       writeNodes();
diff -r ab5c81fcc31a -r 9fd485470fee src/work/deba/map_utils.h
--- a/src/work/deba/map_utils.h	Sun Feb 06 20:14:30 2005 +0000
+++ b/src/work/deba/map_utils.h	Mon Feb 07 10:48:14 2005 +0000
@@ -23,16 +23,17 @@
 
 namespace lemon {
 
-  /// \addtogroup gutils
+  /// \addtogroup mutils
   /// @{
 
-
   /// \brief General inversable map type.
 
   /// This type provides simple inversable map functions. 
   /// The InversableMap wraps an arbitrary ReadWriteMap 
   /// and if a key is setted to a new value then store it
   /// in the inverse map.
+  /// \param _Graph The graph type.
+  /// \param _Map The map to extend with inversable functionality. 
   template <
     typename _Graph, 
     typename _Map
@@ -43,7 +44,9 @@
     typedef _Graph Graph;
 
     typedef _Map Map;
+    /// The key type of InversableMap (Node, Edge, UndirEdge).
     typedef typename _Map::Key Key;
+    /// The value type of the InversableMap.
     typedef typename _Map::Value Value;
     typedef std::map<Value, Key> InverseMap;
     
@@ -60,38 +63,61 @@
     /// It sets the map and the inverse map to given key-value pair.
     void set(const Key& key, const Value& val) {
       Value oldval = Map::operator[](key);
-      typename InverseMap::iterator it = inv_map.find(oldval);
-      if (it != inv_map.end() && it->second == key) {
-	inv_map.erase(it);
+      typename InverseMap::iterator it = invMap.find(oldval);
+      if (it != invMap.end() && it->second == key) {
+	invMap.erase(it);
       }      
-      inv_map.insert(make_pair(val, key));
+      invMap.insert(make_pair(val, key));
       Map::set(key, val);
     }
 
-    ConstReference operator[](const Key&) const {
+    /// \brief The getter function of the map.
+    ///
+    /// It gives back the value associated with the key.
+    ConstReference operator[](const Key& key) const {
       return Map::operator[](key);
     }
 
-    virtual void add(const Key&) {
+    /// \brief Add a new key to the map.
+    ///
+    /// Add a new key to the map. It is called by the
+    /// \c AlterationNotifier.
+    virtual void add(const Key& key) {
       Map::add(key);
     }
 
-    virtual void erase(const Key&) {
+    /// \brief Erase the key from the map.
+    ///
+    /// Erase the key to the map. It is called by the
+    /// \c AlterationNotifier.
+    virtual void erase(const Key& key) {
       Value val = Map::operator[](key);
-      typename InverseMap::iterator it = inv_map.find(val);
-      if (it != inv_map.end() && it->second == key) {
+      typename InverseMap::iterator it = invMap.find(val);
+      if (it != invMap.end() && it->second == key) {
 	invMap.erase(it);
       }
       Map::erase(key);
     }
 
+    /// \brief Clear the keys from the map and inverse map.
+    ///
+    /// Clear the keys from the map and inverse map. It is called by the
+    /// \c AlterationNotifier.
+    virtual void clear() {
+      invMap.clear();
+      Map::clear();
+    }
+
+    /// \brief It gives back the just readeable inverse map.
+    ///
+    /// It gives back the just readeable inverse map.
     const InverseMap& inverse() const {
-      return inv_map;
+      return invMap;
     } 
 
 
   private:
-    InverseMap inv_map;    
+    InverseMap invMap;    
   };
 
 
@@ -135,29 +161,45 @@
       build();
     }
 
+    /// \brief Add a new key to the map.
+    ///
+    /// Add a new key to the map. It is called by the
+    /// \c AlterationNotifier.
     virtual void add(const Item& item) {
       Map::add(item);
-      Map::set(item, inv_map.size());
-      inv_map.push_back(item);
+      Map::set(item, invMap.size());
+      invMap.push_back(item);
     }
 
+    /// \brief Erase the key from the map.
+    ///
+    /// Erase the key to the map. It is called by the
+    /// \c AlterationNotifier.
     virtual void erase(const Item& item) {
-      Map::set(inv_map.back(), Map::operator[](item));
-      inv_map[Map::operator[](item)] = inv_map.back();
+      Map::set(invMap.back(), Map::operator[](item));
+      invMap[Map::operator[](item)] = invMap.back();
       Map::erase(item);
     }
 
+    /// \brief Build the unique map.
+    ///
+    /// Build the unique map. It is called by the
+    /// \c AlterationNotifier.
     virtual void build() {
       Map::build();
       Item it;
       for (getGraph()->first(it); it != INVALID; getGraph()->next(it)) {
-	Map::set(it, inv_map.size());
-	inv_map.push_back(it);	
+	Map::set(it, invMap.size());
+	invMap.push_back(it);	
       }      
     }
     
+    /// \brief Clear the keys from the map.
+    ///
+    /// Clear the keys from the map. It is called by the
+    /// \c AlterationNotifier.
     virtual void clear() {
-      inv_map.clear();
+      invMap.clear();
       Map::clear();
     }
 
@@ -172,11 +214,11 @@
     ///
     /// Gives back the inverse of the map.
     const InverseMap inverse() const {
-      return inv_map;
+      return invMap;
     }
 
   private:
-    vector<Item> inv_map;
+    vector<Item> invMap;
   };
   
   /// Provides an immutable and unique id for each item in the graph.