Changeset 493:bbd1db03f0fe in lemon-0.x for src/work/klao/path.h

Timestamp:

04/30/04 03:59:15 (20 years ago)

Author:

Mihaly Barasz

Branch:

default

Phase:

public

Convert:

svn:c9d7d8f5-90d6-0310-b91f-818b3a526b0e/lemon/trunk@651

Message:

DirPath? fejlodes.
Kiserleti struktura a forditasi idoben kapcsolhato konzisztencia es range
ellenorzesekre.

File:

• src/work/klao/path.h (modified) (5 diffs)

src/work/klao/path.h

@@ -1 +1 @@
 // -*- c++ -*- //
 
-///ingroup datas
+///\ingroup datas
 ///\file
-///\brief Class for representing paths in graphs.
+///\brief Classes for representing paths in graphs.
 
 #ifndef HUGO_PATH_H
@@ -13 +13 @@
 
 #include <invalid.h>
+#include <error.h>
+#include <debug.h>
 
 namespace hugo {
@@ -19 +21 @@
   /// @{
 
-  ///A container for directed paths
-
-  ///\param Graph The graph type in which the path is.
-  ///
-  ///In a sense, the path can be treated as a graph, for is has \c NodeIt
-  ///and \c EdgeIt with the same usage. These types converts to the \c Node
-  ///and \c Edge of the original graph.
-  ///\todo How to clear a path?
-  ///\todo Clarify the consistency checks to do.
-  template<typename Graph>
+
+  //! \brief A structure for representing directed path in a graph.
+  //!
+  //! \param Graph The graph type in which the path is.
+  //! \param DM DebugMode, defaults to DefaultDebugMode.
+  //! 
+  //! In a sense, the path can be treated as a graph, for is has \c NodeIt
+  //! and \c EdgeIt with the same usage. These types converts to the \c Node
+  //! and \c Edge of the original graph.
+  //!
+  //! \todo Thoroughfully check all the range and consistency tests.
+  template<typename Graph, typename DM = DefaultDebugMode>
   class DirPath {
   public:
@@ -43 +47 @@
   public:
 
-    /// Constructor
-    
     /// \param _G The graph in which the path is.
     ///
     DirPath(const Graph &_G) : gr(&_G) {}
 
+    /// \brief Subpath constructor.
+    ///
     /// Subpath defined by two nodes.
     /// \warning It is an error if the two edges are not in order!
+    /// \todo Implement!
     DirPath(const DirPath &P, const NodeIt &a, const NodeIt &b);
+    /// \brief Subpath constructor.
+    ///
     /// Subpath defined by two edges. Contains edges in [a,b)
     /// \warning It is an error if the two edges are not in order!
+    /// \todo Implement!
     DirPath(const DirPath &P, const EdgeIt &a, const EdgeIt &b);
 
+    /// Length of the path.
     size_t length() const { return edges.size(); }
+    /// Returns whether the path is empty.
     bool empty() const { return edges.empty(); }
+
+    /// Resets the path to an empty path.
+    void clear() { edges.clear(); }
+
+    /// \brief Starting point of the path.
+    ///
+    /// Starting point of the path.
+    /// Returns INVALID if the path is empty.
     GraphNode from() const {
       return empty() ? INVALID : gr->tail(edges[0]);
     }
+    /// \brief End point of the path.
+    ///
+    /// End point of the path.
+    /// Returns INVALID if the path is empty.
     GraphNode to() const {
       return empty() ? INVALID : gr->head(edges[length()-1]);
     }
 
+    /// \brief Initializes node or edge iterator to point to the first
+    /// node or edge.
+    ///
+    /// \sa nth
     template<typename It>
     It& first(It &i) const { return i=It(*this); }
 
+    /// \brief Initializes node or edge iterator to point to the node or edge
+    /// of a given index.
     template<typename It>
-    It& nth(It &i, int n) const { return i=It(*this, n); }
-
+    It& nth(It &i, int n) const {
+      // FIXME: this test should be different for NodeIt and EdgeIt:
+      if( DM::range_check && (n<0 || n>int(length())) )
+        fault("DirPath::nth: index out of range");
+      return i=It(*this, n);
+    }
+
+    /// Checks validity of a node or edge iterator.
     template<typename It>
     bool valid(const It &i) const { return i.valid(); }
 
+    /// Steps the given node or edge iterator.
     template<typename It>
-    It& next(It &e) const { return ++e; }
-
-    /// \todo !
-    NodeIt head(const EdgeIt& e) const;
-    NodeIt tail(const EdgeIt& e) const;
+    It& next(It &e) const {
+      if( DM::range_check && !e.valid() )
+        fault("DirPath::next() on invalid iterator");
+      return ++e;
+    }
+
+    /// \brief Returns node iterator pointing to the head node of the
+    /// given edge iterator.
+    NodeIt head(const EdgeIt& e) const {
+      return NodeIt(*this, e.idx+1);
+    }
+
+    /// \brief Returns node iterator pointing to the tail node of the
+    /// given edge iterator.
+    NodeIt tail(const EdgeIt& e) const {
+      return NodeIt(*this, e.idx);
+    }
 
 
@@ -144 +191 @@
     friend class Builder;    
 
-    ///Class to build paths
-
-    ///\ingroup datas
-    ///This class is used to build new paths.
-    ///You can push new edges to the front and to the back of the path in
-    ///arbitrary order the you can commit these changes to the graph.
-    ///\todo We must clarify when the path will be in "transitional" state.
+    /**
+     * \brief Class to build paths
+     * 
+     * \ingroup datas
+     * This class is used to fill a path with edges.
+     *
+     * You can push new edges to the front and to the back of the path in
+     * arbitrary order the you can commit these changes to the graph.
+     *
+     * Fundamentally, for most "Paths" (classes fulfilling the
+     * PathConcept) while the builder is active (after the first modifying
+     * operation and until the commit()) the original Path is in a
+     * "transitional" state (operations ot it have undefined result). But
+     * in the case of DirPath the original path is unchanged until the
+     * commit. However we don't recomend that you use this feature.
+     */
     class Builder {
       DirPath &P;
-      Container d;
+      Container front, back;
 
     public:
-      ///Constructor
-
-      ///\param _P the path you want to build.
+      ///\param _P the path you want to fill in.
       ///
       Builder(DirPath &_P) : P(_P) {}
 
-      ///Set the first node of the path.
+      ///Sets the first node of the path.
       
-      ///Set the first node of the path.
-      ///If the path is empty, this must be call before any call of
-      ///\ref pushFront() or \ref pushBack()
-      void setFirst(const GraphNode &) { }
+      ///Sets the first node of the path. If the path is empty, this
+      ///function or setTo() have to be called before any call to \ref
+      ///pushFront() or \ref pushBack()
+      void setFrom(const GraphNode &) {}
+      
+      ///Sets the last node of the path.
+      
+      ///Sets the last node of the path. If the path is empty, this
+      ///function or setFrom() have to be called before any call of \ref
+      ///pushFront() or \ref pushBack()
+      void setTo(const GraphNode &) {}
       
       ///Push a new edge to the front of the path
 
       ///Push a new edge to the front of the path.
-      ///\sa setFirst()
-      bool pushFront(const GraphEdge& e) {
-        if( empty() || P.gr->head(e)==from() ) {
-          d.push_back(e);
-          return true;
+      ///\sa setTo
+      void pushFront(const GraphEdge& e) {
+        if( DM::consistensy_check && !empty() && P.gr->head(e)!=from() ) {
+          fault("DirPath::Builder::pushFront: nonincident edge");
         }
-        return false;
-      }
+        front.push_back(e);
+      }
+
       ///Push a new edge to the back of the path
 
       ///Push a new edge to the back of the path.
-      ///\sa setFirst()
-      bool pushBack(const GraphEdge& e) {
-        if( empty() || P.gr->tail(e)==to() ) {
-          P.edges.push_back(e);
-          return true;
+      ///\sa setFrom
+      void pushBack(const GraphEdge& e) {
+        if( DM::consistensy_check && !empty() && P.gr->tail(e)!=to() ) {
+          fault("DirPath::Builder::pushBack: nonincident edge");
         }
-        return false;
+        back.push_back(e);
       }
 
       ///Commit the changes to the path.
       void commit() {
-        if( !d.empty() ) {
-          P.edges.insert(P.edges.begin(), d.rbegin(), d.rend());
-          d.clear();
+        if( !(front.empty() && back.empty()) ) {
+          Container tmp;
+          tmp.reserve(front.size()+back.size()+P.length());
+          tmp.insert(tmp.end(), front.rbegin(), front.rend());
+          tmp.insert(tmp.end(), P.edges.begin(), P.edges.end());
+          tmp.insert(tmp.end(), back.begin(), back.end());
+          P.edges.swap(tmp);
+          front.clear();
+          back.clear();
         }
       }
 
-      ///Desctuctor
-
-      ///The desctuctor.
-      ///It commit also commit the changes.
-      ///\todo Is this what we want?
-      ~Builder() { commit(); }
+//       ///Desctuctor
+
+//       ///The desctuctor.
+//       ///It commit also commit the changes.
+//       ///\todo Is this what we want?
+//  Nope. Let's use commit() explicitly.
+//       ~Builder() { commit(); }
 
       // FIXME: Hmm, pontosan hogy is kene ezt csinalni?
       // Hogy kenyelmes egy ilyet hasznalni?
       void reserve(size_t r) {
-        d.reserve(r);
-        P.edges.reserve(P.length()+r);
+        front.reserve(r);
+        back.reserve(r);
       }
 
     private:
-      bool empty() { return d.empty() && P.empty(); }
+      bool empty() {
+        return front.empty() && back.empty() && P.empty();
+      }
 
       GraphNode from() const {
-        if( ! d.empty() )
-          return P.gr->tail(d[d.size()-1]);
+        if( ! front.empty() )
+          return P.gr->tail(front[front.size()-1]);
         else if( ! P.empty() )
           return P.gr->tail(P.edges[0]);
+        else if( ! back.empty() )
+          return P.gr->tail(back[0]);
         else
           return INVALID;
       }
       GraphNode to() const {
-        if( ! P.empty() )
+        if( ! back.empty() )
+          return P.gr->head(back[back.size()-1]);
+        else if( ! P.empty() )
           return P.gr->head(P.edges[P.length()-1]);
-        else if( ! d.empty() )
-          return P.gr->head(d[0]);
+        else if( ! front.empty() )
+          return P.gr->head(front[0]);
         else
           return INVALID;